chore(release): prepare v0.20.0

The shared-font check still handed asar a forward-slash path, which
fails on Windows the same way the inventory listing did.

.agents/skills/subminer-change-verification/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: subminer-change-verification
+description: Verify SubMiner changes with repo-native cheap-first test lanes. Use after code, config, launcher, plugin, runtime, stats, documentation, or workflow changes; do not use for read-only questions.
+---
+
+# SubMiner Change Verification
+
+Verify the behavior claimed by a change without running unrelated expensive checks by default.
+
+## Workflow
+
+1. Inspect the requested scope and changed paths with `git status --short` and `git diff`.
+2. Read `docs/workflow/verification.md` as the source of truth for maintained lanes.
+3. Run the cheapest lane or lanes that cover the changed behavior.
+4. Escalate to the full handoff gate only for substantial or cross-boundary changes.
+5. Report exact commands, results, skipped checks, blockers, and remaining risk.
+
+Do not use hidden wrapper commands. Verification commands are owned by `package.json` and the workflow documentation.
+
+## Lane Selection
+
+- Internal docs, `AGENTS.md`, or `.agents/skills/**`: `bun run test:docs:kb`
+- User-facing `docs-site/**`: `bun run docs:test`, then `bun run docs:build`
+- Config/schema/defaults: `bun run test:config`
+  - If defaults or templates changed, also run `bun run generate:config-example` and `bun run verify:config-example`.
+- General TypeScript source: `bun run typecheck`, then `bun run test:fast`
+- Launcher or mpv plugin: `bun run test:launcher` or `bun run test:env`, based on the behavior changed
+- Runtime compatibility or dist-sensitive wiring: `bun run test:runtime:compat`
+- Stats dashboard: `bun run test:stats`
+- Build/release scripts: `bun run test:scripts`
+
+For substantial changes, use the full gate documented in `AGENTS.md` and `docs/workflow/verification.md`.
+
+## Runtime Escalation
+
+Real runtime checks are required when the claim depends on actual Electron, mpv, overlay, focus, window tracking, launch, or socket behavior. Run the relevant application flow when the environment supports it. Otherwise, report the missing runtime dependency and do not present cheaper checks as authoritative runtime validation.
+
+## Pre-Handoff Checks
+
+Before handoff, reconcile both questions:
+
+1. Do behavior, defaults, flags, shortcuts, ports, APIs, architecture, or workflow changes require documentation updates?
+2. Does the change require a current-outcome fragment under `changes/` according to `changes/README.md`?
+
+Complete required updates before handoff or report the blocker.

.agents/skills/subminer-release/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: subminer-release
+description: Prepare, cut, publish, or repair SubMiner stable and prerelease releases. Use for hands-on release work; do not use for general release questions.
+---
+
+# SubMiner release
+
+Carry out the requested release phase using the repository's current release process.
+
+## Source of truth
+
+Read `docs/RELEASING.md` completely before changing files or release state. Treat it as canonical. Read `changes/README.md` when the work touches change fragments or generated release notes.
+
+Do not copy release commands or policy into this skill. If this skill disagrees with the release guide, follow the guide and reconcile the skill before handoff.
+
+## Workflow
+
+1. Identify whether the request is for a stable release, prerelease, release preparation, publication, or repair.
+2. Inspect the current branch, worktree status, package version, pending change fragments, relevant tags, and latest CI state before making changes.
+3. Follow the matching procedure in `docs/RELEASING.md` in order. Review generated changelog and release-note Markdown before it can be committed or published.
+4. Run every required gate for the requested release phase. Do not treat a cheaper test lane as a substitute for the documented release gate.
+5. Before a stable tag, confirm the package and tag versions match and no pending `changes/*.md` fragments remain. Preserve fragments for prereleases as documented.
+6. Report the resulting version, completed checks, local commit and tag state, remote publication state, skipped platform checks, and any remaining manual work.
+
+## Authorization boundaries
+
+- A request to prepare a release stops before commit, tag, push, or remote publication unless the user also authorizes those actions.
+- A clear request to cut or publish a release includes the documented commit, tag, and push steps. Ask before the first remote mutation when the wording is ambiguous.
+- Do not edit an existing GitHub release, publish to the AUR, change secrets, or alter signing configuration unless the user explicitly requests that operation.
+- Do not switch branches without consent.
+
+## Stop conditions
+
+Stop and report the blocker when required CI or a release gate fails, authentication is missing, versions disagree, required artifacts are absent, or the worktree contains unexpected changes that overlap the release. Do not tag or publish a partially verified release.

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,105 @@
+name: Bug Report
+description: Report something that is broken or behaving incorrectly
+title: '[Bug]: '
+labels: ['bug']
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report! Please search [existing issues](https://github.com/ksyasuda/SubMiner/issues?q=is%3Aissue) first to avoid duplicates.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, including what you expected to happen instead.
+      placeholder: When I open the Yomitan popup, the overlay freezes...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to reproduce
+      description: Minimal, ordered steps that reliably trigger the bug.
+      placeholder: |
+        1. Launch `subminer`
+        2. Play a video in MPV
+        3. Hover a word and press ...
+        4. See error
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      description: Which part of SubMiner is affected?
+      options:
+        - Overlay / Yomitan popup
+        - Anki mining
+        - Subtitle annotations
+        - Subtitle sidebar
+        - Immersion tracking / stats
+        - Launcher / CLI
+        - MPV plugin
+        - Jellyfin integration
+        - Jimaku integration
+        - AniList integration
+        - YouTube integration
+        - Character dictionary
+        - WebSocket / texthooker API
+        - Configuration
+        - Documentation
+        - Other / not sure
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - macOS
+        - Windows
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: SubMiner version
+      description: Output of `subminer --version`, or the release tag / commit you are running.
+      placeholder: v0.15.0
+    validations:
+      required: true
+
+  - type: input
+    id: compositor
+    attributes:
+      label: Compositor (Linux only)
+      description: SubMiner's overlay supports Hyprland and sway. Name yours (and version if known). Leave blank on macOS / Windows.
+      placeholder: Hyprland 0.55
+    validations:
+      required: false
+
+  - type: input
+    id: mpv-version
+    attributes:
+      label: MPV version
+      description: Output of `mpv --version` (first line).
+      placeholder: mpv 0.38.0
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / console output
+      description: |
+        Relevant logs. For verbose output, run `electron . --dev --log-level debug`.
+        This will be rendered as code automatically — no backticks needed.
+      render: shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://docs.subminer.moe
+    about: Setup, configuration, and feature docs — check here before filing an issue.
+  - name: Troubleshooting guide
+    url: https://docs.subminer.moe/troubleshooting
+    about: Common problems and fixes (Hyprland rules, MPV detection, Anki connection, etc.).

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,59 @@
+name: Feature Request
+description: Suggest a new feature or an improvement to an existing one
+title: '[Feature]: '
+labels: ['enhancement']
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the idea! Please search [existing issues](https://github.com/ksyasuda/SubMiner/issues?q=is%3Aissue) first to avoid duplicates.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: What problem are you trying to solve? What is missing or frustrating today?
+      placeholder: When mining a card I have to manually switch to Anki because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the feature or change you'd like to see.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Related area
+      description: Which part of SubMiner does this relate to?
+      options:
+        - Overlay / Yomitan popup
+        - Anki mining
+        - Subtitle annotations
+        - Subtitle sidebar
+        - Immersion tracking / stats
+        - Launcher / CLI
+        - MPV plugin
+        - Jellyfin integration
+        - Jimaku integration
+        - AniList integration
+        - YouTube integration
+        - Character dictionary
+        - WebSocket / texthooker API
+        - Configuration
+        - Documentation
+        - Other / new area
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds you currently use or other approaches you've thought about.
+    validations:
+      required: false

.github/pull_request_template.md

@@ -0,0 +1,36 @@
+<!--
+Thanks for contributing to SubMiner! Fill out the sections below.
+Keep it short — a couple of sentences per section is fine.
+-->
+
+## Summary
+
+<!-- What does this PR do and why? -->
+
+## Type of change
+
+<!-- Check all that apply. -->
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / internal
+- [ ] Documentation
+- [ ] Other
+
+## Related issues
+
+<!-- e.g. "Closes #123". Delete if none. -->
+
+## How was this tested?
+
+<!--
+Describe verification. The default handoff gate is:
+  bun run typecheck && bun run test:fast && bun run test:env && bun run build && bun run test:smoke:dist
+If docs-site/ changed, also: bun run docs:test && bun run docs:build
+-->
+
+## Checklist
+
+- [ ] Reconciled current-outcome changelog fragment(s), or this PR is labeled `skip-changelog` (see [`changes/README.md`](../changes/README.md))
+- [ ] Docs updated in the same PR if behavior, defaults, flags, shortcuts, ports, or APIs changed
+- [ ] Relevant checks pass locally (typecheck, tests, build)

.github/workflows/ci.yml

@@ -8,67 +8,4 @@ on:
 
 jobs:
   build-test-audit:
-    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
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Build (TypeScript check)
-        # Keep explicit typecheck for fast fail before full build/bundle.
-        run: bun run tsc --noEmit
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - 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: Dist smoke suite
-        run: bun run test:smoke:dist
-
-      - name: Build docs
-        run: bun run docs:build
-
-      - 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

.github/workflows/docs-pages.yml

@@ -0,0 +1,78 @@
+name: Docs Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+    paths:
+      - 'docs-site/**'
+      - 'scripts/docs-versioning.ts'
+      - 'scripts/build-versioned-docs.ts'
+      - '.github/workflows/docs-pages.yml'
+      - 'package.json'
+      - 'bun.lock'
+
+concurrency:
+  group: docs-pages-production
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    if: ${{ github.ref_type != 'tag' || !contains(github.ref_name, '-') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Guard stable docs tag shape
+        id: tag_guard
+        if: github.ref_type == 'tag'
+        env:
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          if [[ ! "$TAG_NAME" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "::notice::Skipping non-stable docs tag $TAG_NAME"
+            echo "stable_tag=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "stable_tag=true" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Bun
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Install dependencies
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        run: |
+          bun install --frozen-lockfile
+          cd docs-site && bun install --frozen-lockfile
+
+      - name: Cache versioned docs archives
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        uses: actions/cache@v4
+        with:
+          path: .tmp/docs-versioned-archive-cache
+          key: docs-versioned-archives-${{ runner.os }}-${{ hashFiles('docs-site/.vitepress/**', 'docs-site/public/assets/fonts/**', 'docs-site/package.json', 'docs-site/bun.lock', 'scripts/build-versioned-docs.ts', 'scripts/docs-versioning.ts') }}
+
+      - name: Test docs
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        run: bun run docs:test
+
+      - name: Build versioned docs
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        run: bun run docs:build:versioned
+
+      - name: Deploy docs to Cloudflare Pages
+        if: steps.tag_guard.outputs.stable_tag != 'false'
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy .tmp/docs-versioned-site --project-name "${{ vars.CLOUDFLARE_PAGES_PROJECT_NAME }}" --branch main

.github/workflows/package-release.yml

@@ -0,0 +1,274 @@
+name: Package release
+
+on:
+  workflow_call:
+    secrets:
+      CSC_LINK:
+        required: true
+      CSC_KEY_PASSWORD:
+        required: true
+      APPLE_ID:
+        required: true
+      APPLE_APP_SPECIFIC_PASSWORD:
+        required: true
+      APPLE_TEAM_ID:
+        required: true
+      # Project TMDB key baked into release artifacts; builds stay valid without it.
+      SUBMINER_TMDB_API_KEY:
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  build-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          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/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/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: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Download previous package size reports
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p .tmp/package-baseline
+          previous=$(gh api "repos/$GITHUB_REPOSITORY/releases" --jq '[.[] | select(.draft == false and .tag_name != env.GITHUB_REF_NAME)] | sort_by(.published_at) | last | .tag_name // empty')
+          if [ -n "$previous" ]; then
+            gh release download "$previous" --pattern 'package-size-*.json' --dir .tmp/package-baseline || echo 'Previous release has no package size reports; size comparison will be skipped.'
+          fi
+
+      - name: Build AppImage
+        run: bun run build:appimage
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+
+      - name: Build unversioned AppImage
+        run: |
+          shopt -s nullglob
+          appimages=(release/SubMiner-*.AppImage)
+          if [ "${#appimages[@]}" -eq 0 ]; then
+            echo "No versioned AppImage found to create unversioned artifact."
+            ls -la release
+            exit 1
+          fi
+          cp "${appimages[0]}" release/SubMiner.AppImage
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: xvfb-run -a bun run test:package "release/linux-unpacked/resources"
+
+      - name: Upload AppImage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: appimage
+          path: |
+            release/*.AppImage
+            release/latest*.yml
+            release/*.blockmap
+            release/package-size-*.json
+          if-no-files-found: error
+
+  build-macos:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          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/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/bun.lock', 'vendor/subminer-yomitan/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Validate macOS signing/notarization secrets
+        run: |
+          missing=0
+          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
+            if [ -z "${!name}" ]; then
+              echo "Missing required secret: $name"
+              missing=1
+            fi
+          done
+          if [ "$missing" -ne 0 ]; then
+            echo "Set all required macOS signing/notarization secrets and rerun."
+            exit 1
+          fi
+        env:
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Install dependencies
+        run: |
+          bun install --frozen-lockfile
+          cd stats && bun install --frozen-lockfile
+
+      - name: Build texthooker-ui
+        run: |
+          cd vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Download previous package size reports
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p .tmp/package-baseline
+          previous=$(gh api "repos/$GITHUB_REPOSITORY/releases" --jq '[.[] | select(.draft == false and .tag_name != env.GITHUB_REF_NAME)] | sort_by(.published_at) | last | .tag_name // empty')
+          if [ -n "$previous" ]; then
+            gh release download "$previous" --pattern 'package-size-*.json' --dir .tmp/package-baseline || echo 'Previous release has no package size reports; size comparison will be skipped.'
+          fi
+
+      - name: Build signed + notarized macOS artifacts
+        run: bun run build:mac
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+          CSC_LINK: ${{ secrets.CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: bun run test:package "release/mac-arm64/SubMiner.app/Contents/Resources"
+
+      - name: Upload macOS artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: macos
+          path: |
+            release/*.dmg
+            release/*.zip
+            release/latest*.yml
+            release/*.blockmap
+            release/package-size-*.json
+          if-no-files-found: error
+
+  build-windows:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          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/texthooker-ui/node_modules
+            vendor/subminer-yomitan/node_modules
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock', 'stats/bun.lock', 'vendor/texthooker-ui/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: Build texthooker-ui
+        shell: powershell
+        run: |
+          Set-Location vendor/texthooker-ui
+          bun install --frozen-lockfile
+          bun run build
+
+      - name: Download previous package size reports
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p .tmp/package-baseline
+          previous=$(gh api "repos/$GITHUB_REPOSITORY/releases" --jq '[.[] | select(.draft == false and .tag_name != env.GITHUB_REF_NAME)] | sort_by(.published_at) | last | .tag_name // empty')
+          if [ -n "$previous" ]; then
+            gh release download "$previous" --pattern 'package-size-*.json' --dir .tmp/package-baseline || echo 'Previous release has no package size reports; size comparison will be skipped.'
+          fi
+
+      - name: Verify managed Windows launcher
+        run: bun test src/main/runtime/managed-launcher.test.ts
+
+      - name: Verify Windows launcher bootstrap
+        run: bun test src/main/runtime/windows-launcher-bootstrap.test.ts
+
+      - name: Build unsigned Windows artifacts
+        run: bun run build:win:unsigned
+        env:
+          SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+
+      - name: Smoke packaged runtime assets
+        shell: bash
+        run: bun run test:package "release/win-unpacked/resources"
+
+      - name: Upload Windows artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows
+          path: |
+            release/*.exe
+            release/*.zip
+            release/latest*.yml
+            release/*.blockmap
+            release/package-size-*.json
+          if-no-files-found: error

.github/workflows/prerelease.yml

@@ -0,0 +1,188 @@
+name: Prerelease
+
+on:
+  push:
+    tags:
+      - 'v*-beta.*'
+      - 'v*-rc.*'
+
+concurrency:
+  group: prerelease-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  quality-gate:
+    permissions:
+      contents: read
+    uses: ./.github/workflows/quality-gate.yml
+
+  package:
+    needs: [quality-gate]
+    permissions:
+      contents: read
+    uses: ./.github/workflows/package-release.yml
+    secrets:
+      CSC_LINK: ${{ secrets.CSC_LINK }}
+      CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+      APPLE_ID: ${{ secrets.APPLE_ID }}
+      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
+
+  release:
+    needs: [package]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Download AppImage
+        uses: actions/download-artifact@v4
+        with:
+          name: appimage
+          path: release
+
+      - name: Download macOS artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: macos
+          path: release
+
+      - name: Download Windows artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: windows
+          path: release
+
+      - 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
+          key: ${{ runner.os }}-${{ runner.arch }}-bun-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-bun-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build launcher runtime artifacts
+        run: make build-launcher
+
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
+
+      - name: Enforce generated launcher workflow
+        run: bash scripts/verify-generated-launcher.sh
+
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
+      - name: Package optional assets bundle
+        run: |
+          tar -czf "release/subminer-assets.tar.gz" \
+            config.example.jsonc \
+            plugin/subminer \
+            plugin/subminer.conf \
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
+            resources/bun/licenses
+
+      - name: Package Bun corresponding source
+        run: bun scripts/package-bun-source.mjs
+
+      - name: Generate checksums
+        run: |
+          shopt -s nullglob
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
+          files+=(release/package-size-*.json)
+          if [ "${#files[@]}" -eq 0 ]; then
+            echo "No release artifacts found for checksum generation."
+            exit 1
+          fi
+          : > release/SHA256SUMS.txt
+          for file in "${files[@]}"; do
+            printf '%s  %s\n' \
+              "$(sha256sum "$file" | awk '{print $1}')" \
+              "${file##*/}" >> release/SHA256SUMS.txt
+          done
+
+      - name: Get version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Verify committed prerelease notes
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: |
+          if [ ! -s release/prerelease-notes.md ]; then
+            echo "::error::release/prerelease-notes.md is missing or empty. Run 'bun run changelog:prerelease-notes --version <version>' locally and commit the file before tagging."
+            exit 1
+          fi
+          if ! bun run changelog:check-prerelease-notes --version "$RELEASE_VERSION"; then
+            echo "::error::release/prerelease-notes.md was not generated for $RELEASE_VERSION. Rerun 'bun run changelog:prerelease-notes --version $RELEASE_VERSION' locally, commit, and retag."
+            exit 1
+          fi
+
+      - name: Publish Prerelease
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: |
+          set -euo pipefail
+
+          shopt -s nullglob
+          artifacts=(
+            release/*.AppImage
+            release/*.dmg
+            release/*.exe
+            release/*.zip
+            release/*.tar.gz
+            release/*.tar.gz.sha256
+            release/latest*.yml
+            release/*.blockmap
+            release/SHA256SUMS.txt
+            release/package-size-*.json
+            dist/launcher/subminer
+            dist/launcher/subminer.cmd
+          )
+
+          if [ "${#artifacts[@]}" -eq 0 ]; then
+            echo "No release artifacts found for upload."
+            exit 1
+          fi
+
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
+            gh release edit "$RELEASE_VERSION" \
+              --draft \
+              --prerelease \
+              --title "$RELEASE_VERSION" \
+              --notes-file release/prerelease-notes.md
+          else
+            gh release create "$RELEASE_VERSION" \
+              --draft \
+              --latest=false \
+              --prerelease \
+              --title "$RELEASE_VERSION" \
+              --notes-file release/prerelease-notes.md
+          fi
+
+          for asset in "${artifacts[@]}"; do
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
+          done
+
+          gh release edit "$RELEASE_VERSION" \
+            --draft=false \
+            --prerelease \
+            --title "$RELEASE_VERSION" \
+            --notes-file release/prerelease-notes.md

.github/workflows/quality-gate.yml

@@ -0,0 +1,145 @@
+name: Quality Gate
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  launcher-runtime:
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - name: Verify native runtime staging
+        run: bun test src/main/runtime/managed-launcher.test.ts
+
+      - name: Verify Windows launcher bootstrap
+        run: bun test src/main/runtime/windows-launcher-bootstrap.test.ts
+
+      - name: Verify native mpv process launch
+        run: bun test src/main/runtime/mpv-process.test.ts
+
+      - name: Verify POSIX launcher bootstrap
+        run: bun test src/main/runtime/posix-launcher-bootstrap.test.ts
+
+  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: |
+          # Lua needs only Ubuntu sources; unrelated runner repositories can be unavailable.
+          test -f /etc/apt/sources.list.d/ubuntu.sources
+          apt_sources=(-o Dir::Etc::sourcelist=sources.list.d/ubuntu.sources -o Dir::Etc::sourceparts=-)
+          sudo apt-get "${apt_sources[@]}" update
+          sudo apt-get "${apt_sources[@]}" install -y lua5.4
+          sudo ln -sf /usr/bin/lua5.4 /usr/local/bin/lua
+          lua -v
+
+      - name: Launcher unit and script suites
+        run: bun run test:launcher:unit:src && bun run test:scripts
+
+      - name: Environment suite
+        run: bun run test:env
+
+      - 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: 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: 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 launcher runtime artifacts
+        run: make build-launcher
+
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
+
+      - name: Enforce generated launcher workflow
+        run: bash scripts/verify-generated-launcher.sh

.github/workflows/release.yml

@@ -4,195 +4,37 @@ on:
   push:
     tags:
       - 'v*'
+      - '!v*-beta.*'
+      - '!v*-rc.*'
 
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
 
-permissions:
-  contents: write
-
 jobs:
   quality-gate:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          submodules: true
+    permissions:
+      contents: read
+    uses: ./.github/workflows/quality-gate.yml
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: 1.3.5
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Cache dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.bun/install/cache
-            node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Test suite (source)
-        run: bun run test:fast
-
-      - 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: Dist smoke suite
-        run: bun run test:smoke:dist
-
-  build-linux:
+  package:
     needs: [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
-            vendor/texthooker-ui/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build AppImage
-        run: bun run build:appimage
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Build unversioned AppImage
-        run: |
-          shopt -s nullglob
-          appimages=(release/SubMiner-*.AppImage)
-          if [ "${#appimages[@]}" -eq 0 ]; then
-            echo "No versioned AppImage found to create unversioned artifact."
-            ls -la release
-            exit 1
-          fi
-          cp "${appimages[0]}" release/SubMiner.AppImage
-
-      - name: Upload AppImage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: appimage
-          path: release/*.AppImage
-
-  build-macos:
-    needs: [quality-gate]
-    runs-on: macos-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
-            vendor/texthooker-ui/node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock', 'vendor/texthooker-ui/package.json') }}
-          restore-keys: |
-            ${{ runner.os }}-bun-
-
-      - name: Validate macOS signing/notarization secrets
-        run: |
-          missing=0
-          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
-            if [ -z "${!name}" ]; then
-              echo "Missing required secret: $name"
-              missing=1
-            fi
-          done
-          if [ "$missing" -ne 0 ]; then
-            echo "Set all required macOS signing/notarization secrets and rerun."
-            exit 1
-          fi
-        env:
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Build texthooker-ui
-        run: |
-          cd vendor/texthooker-ui
-          bun install
-          bun run build
-
-      - name: Build signed + notarized macOS artifacts
-        run: bun run build:mac
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CSC_LINK: ${{ secrets.CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-
-      - name: Upload macOS artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: macos
-          path: |
-            release/*.dmg
-            release/*.zip
+    permissions:
+      contents: read
+    uses: ./.github/workflows/package-release.yml
+    secrets:
+      CSC_LINK: ${{ secrets.CSC_LINK }}
+      CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+      APPLE_ID: ${{ secrets.APPLE_ID }}
+      APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+      APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+      SUBMINER_TMDB_API_KEY: ${{ secrets.SUBMINER_TMDB_API_KEY }}
 
   release:
-    needs: [build-linux, build-macos]
+    needs: [package]
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -211,6 +53,12 @@ jobs:
           name: macos
           path: release
 
+      - name: Download Windows artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: windows
+          path: release
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
@@ -229,112 +77,103 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build Bun subminer wrapper
+      - name: Build launcher runtime artifacts
         run: make build-launcher
 
-      - name: Verify Bun subminer wrapper
-        run: dist/launcher/subminer --help >/dev/null
+      - name: Smoke launcher bundle
+        run: bun dist/launcher/subminer.js --help >/dev/null
 
       - name: Enforce generated launcher workflow
         run: bash scripts/verify-generated-launcher.sh
 
+      - name: Verify generated config examples
+        run: bun run verify:config-example
+
       - name: Package optional assets bundle
         run: |
           tar -czf "release/subminer-assets.tar.gz" \
             config.example.jsonc \
             plugin/subminer \
             plugin/subminer.conf \
-            assets/themes/subminer.rasi
+            assets/themes/subminer.rasi \
+            assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer \
+            resources/bun/licenses
+
+      - name: Package Bun corresponding source
+        run: bun scripts/package-bun-source.mjs
 
       - name: Generate checksums
         run: |
           shopt -s nullglob
-          files=(release/*.AppImage release/*.dmg release/*.zip release/*.tar.gz dist/launcher/subminer)
+          files=(release/*.AppImage release/*.dmg release/*.exe release/*.zip release/*.tar.gz release/latest*.yml release/*.blockmap dist/launcher/subminer dist/launcher/subminer.cmd)
+          files+=(release/package-size-*.json)
           if [ "${#files[@]}" -eq 0 ]; then
             echo "No release artifacts found for checksum generation."
             exit 1
           fi
-          sha256sum "${files[@]}" > release/SHA256SUMS.txt
+          : > release/SHA256SUMS.txt
+          for file in "${files[@]}"; do
+            printf '%s  %s\n' \
+              "$(sha256sum "$file" | awk '{print $1}')" \
+              "${file##*/}" >> release/SHA256SUMS.txt
+          done
 
       - name: Get version from tag
         id: version
-        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
 
-      - name: Generate changelog
-        id: changelog
+      - name: Guard against pending changelog fragments
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
-          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
-          if [ -n "$PREV_TAG" ]; then
-            CHANGES=$(git log --pretty=format:"- %s" ${PREV_TAG}..HEAD)
-          else
-            COMMIT_COUNT=$(git rev-list --count HEAD)
-            if [ "$COMMIT_COUNT" -gt 10 ]; then
-              CHANGES=$(git log --pretty=format:"- %s" HEAD~10..HEAD)
-            else
-              CHANGES=$(git log --pretty=format:"- %s")
-            fi
+          if find changes -maxdepth 1 -name '*.md' -not -name README.md -print -quit | grep -q .; then
+            echo "::error::Pending changelog fragments detected. Run 'bun run changelog:build --version $RELEASE_VERSION' locally and commit the polished CHANGELOG.md before tagging. CI no longer auto-builds the changelog because the polish step requires the local 'claude' CLI."
+            exit 1
           fi
-          echo "CHANGES<<EOF" >> $GITHUB_OUTPUT
-          echo "$CHANGES" >> $GITHUB_OUTPUT
-          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Verify changelog is ready for tagged release
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:check --version "$RELEASE_VERSION"
+
+      - name: Generate release notes from changelog
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: bun run changelog:release-notes --version "$RELEASE_VERSION"
 
       - name: Publish Release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
         run: |
           set -euo pipefail
 
-          cat > release-body.md <<'EOF'
-          ## Changes
-          ${{ steps.changelog.outputs.CHANGES }}
-
-          ## Installation
-
-          ### AppImage (Recommended)
-          1. Download the AppImage below
-          2. Make it executable: `chmod +x SubMiner.AppImage`
-          3. Run: `./SubMiner.AppImage`
-
-          ### macOS
-          1. Download `subminer-*.dmg`
-          2. Open the DMG and drag `SubMiner.app` into `/Applications`
-          3. If needed, use the ZIP artifact as an alternative
-
-          ### Manual Installation
-          See the [README](https://github.com/${{ github.repository }}#installation) for manual installation instructions.
-
-          ### Optional Assets (config example + mpv plugin + rofi theme)
-          1. Download `subminer-assets.tar.gz`
-          2. Extract and copy `config.example.jsonc` to `~/.config/SubMiner/config.jsonc`
-          3. Copy `plugin/subminer/` directory contents to `~/.config/mpv/scripts/`
-          4. Copy `plugin/subminer.conf` to `~/.config/mpv/script-opts/`
-          5. Copy `assets/themes/subminer.rasi` to:
-             - Linux: `~/.local/share/SubMiner/themes/subminer.rasi`
-             - macOS: `~/Library/Application Support/SubMiner/themes/subminer.rasi`
-
-          Note: the `subminer` wrapper script uses Bun (`#!/usr/bin/env bun`), so `bun` must be installed and on `PATH`.
-          EOF
-
-          if gh release view "${{ steps.version.outputs.VERSION }}" >/dev/null 2>&1; then
-            gh release edit "${{ steps.version.outputs.VERSION }}" \
-              --title "${{ steps.version.outputs.VERSION }}" \
-              --notes-file release-body.md \
-              --prerelease false
+          if gh release view "$RELEASE_VERSION" >/dev/null 2>&1; then
+            # Do not pass the prerelease flag here; gh defaults to a normal release.
+            gh release edit "$RELEASE_VERSION" \
+              --draft=false \
+              --title "$RELEASE_VERSION" \
+              --notes-file release/release-notes.md
           else
-            gh release create "${{ steps.version.outputs.VERSION }}" \
-              --title "${{ steps.version.outputs.VERSION }}" \
-              --notes-file release-body.md \
-              --prerelease false
+            gh release create "$RELEASE_VERSION" \
+              --title "$RELEASE_VERSION" \
+              --notes-file release/release-notes.md
           fi
 
           shopt -s nullglob
           artifacts=(
             release/*.AppImage
             release/*.dmg
+            release/*.exe
             release/*.zip
             release/*.tar.gz
+            release/*.tar.gz.sha256
+            release/latest*.yml
+            release/*.blockmap
             release/SHA256SUMS.txt
+            release/package-size-*.json
             dist/launcher/subminer
+            dist/launcher/subminer.cmd
           )
 
           if [ "${#artifacts[@]}" -eq 0 ]; then
@@ -343,5 +182,136 @@ jobs:
           fi
 
           for asset in "${artifacts[@]}"; do
-            gh release upload "${{ steps.version.outputs.VERSION }}" "$asset" --clobber
+            gh release upload "$RELEASE_VERSION" "$asset" --clobber
           done
+
+  aur-publish:
+    needs: [release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Get version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+
+      - name: Check AUR publish prerequisites
+        id: aur_prereqs
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          if [ -z "${AUR_SSH_PRIVATE_KEY}" ]; then
+            echo "::warning::Missing AUR_SSH_PRIVATE_KEY; skipping automated AUR publish."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "skip=false" >> "$GITHUB_OUTPUT"
+
+      - name: Configure SSH for AUR
+        id: aur_ssh
+        if: steps.aur_prereqs.outputs.skip != 'true'
+        env:
+          AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          if install -dm700 ~/.ssh \
+            && printf '%s\n' "${AUR_SSH_PRIVATE_KEY}" > ~/.ssh/aur \
+            && chmod 600 ~/.ssh/aur \
+            && ssh-keyscan aur.archlinux.org >> ~/.ssh/known_hosts \
+            && chmod 644 ~/.ssh/known_hosts; then
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "::warning::Unable to configure SSH for AUR; skipping automated AUR publish."
+          echo "skip=true" >> "$GITHUB_OUTPUT"
+
+      - name: Clone AUR repo
+        id: aur_clone
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true'
+        env:
+          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+        run: |
+          set -euo pipefail
+          attempts=3
+          for attempt in $(seq 1 "$attempts"); do
+            if git clone ssh://aur@aur.archlinux.org/subminer-bin.git aur-subminer-bin; then
+              echo "skip=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+
+            rm -rf aur-subminer-bin
+
+            if [ "$attempt" -lt "$attempts" ]; then
+              sleep $((attempt * 15))
+            fi
+          done
+
+          echo "::warning::Unable to clone subminer-bin from AUR after ${attempts} attempts; skipping automated AUR publish."
+          echo "skip=true" >> "$GITHUB_OUTPUT"
+
+      - name: Download release assets for AUR
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: |
+          set -euo pipefail
+          version="$RELEASE_VERSION"
+          install -dm755 .tmp/aur-release-assets
+          gh release download "$version" \
+            --dir .tmp/aur-release-assets \
+            --pattern "SubMiner-${version#v}.AppImage" \
+            --pattern "subminer" \
+            --pattern "subminer-assets.tar.gz"
+
+      - name: Update AUR packaging metadata
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        env:
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: |
+          set -euo pipefail
+          version_no_v="$RELEASE_VERSION"
+          version_no_v="${version_no_v#v}"
+          cp packaging/aur/subminer-bin/PKGBUILD aur-subminer-bin/PKGBUILD
+          cp packaging/aur/subminer-bin/.SRCINFO aur-subminer-bin/.SRCINFO
+          bash scripts/update-aur-package.sh \
+            --pkg-dir aur-subminer-bin \
+            --version "$RELEASE_VERSION" \
+            --appimage ".tmp/aur-release-assets/SubMiner-${version_no_v}.AppImage" \
+            --wrapper ".tmp/aur-release-assets/subminer" \
+            --assets ".tmp/aur-release-assets/subminer-assets.tar.gz"
+
+      - name: Commit and push AUR update
+        if: steps.aur_prereqs.outputs.skip != 'true' && steps.aur_ssh.outputs.skip != 'true' && steps.aur_clone.outputs.skip != 'true'
+        working-directory: aur-subminer-bin
+        env:
+          GIT_SSH_COMMAND: ssh -i ~/.ssh/aur -o IdentitiesOnly=yes
+          RELEASE_VERSION: ${{ steps.version.outputs.VERSION }}
+        run: |
+          set -euo pipefail
+          if git diff --quiet -- PKGBUILD .SRCINFO; then
+            echo "AUR packaging already up to date."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add PKGBUILD .SRCINFO
+          git commit -m "Update to $RELEASE_VERSION"
+
+          attempts=3
+          for attempt in $(seq 1 "$attempts"); do
+            if git push origin HEAD:master; then
+              exit 0
+            fi
+
+            if [ "$attempt" -lt "$attempts" ]; then
+              sleep $((attempt * 15))
+            fi
+          done
+
+          echo "::warning::Unable to push the AUR update after ${attempts} attempts; GitHub release is published, but subminer-bin needs manual follow-up."

.gitignore

@@ -1,13 +1,24 @@
 # Dependencies
 node_modules/
+/package-lock.json
+
+# Superpowers brainstorming
+.superpowers/
 
 # Electron build output
 out/
 dist/
-release/
+release/*
+!release/
+!release/release-notes.md
+!release/prerelease-notes.md
+build/yomitan/
+coverage/
 
 # Launcher build artifact (produced by make build-launcher)
 /subminer
+/main-entry.js
+/main-entry.js.map
 
 # Logs
 *.log
@@ -21,9 +32,7 @@ Thumbs.db
 .idea/
 *.swp
 *.swo
-**/CLAUDE.md
 environment.toml
-**/CLAUDE.md
 .env
 .vscode/*
 
@@ -34,5 +43,27 @@ docs/.vitepress/cache/
 docs/.vitepress/dist/
 tests/*
 .worktrees/
+.tmp/
 .codex/*
 .agents/*
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/subminer-change-verification/
+!.agents/skills/subminer-release/
+!.agents/skills/subminer-scrum-master/
+.agents/skills/subminer-change-verification/*
+!.agents/skills/subminer-change-verification/SKILL.md
+!.agents/skills/subminer-change-verification/scripts/
+.agents/skills/subminer-change-verification/scripts/*
+!.agents/skills/subminer-change-verification/scripts/classify_subminer_diff.sh
+!.agents/skills/subminer-change-verification/scripts/verify_subminer_change.sh
+.agents/skills/subminer-release/*
+!.agents/skills/subminer-release/SKILL.md
+.agents/skills/subminer-scrum-master/*
+!.agents/skills/subminer-scrum-master/SKILL.md
+favicon.png
+.claude/*
+!stats/public/favicon.png
+
+# Browser-automation session artifacts (page snapshots, console logs, downloads)
+.playwright-mcp/

.gitmodules

@@ -5,6 +5,6 @@
 [submodule "vendor/yomitan-jlpt-vocab"]
 	path = vendor/yomitan-jlpt-vocab
 	url = https://github.com/stephenmk/yomitan-jlpt-vocab
-[submodule "yomitan-jlpt-vocab"]
-	path = vendor/yomitan-jlpt-vocab
-	url = https://github.com/stephenmk/yomitan-jlpt-vocab
+[submodule "vendor/subminer-yomitan"]
+	path = vendor/subminer-yomitan
+	url = https://github.com/ksyasuda/subminer-yomitan

.prettierignore

@@ -4,3 +4,4 @@ release
 coverage
 vendor
 *.log
+src/core/services/tokenizer/__fixtures__/golden/*.json

AGENTS.md

@@ -1,29 +1,83 @@
-<!-- BACKLOG.MD MCP GUIDELINES START -->
+# AGENTS.md
 
-<CRITICAL_INSTRUCTION>
+## Internal Docs
 
-## BACKLOG WORKFLOW INSTRUCTIONS
+Start here, then leave this file.
 
-This project uses Backlog.md MCP for all task and project management activities.
+- Internal system of record: [`docs/README.md`](./docs/README.md)
+- Architecture map: [`docs/architecture/README.md`](./docs/architecture/README.md)
+- Workflow map: [`docs/workflow/README.md`](./docs/workflow/README.md)
+- Verification lanes: [`docs/workflow/verification.md`](./docs/workflow/verification.md)
+- Knowledge-base rules: [`docs/knowledge-base/README.md`](./docs/knowledge-base/README.md)
+- Release guide: [`docs/RELEASING.md`](./docs/RELEASING.md)
 
-**CRITICAL GUIDANCE**
+`docs-site/` is user-facing. Do not treat it as the canonical internal source of truth.
 
-- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
-- If your client only supports tools or the above request fails, call `backlog.get_workflow_overview()` tool to load the tool-oriented overview (it lists the matching guide tools).
+`CLAUDE.md` is a symlink to this file; there is one project instruction file, not two.
 
-- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
-- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
-- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work
+## Quick Start
 
-These guides cover:
+- Init workspace: `git submodule update --init --recursive`
+- Install deps: `make deps` or `bun install` plus `(cd vendor/texthooker-ui && bun install --frozen-lockfile)`
+- Fast dev loop: `make dev-watch`
+- Full local run: `bun run dev`
+- Verbose Electron debug: `electron . --start --dev --log-level debug`
 
-- Decision framework for when to create tasks
-- Search-first workflow to avoid duplicates
-- Links to detailed guides for task creation, execution, and finalization
-- MCP tools reference
+## Build / Test
 
-You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.
+- Runtime/package manager: Bun; use the version pinned by `package.json`.
+- Follow [`docs/workflow/verification.md`](./docs/workflow/verification.md) and start with the cheapest sufficient lane.
+- Full handoff gate for substantial changes:
+  `bun run typecheck`
+  `bun run test:fast`
+  `bun run test:env`
+  `bun run build`
+  `bun run test:smoke:dist`
+- If `docs-site/` changed, also run:
+  `bun run docs:test`
+  `bun run docs:build`
+- Prefer `make pretty` and `bun run format:check:src`
 
-</CRITICAL_INSTRUCTION>
+## Change-Specific Checks
 
-<!-- BACKLOG.MD MCP GUIDELINES END -->
+- Config/schema/defaults: `bun run test:config`; if template/defaults changed, `bun run generate:config-example`
+- Launcher/plugin: `bun run test:launcher` or `bun run test:env`
+- Runtime-compat / dist-sensitive: `bun run test:runtime:compat`
+- Stats dashboard UI (`stats/`): `bun run test:stats`
+- Build/release scripts (`scripts/**`): `bun run test:scripts`
+- Internal docs, `AGENTS.md`, or repo skills: `bun run test:docs:kb`
+- User-facing `docs-site/`: `bun run docs:test`, then `bun run docs:build`
+- macOS mpv window helper: `bun test scripts/get-mpv-window-macos.test.ts`
+- Test lanes are directory-discovered via `scripts/test-lanes.ts`; never hand-list test files in `package.json`
+
+## Docs Upkeep
+
+- Docs ship with the change, not after. If a change alters behavior, defaults, flags, shortcuts, ports, or APIs, update the matching docs in the same PR. Touching code without reconciling its docs is an incomplete change.
+- Source of truth for config defaults is the generated `config.example.jsonc`. Never write a default value into prose you didn't read from it, and don't restate the same default across multiple docs; cite/link to one place so there's a single thing to update.
+- Trigger map (touch left → update right):
+  - `src/config/definitions/**` (schema/defaults/template) → `bun run generate:config-example`, then reconcile `docs-site/configuration.md` + any feature doc that cites that default
+  - shortcuts/keybindings (`shortcuts.*`, `keybindings`, `stats.*Key`, `subtitleSidebar.toggleKey`, controller bindings) → `docs-site/shortcuts.md`
+  - CLI flags/subcommands (`src/cli/args.ts`, `launcher/**`) → `docs-site/usage.md` + relevant integration doc
+  - feature behavior (anki / jellyfin / jimaku / anilist / youtube / immersion / stats / websocket / sidebar / character-dictionary / annotations) → matching `docs-site/<feature>.md`
+  - architecture / IPC / workflow / internal process → internal `docs/` (system of record)
+  - feature set / requirements / install flow → `README.md`
+- Removing or renaming a config key: grep `docs-site/` and `docs/` for the old key and any value it documented; legacy/hidden keys (`LEGACY_HIDDEN_CONFIG_PATHS`) should not appear in user docs as current settings.
+- Verify after doc edits: `bun run verify:config-example` (if config touched), `bun run docs:test`, `bun run docs:build`.
+
+## Sensitive Files
+
+- Launcher source of truth: `launcher/*.ts`
+- Generated launcher artifact: `dist/launcher/subminer`; never hand-edit it
+- Repo-root `./subminer` is stale; do not revive it
+- `bun run build` rebuilds bundled Yomitan from `vendor/subminer-yomitan`
+- Do not change signing/packaging identifiers unless the task explicitly requires it
+
+## Release / PR Notes
+
+- User-visible PRs need reconciled current-outcome fragment(s) in `changes/*.md`. Format and rules live in [`changes/README.md`](./changes/README.md) (`type` + `area` keys required; inspect existing same-PR fragments, then update/remove stale bullets or add only genuinely separate outcomes; apply the `skip-changelog` label to opt out).
+- User-visible docs changes get a `type: docs` fragment
+- CI enforces `bun run changelog:lint` and `bun run changelog:pr-check`
+- PR review helpers:
+  - `gh pr view --json number,title --jq '"PR #\\(.number): \\(.title)"'`
+  - `gh api repos/:owner/:repo/pulls/<num>/comments --paginate`
+- For CI debugging, inspect runs with `gh run list/view`; rerun or fix only within the requested scope.

CLAUDE.md

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

Makefile

@@ -1,10 +1,11 @@
-.PHONY: help deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-plugin uninstall uninstall-linux uninstall-macos print-dirs pretty ensure-bun generate-config generate-example-config docs-dev docs docs-preview docs-watch dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop
+.PHONY: help submodules deps build build-launcher install build-linux build-macos build-macos-unsigned clean install-linux install-macos install-windows uninstall uninstall-linux uninstall-macos uninstall-windows print-dirs pretty lint ensure-bun generate-config generate-example-config dev-start dev-start-macos dev-watch dev-watch-macos dev-toggle dev-stop docs-test docs-build docs-build-versioned docs-dev
 
 APP_NAME := subminer
 THEME_SOURCE := assets/themes/subminer.rasi
+THUMBNAILER_SOURCE := assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer
 LAUNCHER_OUT := dist/launcher/$(APP_NAME)
 THEME_FILE := subminer.rasi
-PLUGIN_CONF := plugin/subminer.conf
+THUMBNAILER_FILE := subminer-ffmpegthumbnailer.thumbnailer
 
 # Default install prefix for the wrapper script.
 PREFIX ?= $(HOME)/.local
@@ -20,15 +21,11 @@ MACOS_DATA_DIR ?= $(HOME)/Library/Application Support/SubMiner
 MACOS_APP_DIR ?= $(HOME)/Applications
 MACOS_APP_DEST ?= $(MACOS_APP_DIR)/SubMiner.app
 
-# mpv plugin install directories.
-MPV_CONFIG_DIR ?= $(HOME)/.config/mpv
-MPV_SCRIPTS_DIR ?= $(MPV_CONFIG_DIR)/scripts
-MPV_SCRIPT_OPTS_DIR ?= $(MPV_CONFIG_DIR)/script-opts
-
 # If building from source, the AppImage will typically land in release/.
-APPIMAGE_SRC := $(firstword $(wildcard release/SubMiner-*.AppImage))
-MACOS_APP_SRC := $(firstword $(wildcard release/*.app release/*/*.app))
-MACOS_ZIP_SRC := $(firstword $(wildcard release/SubMiner-*.zip))
+APPIMAGE_SRC = $(firstword $(wildcard release/SubMiner-*.AppImage))
+MACOS_APP_SRC = $(firstword $(wildcard release/*.app release/*/*.app))
+MACOS_ZIP_SRC = $(firstword $(wildcard release/SubMiner-*.zip))
+PRERELEASE_NOTES := release/prerelease-notes.md
 
 UNAME_S := $(shell uname -s 2>/dev/null || echo Unknown)
 ifeq ($(OS),Windows_NT)
@@ -41,6 +38,17 @@ else
 PLATFORM := unknown
 endif
 
+WINDOWS_APPDATA ?= $(if $(APPDATA),$(subst \,/,$(APPDATA)),$(HOME)/AppData/Roaming)
+
+# mpv plugin install directories.
+ifeq ($(PLATFORM),windows)
+MPV_CONFIG_DIR ?= $(WINDOWS_APPDATA)/mpv
+else
+MPV_CONFIG_DIR ?= $(HOME)/.config/mpv
+endif
+MPV_SCRIPTS_DIR ?= $(MPV_CONFIG_DIR)/scripts
+MPV_SCRIPT_OPTS_DIR ?= $(MPV_CONFIG_DIR)/script-opts
+
 help:
 	@printf '%s\n' \
 		"Targets:" \
@@ -56,20 +64,23 @@ help:
 		"  dev-watch-macos  Start watch loop with forced macOS tracker backend" \
 		"  dev-toggle       Toggle overlay in a running local Electron app" \
 		"  dev-stop         Stop a running local Electron app" \
-		"  docs-dev         Run VitePress docs dev server" \
-		"  docs-watch  Run VitePress docs dev + Backlog browser together" \
-		"  docs            Build VitePress static docs" \
-		"  docs-preview     Preview built VitePress docs" \
+		"  docs-test        Run docs tests" \
+		"  docs-build       Build the docs site" \
+		"  docs-build-versioned Build production versioned docs site" \
+		"  docs-dev         Start the docs dev server" \
 		"  install-linux    Install Linux wrapper/theme/app artifacts" \
 		"  install-macos    Install macOS wrapper/theme/app artifacts" \
-		"  install-plugin   Install mpv Lua plugin and plugin config" \
+		"  install-windows  Print Windows packaging/install guidance" \
 		"  generate-config  Generate ~/.config/SubMiner/config.jsonc from centralized defaults" \
 		"" \
 		"Other targets:" \
-		"  deps             Install JS dependencies (root + texthooker-ui)" \
+		"  submodules       Initialize/update git submodules" \
+		"  deps             Initialize submodules and install JS dependencies (root + stats + texthooker-ui)" \
 		"  uninstall-linux  Remove Linux install artifacts" \
 		"  uninstall-macos  Remove macOS install artifacts" \
+		"  uninstall-windows Remove Windows mpv plugin artifacts" \
 		"  print-dirs       Show resolved install locations" \
+		"  lint             Lint stats (format check)" \
 		"" \
 		"Variables:" \
 		"  PREFIX=...        Override wrapper install prefix (default: $$HOME/.local)" \
@@ -78,7 +89,7 @@ help:
 		"  LINUX_DATA_DIR=... Override Linux app data dir" \
 		"  MACOS_DATA_DIR=... Override macOS app data dir" \
 		"  MACOS_APP_DIR=...  Override macOS app install dir (default: $$HOME/Applications)" \
-		"  MPV_CONFIG_DIR=... Override mpv config dir (default: $$HOME/.config/mpv)"
+		"  MPV_CONFIG_DIR=... Override mpv config dir (default: $$HOME/.config/mpv or %APPDATA%/mpv on Windows)"
 
 print-dirs:
 	@printf '%s\n' \
@@ -89,26 +100,38 @@ print-dirs:
 		"MACOS_DATA_DIR=$(MACOS_DATA_DIR)" \
 		"MACOS_APP_DIR=$(MACOS_APP_DIR)" \
 		"MACOS_APP_DEST=$(MACOS_APP_DEST)" \
+		"WINDOWS_APPDATA=$(WINDOWS_APPDATA)" \
+		"MPV_CONFIG_DIR=$(MPV_CONFIG_DIR)" \
+		"MPV_SCRIPTS_DIR=$(MPV_SCRIPTS_DIR)" \
+		"MPV_SCRIPT_OPTS_DIR=$(MPV_SCRIPT_OPTS_DIR)" \
 		"APPIMAGE_SRC=$(APPIMAGE_SRC)" \
 		"MACOS_APP_SRC=$(MACOS_APP_SRC)" \
 		"MACOS_ZIP_SRC=$(MACOS_ZIP_SRC)"
 
-deps:
-	@$(MAKE) --no-print-directory ensure-bun
+submodules:
+	@git submodule update --init --recursive
+
+deps: submodules ensure-bun
 	@bun install
+	@cd stats && bun install --frozen-lockfile
 	@cd vendor/texthooker-ui && bun install --frozen-lockfile
 
 ensure-bun:
 	@command -v bun >/dev/null 2>&1 || { printf '%s\n' "[ERROR] bun not found"; exit 1; }
 
 pretty: ensure-bun
-	@bun run format
+	@bun run format:src
+	@bun run format:stats
+
+lint: ensure-bun
+	@bun run lint:stats
 
 build:
 	@printf '%s\n' "[INFO] Detected platform: $(PLATFORM)"
 	@case "$(PLATFORM)" in \
 		linux) $(MAKE) --no-print-directory build-linux ;; \
 		macos) $(MAKE) --no-print-directory build-macos ;; \
+		windows) printf '%s\n' "[INFO] Windows builds run via: bun run build:win" ;; \
 		*) printf '%s\n' "[ERROR] Unsupported OS for this Makefile target: $(PLATFORM)"; exit 1 ;; \
 	esac
 
@@ -117,6 +140,7 @@ install:
 	@case "$(PLATFORM)" in \
 		linux) $(MAKE) --no-print-directory install-linux ;; \
 		macos) $(MAKE) --no-print-directory install-macos ;; \
+		windows) $(MAKE) --no-print-directory install-windows ;; \
 		*) printf '%s\n' "[ERROR] Unsupported OS for this Makefile target: $(PLATFORM)"; exit 1 ;; \
 	esac
 
@@ -136,18 +160,20 @@ build-macos-unsigned: deps
 	@bun run build:mac:unsigned
 
 build-launcher:
-	@printf '%s\n' "[INFO] Bundling launcher script"
-	@install -d "$(dir $(LAUNCHER_OUT))"
-	@bun build ./launcher/main.ts --target=bun --packages=bundle --outfile="$(LAUNCHER_OUT)"
-	@if ! head -1 "$(LAUNCHER_OUT)" | grep -q '^#!/usr/bin/env bun'; then \
-		{ printf '#!/usr/bin/env bun\n'; cat "$(LAUNCHER_OUT)"; } > "$(LAUNCHER_OUT).tmp" && mv "$(LAUNCHER_OUT).tmp" "$(LAUNCHER_OUT)"; \
-	fi
-	@chmod +x "$(LAUNCHER_OUT)"
-	@printf '%s\n' "[INFO] Launcher artifact: $(LAUNCHER_OUT)"
+	@printf '%s\n' "[INFO] Building launcher runtime artifacts"
+	@bun run build:launcher
 
 clean:
 	@printf '%s\n' "[INFO] Removing build artifacts"
-	@rm -rf dist release
+	@if [ -f "$(PRERELEASE_NOTES)" ]; then \
+		PRERELEASE_NOTES_BACKUP="$$(mktemp -t subminer-prerelease-notes.XXXXXX)" && \
+		cp "$(PRERELEASE_NOTES)" "$$PRERELEASE_NOTES_BACKUP" && \
+		rm -rf dist release && \
+		install -d release && \
+		mv "$$PRERELEASE_NOTES_BACKUP" "$(PRERELEASE_NOTES)"; \
+	else \
+		rm -rf dist release; \
+	fi
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 
 generate-config: ensure-bun
@@ -155,21 +181,8 @@ generate-config: ensure-bun
 	@bun run electron . --generate-config
 
 generate-example-config: ensure-bun
-	@bun run build
 	@bun run generate:config-example
 
-docs-dev: ensure-bun
-	@bun run docs:dev
-
-docs-watch: ensure-bun
-	@bun run docs:watch
-
-docs: ensure-bun
-	@bun run docs:build
-
-docs-preview: ensure-bun
-	@bun run docs:preview
-
 dev-start: ensure-bun
 	@bun run build
 	@bun run electron . --start
@@ -190,20 +203,36 @@ dev-toggle: ensure-bun
 dev-stop: ensure-bun
 	@bun run electron . --stop
 
+docs-test: ensure-bun
+	@bun run docs:test
+
+docs-build: ensure-bun
+	@bun run docs:build
+
+docs-build-versioned: ensure-bun
+	@bun run docs:build:versioned
+
+docs-dev: ensure-bun
+	@bun run docs:dev
+
 
 install-linux: build-launcher
-	@printf '%s\n' "[INFO] Installing Linux wrapper/theme artifacts"
+	@printf '%s\n' "[INFO] Installing Linux wrapper/support artifacts"
 	@install -d "$(BINDIR)"
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(LINUX_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@install -d "$(LINUX_DATA_DIR)/thumbnailers"
+	@install -m 0644 "./$(THUMBNAILER_SOURCE)" "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
+	@install -d "$(LINUX_DATA_DIR)/plugin/subminer"
+	@cp -R ./plugin/subminer/. "$(LINUX_DATA_DIR)/plugin/subminer/"
 	@if [ -n "$(APPIMAGE_SRC)" ]; then \
 		install -m 0755 "$(APPIMAGE_SRC)" "$(BINDIR)/SubMiner.AppImage"; \
 	else \
 		printf '%s\n' "[WARN] No release/SubMiner-*.AppImage found; skipping AppImage install"; \
 		printf '%s\n' "       Build one with: make build"; \
 	fi
-	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
 
 install-macos: build-launcher
 	@printf '%s\n' "[INFO] Installing macOS wrapper/theme/app artifacts"
@@ -211,6 +240,8 @@ install-macos: build-launcher
 	@install -m 0755 "$(LAUNCHER_OUT)" "$(BINDIR)/$(APP_NAME)"
 	@install -d "$(MACOS_DATA_DIR)/themes"
 	@install -m 0644 "./$(THEME_SOURCE)" "$(MACOS_DATA_DIR)/themes/$(THEME_FILE)"
+	@install -d "$(MACOS_DATA_DIR)/plugin/subminer"
+	@cp -R ./plugin/subminer/. "$(MACOS_DATA_DIR)/plugin/subminer/"
 	@install -d "$(MACOS_APP_DIR)"
 	@if [ -n "$(MACOS_APP_SRC)" ]; then \
 		rm -rf "$(MACOS_APP_DEST)"; \
@@ -226,26 +257,34 @@ install-macos: build-launcher
 	fi
 	@printf '%s\n' "Installed to:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_APP_DEST)"
 
-install-plugin:
-	@printf '%s\n' "[INFO] Installing mpv plugin artifacts"
-	@install -d "$(MPV_SCRIPTS_DIR)"
-	@rm -f "$(MPV_SCRIPTS_DIR)/subminer.lua"
-	@install -d "$(MPV_SCRIPTS_DIR)/subminer"
-	@install -d "$(MPV_SCRIPT_OPTS_DIR)"
-	@cp -R ./plugin/subminer/. "$(MPV_SCRIPTS_DIR)/subminer/"
-	@install -m 0644 "./$(PLUGIN_CONF)" "$(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
-	@printf '%s\n' "Installed to:" "  $(MPV_SCRIPTS_DIR)/subminer/main.lua" "  $(MPV_SCRIPTS_DIR)/subminer/" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
+install-windows:
+	@printf '%s\n' "[INFO] Windows builds run via: bun run build:win"
+	@printf '%s\n' "[INFO] SubMiner-managed mpv launches inject the bundled runtime plugin; no global mpv plugin install is needed."
 
-# Uninstall behavior kept unchanged by default.
-uninstall: uninstall-linux
+uninstall:
+	@printf '%s\n' "[INFO] Detected platform: $(PLATFORM)"
+	@case "$(PLATFORM)" in \
+		linux) $(MAKE) --no-print-directory uninstall-linux ;; \
+		macos) $(MAKE) --no-print-directory uninstall-macos ;; \
+		windows) $(MAKE) --no-print-directory uninstall-windows ;; \
+		*) printf '%s\n' "[ERROR] Unsupported OS for this Makefile target: $(PLATFORM)"; exit 1 ;; \
+	esac
 
 uninstall-linux:
 	@rm -f "$(BINDIR)/subminer" "$(BINDIR)/SubMiner.AppImage"
 	@rm -f "$(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)"
+	@rm -f "$(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)"
+	@rm -rf "$(LINUX_DATA_DIR)/plugin/subminer"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(BINDIR)/SubMiner.AppImage" "  $(LINUX_DATA_DIR)/themes/$(THEME_FILE)" "  $(LINUX_DATA_DIR)/thumbnailers/$(THUMBNAILER_FILE)" "  $(LINUX_DATA_DIR)/plugin/subminer"
 
 uninstall-macos:
 	@rm -f "$(BINDIR)/subminer"
 	@rm -f "$(MACOS_DATA_DIR)/themes/$(THEME_FILE)"
+	@rm -rf "$(MACOS_DATA_DIR)/plugin/subminer"
 	@rm -rf "$(MACOS_APP_DEST)"
-	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_APP_DEST)"
+	@printf '%s\n' "Removed:" "  $(BINDIR)/subminer" "  $(MACOS_DATA_DIR)/themes/$(THEME_FILE)" "  $(MACOS_DATA_DIR)/plugin/subminer" "  $(MACOS_APP_DEST)"
+
+uninstall-windows:
+	@rm -rf "$(MPV_SCRIPTS_DIR)/subminer"
+	@rm -f "$(MPV_SCRIPTS_DIR)/subminer.lua" "$(MPV_SCRIPTS_DIR)/subminer-loader.lua" "$(MPV_SCRIPT_OPTS_DIR)/subminer.conf"
+	@printf '%s\n' "Removed:" "  $(MPV_SCRIPTS_DIR)/subminer" "  $(MPV_SCRIPT_OPTS_DIR)/subminer.conf"

README.md

@@ -1,105 +1,285 @@
 <div align="center">
-  <img src="assets/SubMiner.png" width="169" alt="SubMiner logo">
-  <h1>SubMiner</h1>
-  <strong>Look up words, mine to Anki, and enrich cards with context — without leaving mpv.</strong>
-  <br /><br />
 
-[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![Linux](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-informational)]()
-[![Docs](https://img.shields.io/badge/docs-docs.subminer.moe-blueviolet)](https://docs.subminer.moe)
+<img src="assets/SubMiner.png" width="160" alt="SubMiner logo">
+
+# SubMiner
+
+Integrates Yomitan and mpv - on-screen lookups, mine to Anki, and track immersion without leaving the player
+
+[Installation](#quick-start) · [Requirements](#requirements) · [Usage](https://docs.subminer.moe/usage) · [Documentation](https://docs.subminer.moe)
+
+[![Downloads](https://img.shields.io/github/downloads/ksyasuda/SubMiner/total?style=flat-square&color=1a1a2e)](https://github.com/ksyasuda/SubMiner/releases)
+[![Release](https://img.shields.io/github/v/release/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://github.com/ksyasuda/SubMiner/releases/latest)
+[![AUR](https://img.shields.io/aur/version/subminer-bin?style=flat-square&color=1a1a2e)](https://aur.archlinux.org/packages/subminer-bin)
+[![Platform](https://img.shields.io/badge/platform-Linux%20·%20macOS%20·%20Windows-1a1a2e?style=flat-square)](https://github.com/ksyasuda/SubMiner)
+[![License](https://img.shields.io/github/license/ksyasuda/SubMiner?style=flat-square&color=1a1a2e)](https://www.gnu.org/licenses/gpl-3.0)
+[![TypeScript](https://img.shields.io/badge/TypeScript-1a1a2e?style=flat-square&logo=typescript&logoColor=3178c6)](https://www.typescriptlang.org)
+
+[![SubMiner demo](./assets/minecard.webp)](https://github.com/user-attachments/assets/7abab8a9-4e4e-4f06-9f3c-9783e15a3807)
 
 </div>
 
-<br />
+## Features
+
+### Dictionary Lookups
+
+Hover over any word and trigger a lookup to get the full Yomitan popup - definitions, pitch accent, and frequency data - without ever leaving mpv.
 
 <div align="center">
-
-[![SubMiner demo (Animated preview)](./assets/minecard.webp)](./assets/minecard.mp4)
-
+  <img src="docs-site/public/screenshots/yomitan-lookup.png" width="800" alt="Yomitan dictionary popup over annotated subtitles in mpv">
 </div>
 
-<br />
+<br>
 
-## What it does
+### Instant Anki Mining
 
-SubMiner is an Electron overlay that sits on top of mpv. It turns your video player into a full sentence-mining workstation:
+Create an Anki card with the sentence, audio clip, screenshot, and machine translation from the exact playback moment with one key press, click, or controller input.
 
-- **Hover to look up** — Yomitan dictionary popups directly on subtitles
-- **Keyboard-driven lookup mode** — Navigate token-by-token, keep lookup open across tokens, and control popup scrolling/audio/mining without leaving the overlay
-- **One-key mining** — Creates Anki cards with sentence, audio, screenshot, and translation
-- **Instant auto-enrichment** — Optional local AnkiConnect proxy enriches new Yomitan cards immediately
-- **Reading annotations** — Combines N+1 targeting, frequency-dictionary highlighting, and JLPT underlining while you read
-- **Hover-aware playback** — By default, hovering subtitle text pauses mpv and resumes on mouse leave (`subtitleStyle.autoPauseVideoOnHover`)
-- **Subtitle tools** — Download from Jimaku, sync with alass/ffsubsync
-- **Immersion tracking** — SQLite-powered stats on your watch time and mining activity
-- **Custom texthooker page** — Built-in custom texthooker page and websocket, no extra setup
-- **Jellyfin integration** — Remote playback setup, cast device mode, and direct playback launch
-- **AniList progress** — Track episode completion and push watching progress automatically
+<div align="center">
+  <img src="docs-site/public/screenshots/one-key-mining.png" width="800" alt="Anki card created from SubMiner with sentence, audio, and screenshot">
+</div>
 
-## Quick start
+<br>
 
-### 1. Install
+### Reading Annotations
 
-**Linux (AppImage):**
+Real-time subtitle annotations with frequency highlighting, JLPT tags, N+1 targeting, and a character name dictionary. Grammar-only tokens and particles render as plain text so you focus on what matters.
 
-```bash
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
-chmod +x ~/.local/bin/SubMiner.AppImage
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
-chmod +x ~/.local/bin/subminer
+<div align="center">
+  <img src="docs-site/public/screenshots/annotations.png" width="800" alt="Annotated subtitles with frequency coloring, JLPT underlines, and N+1 targets">
+</div>
 
-```
+<br>
 
-> [!NOTE]
-> The `subminer` wrapper uses a [Bun](https://bun.sh) shebang. Make sure `bun` is on your `PATH`.
+### Immersion Dashboard
 
-**From source** or **macOS** — see the [installation guide](https://docs.subminer.moe/installation#from-source).
+Local stats dashboard tracking watch time, vocabulary growth, mining throughput, session history, and trends. All stored locally, no third-party tracking.
 
-### 2. Install the mpv plugin and configuration file
+<div align="center">
+  <img src="docs-site/public/screenshots/stats-overview.png" width="800" alt="Stats dashboard showing watch time, cards mined, streaks, and tracking data">
+</div>
 
-```bash
-wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
-tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
-mkdir -p ~/.config/mpv/scripts/subminer
-mkdir -p ~/.config/mpv/script-opts
-cp -R /tmp/plugin/subminer/. ~/.config/mpv/scripts/subminer/
-cp /tmp/plugin/subminer.conf ~/.config/mpv/script-opts/
-mkdir -p ~/.config/SubMiner && cp /tmp/config.example.jsonc ~/.config/SubMiner/config.jsonc
-```
+<br>
 
-### 3. Set up Yomitan Dictionaries
+### Playlist Browser
 
-```bash
-subminer app --yomitan
-```
+Browse sibling episode files and the active mpv queue in one overlay modal. Open it with `Ctrl+Alt+P` to append episodes from the current directory, jump to queued items, remove entries, or reorder the playlist without leaving playback.
 
-### 4. Mine
+<div align="center">
+  <img src="docs-site/public/screenshots/playlist-browser.png" width="800" alt="Playlist browser modal showing sibling episode files beside the active mpv queue">
+</div>
 
-```bash
-subminer app --start --background
-subminer video.mkv # default plugin config auto-starts visible overlay + resumes playback when ready
-subminer --start video.mkv # optional explicit overlay start when plugin auto_start=no
-```
+<br>
+
+### Integrations
+
+<table>
+  <tr>
+    <td><b>YouTube</b></td>
+    <td>Auto-loaded yt-dlp subtitle tracks at startup with config-driven primary/secondary language priorities and a manual overlay picker on demand (<code>Ctrl+Alt+C</code>)</td>
+  </tr>
+  <tr>
+    <td><b>AniList</b></td>
+    <td>Automatic episode tracking and progress sync</td>
+  </tr>
+  <tr>
+    <td><b>Jellyfin</b></td>
+    <td>Browse, launch, and cast media from your Jellyfin server with setup and discovery controls in the app tray</td>
+  </tr>
+  <tr>
+    <td><b>Jimaku</b></td>
+    <td>Search and download Japanese subtitles</td>
+  </tr>
+  <tr>
+    <td><b>Local Subtitle Generation</b></td>
+    <td>Generate Japanese subtitles from local audio in a standalone modal (<code>Ctrl+Shift+G</code>), the sidebar button, or launcher, with progress and optional managed model downloads. Requires whisper.cpp and FFmpeg. Optional Silero speech detection prioritizes dialogue in separately timed passages. <a href="https://docs.subminer.moe/main/subtitle-generation">Setup guide</a></td>
+  </tr>
+  <tr>
+    <td><b>TsukiHime</b></td>
+    <td>Search and download subtitles extracted from anime releases, with Japanese and secondary-language tabs (<code>Ctrl+Shift+T</code>) — no API key, requires <code>xz</code> on your <code>PATH</code></td>
+  </tr>
+  <tr>
+    <td><b>AniSkip</b></td>
+    <td>Automatic intro detection with chapter markers and a one-key skip (<code>TAB</code> by default)</td>
+  </tr>
+  <tr>
+    <td><b>alass / ffsubsync</b></td>
+    <td>Manual subtitle retiming — requires <code>alass</code> or <code>ffsubsync</code> on your <code>PATH</code> (optional; subtitle syncing is disabled without them)</td>
+  </tr>
+  <tr>
+    <td><b>WebSocket</b></td>
+    <td>Plain subtitle feed plus a dedicated annotated feed for texthooker pages and custom tools</td>
+  </tr>
+</table>
+
+<div align="center">
+  <img src="docs-site/public/screenshots/texthooker.png" width="800" alt="Texthooker page receiving annotated subtitle lines via WebSocket">
+</div>
+
+<br>
+
+---
 
 ## Requirements
 
-| Required                                   | Optional                                           |
-| ------------------------------------------ | -------------------------------------------------- |
-| `bun`                                      |                                                    |
-| `mpv` with IPC socket                      | `yt-dlp`                                           |
-| `ffmpeg`                                   | `guessit` (better AniSkip title/episode detection) |
-| `mecab` + `mecab-ipadic`                   | `fzf` / `rofi`                                     |
-| Linux: `hyprctl` or `xdotool` + `xwininfo` | `chafa`, `ffmpegthumbnailer`                       |
-| macOS: Accessibility permission            |                                                    |
+Only **mpv** is required to run SubMiner. Anki + AnkiConnect are required to mine cards, which is the point of the app, but everything else is optional.
+
+| Dependency           | Status           | What it does                                             |
+| -------------------- | ---------------- | -------------------------------------------------------- |
+| mpv                  | Required         | The video player SubMiner overlays on                    |
+| Anki + AnkiConnect   | Required to mine | Card creation from the Yomitan popup                     |
+| ffmpeg               | Recommended      | Audio clips & screenshots for Anki cards                 |
+| MeCab + mecab-ipadic | Recommended      | More precise annotations and filtering                   |
+| yt-dlp               | Optional         | YouTube playback                                         |
+| xz                   | Optional         | TsukiHime subtitle downloads (not on Windows by default) |
+| alass / ffsubsync    | Optional         | Subtitle sync                                            |
+| guessit              | Optional         | Better anime title and episode detection                 |
+| fzf / rofi           | Optional         | Video picker in the `subminer` launcher (Linux/macOS)    |
+
+<details>
+<summary><b>Platform-specific install commands</b></summary>
+
+**Arch Linux:**
+
+```bash
+sudo pacman -S --needed mpv ffmpeg mecab mecab-ipadic
+```
+
+**macOS:**
+
+```bash
+brew install mpv ffmpeg mecab mecab-ipadic
+```
+
+**Windows:**
+
+```powershell
+winget install shinchiro.mpv
+winget install Gyan.FFmpeg
+```
+
+Then reopen your terminal and check `mpv --version` and `ffmpeg -version`. winget puts `ffmpeg` on `PATH` automatically; mpv uses a regular installer that may not, so if `mpv` is not found, either add its folder (usually `%LOCALAPPDATA%\Programs\mpv`) to `PATH` or set `mpv.executablePath` during first-run setup.
+
+[Scoop](https://scoop.sh) is the alternative if you want one package manager for everything, since it is the only one that also carries `xz`:
+
+```powershell
+scoop bucket add extras
+scoop install extras/mpv main/ffmpeg main/yt-dlp main/xz
+```
+
+See the [full requirements list](https://docs.subminer.moe/installation#_1-install-requirements) for optional dependencies.
+
+</details>
+
+---
+
+## Quick Start
+
+### 1. Install SubMiner
+
+<details>
+<summary><b>Arch Linux (AUR)</b></summary>
+
+```bash
+paru -S subminer-bin
+```
+
+</details>
+
+<details>
+<summary><b>Linux (AppImage)</b></summary>
+
+```bash
+mkdir -p ~/.local/bin
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage \
+ && chmod +x ~/.local/bin/SubMiner.AppImage
+```
+
+The AppImage is all you need. First-run setup can install the optional `subminer` command-line launcher. Every current launcher uses Bun included with the app, so you do not need Bun installed or on `PATH`.
+
+You can also download the launcher wrapper directly:
+
+```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer \
+ && chmod +x ~/.local/bin/subminer
+```
+
+</details>
+
+<details>
+<summary><b>macOS (DMG)</b></summary>
+
+Download the latest DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest) and drag `SubMiner.app` into `/Applications`.
+
+</details>
+
+<details>
+<summary><b>Windows</b></summary>
+
+Download and run the latest installer (`.exe`) from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest).
+
+For terminal use, download `subminer.cmd`. It locates the installed app and uses its private Bun runtime.
+
+</details>
+
+<details>
+<summary><b>From source</b></summary>
+
+See the [build-from-source guide](https://docs.subminer.moe/installation#from-source).
+
+</details>
+
+### 2. Launch & Set Up
+
+Run the installed app and the first-run setup wizard will guide you through importing Yomitan dictionaries and optionally installing the `subminer` command-line launcher. Setup records a custom app location when needed, and the wrapper runs with the app's private Bun runtime.
+
+```bash
+# Linux
+~/.local/bin/SubMiner.AppImage --setup
+
+# macOS
+open -a SubMiner --args --setup
+```
+
+On **Windows**, just run `SubMiner.exe` and the setup will open automatically on first launch.
+
+### 3. Mine
+
+```bash
+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 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.
 
 ## Documentation
 
-For full guides on configuration, Anki, Jellyfin, and more, see [docs.subminer.moe](https://docs.subminer.moe).
+Full guides on configuration, Anki setup, Jellyfin, immersion tracking, and more: **[docs.subminer.moe](https://docs.subminer.moe)**
+
+---
 
 ## Acknowledgments
 
-Built on the shoulders of [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner), [texthooker-ui](https://github.com/Renji-XD/texthooker-ui), [mpvacious](https://github.com/Ajatt-Tools/mpvacious), [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script), and [autosubsync-mpv](https://github.com/joaquintorres/autosubsync-mpv). Subtitles powered by [Jimaku.cc](https://jimaku.cc). Dictionary lookups via [Yomitan](https://github.com/yomidevs/yomitan).
+SubMiner builds on the work of these open-source projects:
+
+| Project                                                                                     | Role                                                                    |
+| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [ani-skip](https://github.com/synacktraa/ani-skip)                                          | AniSkip API client for anime intro/outro skip timestamps                |
+| [Anacreon-Script](https://github.com/friedrich-de/Anacreon-Script)                          | Inspiration for the mining workflow                                     |
+| [asbplayer](https://github.com/killergerbah/asbplayer)                                      | Inspiration for subtitle sidebar and logic for YouTube subtitle parsing |
+| [Bee's Character Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) | Character name recognition in subtitles                                 |
+| [Bun](https://github.com/oven-sh/bun)                                                       | Bundled runtime for the `subminer` command-line launcher                |
+| [GameSentenceMiner](https://github.com/bpwhelan/GameSentenceMiner)                          | Inspiration for Electron overlay with Yomitan integration               |
+| [jellyfin-mpv-shim](https://github.com/jellyfin/jellyfin-mpv-shim)                          | Jellyfin integration                                                    |
+| [Jimaku.cc](https://jimaku.cc)                                                              | Japanese subtitle search and downloads                                  |
+| [Renji's Texthooker Page](https://github.com/Renji-XD/texthooker-ui)                        | Base for the WebSocket texthooker integration                           |
+| [Yomitan](https://github.com/yomidevs/yomitan)                                              | Dictionary engine powering all lookups and the morphological parser     |
+| [yomitan-jlpt-vocab](https://github.com/stephenmk/yomitan-jlpt-vocab)                       | JLPT level tags for vocabulary                                          |
 
 ## License
 
-[GNU General Public License v3.0](LICENSE)
+SubMiner is released under the [GNU General Public License v3.0](LICENSE).
+
+Release packages also bundle an unmodified copy of [Bun](https://github.com/oven-sh/bun), which is MIT licensed and statically links JavaScriptCore (LGPL 2.0) and TinyCC (LGPL 2.1). Its license texts and third-party notices ship inside the app under `resources/bun/licenses`, and each release publishes `bun-v1.3.5-source.tar.gz` with the corresponding source. See [Bundled Bun runtime](https://docs.subminer.moe/installation#bundled-bun-runtime).

assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer

@@ -0,0 +1,4 @@
+[Thumbnailer Entry]
+TryExec=ffmpegthumbnailer
+Exec=ffmpegthumbnailer -i %i -o %o -s %s -f
+MimeType=video/matroska;video/matroska-3d;video/x-matroska;video/x-matroska-3d;

backlog/config.yml

@@ -1,16 +0,0 @@
-project_name: 'SubMiner'
-default_status: 'To Do'
-statuses: ['To Do', 'In Progress', 'Done']
-labels: []
-definition_of_done: []
-date_format: yyyy-mm-dd
-max_column_width: 20
-default_editor: 'nvim'
-auto_open_browser: false
-default_port: 6420
-remote_operations: true
-auto_commit: false
-bypass_git_hooks: false
-check_active_branches: true
-active_branch_days: 30
-task_prefix: 'task'

backlog/milestones/m-0 - codebase-health-remediation.md

@@ -1,8 +0,0 @@
----
-id: m-0
-title: 'Codebase Health Remediation'
----
-
-## Description
-
-Follow-up work from the March 6, 2026 codebase review: strengthen the runnable test gate, remove confirmed dead architecture, and continue decomposition of oversized runtime entrypoints.

backlog/tasks/task-70 - Overlay-runtime-refactor-remove-invisible-mode-and-bind-visible-overlay-to-mpv-subtitles.md

@@ -1,51 +0,0 @@
----
-id: TASK-70
-title: >-
-  Overlay runtime refactor: remove invisible mode and bind visible overlay to
-  mpv subtitles
-status: Done
-assignee: []
-created_date: '2026-02-28 02:38'
-updated_date: '2026-02-28 22:36'
-labels: []
-dependencies: []
-references:
-  - 'commit:a14c9da'
-  - 'commit:74554a3'
-  - 'commit:75442a4'
-  - 'commit:dde51f8'
-  - 'commit:9e4e588'
-  - src/main/overlay-runtime.ts
-  - src/main/runtime/overlay-mpv-sub-visibility.ts
-  - src/renderer/renderer.ts
-  - docs/plans/2026-02-26-secondary-subtitles-main-overlay.md
-priority: medium
-ordinal: 1000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Branch-only commits main..HEAD on refactor-overlay (a14c9da through 9e4e588) rebuilt overlay behavior around visible overlay mode and removed legacy invisible overlay paths.
-
-Delivered behavior:
-
-- Removed renderer invisible overlay layout/offset helpers and main hover-highlight runtime code paths.
-- Added explicit overlay-to-mpv subtitle visibility synchronization so visible overlay state controls primary subtitle visibility consistently.
-- Hardened overlay runtime/bootstrap lifecycle around modal fallback open state and bridge send path edge cases.
-- Updated plugin/config/docs defaults to reflect visible-overlay-first behavior and subtitle binding controls.
-
-Risk/impact context:
-
-- Large cross-layer refactor touching runtime wiring, renderer event handling, and plugin behavior.
-- Regression coverage added/updated for overlay runtime, mpv protocol handling, renderer cleanup, and subtitle rendering paths.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Completed and validated in branch commit set before merge. Refactor reduces dead overlay modes, centralizes subtitle visibility behavior, and documents new defaults/constraints.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-71 - Anki-integration-add-local-AnkiConnect-proxy-transport-for-push-based-auto-enrichment.md

@@ -1,58 +0,0 @@
----
-id: TASK-71
-title: >-
-  Anki integration: add local AnkiConnect proxy transport for push-based
-  auto-enrichment
-status: Done
-assignee: []
-created_date: '2026-02-28 02:38'
-updated_date: '2026-03-04 13:55'
-labels: []
-dependencies: []
-references:
-  - src/anki-integration/anki-connect-proxy.ts
-  - src/anki-integration/anki-connect-proxy.test.ts
-  - src/anki-integration.ts
-  - src/config/resolve/anki-connect.ts
-  - src/core/services/tokenizer/yomitan-parser-runtime.ts
-  - src/core/services/tokenizer/yomitan-parser-runtime.test.ts
-  - docs/anki-integration.md
-  - config.example.jsonc
-priority: medium
-ordinal: 2000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Current unmerged working-tree changes implement an optional local AnkiConnect-compatible proxy and transport switching for card enrichment.
-
-Delivered behavior:
-
-- Added proxy server that forwards AnkiConnect requests and enqueues addNote/addNotes note IDs for post-create enrichment, with de-duplication and loop-configuration protection.
-- Added follow-up response-shape compatibility handling so proxy enqueue works for both envelope (`{result,error}`) and bare JSON payloads, including `multi` variants.
-- Added config schema/defaults/resolution for ankiConnect.proxy (enabled, host, port, upstreamUrl) with validation warnings and fallback behavior.
-- Runtime now supports transport switching (polling vs proxy) and restarts transport when runtime config patches change transport keys.
-- Added Yomitan default-profile server sync helper to keep bundled parser profile aligned with configured Anki endpoint.
-- Updated user docs/config examples for proxy mode setup, troubleshooting, and mining workflow behavior.
-
-Risk/impact context:
-
-- New network surface on local host/port; correctness depends on safe proxy upstream configuration and robust response handling.
-- Tests added for proxy queue behavior, config resolution, and parser sync routines.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Completed implementation in branch working tree; ready to merge once local changes are committed and test gate passes.
-
-Follow-up fix (2026-03-04):
-
-- Updated bundled Yomitan server-sync behavior to target `profileCurrent` instead of hardcoded `profiles[0]`.
-- Added proxy-mode force override so bundled Yomitan always points at SubMiner proxy URL when `ankiConnect.proxy.enabled=true`; this ensures mined cards pass through proxy and trigger auto-enrichment.
-- Added regression tests for blocked existing-server case and force-override injection path.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-72 - macOS-config-validation-UX-show-full-warning-details-in-native-dialog.md

@@ -1,42 +0,0 @@
----
-id: TASK-72
-title: 'macOS config validation UX: show full warning details in native dialog'
-status: Done
-assignee: []
-created_date: '2026-02-28 02:38'
-updated_date: '2026-02-28 22:36'
-labels: []
-dependencies: []
-references:
-  - 'commit:cc2f9ef'
-  - src/main/config-validation.ts
-  - src/main/runtime/startup-config.ts
-  - docs/configuration.md
-priority: low
-ordinal: 3000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Commit cc2f9ef improves startup config-warning visibility on macOS by ensuring full details are surfaced in the native UI path and reflected in docs.
-
-Delivered behavior:
-
-- Config validation/runtime wiring updated so macOS users can access complete warning details instead of truncated notification-only text.
-- Added/updated tests around config validation and startup config warning flows.
-- Updated configuration docs to clarify platform-specific warning presentation behavior.
-
-Risk/impact context:
-
-- Low runtime risk; primarily user-facing diagnostics clarity improvement.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Completed small follow-up fix to reduce config-debug friction on macOS.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-73 - MPV-plugin-split-into-modules-and-optimize-startup-command-runtime.md

@@ -1,84 +0,0 @@
----
-id: TASK-73
-title: 'MPV plugin: split into modules and optimize startup/command runtime'
-status: Done
-assignee: []
-created_date: '2026-02-28 20:50'
-updated_date: '2026-02-28 22:36'
-labels: []
-dependencies: []
-references:
-  - plugin/subminer/main.lua
-  - plugin/subminer/bootstrap.lua
-  - plugin/subminer/process.lua
-  - plugin/subminer/aniskip.lua
-  - plugin/subminer/environment.lua
-  - plugin/subminer/lifecycle.lua
-  - plugin/subminer/messages.lua
-  - plugin/subminer/ui.lua
-  - plugin/subminer/hover.lua
-  - plugin/subminer/options.lua
-  - plugin/subminer/state.lua
-  - plugin/subminer.conf
-  - scripts/test-plugin-start-gate.lua
-  - scripts/test-plugin-process-start-retries.lua
-  - launcher/commands/playback-command.ts
-  - launcher/mpv.ts
-  - launcher/mpv.test.ts
-  - launcher/smoke.e2e.test.ts
-  - Makefile
-  - package.json
-  - docs/mpv-plugin.md
-  - docs/installation.md
-  - docs/architecture.md
-  - README.md
-priority: medium
-ordinal: 4000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Scope: Replace monolithic `plugin/subminer.lua` with modular plugin runtime; optimize command execution paths; align install/docs/tests; fix launcher smoke instability.
-
-Delivered behavior:
-
-- Full plugin cutover to `plugin/subminer/main.lua` + module directory (no runtime compatibility shim with old monolith file).
-- Process/control command path moved toward async subprocess usage for non-start actions (`stop`, `toggle`, `settings`, restart stop leg), reducing synchronous blocking in mpv script runtime.
-- AniSkip path guarded: lookup runs only in SubMiner context (launcher metadata, explicit script-message refresh, or detected running app), instead of every opened file.
-- AniSkip lookup pipeline moved to async subprocess calls (no sync `ps`/`curl` on `file-loaded`) with deferred fetch after auto-start and session-level MAL/title/payload caching.
-- Startup/runtime loading updated with lazy module initialization via bootstrap proxies.
-- Plugin install flow updated to copy `plugin/subminer/` directory and remove legacy `~/.config/mpv/scripts/subminer.lua` file.
-- Added plugin gate script wiring to package scripts (`test:plugin:src`) and launcher test flow.
-- Smoke tests stabilized across sandbox environments where UNIX socket bind can return `EPERM` while preserving normal-path assertions.
-- Playback command cleanup race fixed when mpv exits before exit-listener registration.
-
-Risk/impact context:
-
-- mpv plugin loading path changed from single-file to module directory; packaging/install paths must stay consistent with release assets.
-- Async control/AniSkip path changes reduce blocking but can surface timing differences; regression checks added for cold start, file-load gating, and explicit refresh behavior.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-AniSkip gate/async update delivered in plugin runtime:
-
-- `plugin/subminer/lifecycle.lua`: deferred AniSkip fetch and overlay-start trigger.
-- `plugin/subminer/aniskip.lua`: async lookup pipeline + context guard + session caches.
-- `plugin/subminer/environment.lua`: async app-running detection with short cache.
-- `plugin/subminer/messages.lua`: explicit script-message trigger wiring.
-
-Regression coverage updated:
-
-- `scripts/test-plugin-start-gate.lua` now verifies:
-  - no sync `ps`/`curl` on non-context file load
-  - no AniSkip network lookup on non-context file load
-  - script-message refresh forces async AniSkip lookup
-
-Validation run:
-
-- `bun run test:plugin:src` pass.
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-74 - Startup-warmups-configurable-warmup-vs-defer-with-low-power-mode.md

@@ -1,76 +0,0 @@
----
-id: TASK-74
-title: 'Startup warmups: configurable warmup vs defer with low-power mode'
-status: Done
-assignee: []
-created_date: '2026-02-27 21:05'
-updated_date: '2026-03-01 04:14'
-labels: []
-dependencies: []
-references:
-  - src/types.ts
-  - src/config/definitions/defaults-core.ts
-  - src/config/definitions/options-core.ts
-  - src/config/definitions/template-sections.ts
-  - src/config/resolve/core-domains.ts
-  - src/main/runtime/startup-warmups.ts
-  - src/main/runtime/startup-warmups-main-deps.ts
-  - src/main/runtime/composers/mpv-runtime-composer.ts
-  - src/core/services/startup.ts
-  - src/main.ts
-  - src/config/config.test.ts
-  - src/main/runtime/startup-warmups.test.ts
-  - src/main/runtime/startup-warmups-main-deps.test.ts
-  - src/core/services/app-ready.test.ts
-priority: medium
-ordinal: 7000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add startup warmup controls to allow per-integration warmup or deferred first-use loading.
-
-Scope:
-
-- New config section `startupWarmups` with toggles for `mecab`, `yomitanExtension`, `subtitleDictionaries`, and `jellyfinRemoteSession`.
-- New `startupWarmups.lowPowerMode` policy: defer everything except Yomitan extension.
-- Keep default behavior as full warmup.
-- Ensure deferred integrations lazy-load on first real usage path.
-- Add test coverage for config parsing/defaults and warmup scheduling behavior.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented:
-
-- Added `startupWarmups` to config types/defaults/options/template/resolve.
-- Warmup scheduler now uses per-integration gating functions.
-- Low-power mode now defers MeCab, subtitle dictionaries, and Jellyfin remote session warmups while still warming Yomitan extension.
-- Tokenization path guarantees lazy first-use init for deferred dependencies (Yomitan extension, MeCab when missing, subtitle dictionaries).
-- Added/updated tests across config and runtime warmup modules.
-
-Validation:
-
-- `bun run test:config:src`
-- `bun run test:core:src`
-- `tsc --noEmit`
-
-Follow-up updates:
-
-- Startup now triggers warmups earlier in app-ready flow (right after config validation/log-level setup) instead of waiting for initial args/overlay actions. Goal: tokenization warmup is already done or mostly done by first visible-subs toggle.
-- Tokenization warmup scheduling consolidated as `subtitle-tokenization` stage; when enabled by toggles, it runs Yomitan extension first, then MeCab/dictionary warmups.
-- Added per-stage debug logs for warmup progress and skip reasons:
-  - `stage start/ready: yomitan-extension`
-  - `stage start/ready: mecab`
-  - `stage start/ready: subtitle-dictionaries`
-  - `stage start/ready: jellyfin-remote-session`
-  - `stage skipped: jellyfin-remote-session (disabled|auto-connect off)`
-- Added regression tests for stage-level logging and earlier startup ordering:
-  - `src/main/runtime/startup-warmups.test.ts`
-  - `src/main/runtime/startup-warmups-main-deps.test.ts`
-  - `src/core/services/app-ready.test.ts`
-  <!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-75 - Tokenizer-configurable-POS-exclusions-for-N1-and-frequency-annotations.md

@@ -1,41 +0,0 @@
----
-id: TASK-75
-title: 'Tokenizer: configurable POS exclusions for N+1 and frequency annotations'
-status: Done
-assignee: []
-created_date: '2026-03-01 01:23'
-updated_date: '2026-03-01 04:14'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 6000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-N+1 and frequency highlighting should ignore non-learning tokens (e.g., particles/auxiliary forms) based on MeCab POS1 tags, while remaining user-configurable.
-
-Problem example: for subtitle phrase containing になれば, the highlighted N+1 target should not be the non-useful inflection/token piece when POS indicates an excluded class.
-
-Implement configurable exclusion defaults with add/remove overrides so users can tune behavior without code changes.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Default exclusion set omits non-useful POS1 classes from both N+1 candidate selection and frequency highlighting.
-- [x] #2 Users can add extra POS1 exclusions and remove defaults via config.
-- [x] #3 Tokenizer/annotation tests cover default behavior and config add/remove overrides.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented configurable annotation POS exclusions with defaults+add/remove for both MeCab POS1 and POS2, wired to N+1 candidate selection and frequency highlighting. Added POS2 default exclusion (非自立), expanded POS1 defaults for function words, added Yomitan->MeCab enrichment to carry pos2/pos3 metadata, updated config docs/examples, and added regression tests including になれば case.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-76 - Tokenizer-remove-POS-exclusion-config-surface-and-keep-hardcoded-defaults.md

@@ -1,39 +0,0 @@
----
-id: TASK-76
-title: 'Tokenizer: remove POS exclusion config surface and keep hardcoded defaults'
-status: Done
-assignee: []
-created_date: '2026-03-01 02:45'
-updated_date: '2026-03-01 04:14'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 5000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Remove user-facing config keys for annotation POS exclusions. Keep N+1/frequency POS exclusion behavior as built-in defaults with no config required.
-
-Scope: remove config parsing/registry/docs/example for annotationFilters.pos1Exclusions/pos2Exclusions while preserving runtime filtering behavior.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 No user-facing config option exists for annotation POS exclusions.
-- [x] #2 Runtime N+1/frequency exclusion behavior remains active via built-in defaults.
-- [x] #3 Config/docs/example/tests updated accordingly.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Removed user-facing subtitleStyle.annotationFilters POS exclusion configuration (schema/resolver/options/docs/example). POS-based N+1/frequency filtering now always uses built-in defaults in runtime. Preserved robust exclusion behavior including merged-token overlap POS handling and N+1-only MeCab enrichment path.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-77 - Subtitle-hover-auto-pause-config-and-runtime-behavior.md

@@ -1,53 +0,0 @@
----
-id: TASK-77
-title: 'Subtitle hover: auto-pause playback with config toggle'
-status: Done
-assignee: []
-created_date: '2026-02-28 22:43'
-updated_date: '2026-03-04 12:07'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 8000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add a user-facing subtitle config option to pause mpv playback when the cursor hovers subtitle text and resume playback when the cursor leaves.
-
-Scope:
-
-- New config key: `subtitleStyle.autoPauseVideoOnHover`.
-- Default should be enabled.
-- Hover pause/resume must not unpause if playback was already paused before hover.
-- Docs/examples/tests updated.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 `subtitleStyle.autoPauseVideoOnHover` exists and defaults to `true`.
-- [x] #2 Overlay pauses playback on subtitle hover and resumes on leave only when hover-triggered pause occurred.
-- [x] #3 Main/renderer IPC exposes pause-state query for safe hover behavior.
-- [x] #4 Config docs/examples and user docs/readme mention the new behavior and toggle.
-- [x] #5 Regression tests cover config parsing/validation and hover behavior edge cases.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented `subtitleStyle.autoPauseVideoOnHover` with default `true`, wired through config defaults/resolution/types, renderer state/style, and mouse hover handlers. Added playback pause-state IPC (`getPlaybackPaused`) to avoid false resume when media was already paused. Added renderer hover behavior tests (including race/cancel case) and config/resolve tests. Updated config examples and docs (`README`, usage, shortcuts, mining workflow, configuration) to document default hover pause/resume behavior and disable path.
-
-Follow-up adjustments (2026-03-04):
-
-- Hover pause now resumes immediately when leaving subtitle text (no Yomitan-popup hover retention).
-- Added `subtitleStyle.autoPauseVideoOnYomitanPopup` (default `false`) to optionally keep playback paused while Yomitan popup is open, with auto-resume on close only when SubMiner initiated the popup pause.
-- Yomitan popup control keybinds added while popup is open: `J/K` scroll, `M` mine, `P` audio play, `[` previous audio variant, `]` next audio variant (within selected source).
-- Extension copy drift detection widened so popup runtime changes are reliably re-copied on launch (`popup.js`, `popup-main.js`, `display.js`, `display-audio.js`).
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-78 - Launcher-and-mpv-plugin-auto-start-pause-until-ready-and-single-start-guard.md

@@ -1,55 +0,0 @@
----
-id: TASK-78
-title: 'Launcher + mpv plugin: auto-start visible overlay pause-until-ready and single-start guard'
-status: Done
-assignee: []
-created_date: '2026-02-28 22:45'
-updated_date: '2026-02-28 22:45'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 9000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add startup gating behavior for wrapper + mpv plugin flow so playback starts paused when visible overlay auto-start is enabled, then auto-resumes only after subtitle tokenization is ready.
-
-Scope:
-
-- Plugin option `auto_start_pause_until_ready` (default `yes`).
-- Launcher reads plugin runtime config and starts mpv paused when `auto_start=yes`, `auto_start_visible_overlay=yes`, and `auto_start_pause_until_ready=yes`.
-- Main process signals readiness via mpv script message after tokenized subtitle delivery.
-- Prevent duplicate auto-start attempts from showing `SubMiner already running` OSD.
-- Keep startup/loading OSD messaging visible and update docs/tests.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Launcher reads `auto_start`, `auto_start_visible_overlay`, and `auto_start_pause_until_ready` from `subminer.conf` and starts mpv with `--pause=yes` when all are enabled.
-- [x] #2 Plugin pauses on eligible auto-start and resumes only on readiness signal or timeout fallback.
-- [x] #3 Main process emits `script-message subminer-autoplay-ready` after subtitle tokenization is ready.
-- [x] #4 Auto-start duplicate triggers are idempotent (no duplicate `--start` behavior and no spurious `Already running` OSD for auto-start path).
-- [x] #5 Docs and regression tests cover defaults, startup gating behavior, and duplicate-start suppression.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented startup pause gate across launcher/plugin/main runtime:
-
-- Added plugin runtime config parsing in launcher (`auto_start`, `auto_start_visible_overlay`, `auto_start_pause_until_ready`) and mpv start-paused behavior for eligible runs.
-- Added plugin auto-play gate state, timeout fallback, and readiness release via `subminer-autoplay-ready` script message.
-- Added main-process readiness signaling after tokenization delivery, including unpause fallback command path.
-- Split auto-start visibility control into separate control commands and added duplicate auto-start idempotency guard to suppress repeated auto-start `Already running` noise.
-- Updated plugin defaults to enabled (`auto_start=yes`, `auto_start_visible_overlay=yes`, `auto_start_pause_until_ready=yes`) and refreshed docs (`README`, usage, launcher, installation, plugin/config docs).
-- Added/updated regression coverage (`scripts/test-plugin-start-gate.lua`, launcher smoke/unit tests) validating paused startup, readiness resume, and duplicate-start suppression.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-79 - Jimaku-modal-auto-close-after-successful-subtitle-load.md

@@ -1,50 +0,0 @@
----
-id: TASK-79
-title: 'Jimaku modal: auto-close after successful subtitle load'
-status: Done
-assignee: []
-created_date: '2026-03-01 13:52'
-updated_date: '2026-03-01 14:06'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 10000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Fix Jimaku modal UX so selecting a subtitle file closes the modal automatically once subtitle download+load succeeds.
-
-Current behavior:
-
-- Subtitle file downloads and loads into mpv.
-- Jimaku modal remains open until manual close.
-
-Expected behavior:
-
-- On successful `jimakuDownloadFile` result, close modal immediately.
-- Keep error behavior unchanged (stay open + show error).
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Successful subtitle file selection/download in Jimaku closes modal automatically.
-- [x] #2 Existing error path keeps modal open and shows error.
-- [x] #3 Regression test covers success auto-close behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Fixed renderer Jimaku success flow to close modal immediately after successful `jimakuDownloadFile` result. Added regression test (`src/renderer/modals/jimaku.test.ts`) that reproduces keyboard file-selection success path and asserts modal close state + `notifyOverlayModalClosed('jimaku')` emission. Kept failure path unchanged.
-
-Also wired new test into `test:core:src` and `test:core:dist` package scripts.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-80 - Jimaku-download-rename-subtitle-to-match-current-video.md

@@ -1,50 +0,0 @@
----
-id: TASK-80
-title: 'Jimaku download: rename subtitle to current video basename'
-status: Done
-assignee: []
-created_date: '2026-03-01 14:17'
-updated_date: '2026-03-01 14:19'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 11000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-When user selects a Jimaku subtitle, save subtitle with filename derived from currently playing media filename instead of Jimaku release filename.
-
-Example:
-
-- Current media: `anime.mkv`
-- Downloaded subtitle extension: `.srt`
-- Saved subtitle path: `anime.ja.srt`
-
-Scope:
-
-- Apply in Jimaku download IPC path before writing file.
-- Preserve collision-avoidance behavior (suffix with jimaku entry id/counter when target exists).
-- Keep mpv load flow unchanged except using renamed path.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Jimaku subtitle destination name uses current media basename plus `.ja` and subtitle extension.
-- [x] #2 Existing duplicate filename conflict handling still works.
-- [x] #3 Regression tests cover renamed destination path behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Jimaku download path generation now derives subtitle filename from currently playing media basename and keeps subtitle extension from Jimaku file (`anime.mkv` + `.srt` => `anime.ja.srt`). Added pure helper `buildJimakuSubtitleFilenameFromMediaPath` and routed IPC download flow through it before existing duplicate-path conflict handling. Added regression tests for local path, missing extension fallback, and remote URL media paths.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-81 - Tokenization-performance-disable-yomitan-mecab-and-persistent-local-mecab.md

@@ -1,58 +0,0 @@
----
-id: TASK-81
-title: 'Tokenization performance: disable Yomitan MeCab parser, gate local MeCab init, and add persistent MeCab process'
-status: Done
-assignee: []
-created_date: '2026-03-02 07:44'
-updated_date: '2026-03-02 20:44'
-labels: []
-dependencies: []
-priority: high
-ordinal: 9001
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Reduce subtitle annotation latency by:
-
-- disabling Yomitan-side MeCab parser requests (`useMecabParser=false`);
-- initializing local MeCab only when POS-dependent annotations are enabled (N+1 / JLPT / frequency);
-- replacing per-line local MeCab process spawning with a persistent parser process that auto-shuts down after idle time and restarts on demand.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Yomitan parse requests disable MeCab parser path.
-- [x] #2 MeCab warmup/init is skipped when all POS-dependent annotation toggles are off.
-- [x] #3 Local MeCab tokenizer uses persistent process across subtitle lines.
-- [x] #4 Persistent MeCab process auto-shuts down after idle timeout and restarts on next tokenize activity.
-- [x] #5 Tests cover parser flag, warmup gating, and persistent MeCab lifecycle behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented tokenizer latency optimizations:
-
-- switched Yomitan parse requests to `useMecabParser: false`;
-- added annotation-aware MeCab initialization gating in runtime warmup flow;
-- added persistent local MeCab process (default idle shutdown: 30s) with queued requests, retry-on-process-end, idle auto-shutdown, and automatic restart on new work;
-- added regression tests for Yomitan parse flag, MeCab warmup gating, and persistent/idle lifecycle behavior;
-- fixed tokenization warmup gate so first-use warmup completion is sticky (`tokenizationWarmupCompleted`) and sequential `tokenizeSubtitle` calls no longer re-run Yomitan/dictionary warmup path;
-- added regression coverage in `src/main/runtime/composers/mpv-runtime-composer.test.ts` for sequential tokenize calls (`warmup` side effects run once);
-- post-review critical fix: treat Yomitan default-profile Anki server sync `no-change` as successful check, so `lastSyncedYomitanAnkiServer` is cached and expensive sync checks do not repeat on every subtitle line;
-- added regression assertion in `src/core/services/tokenizer/yomitan-parser-runtime.test.ts` for `updated: false` path returning sync success;
-- post-review performance fix: refactored POS enrichment to pre-index MeCab tokens by surface plus character-position overlap index, replacing repeated active-candidate filtering/full-scan behavior with direct overlap candidate lookup per token;
-- added regression tests in `src/core/services/tokenizer/parser-enrichment-stage.test.ts` for repeated distant-token scan access and repeated active-candidate filter scans; both fail on scan-based behavior and pass with indexed lookup;
-- post-review startup fix: moved JLPT/frequency dictionary initialization from synchronous FS APIs to async `fs/promises` path inspection/read and cooperative chunked entry processing to reduce main-thread stall risk during cold start;
-- post-review first-line latency fix: decoupled tokenization warmup gating so first `tokenizeSubtitle` only waits on Yomitan extension readiness, while MeCab check + dictionary prewarm continue in parallel background warmups;
-- validated with targeted tests and `tsc --noEmit`.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-82 - Subtitle-frequency-highlighting-fixes-for-noisy-readings-and-known-token-color-priority.md

@@ -1,60 +0,0 @@
----
-id: TASK-82
-title: 'Subtitle frequency highlighting: fix noisy Yomitan readings and restore known/N+1 color priority'
-status: Done
-assignee: []
-created_date: '2026-03-02 20:10'
-updated_date: '2026-03-02 01:44'
-labels: []
-dependencies: []
-priority: high
-ordinal: 9002
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Address frequency-highlighting regressions:
-
-- tokens like `断じて` missed rank assignment when Yomitan merged-token reading was truncated/noisy;
-- known/N+1 tokens were incorrectly colored by frequency color instead of known/N+1 color.
-
-Expected behavior:
-
-- known/N+1 color always wins;
-- if token is frequent and within `topX`, frequency rank label can still appear on hover/metadata.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Frequency lookup succeeds for noisy/truncated merged-token readings via robust fallback behavior.
-- [x] #2 Merged-token reading normalization restores missing kana suffixes where safe (`headword === surface` path).
-- [x] #3 Known/N+1 tokens keep known/N+1 color classes; frequency color class does not override them.
-- [x] #4 Frequency rank hover label remains available for in-range frequent tokens, including known/N+1.
-- [x] #5 Regression tests added for tokenizer and renderer behavior.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented and validated:
-
-- tokenizer now normalizes selected Yomitan merged-token readings by appending missing trailing kana suffixes when safe (`headword === surface`);
-- frequency lookup now does lazy fallback: requests `{term, reading}` first, and only requests `{term, reading: null}` for misses;
-- this removes eager `(term, null)` payload inflation on medium-frequency lines and reduces extension RPC payload/load;
-- renderer restored known/N+1 color priority over frequency class coloring;
-- frequency rank label display remains available for frequent known/N+1 tokens;
-- added regression tests covering noisy-reading fallback, lazy fallback-query behavior, and renderer class/label precedence.
-
-Related commits:
-
-- `17a417e` (`fix(subtitle): improve frequency highlight reliability`)
-- `79f37f3` (`fix(subtitle): prioritize known and n+1 colors over frequency`)
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-83 - Jellyfin-subtitle-delay-shift-to-adjacent-cue-without-seek-jumps.md

@@ -1,53 +0,0 @@
----
-id: TASK-83
-title: 'Jellyfin subtitle delay: shift to adjacent cue without seek jumps'
-status: Done
-assignee: []
-created_date: '2026-03-02 00:06'
-updated_date: '2026-03-02 00:06'
-labels: []
-dependencies: []
-priority: high
-ordinal: 9003
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add keybinding-friendly special commands that shift `sub-delay` to align current subtitle start with next/previous cue start, without `sub-seek` probing (avoid playback jump).
-
-Scope:
-
-- add special commands for next/previous line alignment;
-- compute delta from active subtitle cue timeline (external subtitle file/URL, including Jellyfin-delivered URLs);
-- apply `add sub-delay <delta>` and show OSD value;
-- keep existing proxy OSD behavior for direct `sub-delay` keybinding commands.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 New special commands exist for subtitle-delay shift to next/previous cue boundary.
-- [x] #2 Shift logic parses active external subtitle source timings (SRT/VTT/ASS) and computes delta from current `sub-start`.
-- [x] #3 Runtime applies delay shift without `sub-seek` and shows OSD feedback.
-- [x] #4 Direct `sub-delay` proxy commands also show OSD current value.
-- [x] #5 Tests added for cue parsing/shift behavior and IPC dispatch wiring.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented no-jump subtitle-delay alignment commands:
-
-- added `__sub-delay-next-line` and `__sub-delay-prev-line` special commands;
-- added `createShiftSubtitleDelayToAdjacentCueHandler` to parse cue start times from active external subtitle source and apply `add sub-delay` delta from current `sub-start`;
-- wired command handling through IPC runtime deps into main runtime;
-- retained/extended OSD proxy feedback for `sub-delay` keybindings;
-- updated configuration docs and added regression tests for subtitle-delay shift and IPC command routing.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-84 - Docs-Plausible-endpoint-uses-api-event-path.md

@@ -1,37 +0,0 @@
----
-id: TASK-84
-title: 'Docs Plausible endpoint uses /api/event path'
-status: Done
-assignee: []
-created_date: '2026-03-03 00:00'
-updated_date: '2026-03-03 00:00'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 12000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Fix VitePress docs Plausible tracker config to post to hosted worker API event endpoint instead of worker root URL.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Docs theme Plausible `endpoint` points to `https://worker.subminer.moe/api/event`.
-- [x] #2 Plausible docs test asserts `/api/event` endpoint path.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Updated docs Plausible tracker endpoint to `https://worker.subminer.moe/api/event` and updated regression test expectation accordingly.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-84 - Migrate-AniSkip-metadatalookup-orchestration-to-launcher-Electron.md

@@ -1,70 +0,0 @@
----
-id: TASK-84
-title: Migrate AniSkip metadata+lookup orchestration to launcher/Electron
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-03 08:31'
-updated_date: '2026-03-03 08:35'
-labels:
-  - enhancement
-  - aniskip
-  - launcher
-  - mpv-plugin
-dependencies: []
-references:
-  - launcher/aniskip-metadata.ts
-  - launcher/mpv.ts
-  - plugin/subminer/aniskip.lua
-  - plugin/subminer/options.lua
-  - plugin/subminer/state.lua
-  - plugin/subminer/lifecycle.lua
-  - plugin/subminer/messages.lua
-  - plugin/subminer.conf
-  - launcher/aniskip-metadata.test.ts
-documentation:
-  - docs/mpv-plugin.md
-  - launcher/aniskip-metadata.ts
-  - plugin/subminer/aniskip.lua
-  - docs/architecture.md
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Move AniSkip MAL/title-to-MAL lookup and intro payload resolution from mpv Lua to launcher Electron flow, while keeping mpv-side intro skip UX and chapter/chapter prompt behavior in plugin. Launcher should infer/analyze file metadata, fetch AniSkip payload when launching files, and pass resolved skip window via script options; plugin should trust launcher payload and fall back only when absent.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Launcher infers AniSkip metadata for file targets using existing guessit/fallback logic and performs AniSkip MAL + payload resolution during mpv startup.
-- [x] #2 Launcher injects script options containing resolved MAL id and intro window fields (or explicit lookup-failure status) into mpv startup.
-- [x] #3 Lua plugin consumes launcher-provided AniSkip intro data and skips all network lookups when payload is present.
-- [x] #4 Standalone mpv/plugin usage without launcher payload continues to function using existing async in-plugin lookup path.
-- [x] #5 Docs and defaults are updated to document new script-option contract.
-- [x] #6 Launcher tests cover payload generation contract and fallback behavior where metadata is unavailable.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Add launcher-side AniSkip payload resolution helpers in launcher/aniskip-metadata.ts (MAL prefix lookup + AniSkip payload fetch + result normalization).
-2. Wire launcher/mpv.ts + buildSubminerScriptOpts to pass resolved AniSkip fields/mode in --script-opts for file playback.
-3. Update plugin/subminer/aniskip.lua plus options/state to consume injected payload: if intro_start/end present, apply immediately and skip network lookup; otherwise retain existing async behavior.
-4. Ensure fallback for standalone mpv usage remains intact for no-launcher/manual refresh.
-5. Add/update tests/docs/config references for new script-opt contract and edge cases.
-<!-- SECTION:PLAN:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Executed end-to-end migration so launcher resolves AniSkip title/MAL/payload before mpv start and injects it via --script-opts. Plugin now parses and consumes launcher payload (JSON/url/base64), applies OP intro from payload, tracks payload metadata in state, and keeps legacy async lookup path for non-launcher/absent payload playback. Added launcher config key aniskip_payload and updated launcher/aniskip-metadata tests for resolve/payload behavior and contract validation.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-85 - Remove-docs-plausible-analytics-integration.md

@@ -1,38 +0,0 @@
----
-id: TASK-85
-title: 'Remove docs Plausible analytics integration'
-status: Done
-assignee: []
-created_date: '2026-03-03 00:00'
-updated_date: '2026-03-03 00:00'
-labels: []
-dependencies: []
-priority: medium
-ordinal: 12001
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Remove Plausible analytics integration from docs theme and dependency graph. Keep docs build/runtime analytics-free.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Docs theme no longer imports or initializes Plausible tracker.
-- [x] #2 `@plausible-analytics/tracker` removed from dependencies and lockfile.
-- [x] #3 Docs analytics test reflects absence of Plausible wiring.
-
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Deleted Plausible runtime wiring from VitePress theme, removed tracker package via `bun remove`, and updated docs test to assert no Plausible integration remains.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-86 - Renderer-keyboard-driven-Yomitan-lookup-mode-and-popup-key-forwarding.md

@@ -1,68 +0,0 @@
----
-id: TASK-86
-title: 'Renderer: keyboard-driven Yomitan lookup mode and popup key forwarding'
-status: Done
-assignee:
-  - Codex
-created_date: '2026-03-04 13:40'
-updated_date: '2026-03-05 11:30'
-labels:
-  - enhancement
-  - renderer
-  - yomitan
-dependencies:
-  - TASK-77
-references:
-  - src/renderer/handlers/keyboard.ts
-  - src/renderer/handlers/mouse.ts
-  - src/renderer/renderer.ts
-  - src/renderer/state.ts
-  - src/renderer/yomitan-popup.ts
-  - src/core/services/overlay-window.ts
-  - src/preload.ts
-  - src/shared/ipc/contracts.ts
-  - src/types.ts
-  - vendor/yomitan/js/app/frontend.js
-  - vendor/yomitan/js/app/popup.js
-  - vendor/yomitan/js/display/display.js
-  - vendor/yomitan/js/display/popup-main.js
-  - vendor/yomitan/js/display/display-audio.js
-documentation:
-  - README.md
-  - docs/usage.md
-  - docs/shortcuts.md
-priority: medium
-ordinal: 13000
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Add true keyboard-driven token lookup flow in overlay:
-
-- Toggle keyboard token-selection mode and navigate tokens by keyboard (`Arrow` + `HJKL`).
-- Toggle Yomitan lookup window for selected token via fixed accelerator (`Ctrl/Cmd+Y`) without requiring mouse click.
-- Preserve keyboard-only workflow while popup is open by forwarding popup keys (`J/K`, `M`, `P`, `[`, `]`) and restoring overlay focus on popup close.
-- Ensure selection styling and hover metadata tooltips (frequency/JLPT) work for keyboard-selected token.
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [x] #1 Keyboard mode toggle exists and shows visual selection outline for active token.
-- [x] #2 Navigation works via arrows and vim keys while keyboard mode is enabled.
-- [x] #3 Lookup window toggles from selected token with `Ctrl/Cmd+Y`; close path restores overlay keyboard focus.
-- [x] #4 Popup-local controls work via keyboard forwarding (`J/K`, `M`, `P`, `[`, `]`), including mine action.
-- [x] #5 Frequency/JLPT hover tags render for keyboard-selected token.
-- [x] #6 Renderer/runtime tests cover new visibility/selection behavior, and docs are updated.
-<!-- AC:END -->
-
-## Final Summary
-
-<!-- SECTION:FINAL_SUMMARY:BEGIN -->
-
-Implemented keyboard-driven Yomitan workflow end-to-end in renderer + bundled Yomitan runtime bridge. Added overlay-level keyboard mode state, token selection sync, lookup toggle routing, popup command forwarding, and focus recovery after popup close. Follow-up fixes kept lookup open while moving between tokens, made popup-local `J/K` and `ArrowUp/ArrowDown` scroll work from overlay-owned focus with key repeat, skipped keyboard/token annotation flow for parser groups that have no dictionary-backed headword, and preserved paused playback when token navigation jumps across subtitle lines. Updated user docs/README to document the final shortcut behavior.
-
-<!-- SECTION:FINAL_SUMMARY:END -->

backlog/tasks/task-87 - Codebase-health-harden-verification-and-retire-dead-architecture-identified-in-the-March-2026-review.md

@@ -1,71 +0,0 @@
----
-id: TASK-87
-title: >-
-  Codebase health: harden verification and retire dead architecture identified
-  in the March 2026 review
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 03:20'
-labels:
-  - tech-debt
-  - tests
-  - maintainability
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - README.md
-  - src/main.ts
-  - src/anki-integration.ts
-  - src/core/services/immersion-tracker-service.test.ts
-  - src/translators/index.ts
-  - src/subsync/engines.ts
-  - src/subtitle/pipeline.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-Track the remediation work from the March 6, 2026 code review. The review found that the default test gate only exercises 53 of 241 test files, the dedicated subtitle test lane is a no-op, SQLite-backed immersion tracking tests are conditionally skipped in the standard Bun run, src/main.ts still contains a large dead-symbol backlog, several registry/pipeline modules appear unreferenced from live execution paths, and src/anki-integration.ts remains an oversized orchestration file. This parent task should coordinate a safe sequence: improve verification first, then remove dead code and continue decomposition with good test coverage in place.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Child tasks are created for each remediation workstream with explicit dependencies and enough context for an isolated agent to execute them.
-- [ ] #2 The parent task records the recommended sequencing and parallelization strategy so replacement agents can resume without conversation history.
-- [ ] #3 Completion of the parent task leaves the repository with a materially more trustworthy test gate, less dead architecture, and clearer ownership boundaries for the main runtime and Anki integration surfaces.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-Recommended sequencing:
-
-1. Run TASK-87.1, TASK-87.2, TASK-87.3, and TASK-87.7 first. These are the safety-net and tooling tasks and can largely proceed in parallel.
-2. Start TASK-87.4 once TASK-87.1 lands so src/main.ts cleanup happens under a more trustworthy test matrix.
-3. Start TASK-87.5 after TASK-87.1 and TASK-87.2 so dead subsync/pipeline cleanup happens with stronger subtitle and runtime verification.
-4. Start TASK-87.6 after TASK-87.1 so Anki refactors happen with broader default coverage in place.
-5. Keep PRs focused: do not combine verification work with architectural cleanup unless a narrow dependency requires it.
-
-Parallelization guidance:
-
-- Wave 1 parallel: TASK-87.1, TASK-87.2, TASK-87.3, TASK-87.7
-- Wave 2 parallel: TASK-87.4, TASK-87.5, TASK-87.6
-
-Shared review context to restate in child tasks:
-
-- Standard test scripts currently reference only 53 unique test files out of 241 discovered test and type-test files under src/ and launcher/.
-- test:subtitle is currently a placeholder echo even though subtitle sync is a user-facing feature.
-- SQLite-backed immersion tracker tests are conditionally skipped in the standard Bun run.
-- src/main.ts trips many noUnusedLocals/noUnusedParameters diagnostics.
-- src/translators/index.ts, src/subsync/engines.ts, src/subtitle/pipeline.ts, src/tokenizers/index.ts, and src/token-mergers/index.ts appeared unreferenced during review and must be re-verified before deletion.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-87.1 - Testing-workflow-make-standard-test-commands-reflect-the-maintained-test-surface.md

@@ -1,53 +0,0 @@
----
-id: TASK-87.1
-title: >-
-  Testing workflow: make standard test commands reflect the maintained test
-  surface
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tests
-  - maintainability
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - src/main-entry-runtime.test.ts
-  - src/anki-integration/anki-connect-proxy.test.ts
-  - src/main/runtime/jellyfin-remote-playback.test.ts
-  - src/main/runtime/registry.test.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-The current package scripts hand-enumerate a small subset of test files, which leaves the standard green signal misleading. A local audit found 241 test/type-test files under src/ and launcher/, but only 53 unique files referenced by the standard package.json test scripts. This task should redesign the runnable test matrix so maintained tests are either executed by the standard commands or intentionally excluded through a documented rule, instead of silently drifting out of coverage.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 The repository has a documented and reproducible test matrix for standard development commands, including which suites belong in the default lane versus slower or environment-specific lanes.
-- [ ] #2 The standard test entrypoints stop relying on a brittle hand-maintained allowlist for the currently covered unit and integration suites, or an explicit documented mechanism exists that prevents silent omission of new tests.
-- [ ] #3 Representative tests that were previously outside the standard lane from src/main/runtime, src/anki-integration, and entry/runtime surfaces are executed by an automated command and included in the documented matrix.
-- [ ] #4 Documentation for contributors explains which command to run for fast verification, full verification, and environment-specific verification.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Inventory the current test surface under src/ and launcher/ and compare it to package.json scripts to classify fast, full, slow, and environment-specific suites.
-2. Replace or reduce the brittle hand-maintained allowlist so new maintained tests do not silently miss the standard matrix.
-3. Update contributor docs with the intended fast/full/environment-specific commands.
-4. Verify the new matrix by running the relevant commands and by demonstrating at least one previously omitted runtime/Anki/entry test now belongs to an automated lane.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-87.2 - Subtitle-sync-verification-replace-the-no-op-subtitle-lane-with-real-automated-coverage.md

@@ -1,53 +0,0 @@
----
-id: TASK-87.2
-title: >-
-  Subtitle sync verification: replace the no-op subtitle lane with real
-  automated coverage
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tests
-  - subsync
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - README.md
-  - src/core/services/subsync.ts
-  - src/core/services/subsync.test.ts
-  - src/subsync/utils.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-SubMiner advertises subtitle syncing with alass and ffsubsync, but the dedicated test:subtitle command currently does not run any tests. There is already lower-level coverage in src/core/services/subsync.test.ts, but the test matrix and contributor-facing commands do not reflect that reality. This task should replace the no-op lane with real verification, align scripts with the existing subsync test surface, and make the user-facing docs honest about how subtitle sync is verified.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 The test:subtitle entrypoint runs real automated verification instead of echoing a placeholder message.
-- [ ] #2 The subtitle verification lane covers both alass and ffsubsync behavior, including at least one non-happy-path scenario relevant to current functionality.
-- [ ] #3 Contributor-facing documentation points to the real subtitle verification command and no longer implies a dedicated test lane exists when it does not.
-- [ ] #4 The resulting verification strategy integrates cleanly with the repository-wide test matrix without duplicating or hiding existing subsync coverage.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Audit the existing subtitle-sync test surface, especially src/core/services/subsync.test.ts, and decide whether test:subtitle should reuse or regroup that coverage.
-2. Replace the placeholder script with a real automated command and keep the matrix legible alongside TASK-87.1 work.
-3. Update README or related docs so the advertised subtitle verification path matches reality.
-4. Verify both alass and ffsubsync behavior remain covered by the resulting lane.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md

@@ -1,52 +0,0 @@
----
-id: TASK-87.3
-title: >-
-  Immersion tracking verification: make SQLite-backed persistence tests visible
-  and reproducible
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tests
-  - immersion-tracking
-milestone: m-0
-dependencies: []
-references:
-  - src/core/services/immersion-tracker-service.test.ts
-  - src/core/services/immersion-tracker/storage-session.test.ts
-  - src/core/services/immersion-tracker-service.ts
-  - package.json
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-The immersion tracker is persistence-heavy, but its SQLite-backed tests are conditionally skipped in the standard Bun run when node:sqlite support is unavailable. That creates a blind spot around session finalization, telemetry persistence, and retention behavior. This task should establish a reliable automated verification path for the database-backed cases and make the prerequisite/runtime behavior explicit to contributors and CI.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute.
-- [ ] #2 If the current runtime cannot execute the SQLite-backed tests, the repository exposes that limitation clearly instead of silently reporting a misleading green result.
-- [ ] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on.
-- [ ] #4 The resulting verification covers session persistence or finalization behavior that is not exercised by the pure seam tests alone.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Confirm which SQLite-backed immersion tests are currently skipped and why in the standard Bun environment.
-2. Establish a reproducible command or lane for the DB-backed cases, or make the unsupported-runtime limitation explicit and actionable.
-3. Document prerequisites and expected behavior for contributors and CI.
-4. Verify at least one persistence/finalization path beyond the seam tests is exercised by the new lane.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-87.4 - Runtime-composition-root-remove-dead-symbols-and-tighten-module-boundaries-in-src-main.ts.md

@@ -1,53 +0,0 @@
----
-id: TASK-87.4
-title: >-
-  Runtime composition root: remove dead symbols and tighten module boundaries in
-  src/main.ts
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:19'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tech-debt
-  - runtime
-  - maintainability
-milestone: m-0
-dependencies:
-  - TASK-87.1
-references:
-  - src/main.ts
-  - src/main/runtime
-  - package.json
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-A noUnusedLocals/noUnusedParameters compile pass reports a large concentration of dead imports and dead locals in src/main.ts. The file is also far beyond the repo’s preferred size guideline, which makes the runtime composition root difficult to review and easy to break. This task should remove confirmed dead symbols, continue extracting coherent slices where that improves readability, and leave the entrypoint materially easier to understand without changing behavior.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 src/main.ts no longer emits dead-symbol diagnostics under a noUnusedLocals/noUnusedParameters compile pass for the areas touched by this cleanup.
-- [ ] #2 Unused imports, destructured values, and stale locals identified in the current composition root are removed or relocated without behavior changes.
-- [ ] #3 The resulting composition root has clearer ownership boundaries for at least one runtime slice that is currently buried in the monolith.
-- [ ] #4 Relevant runtime and startup verification commands pass after the cleanup, and any command changes are documented if needed.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Re-run the noUnusedLocals/noUnusedParameters compile pass and capture the src/main.ts diagnostics cluster before editing.
-2. Remove dead imports, destructured values, and stale locals in small reviewable slices; extract a coherent helper/module only where that materially reduces coupling.
-3. Keep changes behavior-preserving and avoid mixing unrelated cleanup outside src/main.ts unless required to compile.
-4. Verify with the updated runtime/startup test commands from TASK-87.1 plus a noUnused compile pass.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-87.5 - Dead-architecture-cleanup-delete-unused-registry-and-pipeline-modules-that-are-off-the-live-path.md

@@ -1,57 +0,0 @@
----
-id: TASK-87.5
-title: >-
-  Dead architecture cleanup: delete unused registry and pipeline modules that
-  are off the live path
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:20'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tech-debt
-  - dead-code
-milestone: m-0
-dependencies:
-  - TASK-87.1
-  - TASK-87.2
-references:
-  - src/translators/index.ts
-  - src/subsync/engines.ts
-  - src/subtitle/pipeline.ts
-  - src/tokenizers/index.ts
-  - src/token-mergers/index.ts
-  - src/core/services/subsync.ts
-  - src/core/services/tokenizer.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: high
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-The review found several modules that appear self-contained but unused from the application’s live execution paths: src/translators/index.ts, src/subsync/engines.ts, src/subtitle/pipeline.ts, src/tokenizers/index.ts, and src/token-mergers/index.ts. At the same time, the real runtime behavior is implemented elsewhere. This task should verify those modules are truly unused, remove or consolidate them, and clean up any stale exports, docs, or tests so contributors are not misled by duplicate architecture.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 Each candidate module identified in the review is either removed as dead code or justified and reconnected to a real supported execution path.
-- [ ] #2 Any stale exports, imports, or tests associated with the removed or consolidated modules are cleaned up so the codebase has a single obvious path for the affected behavior.
-- [ ] #3 The cleanup does not regress live tokenization or subtitle sync behavior and the relevant verification commands remain green.
-- [ ] #4 Contributor-facing documentation or internal notes no longer imply that removed duplicate architecture is part of the current design.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Re-verify each candidate module is off the live path by tracing imports from current runtime entrypoints before deleting anything.
-2. Remove or consolidate truly dead modules and clean associated exports/imports/tests so only the supported path remains obvious.
-3. Pay special attention to subtitle sync and tokenization surfaces, since duplicate architecture exists near active code.
-4. Verify the relevant tokenization and subsync commands/tests still pass and update any stale docs or notes.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-87.6 - Anki-integration-maintainability-continue-decomposing-the-oversized-orchestration-layer.md

@@ -1,57 +0,0 @@
----
-id: TASK-87.6
-title: >-
-  Anki integration maintainability: continue decomposing the oversized
-  orchestration layer
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:20'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tech-debt
-  - anki
-  - maintainability
-milestone: m-0
-dependencies:
-  - TASK-87.1
-references:
-  - src/anki-integration.ts
-  - src/anki-integration/field-grouping-workflow.ts
-  - src/anki-integration/note-update-workflow.ts
-  - src/anki-integration/card-creation.ts
-  - src/anki-integration/anki-connect-proxy.ts
-  - src/anki-integration.test.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-  - docs/anki-integration.md
-parent_task_id: TASK-87
-priority: medium
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-src/anki-integration.ts remains an oversized orchestration file even after earlier extractions. It still mixes config normalization, polling setup, media generation, duplicate resolution, field grouping workflows, and user feedback coordination in one class. This task should continue the decomposition so the remaining orchestration surface is smaller and easier to reason about, while preserving existing Anki, proxy, field grouping, and note update behavior.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 The responsibilities currently concentrated in src/anki-integration.ts are split into clearer modules or services with narrow ownership boundaries.
-- [ ] #2 The resulting orchestration surface is materially smaller and easier to review, with at least one mixed-responsibility cluster extracted behind a well-named interface.
-- [ ] #3 Existing Anki integration behavior remains covered by automated verification, including note update, field grouping, and proxy-related flows that the refactor touches.
-- [ ] #4 Any developer-facing docs or notes needed to understand the new structure are updated in the same task.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Map the remaining responsibility clusters inside src/anki-integration.ts and choose one or more extraction seams that reduce mixed concerns without changing behavior.
-2. Move logic behind narrow interfaces/modules rather than creating another giant helper; keep orchestration readable.
-3. Preserve coverage for field grouping, note update, proxy, and card creation flows touched by the refactor.
-4. Update docs or internal notes if the new structure changes where contributors should look for a given behavior.
-<!-- SECTION:PLAN:END -->

backlog/tasks/task-87.7 - Developer-workflow-hygiene-make-docs-watch-reproducible-and-remove-stale-small-surface-drift.md

@@ -1,51 +0,0 @@
----
-id: TASK-87.7
-title: >-
-  Developer workflow hygiene: make docs watch reproducible and remove stale
-  small-surface drift
-status: To Do
-assignee: []
-created_date: '2026-03-06 03:20'
-updated_date: '2026-03-06 03:21'
-labels:
-  - tooling
-  - tech-debt
-milestone: m-0
-dependencies: []
-references:
-  - package.json
-  - bun.lock
-  - src/anki-integration/field-grouping-workflow.ts
-documentation:
-  - docs/reports/2026-02-22-task-100-dead-code-report.md
-parent_task_id: TASK-87
-priority: low
----
-
-## Description
-
-<!-- SECTION:DESCRIPTION:BEGIN -->
-
-The review found a few low-risk but recurring hygiene issues: docs:watch depends on bunx concurrently even though concurrently is not declared in package metadata, and small stale API surface remains after recent refactors, such as unused parameters in field-grouping workflow code. This task should make the developer workflow reproducible and clean up low-risk stale symbols that do not warrant a dedicated architecture task.
-
-<!-- SECTION:DESCRIPTION:END -->
-
-## Acceptance Criteria
-
-<!-- AC:BEGIN -->
-
-- [ ] #1 The docs:watch workflow runs through declared project tooling or is rewritten to avoid undeclared dependencies.
-- [ ] #2 Small stale symbols or parameters identified during the review outside the main composition-root cleanup are removed without behavior changes.
-- [ ] #3 Any contributor-facing command changes are reflected in repository documentation.
-- [ ] #4 The cleanup remains scoped to low-risk workflow and hygiene fixes rather than expanding into large architectural refactors.
-<!-- AC:END -->
-
-## Implementation Plan
-
-<!-- SECTION:PLAN:BEGIN -->
-
-1. Fix the docs:watch workflow so it relies on declared project tooling or an equivalent checked-in command path.
-2. Clean up low-risk stale symbols surfaced by the review outside the main.ts architecture task, such as unused parameters left behind by refactors.
-3. Keep the task scoped: avoid pulling in main composition-root cleanup or larger Anki/runtime refactors.
-4. Verify the affected developer commands still work and document any usage changes.
-<!-- SECTION:PLAN:END -->

build/bun-runtime-manifest.json

@@ -0,0 +1,31 @@
+{
+  "schemaVersion": 1,
+  "version": "1.3.5",
+  "bunRevision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+  "releaseTagCommit": "fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab",
+  "artifacts": {
+    "darwin-arm64": {
+      "file": "bun-darwin-aarch64.zip",
+      "sha256": "db17588a4aea8804856825d4bead3f05e1f37276ca606f37e369b4f72f35d3fb"
+    },
+    "darwin-x64": {
+      "file": "bun-darwin-x64-baseline.zip",
+      "sha256": "34b9a56b851058dafa1bc9d61233f2c383aa996889bba30b3180f5ccc2cff1b2"
+    },
+    "linux-arm64": {
+      "file": "bun-linux-aarch64.zip",
+      "sha256": "ed01000f85bd97785228ad2845dc92a1860b8054856826d7317690ac8f8ee74b"
+    },
+    "linux-x64": {
+      "file": "bun-linux-x64-baseline.zip",
+      "sha256": "6bddacd6a65855698b9816f2d74871eda4dd0b7fa921140c6445248f94a742fd"
+    },
+    "win32-x64": {
+      "file": "bun-windows-x64-baseline.zip",
+      "sha256": "bf447dcc3b06aba9b9706a9db46fcd65e06a4d47d31439922313825d06eb47ca"
+    }
+  },
+  "licenseInventoryStatus": "source-and-notices-pinned-to-binary-revision",
+  "sourceManifest": "build/bun-source-manifest.json",
+  "correspondingSourceAsset": "bun-v1.3.5-source.tar.gz"
+}

build/bun-source-manifest.json

@@ -0,0 +1,148 @@
+{
+  "schemaVersion": 1,
+  "version": "1.3.5",
+  "releaseTag": "bun-v1.3.5",
+  "releaseTagCommit": "fa5a5bbe556a4bda5bde77b4013aa6c3bb4ec9ab",
+  "bunRevision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+  "archiveName": "bun-v1.3.5-source.tar.gz",
+  "sources": [
+    {
+      "name": "bun",
+      "repository": "oven-sh/bun",
+      "revision": "1e86cebd74a5723e818b5c0555276b646bcf0e4c",
+      "destination": "bun",
+      "sha256": "3a766087902a62a4920e5ac5452dbc7143ff97ea19721f945146629fc9f2d82c",
+      "licensePaths": ["LICENSE.md"]
+    },
+    {
+      "name": "WebKit",
+      "repository": "oven-sh/WebKit",
+      "revision": "6d0f3aac0b817cc01a846b3754b21271adedac12",
+      "destination": "bun/vendor/WebKit",
+      "transport": "git-sparse",
+      "exclude": ["JSTests", "LayoutTests", "ManualTests", "PerformanceTests", "WebDriverTests"],
+      "licensePaths": ["Source/JavaScriptCore/COPYING.LIB"]
+    },
+    {
+      "name": "boringssl",
+      "repository": "oven-sh/boringssl",
+      "revision": "f1ffd9e83d4f5c28a9c70d73f9a4e6fcf310062f",
+      "destination": "bun/vendor/boringssl",
+      "sha256": "af8fd325793bb261c70114d09a24f36092fbe252be8ec040f0054ec9455f0ea3",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "brotli",
+      "repository": "google/brotli",
+      "revision": "ed738e842d2fbdf2d6459e39267a633c4a9b2f5d",
+      "upstreamReference": "v1.1.0",
+      "destination": "bun/vendor/brotli",
+      "sha256": "aaa739962a45b508b2e783b915e6b2b57ed3b12bd4b0feac73acfb144dffa54f",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "cares",
+      "repository": "c-ares/c-ares",
+      "revision": "3ac47ee46edd8ea40370222f91613fc16c434853",
+      "destination": "bun/vendor/cares",
+      "sha256": "8c94116cb366ae4a44e487da4d9f7e736287d329efa6f88fdf077cd2d0a2e4b8",
+      "licensePaths": ["LICENSE.md"]
+    },
+    {
+      "name": "hdrhistogram",
+      "repository": "HdrHistogram/HdrHistogram_c",
+      "revision": "be60a9987ee48d0abf0d7b6a175bad8d6c1585d1",
+      "destination": "bun/vendor/hdrhistogram",
+      "sha256": "811c5e5ae5303a75ade50688880af6aad5d2f951ec5785f68186bd18635cdfc9",
+      "licensePaths": ["COPYING.txt", "LICENSE.txt"]
+    },
+    {
+      "name": "highway",
+      "repository": "google/highway",
+      "revision": "ac0d5d297b13ab1b89f48484fc7911082d76a93f",
+      "destination": "bun/vendor/highway",
+      "sha256": "a7a816f4b62a0414ff0d39c0a8875847468dd6f7c9ad71781a24469a756cdea7",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "libarchive",
+      "repository": "libarchive/libarchive",
+      "revision": "9525f90ca4bd14c7b335e2f8c84a4607b0af6bdf",
+      "destination": "bun/vendor/libarchive",
+      "sha256": "944db9ab58a3cbdb5d947db4f04a3cc15f83b3147fcf7830ada592ba8d4a102c",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "libdeflate",
+      "repository": "ebiggers/libdeflate",
+      "revision": "c8c56a20f8f621e6a966b716b31f1dedab6a41e3",
+      "destination": "bun/vendor/libdeflate",
+      "sha256": "1e5cc06bdbf3e1245d8b89c9e3588f507e3c8bc53fe8b8229770a9e8661dea81",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "libuv",
+      "repository": "libuv/libuv",
+      "revision": "f3ce527ea940d926c40878ba5de219640c362811",
+      "destination": "bun/vendor/libuv",
+      "sha256": "46040d51e8aa86a7c84e377e224d427c35022ec6e3ed8ed399493b0d8574d0cf",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "lolhtml",
+      "repository": "cloudflare/lol-html",
+      "revision": "d64457d9ff0143deef025d5df7e8586092b9afb7",
+      "destination": "bun/vendor/lolhtml",
+      "sha256": "893b77b460f4c4f4634c973f72cf35e38ebe30646d14a92db3f50ee7e586c0ad",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "lshpack",
+      "repository": "litespeedtech/ls-hpack",
+      "revision": "8905c024b6d052f083a3d11d0a169b3c2735c8a1",
+      "destination": "bun/vendor/lshpack",
+      "sha256": "07d8bf901bb1b15543f38eabd23938519e1210eebadb52f3d651d6ef130ef973",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "mimalloc",
+      "repository": "oven-sh/mimalloc",
+      "revision": "1beadf9651a7bfdec6b5367c380ecc3fe1c40d1a",
+      "destination": "bun/vendor/mimalloc",
+      "sha256": "317ec2a83462ece78c344c4955c6fee103b412a8e6a0d6ddf9ec8963ed9c0881",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "picohttpparser",
+      "repository": "h2o/picohttpparser",
+      "revision": "066d2b1e9ab820703db0837a7255d92d30f0c9f5",
+      "destination": "bun/vendor/picohttpparser",
+      "sha256": "637ff2ab6f5c7f7e05a5b5dc393d5cf2fea8d4754fcaceaaf935ffff5c1323ee",
+      "licensePaths": ["picohttpparser.c", "picohttpparser.h"]
+    },
+    {
+      "name": "tinycc",
+      "repository": "oven-sh/tinycc",
+      "revision": "29985a3b59898861442fa3b43f663fc1af2591d7",
+      "destination": "bun/vendor/tinycc",
+      "sha256": "813cc09aafd6cea9c1ae6b745781e6b27576a0c103f49b63b5c8a732bbe3d290",
+      "licensePaths": ["COPYING"]
+    },
+    {
+      "name": "zlib",
+      "repository": "cloudflare/zlib",
+      "revision": "886098f3f339617b4243b286f5ed364b9989e245",
+      "destination": "bun/vendor/zlib",
+      "sha256": "14bf449df8308696af52f87de88f54c9eb9c91ec5e280587f9d37f7a3f6ed9bb",
+      "licensePaths": ["LICENSE"]
+    },
+    {
+      "name": "zstd",
+      "repository": "facebook/zstd",
+      "revision": "f8745da6ff1ad1e7bab384bd1f9d742439278e99",
+      "destination": "bun/vendor/zstd",
+      "sha256": "4b0bd1f0cfb25e61b9103c35f27395530ff5b4c0d2513a00fd745849e85ea52c",
+      "licensePaths": ["COPYING", "LICENSE"]
+    }
+  ]
+}

build/installer.nsh

@@ -0,0 +1,153 @@
+!include "MUI2.nsh"
+!include "nsDialogs.nsh"
+
+Var WindowsMpvShortcutStartMenuPath
+Var WindowsMpvShortcutDesktopPath
+
+!macro ResolveWindowsMpvShortcutPaths
+  !ifdef MENU_FILENAME
+    StrCpy $WindowsMpvShortcutStartMenuPath "$SMPROGRAMS\${MENU_FILENAME}\SubMiner mpv.lnk"
+  !else
+    StrCpy $WindowsMpvShortcutStartMenuPath "$SMPROGRAMS\SubMiner mpv.lnk"
+  !endif
+  StrCpy $WindowsMpvShortcutDesktopPath "$DESKTOP\SubMiner mpv.lnk"
+!macroend
+
+!ifndef BUILD_UNINSTALLER
+Var WindowsMpvShortcutStartMenuCheckbox
+Var WindowsMpvShortcutDesktopCheckbox
+Var WindowsMpvShortcutStartMenuEnabled
+Var WindowsMpvShortcutDesktopEnabled
+Var WindowsMpvShortcutDefaultsInitialized
+
+!macro customInit
+  StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+  StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+  StrCpy $WindowsMpvShortcutDefaultsInitialized "0"
+!macroend
+
+!macro customPageAfterChangeDir
+  PageEx custom
+    PageCallbacks WindowsMpvShortcutPageCreate WindowsMpvShortcutPageLeave
+    Caption " "
+  PageExEnd
+!macroend
+
+Function HasExistingInstallation
+  ReadRegStr $0 SHELL_CONTEXT "Software\${APP_GUID}" InstallLocation
+  ${if} $0 == ""
+    Push "0"
+  ${else}
+    Push "1"
+  ${endif}
+FunctionEnd
+
+Function InitializeWindowsMpvShortcutDefaults
+  ${if} $WindowsMpvShortcutDefaultsInitialized == "1"
+    Return
+  ${endif}
+
+  !insertmacro ResolveWindowsMpvShortcutPaths
+  Call HasExistingInstallation
+  Pop $0
+
+  ${if} $0 == "1"
+    ${if} ${FileExists} "$WindowsMpvShortcutStartMenuPath"
+      StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+    ${else}
+      StrCpy $WindowsMpvShortcutStartMenuEnabled "0"
+    ${endif}
+
+    ${if} ${FileExists} "$WindowsMpvShortcutDesktopPath"
+      StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+    ${else}
+      StrCpy $WindowsMpvShortcutDesktopEnabled "0"
+    ${endif}
+  ${else}
+    StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+    StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+  ${endif}
+
+  StrCpy $WindowsMpvShortcutDefaultsInitialized "1"
+FunctionEnd
+
+Function WindowsMpvShortcutPageCreate
+  Call InitializeWindowsMpvShortcutDefaults
+
+  !insertmacro MUI_HEADER_TEXT "Windows mpv launcher" "Choose where to create the optional SubMiner mpv shortcuts."
+
+  nsDialogs::Create 1018
+  Pop $0
+
+  ${NSD_CreateLabel} 0u 0u 300u 30u "SubMiner mpv launches SubMiner.exe --launch-mpv so people can open mpv with the SubMiner profile from a separate Windows shortcut."
+  Pop $0
+
+  ${NSD_CreateCheckbox} 0u 44u 280u 12u "Create Start Menu shortcut"
+  Pop $WindowsMpvShortcutStartMenuCheckbox
+  ${if} $WindowsMpvShortcutStartMenuEnabled == "1"
+    ${NSD_Check} $WindowsMpvShortcutStartMenuCheckbox
+  ${endif}
+
+  ${NSD_CreateCheckbox} 0u 64u 280u 12u "Create Desktop shortcut"
+  Pop $WindowsMpvShortcutDesktopCheckbox
+  ${if} $WindowsMpvShortcutDesktopEnabled == "1"
+    ${NSD_Check} $WindowsMpvShortcutDesktopCheckbox
+  ${endif}
+
+  ${NSD_CreateLabel} 0u 90u 300u 24u "Upgrades preserve the current SubMiner mpv shortcut locations instead of recreating shortcuts you already removed."
+  Pop $0
+
+  nsDialogs::Show
+FunctionEnd
+
+Function WindowsMpvShortcutPageLeave
+  ${NSD_GetState} $WindowsMpvShortcutStartMenuCheckbox $0
+  ${if} $0 == ${BST_CHECKED}
+    StrCpy $WindowsMpvShortcutStartMenuEnabled "1"
+  ${else}
+    StrCpy $WindowsMpvShortcutStartMenuEnabled "0"
+  ${endif}
+
+  ${NSD_GetState} $WindowsMpvShortcutDesktopCheckbox $0
+  ${if} $0 == ${BST_CHECKED}
+    StrCpy $WindowsMpvShortcutDesktopEnabled "1"
+  ${else}
+    StrCpy $WindowsMpvShortcutDesktopEnabled "0"
+  ${endif}
+FunctionEnd
+
+!macro customInstall
+  Call InitializeWindowsMpvShortcutDefaults
+  !insertmacro ResolveWindowsMpvShortcutPaths
+
+  ${if} $WindowsMpvShortcutStartMenuEnabled == "1"
+    !ifdef MENU_FILENAME
+      CreateDirectory "$SMPROGRAMS\${MENU_FILENAME}"
+    !endif
+    CreateShortCut "$WindowsMpvShortcutStartMenuPath" "$appExe" "--launch-mpv" "$appExe" 0 "" "" "Launch mpv with the SubMiner profile"
+    # electron-builder's upstream NSIS templates use the same WinShell call for AppUserModelID wiring.
+    # WinShell.dll comes from electron-builder's cached nsis-resources bundle, so bun run build:win needs no extra repo-local setup.
+    ClearErrors
+    WinShell::SetLnkAUMI "$WindowsMpvShortcutStartMenuPath" "${APP_ID}"
+  ${else}
+    Delete "$WindowsMpvShortcutStartMenuPath"
+  ${endif}
+
+  ${if} $WindowsMpvShortcutDesktopEnabled == "1"
+    CreateShortCut "$WindowsMpvShortcutDesktopPath" "$appExe" "--launch-mpv" "$appExe" 0 "" "" "Launch mpv with the SubMiner profile"
+    # ClearErrors keeps the optional AUMI assignment non-fatal if the packaging environment is missing WinShell.
+    ClearErrors
+    WinShell::SetLnkAUMI "$WindowsMpvShortcutDesktopPath" "${APP_ID}"
+  ${else}
+    Delete "$WindowsMpvShortcutDesktopPath"
+  ${endif}
+
+  System::Call 'Shell32::SHChangeNotify(i 0x8000000, i 0, i 0, i 0)'
+!macroend
+!endif
+
+!macro customUnInstall
+  !insertmacro ResolveWindowsMpvShortcutPaths
+  Delete "$WindowsMpvShortcutStartMenuPath"
+  Delete "$WindowsMpvShortcutDesktopPath"
+!macroend

build/signpath-windows-artifact-config.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<artifact-configuration xmlns="http://signpath.io/artifact-configuration/v1">
+  <zip-file>
+    <pe-file path="SubMiner-*.exe" max-matches="unbounded">
+      <authenticode-sign />
+    </pe-file>
+    <zip-file path="SubMiner-*.zip" max-matches="unbounded">
+      <directory path="*">
+        <pe-file path="*.exe" max-matches="unbounded">
+          <authenticode-sign />
+        </pe-file>
+        <pe-file path="*.dll" max-matches="unbounded">
+          <authenticode-sign />
+        </pe-file>
+        <pe-file path="*.node" max-matches="unbounded">
+          <authenticode-sign />
+        </pe-file>
+      </directory>
+    </zip-file>
+  </zip-file>
+</artifact-configuration>

changes/README.md

@@ -0,0 +1,55 @@
+# Changelog Fragments
+
+Add one `.md` file per user-visible PR in this directory.
+
+Use this format:
+
+```md
+type: added
+area: overlay
+
+- Added keyboard navigation for Yomitan popups.
+- Added auto-pause toggle when opening the popup.
+```
+
+For breaking changes, add `breaking: true`:
+
+```md
+type: changed
+area: config
+breaking: true
+
+- Renamed `foo.bar` to `foo.baz`.
+```
+
+Rules:
+
+- `type` required: `added`, `changed`, `fixed`, `docs`, or `internal`
+- `area` required: short product area like `overlay`, `launcher`, `release`
+- `breaking` optional: set to `true` to flag as a breaking change
+- each non-empty body line becomes a bullet
+- `README.md` is ignored by the generator
+- if a PR should not produce release notes, apply the `skip-changelog` label instead of adding a fragment
+
+PR branch workflow:
+
+- Before adding a fragment or bullet, inspect the `changes/*.md` files already changed in the PR
+- If the new work fixes, modifies, renames, or supersedes behavior introduced or referenced by that fragment, edit or remove the stale bullet instead of adding follow-up churn
+- Add a new bullet only when it describes a truly separate user-visible outcome
+- Multiple fragment files are allowed when one PR has genuinely separate release-note outcomes, but keep them minimized and current
+
+How fragments turn into a release:
+
+- At release time, `bun run changelog:build` (and `bun run changelog:prerelease-notes`) pipes every pending fragment through `claude -p` to merge related items, drop noise, and rewrite into a clean user-facing release body. Write fragments as raw, informative notes — don't worry about polished prose, deduping across PRs, or line-by-line phrasing. The polish step handles all of that.
+- The polish step treats pending fragments as the final release outcome, not prerelease history. If a feature is added and then renamed or fixed before the stable cut, ship the final feature bullet instead of separate prerelease-only breaking/fix entries.
+- `CHANGELOG.md`, GitHub release notes, and prerelease notes all use short top-level items with one nested bullet per distinct change, instead of packing a release's worth of detail into a single paragraph bullet. An item with only one thing to say stays inline on the top-level bullet. Release notes and prerelease notes additionally cover user benefit and any useful action note in their nested bullets.
+- `internal` fragments stay in `CHANGELOG.md` (inside a collapsed `<details>` block) but are dropped from the GitHub release notes entirely.
+- The polished `CHANGELOG.md` and `release/release-notes.md` are committed and reviewed before tagging — edit the Markdown by hand if Claude misses something.
+
+Prerelease notes:
+
+- prerelease tags like `v0.11.3-beta.1` and `v0.11.3-rc.1` reuse the current pending fragments to generate `release/prerelease-notes.md`
+- from the second prerelease of a base version onward, the notes also open with a `## Changes since <previous tag>` section generated from the fragment diff against the previous beta/RC tag; keep fragment edits meaningful. Editorial-only rewording is filtered out of that section, while genuinely changed behavior and deleted fragments (reverted changes) are reported
+- existing prerelease notes are a reviewed baseline; later prerelease runs should replace stale beta/RC wording with the current outcome instead of appending fix churn
+- prerelease note generation does not consume fragments and does not update `CHANGELOG.md` or `docs-site/changelog.md`
+- the final stable release is the point where `bun run changelog:build` consumes fragments into the stable changelog and release notes

config.example.jsonc

@@ -2,22 +2,51 @@
  * SubMiner Example Configuration File
  *
  * This file is auto-generated from src/config/definitions.ts.
- * Copy to $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc) and edit as needed.
+ * Copy to %APPDATA%/SubMiner/config.jsonc on Windows, or $XDG_CONFIG_HOME/SubMiner/config.jsonc (or ~/.config/SubMiner/config.jsonc) on Linux/macOS.
  */
 {
+
   // ==========================================
-  // Overlay Auto-Start
-  // When overlay connects to mpv, automatically show overlay and hide mpv subtitles.
+  // Subtitle Selection
+  // Select primary and secondary mpv subtitle tracks from the overlay.
+  // Hot-reload: enabling or disabling updates the session shortcut immediately.
   // ==========================================
-  "auto_start_overlay": false, // When overlay connects to mpv, automatically show overlay and hide mpv subtitles. Values: true | false
+  "subtitleSelection": {
+    "enabled": false // Use the SubMiner modal to select primary and secondary subtitle tracks. When enabled, its shortcut overrides mpv subtitle selection. Values: true | false
+  }, // Select primary and secondary mpv subtitle tracks from the overlay.
+
+  // ==========================================
+  // Japanese Subtitle Generation
+  // Generate timed Japanese subtitles from local audio using whisper.cpp.
+  // Configure an existing GGML model path or explicitly download a SubMiner-managed model.
+  // Hot-reload: settings apply to the next generation or model download.
+  // ==========================================
+  "subtitleGeneration": {
+    "whisperPath": "", // Optional path override for whisper.cpp. Leave empty to find whisper-cli on PATH.
+    "modelPath": "", // Path to an existing multilingual whisper.cpp GGML model. Leave empty to use a SubMiner-managed model. A configured path always takes precedence.
+    "managedModel": "small", // Multilingual whisper.cpp model to use when modelPath is empty. Download it explicitly from the generation modal or launcher. Values: tiny | tiny-q5_1 | tiny-q8_0 | base | base-q5_1 | base-q8_0 | small | small-q5_1 | small-q8_0 | medium | medium-q5_0 | medium-q8_0 | large-v1 | large-v2 | large-v2-q5_0 | large-v2-q8_0 | large-v3 | large-v3-q5_0 | large-v3-turbo | large-v3-turbo-q5_0 | large-v3-turbo-q8_0
+    "threads": 4, // Positive integer CPU thread count for whisper.cpp Japanese transcription.
+    "ffmpegPath": "", // Optional FFmpeg path override for audio extraction. Leave empty to find ffmpeg on PATH.
+    "ffprobePath": "", // Optional FFprobe path override for audio tracks and timing. Leave empty to find ffprobe on PATH.
+    "vadModelPath": "", // Path to a whisper.cpp Silero VAD model. Enables dialogue-focused generation while retaining uncertain audible sections, which may include songs. Leave empty to transcribe the full audio.
+    "vadPath": "" // Optional speech detector executable override. With vadModelPath configured, leave empty to find whisper-vad-speech-segments or vad-speech-segments on PATH.
+  }, // Generate timed Japanese subtitles from local audio using whisper.cpp.
+
+  // ==========================================
+  // Visible Overlay Auto-Start
+  // Show the visible subtitle overlay automatically after managed mpv playback starts SubMiner.
+  // SubMiner can still auto-start in the background when this is false.
+  // ==========================================
+  "auto_start_overlay": true, // Show the visible subtitle overlay automatically when the bundled mpv plugin starts SubMiner. Values: true | false
 
   // ==========================================
   // Texthooker Server
-  // Control whether browser opens automatically for texthooker.
+  // Configure texthooker startup launch and browser opening behavior.
   // ==========================================
   "texthooker": {
-    "openBrowser": true, // Open browser setting. Values: true | false
-  }, // Control whether browser opens automatically for texthooker.
+    "launchAtStartup": false, // Launch texthooker server automatically when SubMiner starts. Values: true | false
+    "openBrowser": false // Open the texthooker page in the default browser when the server starts. Values: true | false
+  }, // Configure texthooker startup launch and browser opening behavior.
 
   // ==========================================
   // WebSocket Server
@@ -25,18 +54,162 @@
   // Auto mode disables built-in server if mpv_websocket is detected.
   // ==========================================
   "websocket": {
-    "enabled": "auto", // Built-in subtitle websocket server mode. Values: auto | true | false
-    "port": 6677, // Built-in subtitle websocket server port.
+    "enabled": false, // Built-in subtitle websocket server mode. Values: auto | true | false
+    "port": 6677 // Built-in subtitle websocket server port.
   }, // Built-in WebSocket server broadcasts subtitle text to connected clients.
 
+  // ==========================================
+  // Annotation WebSocket
+  // Dedicated annotated subtitle websocket for bundled texthooker and token-aware clients.
+  // Independent from websocket.auto and defaults to port 6678.
+  // ==========================================
+  "annotationWebsocket": {
+    "enabled": false, // Annotated subtitle websocket server enabled state. Values: true | false
+    "port": 6678 // Annotated subtitle websocket server port.
+  }, // Dedicated annotated subtitle websocket for bundled texthooker and token-aware clients.
+
   // ==========================================
   // Logging
   // Controls logging verbosity.
   // Set to debug for full runtime diagnostics.
+  // Hot-reload: logging.level and logging.files apply live while SubMiner is running.
   // ==========================================
   "logging": {
-    "level": "info", // Minimum log level for runtime logging. Values: debug | info | warn | error
-  }, // Controls logging verbosity. Keep this as an object; do not replace with a bare string.
+    "level": "warn", // Minimum log level for runtime logging. Values: debug | info | warn | error
+    "rotation": 7, // Number of days of app, launcher, and mpv logs to retain.
+    "files": {
+      "app": true, // Write SubMiner app runtime logs. Values: true | false
+      "launcher": true, // Write launcher command logs. Values: true | false
+      "mpv": false // Write mpv player logs. Enable temporarily when debugging mpv/plugin startup. Values: true | false
+    } // Files setting.
+  }, // Controls logging verbosity.
+
+  // ==========================================
+  // Controller Support
+  // Gamepad support for the visible overlay while keyboard-only mode is active.
+  // Use Alt+C to pick a preferred controller and remap actions inline with learn mode.
+  // Trigger input mode can be auto, digital-only, or analog-thresholded depending on the controller.
+  // Override controller.buttonIndices when your pad reports non-standard raw button numbers.
+  // ==========================================
+  "controller": {
+    "enabled": false, // Enable overlay controller support through the Chrome Gamepad API. Values: true | false
+    "preferredGamepadId": "", // Preferred controller id saved from the controller config modal.
+    "preferredGamepadLabel": "", // Preferred controller display label saved for diagnostics.
+    "smoothScroll": true, // Use smooth scrolling for controller-driven popup scroll input. Values: true | false
+    "scrollPixelsPerSecond": 900, // Base popup scroll speed for controller stick input.
+    "horizontalJumpPixels": 160, // Popup page-jump distance for controller jump input.
+    "stickDeadzone": 0.2, // Deadzone applied to controller stick axes.
+    "triggerInputMode": "auto", // How controller triggers are interpreted: auto, pressed-only, or thresholded analog. Values: auto | digital | analog
+    "triggerDeadzone": 0.5, // Minimum analog trigger value required when trigger input uses auto or analog mode.
+    "repeatDelayMs": 320, // Delay before repeating held controller actions.
+    "repeatIntervalMs": 120, // Repeat interval for held controller actions.
+    "buttonIndices": {
+      "select": 6, // Raw button index used for the controller select/minus/back button.
+      "buttonSouth": 0, // Raw button index used for controller south/A button input.
+      "buttonEast": 1, // Raw button index used for controller east/B button input.
+      "buttonWest": 2, // Raw button index used for controller west/X button input.
+      "buttonNorth": 3, // Raw button index used for controller north/Y button input.
+      "leftShoulder": 4, // Raw button index used for controller left shoulder input.
+      "rightShoulder": 5, // Raw button index used for controller right shoulder input.
+      "leftStickPress": 9, // Raw button index used for controller L3 input.
+      "rightStickPress": 10, // Raw button index used for controller R3 input.
+      "leftTrigger": 6, // Raw button index used for controller L2 input.
+      "rightTrigger": 7 // Raw button index used for controller R2 input.
+    }, // Semantic button-name reference mapping used for debug output. Updating it does not rewrite existing raw binding descriptors.
+    "bindings": {
+      "toggleLookup": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 0 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for toggling lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "closeLookup": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 1 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for closing lookup. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "toggleKeyboardOnlyMode": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 3 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for toggling keyboard-only mode. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "mineCard": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 2 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for mining the active card. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "quitMpv": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 6 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for quitting mpv. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "previousAudio": {
+        "kind": "none" // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+      }, // Controller binding descriptor for previous Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "nextAudio": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 5 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for next Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "playCurrentAudio": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 4 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for playing the current Yomitan audio. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "toggleMpvPause": {
+        "kind": "button", // Discrete binding input source kind. When kind is "axis", set both axisIndex and direction. Values: none | button | axis
+        "buttonIndex": 9 // Raw button index captured for this discrete controller action.
+      }, // Controller binding descriptor for toggling mpv play/pause. Use Alt+C learn mode or set a raw button/axis descriptor manually. If kind is "axis", direction is required.
+      "leftStickHorizontal": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 0, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "horizontal" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      }, // Axis binding descriptor used for left/right token selection. Use Alt+C learn mode or set a raw axis descriptor manually.
+      "leftStickVertical": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 1, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "vertical" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      }, // Axis binding descriptor used for primary popup scrolling. Use Alt+C learn mode or set a raw axis descriptor manually.
+      "rightStickHorizontal": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 3, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "none" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      }, // Axis binding descriptor reserved for alternate right-stick mappings. Use Alt+C learn mode or set a raw axis descriptor manually.
+      "rightStickVertical": {
+        "kind": "axis", // Analog binding input source kind. Values: none | axis
+        "axisIndex": 4, // Raw axis index captured for this analog controller action.
+        "dpadFallback": "none" // Optional D-pad fallback used when this analog controller action should also read D-pad input. Values: none | horizontal | vertical
+      } // Axis binding descriptor used for popup page jumps. Use Alt+C learn mode or set a raw axis descriptor manually.
+    }, // Raw controller binding descriptors saved by Alt+C learn mode. For discrete axis bindings, kind "axis" requires axisIndex and direction.
+    "profiles": {} // Per-controller binding and button-index overrides keyed by the controller id reported by the Gamepad API.
+  }, // Gamepad support for the visible overlay while keyboard-only mode is active.
+
+  // ==========================================
+  // Startup Warmups
+  // Background warmup controls for MeCab, Yomitan, dictionaries, and Jellyfin session.
+  // Disable individual warmups to defer load until first real usage.
+  // lowPowerMode defers all warmups except Yomitan extension.
+  // ==========================================
+  "startupWarmups": {
+    "lowPowerMode": false, // Defer startup warmups except Yomitan extension. Values: true | false
+    "mecab": true, // Warm up MeCab tokenizer at startup. Values: true | false
+    "yomitanExtension": true, // Warm up Yomitan extension at startup. Values: true | false
+    "subtitleDictionaries": true, // Warm up subtitle dictionaries at startup. Values: true | false
+    "jellyfinRemoteSession": false // Warm up Jellyfin remote session at startup. Values: true | false
+  }, // Background warmup controls for MeCab, Yomitan, dictionaries, and Jellyfin session.
+
+  // ==========================================
+  // Updates
+  // Automatic update check behavior.
+  // Manual checks from the tray or launcher are always allowed.
+  // ==========================================
+  "updates": {
+    "enabled": true, // Run automatic update checks in the background. Values: true | false
+    "checkIntervalHours": 24, // Minimum hours between automatic update checks.
+    "notificationType": "overlay", // How SubMiner announces available updates. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
+    "channel": "stable" // Release channel used for update checks. Values: stable | prerelease
+  }, // Automatic update check behavior.
+
+  // ==========================================
+  // Notifications
+  // Overlay notification display behavior.
+  // Hot-reload: position changes apply to the next overlay notification.
+  // ==========================================
+  "notifications": {
+    "overlayPosition": "top-right" // Position for in-overlay notification cards. Values: top-left | top | top-right
+  }, // Overlay notification display behavior.
 
   // ==========================================
   // Keyboard Shortcuts
@@ -44,51 +217,206 @@
   // Hot-reload: shortcut changes apply live and update the session help modal on reopen.
   // ==========================================
   "shortcuts": {
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Toggle visible overlay global setting.
-    "copySubtitle": "CommandOrControl+C", // Copy subtitle setting.
-    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Copy subtitle multiple setting.
-    "updateLastCardFromClipboard": "CommandOrControl+V", // Update last card from clipboard setting.
-    "triggerFieldGrouping": "CommandOrControl+G", // Trigger field grouping setting.
-    "triggerSubsync": "Ctrl+Alt+S", // Trigger subsync setting.
-    "mineSentence": "CommandOrControl+S", // Mine sentence setting.
-    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Mine sentence multiple setting.
+    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.
+    "copySubtitle": "CommandOrControl+C", // Accelerator that copies the current subtitle line to the clipboard.
+    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.
+    "updateLastCardFromClipboard": "CommandOrControl+V", // Accelerator that updates the last mined Anki card using the current clipboard contents.
+    "triggerFieldGrouping": "CommandOrControl+G", // Accelerator that triggers Kiku field grouping on duplicate cards.
+    "triggerSubsync": "Ctrl+Alt+S", // Accelerator that triggers subsync against the active subtitle file.
+    "mineSentence": "CommandOrControl+S", // Accelerator that mines the current sentence as a new Anki card.
+    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Accelerator that mines consecutive sentences while the multi-mine window stays open.
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
-    "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
-    "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
-    "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
+    "toggleSecondarySub": "CommandOrControl+Shift+V", // Accelerator that toggles the secondary subtitle bar visibility.
+    "markAudioCard": "CommandOrControl+Shift+A", // Accelerator that marks the last mined card as an audio card.
+    "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).
+    "openSubtitleSelection": "g-s", // Open subtitle selection when enabled. Use g-s to press g then s. Set null to unbind.
+    "openSubtitleGeneration": "Ctrl+Shift+G", // Accelerator that opens the standalone Japanese subtitle generation modal.
+    "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.
+    "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.
 
   // ==========================================
   // Keybindings (MPV Commands)
-  // Extra keybindings that are merged with built-in defaults.
+  // Default and custom keybindings that are merged with built-in defaults.
   // Set command to null to disable a default keybinding.
   // Hot-reload: keybinding changes apply live and update the session help modal on reopen.
   // ==========================================
-  "keybindings": [], // Extra keybindings that are merged with built-in defaults.
+  "keybindings": [
+    {
+      "key": "Space", // Key setting.
+      "command": [
+        "cycle",
+        "pause"
+      ] // Command setting.
+    },
+    {
+      "key": "KeyF", // Key setting.
+      "command": [
+        "cycle",
+        "fullscreen"
+      ] // Command setting.
+    },
+    {
+      "key": "KeyJ", // Key setting.
+      "command": [
+        "cycle",
+        "sid"
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyJ", // Key setting.
+      "command": [
+        "cycle",
+        "secondary-sid"
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowRight", // Key setting.
+      "command": [
+        "seek",
+        5
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowLeft", // Key setting.
+      "command": [
+        "seek",
+        -5
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowUp", // Key setting.
+      "command": [
+        "seek",
+        60
+      ] // Command setting.
+    },
+    {
+      "key": "ArrowDown", // Key setting.
+      "command": [
+        "seek",
+        -60
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyH", // Key setting.
+      "command": [
+        "sub-seek",
+        -1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyL", // Key setting.
+      "command": [
+        "sub-seek",
+        1
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Shift+ArrowLeft", // Key setting.
+      "command": [
+        "sub-step",
+        -1
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Shift+ArrowRight", // Key setting.
+      "command": [
+        "sub-step",
+        1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        -0.1
+      ] // Command setting.
+    },
+    {
+      "key": "Shift+KeyZ", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
+      ] // Command setting.
+    },
+    {
+      "key": "KeyX", // Key setting.
+      "command": [
+        "add",
+        "sub-delay",
+        0.1
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Alt+KeyC", // Key setting.
+      "command": [
+        "__youtube-picker-open"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Alt+KeyP", // Key setting.
+      "command": [
+        "__playlist-browser-open"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Shift+KeyH", // Key setting.
+      "command": [
+        "__replay-subtitle"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+Shift+KeyL", // Key setting.
+      "command": [
+        "__play-next-subtitle"
+      ] // Command setting.
+    },
+    {
+      "key": "KeyQ", // Key setting.
+      "command": [
+        "quit"
+      ] // Command setting.
+    },
+    {
+      "key": "Ctrl+KeyW", // Key setting.
+      "command": [
+        "quit"
+      ] // Command setting.
+    }
+  ], // Default and custom keybindings that are merged with built-in defaults.
 
   // ==========================================
   // Secondary Subtitles
   // Dual subtitle track options.
-  // Used by subminer YouTube subtitle generation as secondary language preferences.
+  // Used by managed subtitle loading as secondary language preferences for local and YouTube playback.
   // Hot-reload: defaultMode updates live while SubMiner is running.
   // ==========================================
   "secondarySub": {
-    "secondarySubLanguages": [], // Secondary sub languages setting.
-    "autoLoadSecondarySub": false, // Auto load secondary sub setting. Values: true | false
-    "defaultMode": "hover", // Default mode setting.
+    "secondarySubLanguages": [], // Language code priority list used to auto-select a secondary subtitle track when available.
+    "autoLoadSecondarySub": false, // Automatically load a matching secondary subtitle when the primary subtitle loads. Values: true | false
+    "defaultMode": "hover" // Default visibility mode for the secondary subtitle bar. Values: hidden | visible | hover
   }, // Dual subtitle track options.
 
   // ==========================================
-  // Auto Subtitle Sync
+  // Subtitle Sync
   // Subsync engine and executable paths.
+  // Hot-reload: subsync changes apply to the next subtitle sync run.
   // ==========================================
   "subsync": {
-    "defaultMode": "auto", // Subsync default mode. Values: auto | manual
-    "alass_path": "", // Alass path setting.
-    "ffsubsync_path": "", // Ffsubsync path setting.
-    "ffmpeg_path": "", // Ffmpeg path setting.
-    "replace": true, // Replace active subtitle file when synchronization succeeds.
+    "alass_path": "", // Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffsubsync_path": "", // Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffmpeg_path": "", // Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.
+    "replace": true // Replace the active subtitle file when sync completes. Values: true | false
   }, // Subsync engine and executable paths.
 
   // ==========================================
@@ -96,7 +424,7 @@
   // Initial vertical subtitle position from the bottom.
   // ==========================================
   "subtitlePosition": {
-    "yPercent": 10, // Y percent setting.
+    "yPercent": 10 // Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.
   }, // Initial vertical subtitle position from the bottom.
 
   // ==========================================
@@ -105,166 +433,321 @@
   // Hot-reload: subtitle style changes apply live without restarting SubMiner.
   // ==========================================
   "subtitleStyle": {
+    "primaryDefaultMode": "visible", // Default primary subtitle bar visibility mode. hidden hides it, visible shows it, hover reveals it on hover. Values: hidden | visible | hover
+    "css": {
+      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP", // Font family setting.
+      "color": "#cad3f5", // Color setting.
+      "background-color": "transparent", // Background color setting.
+      "font-size": "35px", // Font size setting.
+      "font-weight": "600", // Font weight setting.
+      "font-style": "normal", // Font style setting.
+      "line-height": "1.35", // Line height setting.
+      "letter-spacing": "-0.01em", // Letter spacing setting.
+      "word-spacing": "0", // Word spacing setting.
+      "font-kerning": "normal", // Font kerning setting.
+      "text-rendering": "geometricPrecision", // Text rendering setting.
+      "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)", // Text shadow setting.
+      "backdrop-filter": "blur(6px)", // Backdrop filter setting.
+      "--subtitle-hover-token-color": "#f4dbd6", // Subtitle hover token color setting.
+      "--subtitle-hover-token-background-color": "transparent" // Subtitle hover token background color setting.
+    }, // CSS declaration object applied to primary subtitles after normal subtitle style defaults.
     "enableJlpt": false, // Enable JLPT vocabulary level underlines. When disabled, JLPT tagging lookup and underlines are skipped. Values: true | false
     "preserveLineBreaks": false, // Preserve line breaks in visible overlay subtitle rendering. When false, line breaks are flattened to spaces for a single-line flow. Values: true | false
     "autoPauseVideoOnHover": true, // Automatically pause mpv playback while hovering subtitle text, then resume on leave. Values: true | false
-    "hoverTokenColor": "#f4dbd6", // Hex color used for hovered subtitle token highlight in mpv.
-    "hoverTokenBackgroundColor": "rgba(54, 58, 79, 0.84)", // CSS color used for hovered subtitle token background highlight in mpv.
-    "fontFamily": "M PLUS 1 Medium, Source Han Sans JP, Noto Sans CJK JP", // Font family setting.
-    "fontSize": 35, // Font size setting.
-    "fontColor": "#cad3f5", // Font color setting.
-    "fontWeight": "600", // Font weight setting.
-    "lineHeight": 1.35, // Line height setting.
-    "letterSpacing": "-0.01em", // Letter spacing setting.
-    "wordSpacing": 0, // Word spacing setting.
-    "fontKerning": "normal", // Font kerning setting.
-    "textRendering": "geometricPrecision", // Text rendering setting.
-    "textShadow": "0 3px 10px rgba(0,0,0,0.69)", // Text shadow setting.
-    "fontStyle": "normal", // Font style setting.
-    "backgroundColor": "rgb(30, 32, 48, 0.88)", // Background color setting.
-    "backdropFilter": "blur(6px)", // Backdrop filter setting.
-    "nPlusOneColor": "#c6a0f6", // N plus one color setting.
-    "knownWordColor": "#a6da95", // Known word color setting.
+    "autoPauseVideoOnYomitanPopup": true, // Automatically pause mpv playback while Yomitan popup is open, then resume when popup closes. Values: true | false
+    "primaryVisibleOnYomitanPopup": true, // Keep the primary subtitle bar visible while a Yomitan popup is open when primary subtitles are in hover mode. Values: true | false
+    "nameMatchEnabled": false, // Enable character dictionary sync and subtitle token coloring for character-name matches. Values: true | false
+    "nameMatchImagesEnabled": false, // Show small character portraits beside subtitle tokens matched from the SubMiner character dictionary. Values: true | false
+    "nameMatchColor": "#f5bde6", // Hex color used when a subtitle token matches an entry from the SubMiner character dictionary.
+    "nPlusOneColor": "#c6a0f6", // Color used for the single N+1 target token subtitle highlight.
+    "knownWordColor": "#a6da95", // Color used for known-word subtitle highlights.
+    "knownWordMaturityColors": {
+      "new": "#ee99a0", // Color for known words whose Anki cards are new (never reviewed), when maturity highlighting is enabled.
+      "learning": "#b7bdf8", // Color for known words whose Anki cards are in (re)learning, when maturity highlighting is enabled.
+      "young": "#91d7e3", // Color for known words whose Anki cards are in review below the mature threshold, when maturity highlighting is enabled.
+      "mature": "#a6da95" // Color for known words whose Anki cards are at or above the mature interval threshold, when maturity highlighting is enabled.
+    }, // Known word maturity colors setting.
     "jlptColors": {
       "N1": "#ed8796", // N1 setting.
       "N2": "#f5a97f", // N2 setting.
       "N3": "#f9e2af", // N3 setting.
-      "N4": "#a6e3a1", // N4 setting.
-      "N5": "#8aadf4", // N5 setting.
+      "N4": "#8bd5ca", // N4 setting.
+      "N5": "#8aadf4" // N5 setting.
     }, // Jlpt colors setting.
     "frequencyDictionary": {
       "enabled": false, // Enable frequency-dictionary-based highlighting based on token rank. Values: true | false
-      "sourcePath": "", // Optional absolute path to a frequency dictionary directory. If empty, SubMiner searches installed/default frequency-dictionary locations.
-      "topX": 1000, // Only color tokens with frequency rank <= topX (default: 1000).
+      "sourcePath": "", // Optional absolute path to a frequency dictionary directory. If empty, built-in discovery search paths are used.
+      "topX": 10000, // Only color tokens with frequency rank <= topX (default: 10000).
       "mode": "single", // single: use one color for all matching tokens. banded: use color ramp by frequency band. Values: single | banded
-      "matchMode": "headword", // Frequency lookup text selection mode. Values: headword | surface
+      "matchMode": "headword", // headword: frequency lookup uses dictionary form. surface: lookup uses subtitle-visible token text. Values: headword | surface
       "singleColor": "#f5a97f", // Color used when frequencyDictionary.mode is `single`.
-      "bandedColors": ["#ed8796", "#f5a97f", "#f9e2af", "#a6e3a1", "#8aadf4"], // Five colors used for rank bands when mode is `banded` (from most common to least within topX).
+      "bandedColors": [
+        "#ed8796",
+        "#f5a97f",
+        "#f9e2af",
+        "#8bd5ca",
+        "#8aadf4"
+      ] // Five colors used for rank bands when mode is `banded` (from most common to least within topX).
     }, // Frequency dictionary setting.
     "secondary": {
-      "fontFamily": "Inter, Noto Sans, Helvetica Neue, sans-serif", // Font family setting.
-      "fontSize": 24, // Font size setting.
-      "fontColor": "#cad3f5", // Font color setting.
-      "lineHeight": 1.35, // Line height setting.
-      "letterSpacing": "-0.01em", // Letter spacing setting.
-      "wordSpacing": 0, // Word spacing setting.
-      "fontKerning": "normal", // Font kerning setting.
-      "textRendering": "geometricPrecision", // Text rendering setting.
-      "textShadow": "0 3px 10px rgba(0,0,0,0.69)", // Text shadow setting.
-      "backgroundColor": "transparent", // Background color setting.
-      "backdropFilter": "blur(6px)", // Backdrop filter setting.
-      "fontWeight": "normal", // Font weight setting.
-      "fontStyle": "normal", // Font style setting.
-    }, // Secondary setting.
+      "css": {
+        "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP", // Font family setting.
+        "color": "#cad3f5", // Color setting.
+        "background-color": "transparent", // Background color setting.
+        "font-size": "24px", // Font size setting.
+        "font-weight": "600", // Font weight setting.
+        "font-style": "normal", // Font style setting.
+        "line-height": "1.35", // Line height setting.
+        "letter-spacing": "-0.01em", // Letter spacing setting.
+        "word-spacing": "0", // Word spacing setting.
+        "font-kerning": "normal", // Font kerning setting.
+        "text-rendering": "geometricPrecision", // Text rendering setting.
+        "text-shadow": "-1px -1px 2px rgba(0,0,0,0.95), 1px -1px 2px rgba(0,0,0,0.95), -1px 1px 2px rgba(0,0,0,0.95), 1px 1px 2px rgba(0,0,0,0.95), 0 0 8px rgba(0,0,0,0.5)", // Text shadow setting.
+        "backdrop-filter": "blur(6px)" // Backdrop filter setting.
+      } // CSS declaration object applied to secondary subtitles after normal subtitle style defaults.
+    } // Secondary setting.
   }, // Primary and secondary subtitle styling.
 
+  // ==========================================
+  // Subtitle Sidebar
+  // Parsed-subtitle sidebar cue list styling, behavior, and toggle key.
+  // Hot-reload: subtitle sidebar changes apply live without restarting SubMiner.
+  // ==========================================
+  "subtitleSidebar": {
+    "enabled": true, // Enable the subtitle sidebar feature for parsed subtitle sources. Values: true | false
+    "autoOpen": false, // Automatically open the subtitle sidebar once during overlay startup. Values: true | false
+    "layout": "overlay", // Render the subtitle sidebar as a floating overlay or reserve space inside mpv. Values: overlay | embedded
+    "toggleKey": "Backslash", // KeyboardEvent.code used to toggle the subtitle sidebar open and closed.
+    "pauseVideoOnHover": true, // Pause mpv while hovering the subtitle sidebar, then resume on leave. Values: true | false
+    "autoScroll": true, // Auto-scroll the active subtitle cue into view while playback advances. Values: true | false
+    "css": {
+      "font-family": "Hiragino Sans, M PLUS 1, Source Han Sans JP, Noto Sans CJK JP", // Font family setting.
+      "color": "#cad3f5", // Color setting.
+      "background-color": "rgba(73, 77, 100, 0.9)", // Background color setting.
+      "font-size": "16px", // Font size setting.
+      "opacity": "0.95", // Opacity setting.
+      "--subtitle-sidebar-max-width": "420px", // Subtitle sidebar max width setting.
+      "--subtitle-sidebar-timestamp-color": "#a5adcb", // Subtitle sidebar timestamp color setting.
+      "--subtitle-sidebar-active-line-color": "#f5bde6", // Subtitle sidebar active line color setting.
+      "--subtitle-sidebar-active-background-color": "rgba(138, 173, 244, 0.22)", // Subtitle sidebar active background color setting.
+      "--subtitle-sidebar-hover-background-color": "rgba(54, 58, 79, 0.84)" // Subtitle sidebar hover background color setting.
+    } // CSS declaration object applied to the subtitle sidebar. Includes color, background-color, and all font properties.
+  }, // Parsed-subtitle sidebar cue list styling, behavior, and toggle key.
+
+  // ==========================================
+  // Shared AI Provider
+  // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
+  // ==========================================
+  "ai": {
+    "enabled": false, // Enable shared OpenAI-compatible AI provider features. Values: true | false
+    "apiKey": "", // Static API key for the shared OpenAI-compatible AI provider.
+    "apiKeyCommand": "", // Shell command used to resolve the shared AI provider API key.
+    "model": "openai/gpt-4o-mini", // Default model identifier requested from the shared AI provider.
+    "baseUrl": "https://openrouter.ai/api", // Base URL for the shared OpenAI-compatible AI provider.
+    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // Default system prompt sent with shared AI provider requests.
+    "requestTimeoutMs": 15000 // Timeout in milliseconds for shared AI provider requests.
+  }, // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
+
   // ==========================================
   // AnkiConnect Integration
   // Automatic Anki updates and media generation options.
-  // Hot-reload: AI translation settings update live while SubMiner is running.
+  // Hot-reload: ankiConnect.ai.enabled, media.normalizeAudio/mirrorMpvVolume/reviewTiming, knownWords, nPlusOne, fields.word/audio/wordAudio/image/sentence/miscInfo, behavior.autoUpdateNewCards, isLapis.sentenceCardModel, isKiku.fieldGrouping, isSenren.fieldGrouping, and lapisKiku.wordCardKind update live while SubMiner is running.
+  // Shared AI provider transport settings are read from top-level ai and typically require restart.
   // Most other AnkiConnect settings still require restart.
   // ==========================================
   "ankiConnect": {
-    "enabled": false, // Enable AnkiConnect integration. Values: true | false
-    "url": "http://127.0.0.1:8765", // Url setting.
+    "enabled": true, // Enable AnkiConnect integration. Values: true | false
+    "url": "http://127.0.0.1:8765", // Base URL of the AnkiConnect HTTP server.
     "pollingRate": 3000, // Polling interval in milliseconds.
     "proxy": {
-      "enabled": false, // Enable local AnkiConnect-compatible proxy for push-based auto-enrichment. Values: true | false
+      "enabled": true, // Enable local AnkiConnect-compatible proxy for push-based auto-enrichment. Values: true | false
       "host": "127.0.0.1", // Bind host for local AnkiConnect proxy.
       "port": 8766, // Bind port for local AnkiConnect proxy.
-      "upstreamUrl": "http://127.0.0.1:8765", // Upstream AnkiConnect URL proxied by local AnkiConnect proxy.
+      "upstreamUrl": "http://127.0.0.1:8765" // Upstream AnkiConnect URL proxied by local AnkiConnect proxy.
     }, // Proxy setting.
-    "tags": ["SubMiner"], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
+    "tags": [
+      "SubMiner"
+    ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
+    "deck": "", // Restrict duplicate detection and card enrichment to this Anki deck. Leave empty to use the Yomitan mining deck when available.
     "fields": {
-      "audio": "ExpressionAudio", // Audio setting.
-      "image": "Picture", // Image setting.
-      "sentence": "Sentence", // Sentence setting.
-      "miscInfo": "MiscInfo", // Misc info setting.
-      "translation": "SelectionText", // Translation setting.
+      "word": "Expression", // Card field for the mined word or expression text.
+      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "wordAudio": "ExpressionAudio", // Existing word-audio field read to time the frozen first frame of animated images. This mapping is only used for synchronization.
+      "image": "Picture", // Card field that receives the captured screenshot or animated image.
+      "sentence": "Sentence", // Card field that receives the source sentence text.
+      "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
+      "translation": "SelectionText" // Card field that receives the current selection or translated text.
     }, // Fields setting.
     "ai": {
-      "enabled": false, // Enabled setting. Values: true | false
-      "alwaysUseAiTranslation": false, // Always use ai translation setting. Values: true | false
-      "apiKey": "", // Api key setting.
-      "model": "openai/gpt-4o-mini", // Model setting.
-      "baseUrl": "https://openrouter.ai/api", // Base url setting.
-      "targetLanguage": "English", // Target language setting.
-      "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // System prompt setting.
+      "enabled": false, // Enable AI provider usage for Anki translation/enrichment flows. Values: true | false
+      "model": "", // Optional model override for Anki AI translation/enrichment flows.
+      "systemPrompt": "" // Optional system prompt override for Anki AI translation/enrichment flows.
     }, // Ai setting.
     "media": {
-      "generateAudio": true, // Generate audio setting. Values: true | false
-      "generateImage": true, // Generate image setting. Values: true | false
-      "imageType": "static", // Image type setting.
-      "imageFormat": "jpg", // Image format setting.
-      "imageQuality": 92, // Image quality setting.
-      "animatedFps": 10, // Animated fps setting.
-      "animatedMaxWidth": 640, // Animated max width setting.
-      "animatedCrf": 35, // Animated crf setting.
-      "audioPadding": 0.5, // Audio padding setting.
-      "fallbackDuration": 3, // Fallback duration setting.
-      "maxMediaDuration": 30, // Max media duration setting.
+      "generateAudio": true, // Generate sentence audio for mined cards. Values: true | false
+      "generateImage": true, // Generate screenshot or animated image for mined cards. Values: true | false
+      "imageType": "static", // Image capture type: "static" for a single still frame, "avif" for an animated AVIF. Values: static | avif
+      "imageFormat": "jpg", // Encoding format used when imageType is "static". Values: jpg | png | webp
+      "imageQuality": 92, // Quality (0-100) used for lossy static image encoders.
+      "imageMaxWidth": 0, // Maximum width for static images, in pixels. Set to 0 to preserve the source resolution.
+      "imageMaxHeight": 0, // Maximum height for static images, in pixels. Set to 0 to preserve the source resolution.
+      "animatedFps": 10, // Target frame rate for animated AVIF captures.
+      "animatedMaxWidth": 640, // Maximum width applied to animated AVIF captures.
+      "animatedMaxHeight": 0, // Maximum height for animated AVIF captures, in pixels. Set to 0 to preserve aspect ratio.
+      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
+      "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
+      "normalizeAudio": true, // Normalize generated sentence audio loudness during media extraction. Changes apply live. Values: true | false
+      "mirrorMpvVolume": true, // Apply mpv's current software volume curve to generated sentence audio. Changes apply live. Values: true | false
+      "reviewTiming": false, // Review and preview subtitle media timing before SubMiner creates or enriches a mined card. Values: true | false
+      "audioPadding": 0, // Seconds of padding appended to both ends of generated sentence audio and animated AVIF clips.
+      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds. 0 disables the cap.
     }, // Media setting.
+    "knownWords": {
+      "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
+      "maturityEnabled": false, // Color known-word highlights by Anki card maturity (new, learning, young, mature) instead of a single color. Requires known-word highlighting. Values: true | false
+      "matureThresholdDays": 21, // Card interval in days at which a known word counts as mature (Anki convention: 21).
+      "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
+      "addMinedWordsImmediately": true, // Immediately append newly mined card words into the known-word cache. Values: true | false
+      "matchMode": "headword", // Known-word matching strategy for subtitle annotations. Cache matches always receive known-word highlighting even when POS filters suppress other annotation types. Values: headword | surface
+      "decks": {} // Decks and expression/word fields for known-word cache. Object mapping deck names to arrays of field names to extract, e.g. { "Kaishi 1.5k": ["Word"] }. Reading fields (Reading, Word Reading, ExpressionReading) are always probed so cached words match only in the reading their note teaches; words from notes without readings match in any reading.
+    }, // Known words setting.
     "behavior": {
-      "overwriteAudio": true, // Overwrite audio setting. Values: true | false
-      "overwriteImage": true, // Overwrite image setting. Values: true | false
-      "mediaInsertMode": "append", // Media insert mode setting.
-      "highlightWord": true, // Highlight word setting. Values: true | false
-      "notificationType": "osd", // Notification type setting.
-      "autoUpdateNewCards": true, // Automatically update newly added cards. Values: true | false
+      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
+      "overwriteImage": true, // When updating an existing card, overwrite the image field instead of skipping it. Values: true | false
+      "mediaInsertMode": "append", // Whether new media is appended after or prepended before existing field contents on update. Values: append | prepend
+      "highlightWord": true, // Bold the mined word inside the sentence field on the saved Anki card. Values: true | false
+      "notificationType": "overlay", // Notification surface used to announce mining and update outcomes. overlay shows notifications on the overlay, system uses OS notifications, both uses overlay and system. osd and osd-system are legacy config-file-only values. Values: overlay | system | both | none | osd | osd-system
+      "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
     }, // Behavior setting.
     "nPlusOne": {
-      "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
-      "refreshMinutes": 1440, // Minutes between known-word cache refreshes.
-      "matchMode": "headword", // Known-word matching strategy for N+1 highlighting. Values: headword | surface
-      "decks": [], // Decks used for N+1 known-word cache scope. Supports one or more deck names.
-      "minSentenceWords": 3, // Minimum sentence word count required for N+1 targeting (default: 3).
-      "nPlusOne": "#c6a0f6", // Color used for the single N+1 target token highlight.
-      "knownWord": "#a6da95", // Color used for legacy known-word highlights.
+      "enabled": false, // Enable N+1 subtitle highlighting (highlights the one unknown word in a sentence). Requires known-word cache data. Values: true | false
+      "minSentenceWords": 3 // Minimum sentence word count required for N+1 targeting (default: 3).
     }, // N plus one setting.
     "metadata": {
-      "pattern": "[SubMiner] %f (%t)", // Pattern setting.
+      "pattern": "[SubMiner] %f (%t)" // Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).
     }, // Metadata setting.
     "isLapis": {
-      "enabled": false, // Enabled setting. Values: true | false
-      "sentenceCardModel": "Japanese sentences", // Sentence card model setting.
+      "enabled": false, // Enable Lapis-specific mining behaviors and sentence card model targeting. Values: true | false
+      "sentenceCardModel": "Lapis" // Note type name used by Lapis sentence cards.
     }, // Is lapis setting.
     "isKiku": {
-      "enabled": false, // Enabled setting. Values: true | false
+      "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
-      "deleteDuplicateInAuto": true, // Delete duplicate in auto setting. Values: true | false
+      "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     }, // Is kiku setting.
+    "isSenren": {
+      "enabled": false, // Enable Senren-specific duplicate handling (scene-switching field grouping, including miscInfo grouping). Mutually exclusive with isKiku.enabled. Values: true | false
+      "fieldGrouping": "auto", // Senren duplicate-card field grouping mode (scene switching). Values: auto | manual | disabled
+      "deleteDuplicateInAuto": true // When Senren field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
+    }, // Is senren setting.
+    "lapisKiku": {
+      "wordCardKind": "word-and-sentence" // Card-type flag SubMiner marks on Kiku/Lapis word cards. Only one flag is set at a time; the others are cleared. Requires isKiku.enabled or isLapis.enabled. Values: word-and-sentence | click | sentence | audio | none
+    } // Lapis kiku setting.
   }, // Automatic Anki updates and media generation options.
 
   // ==========================================
   // Jimaku
   // Jimaku API configuration and defaults.
+  // Hot-reload: Jimaku changes apply to the next Jimaku request.
   // ==========================================
   "jimaku": {
-    "apiBaseUrl": "https://jimaku.cc", // Api base url setting.
+    "apiBaseUrl": "https://jimaku.cc", // Base URL of the Jimaku subtitle search API.
+    "apiKey": "", // Jimaku API key. Optional but recommended for higher rate limits. Get one for free at https://jimaku.cc.
+    "apiKeyCommand": "", // Shell command that prints the Jimaku API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
     "languagePreference": "ja", // Preferred language used in Jimaku search. Values: ja | en | none
-    "maxEntryResults": 10, // Maximum Jimaku search results returned.
+    "maxEntryResults": 10 // Maximum Jimaku search results returned.
   }, // Jimaku API configuration and defaults.
 
   // ==========================================
-  // YouTube Subtitle Generation
-  // Defaults for subminer YouTube subtitle extraction/transcription mode.
+  // 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.
   // ==========================================
-  "youtubeSubgen": {
-    "mode": "automatic", // YouTube subtitle generation mode for the launcher script. Values: automatic | preprocess | off
-    "whisperBin": "", // Path to whisper.cpp CLI used as fallback transcription engine.
-    "whisperModel": "", // Path to whisper model used for fallback transcription.
-    "primarySubLanguages": ["ja", "jpn"], // Comma-separated primary subtitle language priority used by the launcher.
-  }, // Defaults for subminer YouTube subtitle extraction/transcription mode.
+  "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.
+
+  // ==========================================
+  // TMDB
+  // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+  // Hot-reload: TMDB changes apply to the next TMDB request.
+  // ==========================================
+  "tmdb": {
+    "apiKey": "", // Your own TMDB API key or read access token for live-action posters and synopses in the stats Library. Release builds bundle a project key, so set this only to use your own quota or when running from source (free under Settings > API on themoviedb.org).
+    "apiKeyCommand": "" // Shell command that prints the TMDB API key to stdout. Used instead of apiKey to avoid storing the key in plain text.
+  }, // TMDB (The Movie Database) metadata for live-action dramas and movies in the stats Library: posters, synopses, and grouping by show.
+
+  // ==========================================
+  // YouTube Playback Settings
+  // Defaults for managed subtitle language preferences and YouTube subtitle loading.
+  // Hot-reload: primarySubLanguages applies to the next YouTube subtitle load.
+  // ==========================================
+  "youtube": {
+    "primarySubLanguages": [
+      "ja",
+      "jpn"
+    ], // Comma-separated primary subtitle language priority for managed subtitle auto-selection.
+    "mediaCache": {
+      "mode": "direct", // How YouTube card audio/images are extracted. Values: direct | background
+      "maxHeight": 720 // Maximum video height downloaded for the YouTube background media cache. Set to 0 for unlimited.
+    } // Media cache setting.
+  }, // Defaults for managed subtitle language preferences and YouTube subtitle loading.
 
   // ==========================================
   // Anilist
   // Anilist API credentials and update behavior.
+  // Includes optional auto-sync for a merged MRU-based character dictionary in bundled Yomitan.
+  // Character dictionaries are keyed by AniList media ID (no season/franchise merge).
   // ==========================================
   "anilist": {
     "enabled": false, // Enable AniList post-watch progress updates. Values: true | false
     "accessToken": "", // Optional explicit AniList access token override; leave empty to use locally stored token from setup.
+    "characterDictionary": {
+      "maxLoaded": 3, // Maximum number of most-recently-used anime snapshots included in the merged Yomitan character dictionary.
+      "profileScope": "all", // Yomitan profile scope for character dictionary settings updates. Values: all | active
+      "collapsibleSections": {
+        "description": false, // Open the Description section by default in character dictionary glossary entries. Values: true | false
+        "characterInformation": false, // Open the Character Information section by default in character dictionary glossary entries. Values: true | false
+        "voicedBy": false // Open the Voiced by section by default in character dictionary glossary entries. Values: true | false
+      } // Collapsible sections setting.
+    } // Character dictionary setting.
   }, // Anilist API credentials and update behavior.
 
+  // ==========================================
+  // Yomitan
+  // Optional external Yomitan profile integration.
+  // Setting yomitan.externalProfilePath switches SubMiner to read-only external-profile mode.
+  // For GameSentenceMiner on Linux, the default overlay profile is usually ~/.config/gsm_overlay.
+  // In external-profile mode SubMiner will not import, delete, or modify Yomitan dictionaries/settings.
+  // ==========================================
+  "yomitan": {
+    "externalProfilePath": "" // Optional external Yomitan Electron profile path to use in read-only mode for shared dictionaries/settings. Example: ~/.config/gsm_overlay
+  }, // Optional external Yomitan profile integration.
+
+  // ==========================================
+  // MPV Launcher
+  // SubMiner-managed mpv launch and bundled plugin options.
+  // Set mpv.socketPath to the IPC socket used by the launcher, Electron app, and bundled plugin.
+  // autoStartSubMiner starts SubMiner in the background; auto_start_overlay only controls visible overlay display.
+  // Set mpv.launchMode to choose normal, maximized, or fullscreen SubMiner-managed mpv playback.
+  // Set mpv.profile to pass an mpv profile to managed mpv launches; leave it blank to pass none.
+  // Leave mpv.executablePath blank to auto-discover mpv.exe from SUBMINER_MPV_PATH or PATH.
+  // ==========================================
+  "mpv": {
+    "executablePath": "", // Optional absolute path to mpv.exe for Windows launch flows. Leave empty to auto-discover from SUBMINER_MPV_PATH or PATH.
+    "launchMode": "normal", // Default window state for SubMiner-managed mpv launches. Values: normal | maximized | fullscreen
+    "profile": "", // Optional mpv profile name passed to SubMiner-managed mpv launches. Leave empty to pass no profile.
+    "socketPath": "/tmp/subminer-socket", // mpv IPC socket path used by SubMiner-managed playback and the bundled mpv plugin.
+    "backend": "auto", // Window tracking backend passed to the bundled mpv plugin. Auto detects the current platform. Values: auto | hyprland | sway | x11 | macos | windows
+    "autoStartSubMiner": true, // Start SubMiner in the background when SubMiner-managed mpv loads a file. Values: true | false
+    "pauseUntilOverlayReady": true, // Pause mpv on visible-overlay auto-start until SubMiner signals subtitle tokenization readiness. Values: true | false
+    "subminerBinaryPath": "", // Optional SubMiner app binary path passed to the bundled mpv plugin. Leave empty to use the launcher-detected app path.
+    "aniskipEnabled": true, // Enable AniSkip intro detection, chapter markers, and the skip-intro key. Values: true | false
+    "aniskipButtonKey": "TAB" // mpv key used to skip the detected intro while the skip prompt is visible.
+  }, // SubMiner-managed mpv launch and bundled plugin options.
+
   // ==========================================
   // Jellyfin
   // Optional Jellyfin integration for auth, browsing, and playback launch.
@@ -274,20 +757,25 @@
   "jellyfin": {
     "enabled": false, // Enable optional Jellyfin integration and CLI control commands. Values: true | false
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
+    "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
-    "deviceId": "subminer", // Device id setting.
-    "clientName": "SubMiner", // Client name setting.
-    "clientVersion": "0.1.0", // Client version setting.
     "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
     "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
     "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false
     "autoAnnounce": false, // When enabled, automatically trigger remote announce/visibility check on websocket connect. Values: true | false
-    "remoteControlDeviceName": "SubMiner", // Device name reported for Jellyfin remote control sessions.
     "pullPictures": false, // Enable Jellyfin poster/icon fetching for launcher menus. Values: true | false
     "iconCacheDir": "/tmp/subminer-jellyfin-icons", // Directory used by launcher for cached Jellyfin poster icons.
     "directPlayPreferred": true, // Try direct play before server-managed transcoding when possible. Values: true | false
-    "directPlayContainers": ["mkv", "mp4", "webm", "mov", "flac", "mp3", "aac"], // Container allowlist for direct play decisions.
-    "transcodeVideoCodec": "h264", // Preferred transcode video codec when direct play is unavailable.
+    "directPlayContainers": [
+      "mkv",
+      "mp4",
+      "webm",
+      "mov",
+      "flac",
+      "mp3",
+      "aac"
+    ], // Container allowlist for direct play decisions.
+    "transcodeVideoCodec": "h264" // Preferred transcode video codec when direct play is unavailable.
   }, // Optional Jellyfin integration for auth, browsing, and playback launch.
 
   // ==========================================
@@ -296,9 +784,10 @@
   // Uses official SubMiner Discord app assets for polished card visuals.
   // ==========================================
   "discordPresence": {
-    "enabled": false, // Enable optional Discord Rich Presence updates. Values: true | false
+    "enabled": true, // Enable optional Discord Rich Presence updates. Values: true | false
+    "presenceStyle": "default", // Presence card text preset: "default" (clean bilingual), "meme" (Mining and crafting), "japanese" (fully JP), or "minimal". Values: default | meme | japanese | minimal
     "updateIntervalMs": 3000, // Minimum interval between presence payload updates.
-    "debounceMs": 750, // Debounce delay used to collapse bursty presence updates.
+    "debounceMs": 750 // Debounce delay used to collapse bursty presence updates.
   }, // Optional Discord Rich Presence activity card updates for current playback/study session.
 
   // ==========================================
@@ -315,12 +804,33 @@
     "queueCap": 1000, // In-memory write queue cap before overflow policy applies.
     "payloadCapBytes": 256, // Max JSON payload size per event before truncation.
     "maintenanceIntervalMs": 86400000, // Maintenance cadence (prune + rollup + vacuum checks).
+    "retentionMode": "preset", // Retention mode (`preset` uses preset values, `advanced` uses explicit values). Values: preset | advanced
+    "retentionPreset": "balanced", // Retention preset when `retentionMode` is `preset`. Values: minimal | balanced | deep-history
     "retention": {
-      "eventsDays": 7, // Raw event retention window in days.
-      "telemetryDays": 30, // Telemetry retention window in days.
-      "dailyRollupsDays": 365, // Daily rollup retention window in days.
-      "monthlyRollupsDays": 1825, // Monthly rollup retention window in days.
-      "vacuumIntervalDays": 7, // Minimum days between VACUUM runs.
+      "eventsDays": 0, // Raw event retention window in days. Use 0 to keep all.
+      "telemetryDays": 0, // Telemetry retention window in days. Use 0 to keep all.
+      "sessionsDays": 0, // Session retention window in days. Use 0 to keep all.
+      "dailyRollupsDays": 0, // Daily rollup retention window in days. Use 0 to keep all.
+      "monthlyRollupsDays": 0, // Monthly rollup retention window in days. Use 0 to keep all.
+      "vacuumIntervalDays": 0 // Minimum days between VACUUM runs. Use 0 to disable.
     }, // Retention setting.
+    "lifetimeSummaries": {
+      "global": true, // Maintain global lifetime stats rows. Values: true | false
+      "anime": true, // Maintain per-anime lifetime stats rows. Values: true | false
+      "media": true // Maintain per-media lifetime stats rows. Values: true | false
+    } // Lifetime summaries setting.
   }, // Enable/disable immersion tracking.
+
+  // ==========================================
+  // Stats Dashboard
+  // Local immersion stats dashboard served on localhost and available as an in-app overlay.
+  // Uses the immersion tracking database for overview, trends, sessions, and vocabulary views.
+  // ==========================================
+  "stats": {
+    "toggleKey": "Backquote", // Key code to toggle the stats overlay.
+    "markWatchedKey": "KeyW", // Key code to mark the current video as watched and advance to the next playlist entry.
+    "serverPort": 6969, // Port for the stats HTTP server.
+    "autoStartServer": true, // Automatically start the stats server on launch. Values: true | false
+    "autoOpenBrowser": false // Automatically open the stats dashboard in a browser when the server starts. Values: true | false
+  } // Local immersion stats dashboard served on localhost and available as an in-app overlay.
 }

docs-site/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+.vitepress/cache/
+.vitepress/dist/
+.DS_Store
+.codex/
+.agents/
+**/CLAUDE.md
+.claude/*

docs-site/.vitepress/config.ts

@@ -0,0 +1,502 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, posix, resolve, sep } from 'node:path';
+import type { DefaultTheme, HeadConfig, TransformContext, UserConfig } from 'vitepress';
+
+const DOCS_HOSTNAME = 'https://docs.subminer.moe';
+const PLAUSIBLE_PROXY_HOSTNAME = 'https://worker.sudacode.com';
+const PLAUSIBLE_SITE_SCRIPT_PATH = '/js/pa-h28Pn9ppgTJRmiSJlyPT6.js';
+const PLAUSIBLE_ENDPOINT = `${PLAUSIBLE_PROXY_HOSTNAME}/api/event`;
+const PLAUSIBLE_INIT_SCRIPT = [
+  'window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};',
+  `plausible.init({ endpoint: '${PLAUSIBLE_ENDPOINT}' });`,
+].join('\n');
+
+type DocsChannel = 'stable-root' | 'stable-archive' | 'main';
+
+type VersionManifest = {
+  latestStable: string;
+  channels: Array<{ label: string; path: string }>;
+  versions: Array<{ version: string; path: string }>;
+};
+
+function optionalEnv(value: string | undefined): string | undefined {
+  return value && value !== 'undefined' ? value : undefined;
+}
+
+const base = normalizeBase(optionalEnv(process.env.SUBMINER_DOCS_BASE) ?? '/');
+const outDir = optionalEnv(process.env.SUBMINER_DOCS_OUT_DIR);
+const docsSourceDir = optionalEnv(process.env.SUBMINER_DOCS_SOURCE_DIR) ?? process.cwd();
+// The tracked `docs-site/` checkout, which stays a git working tree even when
+// `docsSourceDir` points at an untracked release snapshot. Used for git lookups only.
+const repoDocsDir = optionalEnv(process.env.SUBMINER_DOCS_REPO_DIR) ?? process.cwd();
+const channel = normalizeChannel(optionalEnv(process.env.SUBMINER_DOCS_CHANNEL));
+const docsVersion = optionalEnv(process.env.SUBMINER_DOCS_VERSION);
+const latestStable = optionalEnv(process.env.SUBMINER_DOCS_LATEST_STABLE) ?? 'v0.18.0';
+const versionManifest = parseVersionManifest(process.env.SUBMINER_DOCS_VERSION_MANIFEST);
+const versionLinkOrigin =
+  optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? 'production';
+
+function getLocalArchiveDir(): string {
+  return resolve(
+    optionalEnv(process.env.SUBMINER_DOCS_LOCAL_ARCHIVE_DIR) ??
+      join(docsSourceDir, '..', '.tmp/docs-versioned-site'),
+  );
+}
+
+function normalizeBase(value: string): string {
+  if (!value || value === '/') return '/';
+  return `/${value.replace(/^\/+|\/+$/g, '')}/`;
+}
+
+function normalizeChannel(value: string | undefined): DocsChannel {
+  if (value === 'main' || value === 'stable-archive') return value;
+  return 'stable-root';
+}
+
+function parseVersionManifest(value: string | undefined): VersionManifest {
+  if (!value || value === 'undefined') {
+    return {
+      latestStable,
+      channels: [
+        { label: 'Latest stable', path: '/' },
+        { label: 'main', path: '/main/' },
+      ],
+      versions: [{ version: latestStable, path: `/v/${latestStable.replace(/^v/, '')}/` }],
+    };
+  }
+
+  return JSON.parse(value) as VersionManifest;
+}
+
+function withDocsBase(path: string): string {
+  if (/^[a-z]+:\/\//i.test(path)) return path;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  if (base === '/') return normalizedPath;
+  return `${base.replace(/\/$/, '')}${normalizedPath}`;
+}
+
+function pageToRoute(page: string): string | null {
+  if (page === '404.md') return null;
+
+  const route = page
+    .replace(/(^|\/)index\.md$/, '')
+    .replace(/\.md$/, '')
+    .replace(/\/$/, '');
+  return route ? `/${route}` : '/';
+}
+
+// Only the root channel is indexable. `main` and every /v/<version>/ archive are
+// near-verbatim copies of it, so they own their URL via a self-referential canonical
+// and are excluded from the index instead of being consolidated onto root. Uniform
+// self-canonical plus noindex avoids mixing noindex with a cross-page canonical,
+// which Google treats as a conflicting signal.
+const isIndexableChannel = channel === 'stable-root';
+
+function pageToCanonicalHref(page: string): string | null {
+  const route = pageToRoute(page);
+  if (!route) return null;
+
+  if (!isIndexableChannel) {
+    return `${DOCS_HOSTNAME}${canonicalRouteWithBase(route)}`;
+  }
+
+  return route === '/' ? `${DOCS_HOSTNAME}/` : `${DOCS_HOSTNAME}${route}`;
+}
+
+function canonicalRouteWithBase(route: string): string {
+  const routeWithBase = withDocsBase(route);
+  return route === '/' ? routeWithBase : routeWithBase.replace(/\/$/, '');
+}
+
+function transformPageHead({ page }: TransformContext): HeadConfig[] {
+  const href = pageToCanonicalHref(page);
+  const head: HeadConfig[] = href ? [['link', { rel: 'canonical', href }]] : [];
+
+  // Crawlable so links still pass through, but out of the index: ~30 archived copies
+  // of every page otherwise soak up the crawl budget the current docs need.
+  if (!isIndexableChannel) {
+    head.push(['meta', { name: 'robots', content: 'noindex,follow' }]);
+  }
+
+  return head;
+}
+
+function linkToPagePath(link: string): string | null {
+  if (!link.startsWith('/') || link.startsWith('/v/') || link.startsWith('/main/')) {
+    return null;
+  }
+
+  const withoutHash = link.split('#')[0] ?? '/';
+  const withoutQuery = withoutHash.split('?')[0] ?? '/';
+  const route = withoutQuery.replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+function hasPageForLink(link: string): boolean {
+  const pagePath = linkToPagePath(link);
+  if (!pagePath) return true;
+  return existsSync(join(docsSourceDir, pagePath));
+}
+
+function filterNav(items: DefaultTheme.NavItem[]): DefaultTheme.NavItem[] {
+  return items
+    .map((item) => {
+      if ('items' in item && item.items) {
+        return { ...item, items: filterNav(item.items as DefaultTheme.NavItem[]) };
+      }
+      if ('link' in item && item.link && !hasPageForLink(item.link)) {
+        return null;
+      }
+      return item;
+    })
+    .filter((item): item is DefaultTheme.NavItem => Boolean(item));
+}
+
+function filterSidebar(items: DefaultTheme.SidebarItem[]): DefaultTheme.SidebarItem[] {
+  return items
+    .map((item) => {
+      const filteredChildren = item.items ? filterSidebar(item.items) : undefined;
+      if (item.link && !hasPageForLink(item.link)) return null;
+      if (item.items && filteredChildren?.length === 0 && !item.link) return null;
+      return { ...item, items: filteredChildren };
+    })
+    .filter((item): item is DefaultTheme.SidebarItem => Boolean(item));
+}
+
+function versionSwitchLink(path: string): string {
+  if (/^[a-z]+:\/\//i.test(path)) return path;
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  if (versionLinkOrigin === 'local') return localVersionSwitchLink(normalizedPath);
+  return `${DOCS_HOSTNAME}${normalizedPath}`;
+}
+
+function localVersionSwitchLink(path: string): string {
+  if (base === '/') return path;
+
+  const basePath = base.replace(/\/$/, '');
+  const targetPath = path === '/' ? '/' : path.replace(/\/$/, '');
+  const relativePath = posix.relative(basePath, targetPath) || '.';
+
+  return path.endsWith('/') ? `${relativePath}/` : relativePath;
+}
+
+function shouldHandleLocalVersionRoute(pathname: string): boolean {
+  if (base !== '/' || channel !== 'stable-root') return false;
+  return /^\/main(?:\/|$)/.test(pathname) || /^\/v\/[^/]+(?:\/|$)/.test(pathname);
+}
+
+function contentTypeForPath(path: string): string {
+  switch (extname(path)) {
+    case '.css':
+      return 'text/css; charset=utf-8';
+    case '.gif':
+      return 'image/gif';
+    case '.ico':
+      return 'image/x-icon';
+    case '.jpg':
+    case '.jpeg':
+      return 'image/jpeg';
+    case '.js':
+    case '.mjs':
+      return 'text/javascript; charset=utf-8';
+    case '.json':
+    case '.jsonc':
+      return 'application/json; charset=utf-8';
+    case '.mp4':
+      return 'video/mp4';
+    case '.png':
+      return 'image/png';
+    case '.svg':
+      return 'image/svg+xml';
+    case '.ttf':
+      return 'font/ttf';
+    case '.webm':
+      return 'video/webm';
+    case '.woff':
+      return 'font/woff';
+    case '.woff2':
+      return 'font/woff2';
+    case '.xml':
+      return 'application/xml; charset=utf-8';
+    default:
+      return 'text/html; charset=utf-8';
+  }
+}
+
+function isFile(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function archiveFileForPathname(pathname: string): string | null {
+  if (!shouldHandleLocalVersionRoute(pathname)) return null;
+
+  const localArchiveDir = getLocalArchiveDir();
+  const routePath = decodeURIComponent(pathname).replace(/^\/+/, '');
+  const filePath = resolve(localArchiveDir, routePath);
+  if (filePath !== localArchiveDir && !filePath.startsWith(`${localArchiveDir}${sep}`)) {
+    return null;
+  }
+
+  const candidates = pathname.endsWith('/')
+    ? [join(filePath, 'index.html')]
+    : extname(filePath)
+      ? [filePath]
+      : [`${filePath}.html`, join(filePath, 'index.html')];
+
+  return candidates.find(isFile) ?? null;
+}
+
+function serveLocalArchiveRoute(pathname: string, response: DevServerResponse): boolean {
+  if (
+    (optionalEnv(process.env.SUBMINER_DOCS_VERSION_LINK_ORIGIN) ?? versionLinkOrigin) !== 'local'
+  ) {
+    return false;
+  }
+
+  const filePath = archiveFileForPathname(pathname);
+  if (!filePath) return false;
+
+  response.statusCode = 200;
+  response.setHeader('Content-Type', contentTypeForPath(filePath));
+  response.end(readFileSync(filePath));
+  return true;
+}
+
+type DevServerResponse = {
+  statusCode: number;
+  setHeader(name: string, value: string): void;
+  end(chunk?: string | Uint8Array): void;
+};
+
+const versionItems = [
+  {
+    text: `Latest stable (${versionManifest.latestStable})`,
+    link: versionSwitchLink('/'),
+    target: '_self',
+    noIcon: true,
+  },
+  ...versionManifest.channels
+    .filter((entry) => entry.label !== 'Latest stable')
+    .map((entry) => ({
+      text: entry.label,
+      link: versionSwitchLink(entry.path),
+      target: '_self',
+      noIcon: true,
+    })),
+  ...versionManifest.versions.map((entry) => ({
+    text: entry.version,
+    link: versionSwitchLink(entry.path),
+    target: '_self',
+    noIcon: true,
+  })),
+];
+
+function sitemapUrlToPage(url: string): string {
+  const route = url.replace(/\.html$/, '').replace(/^\/+|\/+$/g, '');
+  return route ? `${route}.md` : 'index.md';
+}
+
+// VitePress derives <lastmod> by running `git log` inside its source dir. Production
+// builds point that at an untracked snapshot of the release tag, so the lookup comes
+// back empty and the sitemap ships with no dates at all. Resolve it from the tracked
+// checkout at the ref being built instead.
+function lastModifiedFor(url: string): string | undefined {
+  const ref = docsVersion && docsVersion !== 'main' ? docsVersion : 'HEAD';
+  const result = spawnSync('git', ['log', '-1', '--format=%cI', ref, '--', sitemapUrlToPage(url)], {
+    cwd: repoDocsDir,
+    encoding: 'utf8',
+  });
+
+  return (result.status === 0 && result.stdout.trim()) || undefined;
+}
+
+// Only the root channel publishes a sitemap. Archived and `main` builds would emit
+// their own copies listing the same canonical URLs, which just advertises the
+// duplicate trees we are trying to keep out of the index.
+const sitemap: UserConfig['sitemap'] = isIndexableChannel
+  ? {
+      hostname: DOCS_HOSTNAME,
+      transformItems(items) {
+        return items
+          .filter((item) => item.url !== 'README' && item.url !== `${DOCS_HOSTNAME}/README`)
+          .map((item) => ({ ...item, lastmod: item.lastmod ?? lastModifiedFor(item.url) }));
+      },
+    }
+  : undefined;
+
+const nav: DefaultTheme.NavItem[] = [
+  { text: 'Home', link: '/' },
+  { text: 'Get Started', link: '/installation' },
+  { text: 'Mining', link: '/mining-workflow' },
+  { text: 'Configuration', link: '/configuration' },
+  { text: 'Changelog', link: '/changelog' },
+  { text: 'Troubleshooting', link: '/troubleshooting' },
+  { text: docsVersion ?? (channel === 'main' ? 'main' : latestStable), items: versionItems },
+];
+
+const sidebar: DefaultTheme.SidebarItem[] = [
+  {
+    text: 'Getting Started',
+    items: [
+      { text: 'Overview', link: '/' },
+      { text: 'Installation', link: '/installation' },
+      { text: 'Usage', link: '/usage' },
+      { text: 'Mining Workflow', link: '/mining-workflow' },
+      { text: 'Launcher Script', link: '/launcher-script' },
+    ],
+  },
+  {
+    text: 'Reference',
+    items: [
+      { text: 'Configuration', link: '/configuration' },
+      { text: 'Keyboard Shortcuts', link: '/shortcuts' },
+      { text: 'Subtitle Annotations', link: '/subtitle-annotations' },
+      { text: 'Subtitle Sidebar', link: '/subtitle-sidebar' },
+      { text: 'Immersion Tracking', link: '/immersion-tracking' },
+      { text: 'Troubleshooting', link: '/troubleshooting' },
+    ],
+  },
+  {
+    text: 'Integrations',
+    items: [
+      { text: 'MPV Plugin', link: '/mpv-plugin' },
+      { text: 'Anki', link: '/anki-integration' },
+      { text: 'Jellyfin', link: '/jellyfin-integration' },
+      { text: 'YouTube', link: '/youtube-integration' },
+      { text: 'Jimaku', link: '/jimaku-integration' },
+      { text: 'Subtitle Generation', link: '/subtitle-generation' },
+      { text: 'TsukiHime', link: '/tsukihime-integration' },
+      { text: 'AniList', link: '/anilist-integration' },
+      { text: 'AniSkip', link: '/aniskip-integration' },
+      { text: 'Character Dictionary', link: '/character-dictionary' },
+    ],
+  },
+  {
+    text: 'Development',
+    items: [
+      { text: 'Building & Testing', link: '/development' },
+      { text: 'Architecture', link: '/architecture' },
+      { text: 'IPC + Runtime Contracts', link: '/ipc-contracts' },
+      { text: 'WebSocket + Texthooker API', link: '/websocket-texthooker-api' },
+      { text: 'Changelog', link: '/changelog' },
+    ],
+  },
+];
+
+const config: UserConfig = {
+  title: 'SubMiner Docs',
+  description:
+    'SubMiner: an MPV immersion-mining overlay with Yomitan and AnkiConnect integration.',
+  base,
+  ...(outDir ? { outDir } : {}),
+  vite: {
+    plugins: [
+      {
+        name: 'subminer-docs-local-version-redirects',
+        configureServer(server) {
+          server.middlewares.use((request, response, next) => {
+            const requestUrl = new URL(request.url ?? '/', 'http://localhost');
+            if (serveLocalArchiveRoute(requestUrl.pathname, response)) {
+              return;
+            }
+
+            if (!shouldHandleLocalVersionRoute(requestUrl.pathname)) {
+              next();
+              return;
+            }
+
+            response.statusCode = 302;
+            response.setHeader(
+              'Location',
+              `${DOCS_HOSTNAME}${requestUrl.pathname}${requestUrl.search}`,
+            );
+            response.end();
+          });
+        },
+      },
+    ],
+  },
+  head: [
+    ['link', { rel: 'preconnect', href: PLAUSIBLE_PROXY_HOSTNAME }],
+    [
+      'script',
+      {
+        async: '',
+        src: `${PLAUSIBLE_PROXY_HOSTNAME}${PLAUSIBLE_SITE_SCRIPT_PATH}`,
+      },
+    ],
+    ['script', {}, PLAUSIBLE_INIT_SCRIPT],
+    ['link', { rel: 'icon', href: withDocsBase('/favicon.ico'), sizes: 'any' }],
+    [
+      'link',
+      {
+        rel: 'icon',
+        type: 'image/png',
+        href: withDocsBase('/favicon-32x32.png'),
+        sizes: '32x32',
+      },
+    ],
+    [
+      'link',
+      {
+        rel: 'icon',
+        type: 'image/png',
+        href: withDocsBase('/favicon-16x16.png'),
+        sizes: '16x16',
+      },
+    ],
+    [
+      'link',
+      {
+        rel: 'apple-touch-icon',
+        href: withDocsBase('/apple-touch-icon.png'),
+        sizes: '180x180',
+      },
+    ],
+  ],
+  appearance: 'dark',
+  cleanUrls: true,
+  metaChunk: true,
+  sitemap,
+  transformHead: transformPageHead,
+  lastUpdated: true,
+  srcExclude: ['subagents/**', 'README.md'],
+  markdown: {
+    theme: {
+      light: 'catppuccin-latte',
+      dark: 'catppuccin-macchiato',
+    },
+  },
+  themeConfig: {
+    logo: {
+      light: '/assets/SubMiner.png',
+      dark: '/assets/SubMiner.png',
+    },
+    siteTitle: 'SubMiner Docs',
+    nav: filterNav(nav),
+    sidebar: filterSidebar(sidebar),
+    search: {
+      provider: 'local',
+    },
+    footer: {
+      message: 'Released under the GPL-3.0 License.',
+      copyright: 'Copyright © 2026-present sudacode',
+    },
+    editLink: {
+      pattern: 'https://github.com/ksyasuda/SubMiner/edit/main/docs-site/:path',
+      text: 'Edit this page on GitHub',
+    },
+    outline: { level: [2, 3], label: 'On this page' },
+    externalLinkIcon: true,
+    docFooter: { prev: 'Previous', next: 'Next' },
+    returnToTopLabel: 'Back to top',
+    socialLinks: [{ icon: 'github', link: 'https://github.com/ksyasuda/SubMiner' }],
+  },
+};
+
+export default config;

docs-site/.vitepress/theme/TuiLayout.vue

@@ -0,0 +1,18 @@
+<script setup>
+import DefaultTheme from 'vitepress/theme';
+import StatusLine from './components/StatusLine.vue';
+import BlinkingCursor from './components/BlinkingCursor.vue';
+
+const { Layout } = DefaultTheme;
+</script>
+
+<template>
+  <Layout>
+    <template #home-hero-info-after>
+      <BlinkingCursor />
+    </template>
+    <template #layout-bottom>
+      <StatusLine />
+    </template>
+  </Layout>
+</template>

docs-site/.vitepress/theme/components/BlinkingCursor.vue

@@ -0,0 +1,3 @@
+<template>
+  <span class="tui-cursor" aria-hidden="true">█</span>
+</template>

docs-site/.vitepress/theme/components/StatusLine.vue

@@ -0,0 +1,48 @@
+<script setup>
+import { useRoute, useData } from 'vitepress';
+import { computed } from 'vue';
+import { formatStatusLineFilePath } from '../status-line';
+
+const route = useRoute();
+const { page, frontmatter } = useData();
+
+const mode = computed(() => {
+  const layout = frontmatter.value.layout;
+  if (layout === 'home') return 'HOME';
+  return 'NORMAL';
+});
+
+const filePath = computed(() => {
+  return formatStatusLineFilePath(route.path);
+});
+
+const section = computed(() => {
+  const path = route.path;
+  if (path === '/') return 'root';
+  const parts = path.split('/').filter(Boolean);
+  return parts[0] || 'root';
+});
+
+const lastUpdated = computed(() => {
+  if (!page.value.lastUpdated) return '';
+  const date = new Date(page.value.lastUpdated);
+  return date.toISOString().slice(0, 10);
+});
+</script>
+
+<template>
+  <footer class="tui-statusline" aria-label="Page info">
+    <div class="tui-statusline__left">
+      <span class="tui-statusline__mode" :data-mode="mode">{{ mode }}</span>
+      <span class="tui-statusline__sep"></span>
+      <span class="tui-statusline__file">{{ filePath }}</span>
+    </div>
+    <div class="tui-statusline__right">
+      <span class="tui-statusline__section">{{ section }}</span>
+      <span class="tui-statusline__sep"></span>
+      <span v-if="lastUpdated" class="tui-statusline__date">{{ lastUpdated }}</span>
+      <span v-if="lastUpdated" class="tui-statusline__sep"></span>
+      <span class="tui-statusline__branch">GPL-3.0</span>
+    </div>
+  </footer>
+</template>

docs-site/.vitepress/theme/index.ts

@@ -2,7 +2,9 @@ import DefaultTheme from 'vitepress/theme';
 import { useRoute } from 'vitepress';
 import { nextTick, onMounted, watch } from 'vue';
 import '@catppuccin/vitepress/theme/macchiato/mauve.css';
+import './tui-theme.css';
 import './mermaid-modal.css';
+import TuiLayout from './TuiLayout.vue';
 
 let mermaidLoader: Promise<any> | null = null;
 const MERMAID_MODAL_ID = 'mermaid-diagram-modal';
@@ -112,6 +114,11 @@ async function getMermaid() {
         startOnLoad: false,
         securityLevel: 'loose',
         theme: 'base',
+        flowchart: {
+          padding: 16,
+          nodeSpacing: 30,
+          rankSpacing: 40,
+        },
         themeVariables: {
           background: '#24273a',
           primaryColor: '#363a4f',
@@ -177,7 +184,8 @@ async function renderMermaidBlocks() {
 }
 
 export default {
-  ...DefaultTheme,
+  Layout: TuiLayout,
+  extends: DefaultTheme,
   setup() {
     const route = useRoute();
     const render = () => {

docs-site/.vitepress/theme/mermaid-modal.css

@@ -1,11 +1,20 @@
 .mermaid-interactive {
   cursor: zoom-in;
+  transition: outline-color 180ms ease;
+  overflow-x: auto;
+  overflow-y: hidden;
+  text-align: center;
+}
+
+.mermaid-interactive svg {
+  display: inline-block;
+  min-width: 0;
 }
 
 .mermaid-interactive:focus-visible {
   outline: 2px solid var(--vp-c-brand-1);
   outline-offset: 4px;
-  border-radius: 6px;
+  border-radius: 0;
 }
 
 .mermaid-modal {
@@ -23,6 +32,8 @@
   position: absolute;
   inset: 0;
   background: rgba(0, 0, 0, 0.72);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
 }
 
 .mermaid-modal__dialog {
@@ -32,9 +43,9 @@
   width: min(96vw, 1800px);
   max-height: 92vh;
   border: 1px solid var(--vp-c-border);
-  border-radius: 12px;
+  border-radius: 0;
   background: var(--vp-c-bg);
-  box-shadow: var(--vp-shadow-4);
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3), 0 24px 64px rgba(0, 0, 0, 0.2);
   overflow: hidden;
 }
 
@@ -44,11 +55,19 @@
   margin-right: 16px;
   margin-top: 12px;
   border: 1px solid var(--vp-c-border);
-  border-radius: 6px;
+  border-radius: 0;
   padding: 4px 10px;
   background: var(--vp-c-bg-soft);
   color: var(--vp-c-text-1);
-  font-size: 14px;
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  cursor: pointer;
+  transition: border-color 180ms ease, color 180ms ease;
+}
+
+.mermaid-modal__close:hover {
+  border-color: var(--vp-c-brand-1);
+  color: var(--vp-c-brand-1);
 }
 
 .mermaid-modal__content {

docs-site/.vitepress/theme/status-line.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from 'bun:test';
+import { formatStatusLineFilePath } from './status-line';
+
+test('status line file path formats root home as index markdown', () => {
+  expect(formatStatusLineFilePath('/')).toBe('index.md');
+});
+
+test('status line file path formats version archive home without trailing slash', () => {
+  expect(formatStatusLineFilePath('/v/0.12.0/')).toBe('v/0.12.0.md');
+});
+
+test('status line file path keeps normal docs routes as markdown files', () => {
+  expect(formatStatusLineFilePath('/v/0.12.0/configuration')).toBe(
+    'v/0.12.0/configuration.md',
+  );
+});

docs-site/.vitepress/theme/status-line.ts

@@ -0,0 +1,4 @@
+export function formatStatusLineFilePath(routePath: string): string {
+  if (routePath === '/') return 'index.md';
+  return `${routePath.replace(/^\/|\/$/g, '')}.md`;
+}

docs-site/.vitepress/theme/tui-theme.css

@@ -0,0 +1,689 @@
+@import '@fontsource/jetbrains-mono/400.css';
+@import '@fontsource/jetbrains-mono/500.css';
+@import '@fontsource/jetbrains-mono/600.css';
+@import '@fontsource/jetbrains-mono/700.css';
+
+@font-face {
+  font-family: 'M PLUS 1';
+  src: url('../../public/assets/fonts/Mplus1-Medium.ttf') format('truetype');
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Manrope Default';
+  src: url('../../public/assets/fonts/manrope-latin-600-normal.ttf') format('truetype');
+  font-weight: 600;
+  font-style: normal;
+  font-display: swap;
+}
+
+:root {
+  --tui-font-mono: 'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace;
+  --tui-font-body:
+    'Manrope Default',
+    'M PLUS 1',
+    'Manrope',
+    'Noto Sans CJK JP',
+    'Noto Sans JP',
+    'Hiragino Kaku Gothic ProN',
+    'Meiryo',
+    'Yu Gothic',
+    'Hiragino Sans',
+    system-ui,
+    sans-serif;
+  --tui-transition: 180ms ease;
+
+  /* Theme-specific values — overridden in .dark below */
+  --tui-nav-bg: color-mix(in srgb, var(--vp-c-bg-alt) 88%, transparent);
+  --tui-table-hover-bg: color-mix(in srgb, var(--vp-c-bg-soft) 80%, transparent);
+  --tui-link-underline: color-mix(in srgb, var(--vp-c-brand-1) 40%, transparent);
+  --tui-selection-bg: hsla(267, 83%, 45%, 0.14);
+  --tui-hero-glow: hsla(267, 83%, 45%, 0.05);
+  --tui-step-hover-bg: var(--vp-c-bg-alt);
+  --tui-step-hover-glow: color-mix(in srgb, var(--vp-c-brand-1) 30%, transparent);
+}
+
+.dark {
+  --tui-nav-bg: hsla(232, 23%, 18%, 0.82);
+  --tui-table-hover-bg: hsla(232, 23%, 18%, 0.4);
+  --tui-link-underline: hsla(267, 83%, 80%, 0.3);
+  --tui-selection-bg: hsla(267, 83%, 80%, 0.22);
+  --tui-hero-glow: hsla(267, 83%, 80%, 0.06);
+  --tui-step-hover-bg: hsla(232, 23%, 18%, 0.6);
+  --tui-step-hover-glow: hsla(267, 83%, 80%, 0.3);
+}
+
+:root {
+  --vp-font-family-base: var(--tui-font-body);
+  --vp-font-family-heading: var(--tui-font-body);
+  --vp-font-family-mono: var(--tui-font-mono);
+}
+
+.vp-doc {
+  font-family: var(--vp-font-family-base);
+}
+
+/* === Selection === */
+::selection {
+  background: var(--tui-selection-bg);
+  color: var(--vp-c-text-1);
+}
+
+/* === Scrollbar === */
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--vp-c-divider);
+  border-radius: 0;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--vp-c-text-3);
+}
+
+/* === Global transitions === */
+a,
+button,
+.VPFeature,
+.VPNavBarMenuLink,
+.VPSidebarItem .text {
+  transition: color var(--tui-transition), background var(--tui-transition),
+    border-color var(--tui-transition), opacity var(--tui-transition);
+}
+
+/* === Nav bar === */
+.VPNav .VPNavBarTitle .title {
+  font-family: var(--tui-font-mono);
+  font-weight: 600;
+  font-size: 14px;
+  letter-spacing: -0.02em;
+}
+
+.VPNav .VPNavBarMenuLink {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.VPNav .VPNavBar {
+  border-bottom: 1px solid var(--vp-c-divider);
+  backdrop-filter: blur(12px) saturate(1.2);
+  -webkit-backdrop-filter: blur(12px) saturate(1.2);
+}
+
+.VPNav .VPNavBar:not(.has-sidebar) {
+  background: var(--tui-nav-bg);
+}
+
+.VPNav .VPNavBar.has-sidebar .content {
+  backdrop-filter: blur(12px) saturate(1.2);
+  -webkit-backdrop-filter: blur(12px) saturate(1.2);
+}
+
+/* === Sidebar === */
+.VPSidebar .VPSidebarItem .text {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+}
+
+.VPSidebar .VPSidebarItem.is-active.is-link > .item .text::before {
+  content: '> ';
+  color: var(--vp-c-brand-1);
+}
+
+.VPSidebar .VPSidebarItem.is-link:not(.is-active) > .item .text::before {
+  content: '  ';
+  opacity: 0.4;
+}
+
+.VPSidebar .VPSidebarItem.is-link:not(.is-active) > .item:hover .text::before {
+  content: '> ';
+  color: var(--vp-c-text-3);
+  opacity: 0.6;
+}
+
+.VPSidebar .VPSidebarItem.is-link:not(.is-active) > .item:hover .text {
+  color: var(--vp-c-text-1) !important;
+}
+
+.VPSidebar .VPSidebarItem.level-0 > .item .text {
+  font-weight: 700;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.VPSidebar .VPSidebarItem.level-0 > .item .text::before {
+  content: '# ';
+  color: var(--vp-c-text-3);
+}
+
+.VPSidebar .VPSidebarItem.level-0 .items {
+  border-left: 1px solid var(--vp-c-divider);
+  margin-left: 6px;
+  padding-left: 12px;
+}
+
+/* === Headings === */
+.vp-doc h1,
+.vp-doc h2,
+.vp-doc h3,
+.vp-doc h4 {
+  font-family: var(--vp-font-family-heading);
+}
+
+.vp-doc h1 {
+  letter-spacing: -0.02em;
+}
+
+.vp-doc h1::before {
+  content: '> ';
+  color: var(--vp-c-brand-1);
+  font-weight: 400;
+}
+
+.vp-doc h2 {
+  border-bottom: none;
+  padding-bottom: 4px;
+}
+
+.vp-doc h2::after {
+  content: '';
+  display: block;
+  margin-top: 6px;
+  height: 1px;
+  background: repeating-linear-gradient(
+    to right,
+    var(--vp-c-divider) 0,
+    var(--vp-c-divider) 1ch,
+    transparent 1ch,
+    transparent 1.5ch
+  );
+}
+
+/* === Inline code === */
+.vp-doc :not(pre) > code {
+  border-radius: 0;
+  padding: 2px 6px;
+  font-size: 0.88em;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-brand-1);
+  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
+    monospace;
+  font-variant-ligatures: none;
+}
+
+/* === Code blocks === */
+.vp-doc div[class*='language-'] {
+  border-radius: 0;
+  border: 1px solid var(--vp-c-divider);
+  background: var(--vp-c-bg-alt) !important;
+  font-family: var(--tui-font-mono), 'M PLUS 1', 'Noto Sans CJK JP', 'Noto Sans JP',
+    monospace;
+  font-variant-ligatures: none;
+}
+
+.vp-doc div[class*='language-']::before {
+  font-family: var(--tui-font-mono);
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  color: var(--vp-c-text-3);
+}
+
+.vp-doc div[class*='language-'] > button.copy {
+  border-radius: 0;
+}
+
+/* === Tables === */
+.vp-doc table {
+  border-collapse: collapse;
+  border: 1px solid var(--vp-c-divider);
+}
+
+.vp-doc table th {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  background: var(--vp-c-bg-soft);
+}
+
+.vp-doc table td,
+.vp-doc table th {
+  border: 1px solid var(--vp-c-divider);
+}
+
+.vp-doc table tr:hover td {
+  background: var(--tui-table-hover-bg);
+}
+
+/* === Links === */
+.vp-doc a {
+  text-decoration: none;
+  border-bottom: 1px solid var(--tui-link-underline);
+  transition: border-color var(--tui-transition), color var(--tui-transition);
+}
+
+.vp-doc a:hover {
+  border-bottom-color: var(--vp-c-brand-1);
+}
+
+/* === Custom containers === */
+.vp-doc .custom-block {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 0;
+  padding: 16px 20px;
+  margin: 16px 0;
+  position: relative;
+  background: var(--vp-c-bg-soft);
+}
+
+.vp-doc .custom-block::before {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  position: absolute;
+  top: -1px;
+  left: 12px;
+  transform: translateY(-50%);
+  padding: 0 6px;
+  background: var(--vp-c-bg);
+}
+
+.vp-doc .custom-block.tip,
+.vp-doc .custom-block.info,
+.vp-doc .custom-block.warning,
+.vp-doc .custom-block.danger,
+.vp-doc .custom-block.details {
+  border-left-width: 1px;
+}
+
+.vp-doc .custom-block.tip { border-color: var(--vp-c-brand-1); }
+.vp-doc .custom-block.tip::before { content: '-- tip'; color: var(--vp-c-brand-1); }
+
+.vp-doc .custom-block.info { border-color: var(--vp-c-brand-2); }
+.vp-doc .custom-block.info::before { content: '-- info'; color: var(--vp-c-brand-2); }
+
+.vp-doc .custom-block.warning { border-color: var(--vp-c-warning-1); }
+.vp-doc .custom-block.warning::before { content: '-- warning'; color: var(--vp-c-warning-1); }
+
+.vp-doc .custom-block.danger { border-color: var(--vp-c-danger-1); }
+.vp-doc .custom-block.danger::before { content: '-- danger'; color: var(--vp-c-danger-1); }
+
+.vp-doc .custom-block.details { border-color: var(--vp-c-divider); }
+.vp-doc .custom-block.details::before { content: '-- details'; color: var(--vp-c-text-2); }
+
+.vp-doc .custom-block .custom-block-title {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+  font-weight: 600;
+}
+
+/* === Blockquotes === */
+.vp-doc blockquote {
+  border-left: 2px solid var(--vp-c-divider);
+  padding: 4px 0 4px 16px;
+  margin: 16px 0;
+  color: var(--vp-c-text-2);
+  font-style: normal;
+  position: relative;
+}
+
+.vp-doc blockquote::before {
+  content: '│';
+  position: absolute;
+  left: -2px;
+  top: 4px;
+  color: var(--vp-c-brand-1);
+  font-family: var(--tui-font-mono);
+  font-size: 14px;
+  line-height: 1;
+  opacity: 0;
+}
+
+/* === Horizontal rules === */
+.vp-doc hr {
+  border: none;
+  height: 1px;
+  margin: 24px 0;
+  background: repeating-linear-gradient(
+    to right,
+    var(--vp-c-divider) 0,
+    var(--vp-c-divider) 1ch,
+    transparent 1ch,
+    transparent 1.5ch
+  );
+}
+
+/* === Lists === */
+.vp-doc ul > li::marker {
+  color: var(--vp-c-text-3);
+}
+
+.vp-doc ol > li::marker {
+  font-family: var(--tui-font-mono);
+  font-size: 0.85em;
+  color: var(--vp-c-text-3);
+}
+
+/* === Focus-visible === */
+:focus-visible {
+  outline: 2px solid var(--vp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.vp-doc a:focus-visible {
+  outline-offset: 3px;
+  border-bottom-color: transparent;
+}
+
+/* === Feature icon hover === */
+.VPFeatures .VPFeature .icon {
+  transition: transform 280ms ease;
+}
+
+.VPFeatures .VPFeature:hover .icon {
+  transform: translateY(-2px);
+}
+
+/* === Blinking cursor === */
+.tui-cursor {
+  display: inline-block;
+  color: var(--vp-c-brand-1);
+  animation: tui-blink 1s step-end infinite;
+  font-family: var(--tui-font-mono);
+  font-size: 0.9em;
+  vertical-align: baseline;
+  margin-left: 2px;
+  line-height: 1;
+}
+
+@keyframes tui-blink {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0; }
+}
+
+
+/* === Statusline === */
+.tui-statusline {
+  position: fixed;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  z-index: 50;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  height: 28px;
+  padding: 0 12px;
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  font-weight: 500;
+  background: var(--vp-c-bg-soft);
+  border-top: 1px solid var(--vp-c-divider);
+  color: var(--vp-c-text-2);
+  user-select: none;
+}
+
+.tui-statusline__left,
+.tui-statusline__right {
+  display: flex;
+  align-items: center;
+  gap: 0;
+}
+
+.tui-statusline__mode {
+  padding: 0 10px;
+  font-weight: 700;
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  color: var(--vp-c-bg);
+  background: var(--vp-c-brand-1);
+  line-height: 28px;
+  margin-left: -12px;
+}
+
+.tui-statusline__mode[data-mode="HOME"] {
+  background: var(--vp-c-brand-2);
+}
+
+.tui-statusline__sep {
+  display: inline-block;
+  margin: 0 2px;
+  color: var(--vp-c-divider);
+}
+
+.tui-statusline__sep::after {
+  content: '|';
+}
+
+.tui-statusline__file {
+  padding: 0 8px;
+  color: var(--vp-c-text-1);
+}
+
+.tui-statusline__section {
+  padding: 0 8px;
+  color: var(--vp-c-text-2);
+}
+
+.tui-statusline__date {
+  padding: 0 8px;
+  color: var(--vp-c-text-3);
+}
+
+.tui-statusline__branch {
+  padding: 0 10px;
+  font-weight: 600;
+  color: var(--vp-c-bg);
+  background: var(--vp-c-brand-3, var(--vp-c-brand-1));
+  line-height: 28px;
+  margin-right: -12px;
+}
+
+body {
+  padding-bottom: 28px;
+}
+
+@media (max-width: 640px) {
+  .tui-statusline__section,
+  .tui-statusline__date {
+    display: none;
+  }
+
+  .VPHome .VPHero::before {
+    display: none;
+  }
+}
+
+/* === Hero === */
+.VPHero .name {
+  font-family: var(--tui-font-mono) !important;
+}
+
+.VPHero .clip {
+  -webkit-text-fill-color: var(--vp-c-brand-1) !important;
+}
+
+.VPHero .text {
+  font-family: var(--tui-font-mono) !important;
+  font-size: 2rem !important;
+}
+
+.VPHero .tagline {
+  font-family: var(--tui-font-body);
+  color: var(--vp-c-text-2);
+}
+
+.VPHero .actions .action .VPButton {
+  font-family: var(--tui-font-mono);
+  font-size: 13px;
+  border-radius: 8px;
+  text-transform: lowercase;
+  transition: all var(--tui-transition);
+}
+
+.VPHero .actions .action .VPButton:hover {
+  transform: translateY(-1px);
+}
+
+.VPHero .actions .action .VPButton::before {
+  content: '[';
+  opacity: 0.5;
+  margin-right: 2px;
+}
+
+.VPHero .actions .action .VPButton::after {
+  content: ']';
+  opacity: 0.5;
+  margin-left: 2px;
+}
+
+.VPHero .image-container .image-bg {
+  opacity: 0.6;
+}
+
+/* === Features === */
+.VPFeatures .VPFeature {
+  border-radius: 8px !important;
+  border: 1px solid var(--vp-c-divider) !important;
+  transition: border-color var(--tui-transition), background var(--tui-transition),
+    transform var(--tui-transition);
+  position: relative;
+  overflow: hidden;
+}
+
+.VPFeatures .VPFeature::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  width: 0;
+  height: 2px;
+  background: var(--vp-c-brand-1);
+  transition: width 280ms ease;
+}
+
+.VPFeatures .VPFeature:hover {
+  border-color: var(--vp-c-brand-1) !important;
+  transform: translateY(-2px);
+}
+
+.VPFeatures .VPFeature:hover::after {
+  width: 100%;
+}
+
+.VPFeatures .VPFeature .title {
+  font-family: var(--tui-font-mono);
+  font-size: 14px;
+}
+
+.VPFeatures .VPFeature .details {
+  font-family: var(--tui-font-body);
+}
+
+/* === Outline === */
+.VPDocAsideOutline .outline-title {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.VPDocAsideOutline .outline-link {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  transition: color var(--tui-transition);
+}
+
+.VPDocAsideOutline .outline-link.active {
+  color: var(--vp-c-brand-1);
+}
+
+.VPDocAsideOutline .outline-link.active::before {
+  content: '> ';
+}
+
+/* === Doc footer === */
+.VPDocFooter .edit-link-button,
+.VPDocFooter .last-updated-text {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+}
+
+.VPDocFooter .pager-link {
+  border-radius: 0;
+  transition: border-color var(--tui-transition);
+}
+
+.VPDocFooter .pager-link:hover {
+  border-color: var(--vp-c-brand-1);
+}
+
+.VPDocFooter .pager-link .title {
+  font-family: var(--tui-font-mono);
+}
+
+.VPDocFooter .pager-link .desc {
+  font-family: var(--tui-font-mono);
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+/* === Search === */
+.VPLocalSearchBox .search-input {
+  font-family: var(--tui-font-mono);
+}
+
+/* === Background texture === */
+.VPDoc,
+.VPHome {
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.015'/%3E%3C/svg%3E");
+  background-repeat: repeat;
+  background-size: 200px 200px;
+}
+
+/* === Hero glow === */
+.VPHome .VPHero {
+  position: relative;
+  overflow: hidden;
+}
+
+.VPHome .VPHero::before {
+  content: '';
+  position: absolute;
+  top: -120px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 600px;
+  height: 400px;
+  background: radial-gradient(
+    ellipse at center,
+    var(--tui-hero-glow) 0%,
+    transparent 70%
+  );
+  pointer-events: none;
+  z-index: -1;
+}
+
+/* === Footer === */
+.VPFooter {
+  font-family: var(--tui-font-mono);
+  font-size: 12px;
+  border-top: 1px solid var(--vp-c-divider);
+}

docs-site/README.md

@@ -0,0 +1,47 @@
+# SubMiner docs
+
+In-repo VitePress documentation source for SubMiner.
+
+Internal architecture/workflow source of truth lives in `docs/README.md` at the repo root. Keep `docs-site/` user-facing.
+
+## Local development
+
+```bash
+bun --cwd docs-site install
+bun run docs:dev
+```
+
+Build and preview:
+
+```bash
+bun run docs:build
+bun run docs:preview
+bun run docs:test
+```
+
+Direct package commands still work from `docs-site/` if you prefer:
+
+```bash
+cd docs-site
+bun install
+bun run docs:dev
+```
+
+## Cloudflare Pages
+
+- Git repo: `ksyasuda/SubMiner`
+- Production branch: `main`
+- Automatic production and preview deployments: disabled
+- Custom domain: `docs.subminer.moe` attached to Production
+- Deployment path: GitHub Actions direct upload with Wrangler
+
+The public docs root is stable-only:
+
+- `/` serves the latest stable release docs.
+- `/main/` serves development docs from `main`.
+- `/v/<version>/` serves stable release archives.
+- Prerelease tags do not update the docs site.
+
+Only `/` is indexable. `/main/` and every `/v/<version>/` page carries a self-referential canonical plus `noindex,follow`, and the generated `_headers` file repeats that as an `X-Robots-Tag`. They stay crawlable so their links still resolve, but ~30 archived copies of every page would otherwise consume the crawl budget the current docs need. Only the root build emits `sitemap.xml`, and its `<lastmod>` dates come from `git log` against the tracked checkout at the released tag, because the build renders from an untracked snapshot that VitePress cannot date itself.
+
+Keep Cloudflare Git auto-deploy disabled. The production deploy is `.github/workflows/docs-pages.yml`, which uploads `.tmp/docs-versioned-site` with `--branch main` so tag-triggered runs update Production instead of creating preview deployments.

docs-site/anilist-integration.md

@@ -0,0 +1,137 @@
+# AniList integration
+
+SubMiner syncs your watch progress to [AniList](https://anilist.co). Finish an episode and it reads the title and episode number off the filename, finds the matching AniList entry, and updates your progress through the GraphQL API. A failed update retries in the background with exponential backoff.
+
+The same AniList data feeds [cover art](#cover-art) in the stats dashboard and the [Character Dictionary](/character-dictionary) for in-overlay name lookup.
+
+[AniList](https://anilist.co) is a free anime tracking site. The **access token** is a private key SubMiner keeps so it can update your list for you. You approve it once during setup, and your AniList password never touches SubMiner.
+
+## Setup
+
+AniList integration is opt-in. To enable it:
+
+1. Set `anilist.enabled` to `true` in your config.
+2. Leave `anilist.accessToken` empty and restart SubMiner (or run `--anilist-setup`).
+3. Approve access in the AniList authorization page.
+4. The callback returns to SubMiner via the `subminer://anilist-setup?...` protocol URL, and SubMiner stores the token automatically.
+
+```jsonc
+{
+  "anilist": {
+    "enabled": true,
+    "accessToken": "",
+  },
+}
+```
+
+The access token is encrypted at rest using Electron's `safeStorage` API. On Linux this defaults to `gnome-libsecret`; override the backend with `--password-store=<backend>` (for example `--password-store=basic_text`).
+
+If the embedded auth UI fails to render, SubMiner opens the authorize URL in your default browser and shows fallback instructions in-app.
+
+::: tip
+You can also set `anilist.accessToken` directly in config to skip the setup flow entirely. When blank, SubMiner uses the locally stored encrypted token.
+:::
+
+## How tracking works
+
+SubMiner watches playback and pushes an AniList progress update once an episode counts as watched. That means at least 85% of its duration, and at least 10 minutes either way.
+
+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 base title (with any `Season N` / `SN` marker stripped) is searched against the AniList GraphQL API, and SubMiner picks the best match by comparing titles (romaji, English, native, synonyms) and filtering by episode count. AniList has no notion of numbered seasons - sequels are separate entries with their own titles (`Zoku`, `Kan`, `2nd Season`), so searching `<title> Season 3` finds nothing. For season 2 and later, SubMiner instead walks `SEQUEL` relations from the season 1 entry, preferring the TV line, and falls back to ordering the franchise's TV entries by air date when the relation chain is incomplete. If neither locates the season, SubMiner **skips the update** rather than writing progress to the season 1 entry, and tells you to pin the right entry with a [character dictionary override](/character-dictionary#correcting-anilist-matches).
+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`, 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
+
+Failed AniList updates are persisted to a retry queue on disk and retried with exponential backoff.
+
+Updates are skipped if the media path cannot produce a safe, nonempty identity. Invalid entries are discarded when loading or adding to the retry queue.
+
+| Parameter        | Value      |
+| ---------------- | ---------- |
+| Initial backoff  | 30 seconds |
+| Maximum backoff  | 6 hours    |
+| Maximum attempts | 8          |
+| Queue capacity   | 500 items  |
+
+After 8 failed attempts, the update is moved to a dead-letter queue and no longer retried automatically. The queue is persisted across restarts so no updates are lost if SubMiner exits before a retry succeeds.
+
+Use `--anilist-retry-queue` to manually process one ready item from the queue.
+
+## Cover art
+
+SubMiner fetches cover art from AniList for display in the stats dashboard. When a new video starts playing, the cover art fetcher:
+
+1. Checks the local database for cached art.
+2. If missing, parses the media title (guessit then fallback) and searches the AniList API.
+3. Downloads the cover image from the AniList CDN and caches it locally (both URL and blob).
+4. Stores AniList metadata (romaji/English titles, total episodes) alongside the cover for dashboard display.
+
+A no-match result is cached for 5 minutes before SubMiner retries, preventing repeated API calls for unrecognized media.
+
+When AniList has no match, SubMiner tries [TMDB](/configuration#tmdb) next so live-action dramas and movies get a poster and synopsis too. See [Immersion tracking](/immersion-tracking#library) for how live-action entries are grouped.
+
+If the automatic match is wrong, use **Change AniList Entry** on a title in the stats Library. Relinking rewrites the cached art for every episode of that title, and both the detail view and the Library grid pick up the new cover right away: the grid refetches after a relink, and cover responses carry an ETag and are revalidated on each request instead of being cached for a day.
+
+## Rate limiting
+
+All AniList API calls go through a shared rate limiter that enforces a sliding window of 20 requests per minute. The limiter also reads AniList's `X-RateLimit-Remaining` and `Retry-After` response headers and pauses requests when the server signals throttling. This applies to both episode tracking and cover art fetching.
+
+## Configuration reference
+
+```jsonc
+{
+  "anilist": {
+    "enabled": true,
+    "accessToken": "",
+    "characterDictionary": {
+      "maxLoaded": 3,
+      "profileScope": "all",
+      "collapsibleSections": {
+        "description": false,
+        "characterInformation": false,
+        "voicedBy": false,
+      },
+    },
+  },
+}
+```
+
+| Option                                      | Values                  | Description                                                                                                  |
+| ------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `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                                                       |
+
+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
+
+| Command                 | Description                                                   |
+| ----------------------- | ------------------------------------------------------------- |
+| `--anilist-setup`       | Open AniList setup/auth flow helper window                    |
+| `--anilist-status`      | Print current token resolution state and retry queue counters |
+| `--anilist-logout`      | Clear stored AniList token from local persisted state         |
+| `--anilist-retry-queue` | Process one ready retry queue item immediately                |
+
+## Troubleshooting
+
+- **Updates not triggering:** Confirm `anilist.enabled` is `true`. SubMiner requires at least 85% of the episode watched and a minimum of 10 minutes. Short episodes or partial watches will not trigger an update.
+- **Update not possible:** Add the season to your AniList Planning or Watching list first. SubMiner will not create new AniList list entries automatically.
+- **Wrong episode or title matched:** Detection quality is best when `guessit` is installed and on your `PATH`. Without it, SubMiner falls back to internal filename parsing which can be less accurate with unusual naming conventions.
+- **Token issues:** Run `--anilist-status` to check token state. If the token is invalid or expired, run `--anilist-setup` or `--anilist-logout` and re-authenticate.
+- **Updates failing repeatedly:** Run `--anilist-status` to see retry queue counters. Items that fail 8 times are moved to the dead-letter queue. Check network connectivity and AniList API status.
+- **Cover art missing:** Cover art is fetched on a best-effort basis using title matching. If the filename is hard to parse, the search may return no results. The fetcher retries after 5 minutes.
+- **Encryption unavailable on Linux:** If you see warnings about safeStorage, try `--password-store=basic_text` as a workaround, or start your desktop keyring (gnome-keyring, KWallet).
+
+## Related
+
+- [Character Dictionary](/character-dictionary) - AniList-powered character name dictionary for Yomitan
+- [Configuration Reference](/configuration) - full config options
+- [Jellyfin Integration](/jellyfin-integration) - media server integration

docs-site/aniskip-integration.md

@@ -0,0 +1,53 @@
+# AniSkip integration
+
+SubMiner looks up anime intro timings from [AniSkip](https://aniskip.com) so you can jump past the OP with one key.
+
+Intro detection runs in the SubMiner app over the mpv IPC socket. It works whenever the overlay is connected to mpv, not only at launch, and covers every local file loaded during the session including playlist advances.
+
+## Setup
+
+AniSkip is enabled by default. Disable it or change the skip key in your config:
+
+```jsonc
+{
+  "mpv": {
+    "aniskipEnabled": true, // default: true
+    "aniskipButtonKey": "TAB",
+  },
+}
+```
+
+Both settings hot-reload: changing them in your config takes effect immediately without restarting playback or mpv.
+
+For best title and episode detection, install [`guessit`](https://github.com/guessit-io/guessit):
+
+```bash
+python3 -m pip install --user guessit
+```
+
+Without `guessit`, SubMiner falls back to its own filename parser. That handles the usual release naming, but unusual formats slip past it.
+
+## How it works
+
+On each local file load:
+
+1. SubMiner infers the anime title, season, and episode number from the filename and path (using `guessit` if available, otherwise the built-in parser). Remote URLs are skipped entirely.
+2. The title is matched against MyAnimeList to resolve a MAL id.
+3. SubMiner queries the AniSkip API for an OP skip interval for that MAL id and episode.
+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.
+
+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 a definitive "no intro found" is cached, so a failed lookup gets retried on the next load rather than sticking. If mpv reloads the same file, SubMiner re-applies the chapter markers without hitting the API again.
+
+## Triggering from mpv
+
+AniSkip actions are also reachable from mpv script-messages:
+
+| Command | Effect |
+| ------- | ------ |
+| `script-message subminer-skip-intro` | Skip to the intro end immediately (same as pressing the key) |
+| `script-message subminer-aniskip-refresh` | Force a fresh lookup for the current file, discarding any cached result |
+
+The SubMiner app handles both over the IPC socket.

docs-site/anki-integration.md

@@ -0,0 +1,427 @@
+# Anki integration
+
+SubMiner uses the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on to create and update Anki cards with sentence context, audio, and screenshots.
+This project is built primarily for [Kiku](https://kiku.youyoumu.my.id/) and [Lapis](https://github.com/donkuri/lapis) note types, including sentence-card and field-grouping behavior.
+
+::: tip New to these terms?
+
+- **Anki** is the flashcard app where your study cards live.
+- **AnkiConnect** is a free add-on that lets other programs (like SubMiner) talk to Anki over a local connection. SubMiner needs it installed to add or edit cards.
+- A **note type** (also called a "model") is the template that defines what a card looks like - for example the Kiku or Lapis templates many Japanese learners use.
+- A **field** is one labeled slot in that template, such as `Sentence`, `Expression`, or `Picture`. SubMiner fills these fields when it mines a card.
+  :::
+
+## Prerequisites
+
+1. Install [Anki](https://apps.ankiweb.net/).
+2. Install the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on (code: `2055492159`).
+3. Keep Anki running while using SubMiner.
+
+AnkiConnect listens on `http://127.0.0.1:8765` by default. If you changed the port in AnkiConnect's settings, update `ankiConnect.url` in your SubMiner config.
+
+AnkiConnect and Kiku/Senren settings follow the [configuration validation rules](/configuration#configuration-file): invalid values produce a warning and fall back to the option's default. Use JSON booleans such as `true`, not strings such as `"true"`, and a positive number for `ankiConnect.pollingRate`.
+
+## Auto-enrichment transport
+
+When you add a word via Yomitan, SubMiner detects the new card and fills in the sentence, audio, and image fields automatically. Two detection methods are available:
+
+**Proxy mode** (default) - SubMiner runs a small local server between Yomitan and Anki. Yomitan sends the new card to SubMiner, SubMiner fills in the media fields, and the finished card goes on to Anki. There is no polling delay.
+
+**Polling mode** (fallback, when the proxy is disabled) - SubMiner asks AnkiConnect every few seconds whether new cards showed up, then fills them in. Less to configure, at the cost of roughly a 3 second delay.
+
+Use proxy mode unless your Yomitan runs in a browser rather than the bundled instance, in which case polling is the simpler path.
+
+In both modes, the enrichment workflow is the same:
+
+1. Checks if a duplicate expression already exists (for field grouping).
+2. Updates the sentence field with the current subtitle.
+3. Generates and uploads audio and image media.
+4. 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 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)
+
+```jsonc
+"ankiConnect": {
+  "url": "http://127.0.0.1:8765", // real AnkiConnect
+  "proxy": {
+    "enabled": true,
+    "host": "127.0.0.1",
+    "port": 8766,
+    "upstreamUrl": "http://127.0.0.1:8765"
+  }
+}
+```
+
+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 **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 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`).
+
+### Browser/Yomitan external setup (separate profile)
+
+If you want SubMiner to use proxy mode without touching your main/default Yomitan profile, create or select a separate Yomitan profile just for SubMiner and set its Anki server to the proxy URL.
+
+That profile isolation gives you both benefits:
+
+- SubMiner can auto-enrich immediately via proxy.
+- Your default Yomitan profile keeps its existing Anki server setting.
+
+In Yomitan, go to Settings → Profile and:
+
+1. Create a profile for SubMiner (or choose one dedicated profile).
+2. Open Anki settings for that profile.
+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 the active profile when its server is blank or still default.
+
+### Proxy troubleshooting (quick checks)
+
+If auto-enrichment appears to do nothing:
+
+1. Confirm proxy listener is running while SubMiner is active:
+
+```bash
+ss -ltnp | rg 8766
+```
+
+2. Confirm requests can pass through the proxy:
+
+```bash
+curl -sS http://127.0.0.1:8766 \
+  -H 'content-type: application/json' \
+  -d '{"action":"version","version":2}'
+```
+
+3. Check the log sinks in `~/.config/SubMiner/logs/`:
+
+- App runtime log: `app-YYYY-MM-DD.log`
+- Launcher log: `launcher-YYYY-MM-DD.log`
+- mpv log: `mpv-YYYY-MM-DD.log`
+
+4. Check that the config JSONC parses and the logging shape is right:
+
+```jsonc
+"logging": {
+  "level": "debug"
+}
+```
+
+`"logging": "debug"` is invalid for current schema and can break reload/start behavior.
+
+## Field mapping
+
+SubMiner maps its data to your Anki note fields. Configure these under `ankiConnect.fields`:
+
+```jsonc
+"ankiConnect": {
+  "fields": {
+    "word": "Expression",        // mined word / expression text
+    "audio": "SentenceAudio",    // sentence audio clip cut from the video
+    "wordAudio": "ExpressionAudio", // existing Yomitan word audio, read for animation sync
+    "image": "Picture",          // screenshot or animated clip
+    "sentence": "Sentence",      // subtitle text
+    "miscInfo": "MiscInfo"       // metadata (filename, timestamp)
+  }
+}
+```
+
+`fields.audio` receives the **sentence** audio SubMiner cuts from the video, not word audio. Yomitan writes its own dictionary audio when you mine, so point this at a separate field such as `SentenceAudio` to keep the two apart. The built-in default is still `ExpressionAudio`, which collides with Yomitan on note types that use that field for word audio.
+
+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.
+
+`fields.wordAudio` selects the existing dictionary-audio field used to calculate the animated image's opening freeze. This mapping only reads audio; `fields.audio` still controls where generated sentence audio is written. See [config.example.jsonc](/config.example.jsonc) for defaults.
+
+These mappings always control normal word-card enrichment, including Yomitan proxy/polling updates and manual clipboard updates. Enabling Lapis or Kiku does not replace the configured word-card sentence and audio fields with `Sentence` and `SentenceAudio`. The dedicated sentence-card and audio-card shortcuts still use those Lapis/Kiku field names.
+
+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
+
+If you only want sentence and audio on your cards:
+
+```jsonc
+"ankiConnect": {
+  "enabled": true,
+  "fields": {
+    "sentence": "Sentence",
+    "audio": "SentenceAudio"
+  }
+}
+```
+
+## Media generation
+
+SubMiner shells out to FFmpeg for audio clips and screenshots, so FFmpeg has to be installed and on `PATH`.
+
+For remote streams such as Jellyfin playback, SubMiner downloads the clip's time window once into a temporary Matroska file (a stream copy, no re-encoding) and reads the timing review waveform, audio preview, audio, and image from that file instead of fetching the stream again for each step. The window covers the clip plus padding, plus the visible timeline in timing review, and grows when you reveal more of the timeline. It is deleted when a different window replaces it, after ten minutes without use, or when SubMiner exits. If the download fails, media generation reads the remote stream directly as before.
+
+### Audio
+
+Audio is extracted from the video file using the subtitle's start and end timestamps. Padding is opt-in; keep it at `0` when you want sentence audio to start exactly at the mined sentence.
+
+```jsonc
+"ankiConnect": {
+  "media": {
+    "generateAudio": true,
+    "normalizeAudio": true,      // normalize generated clip loudness
+    "mirrorMpvVolume": true,     // apply the current mpv volume level
+    "reviewTiming": false,       // review and adjust timing before media generation
+    "audioPadding": 0,           // optional seconds before and after subtitle timing
+    "maxMediaDuration": 30       // cap total duration in seconds
+  }
+}
+```
+
+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.
+
+The audio is uploaded to Anki's media folder and inserted as `[sound:audio_<timestamp>.mp3]`.
+
+Overlay and stats-dashboard mining use the same `media.maxMediaDuration` limit. See the [configuration example](/config.example.jsonc) for its default and how to disable the cap.
+
+Set `media.reviewTiming` to `true` to pause playback and check the clip before its media is generated. It applies to word, sentence, and audio cards.
+
+The review opens on the subtitle range plus your configured audio padding. Subtitles usually hang around after the dialogue has stopped, so once the waveform loads, an untouched clip end pulls back to just after the last speech in the line. The Line end rail still marks the original subtitle timing, Reset puts it back, and a line whose speech runs right through its end is left alone.
+
+**Adjusting the clip.** Drag either edge to trim, drag the middle to slide the whole clip without changing its length, or click anywhere on the waveform to snap the nearer edge there. A focused edge also moves with the arrow keys: 100 ms per press, or 500 ms with Shift. The 100 ms buttons do the same thing. Earlier and Later each reveal two more seconds of timeline without moving the selection.
+
+**Choosing the screenshot.** With still images enabled, drag the screenshot slider or use the Frame buttons to choose a video frame independently of the audio. Earlier and Later reveal more time for both sliders. The image follows the audio midpoint until you pick a frame, then stays fixed while you trim audio. Reset below the image restores automatic selection; the audio Reset affects only the audio. The screenshot slider also supports arrow keys, Home, and End.
+
+The picker supports local video and seekable remote streams, including Jellyfin, without seeking the main player. A selected frame must load before you can confirm; if it fails, choose another frame or Reset. The picker is hidden when image generation is disabled or animated AVIF is selected. Animated images continue to use the reviewed audio range.
+
+**Keys.** Space previews the selection with a playhead sweeping the clip. The preview ends when the hidden player has actually played the last sample, so Bluetooth output latency does not clip the tail. Enter confirms and Escape cancels.
+
+**The waveform.** SubMiner reads a center channel when one carries dialogue and falls back to a mono mix otherwise, keeps only the 250 to 3500 Hz speech band, and draws each slice's loudness against the clip's own noise floor. Steady background music flattens out and dialogue stands up, which makes it much easier to tell adjacent lines apart. The mined subtitle appears as a tinted band with labeled line-start and line-end rails. If waveform analysis fails, the timing controls still work.
+
+The range you confirm is used exactly as-is; SubMiner does not add audio padding a second time. Static screenshots take its midpoint, and animated AVIF clips cover the whole range.
+
+**Pulling in adjacent lines.** Press `P` or `N`, or use the Prev and Next steppers above the sentence preview, to add the previous or next subtitle line. Repeat for as many lines as exist. Shift+`P` and Shift+`N` remove them again. The sentence preview lists every included line with the mined one highlighted, so you always see the sentence field before confirming. The clip bounds and the waveform rails follow the outermost added line, keeping the review's audio padding.
+
+Confirming writes the combined lines to the sentence field. Reset drops the added lines along with any timing changes. Adjacent lines come from the parsed subtitle track when one is loaded; otherwise you only get lines that already played. A clip capped by `media.maxMediaDuration` still keeps the full combined sentence even when the audio cannot stretch to cover every added line.
+
+**Canceling.** You can go back to editing, finish with the original timing, create the card without audio or an image, or discard it. Discard deletes an existing Yomitan or audio card, and skips creation entirely for a direct sentence card. A failed audio preview does not block confirmation or card creation.
+
+When word-card enrichment changes the sentence context, including an expanded timing-review selection, SubMiner regenerates `SentenceFurigana` from the final sentence. Unchanged sentences keep their existing furigana formatting. If generation fails, SubMiner clears stale furigana so compatible templates can fall back to `Sentence`.
+
+Clipboard updates and stats-dashboard mining never open timing review. The option is off by default and hot-reloads. **Review Media Timing** in the runtime options palette (`Ctrl/Cmd+Shift+O`) toggles it for the current session.
+
+If SubMiner closes the overlay while a timing review is still loading, it cancels pending setup and modal retries and restores playback if the review paused it. A new timing review can start after the overlay reopens.
+
+### Screenshots (static)
+
+A single frame is captured at the current playback position.
+
+```jsonc
+"ankiConnect": {
+  "media": {
+    "generateImage": true,
+    "imageType": "static",
+    "imageFormat": "jpg",        // "jpg", "png", or "webp"
+    "imageQuality": 92,          // 1–100
+    "imageMaxWidth": 0,          // 0 = preserve source resolution
+    "imageMaxHeight": 0
+  }
+}
+```
+
+### Animated clips (AVIF)
+
+SubMiner can produce an animated AVIF spanning the subtitle duration instead of a still frame.
+
+```jsonc
+"ankiConnect": {
+  "media": {
+    "generateImage": true,
+    "imageType": "avif",
+    "animatedFps": 10,
+    "animatedMaxWidth": 640,
+    "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. `media.syncAnimatedImageToWordAudio` (default `true`) prepends a frozen first frame matching the existing audio duration in `fields.wordAudio`, so the motion starts together with the sentence audio. The freeze is baked into the image when mined; changing the mapping does not repair previously generated images.
+
+### Behavior options
+
+```jsonc
+"ankiConnect": {
+  "behavior": {
+    "overwriteAudio": true,         // replace existing audio, or append
+    "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"
+  }
+}
+```
+
+`both` now means overlay + system notification. `osd` and `osd-system` are legacy config-file-only values; set `notificationType` to `"osd-system"` in `config.jsonc` if you previously used `both` and want to keep mpv OSD + system notifications. The Settings window shows `osd` or `osd-system` when already configured, but only offers `overlay`, `system`, `both`, and `none` as normal choices.
+
+When media is available, mined-card overlay and system notifications include the same current-frame thumbnail.
+
+`overwriteAudio` applies to automatic card updates and duplicate-card enrichment. Manual clipboard subtitle updates (`Ctrl/Cmd+C`, then `Ctrl/Cmd+V`) always replace generated sentence audio in `ankiConnect.fields.audio`, even when `overwriteAudio` is disabled.
+
+## Sentence cards (Lapis)
+
+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 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": "Lapis" // default; point at your Lapis/Kiku note type
+  }
+}
+```
+
+Trigger with the mine sentence shortcut (`Ctrl/Cmd+S` by default). The card is created directly via AnkiConnect with the sentence, audio, and image filled in.
+
+The dedicated sentence-card and audio-card shortcuts use the Lapis/Kiku-compatible `Sentence` and `SentenceAudio` fields. This does not affect the configured fields used to enrich normal word cards.
+
+To mine multiple subtitle lines as one sentence card, use `Ctrl/Cmd+Shift+S` followed by a digit (1–9) to select how many recent lines to combine.
+
+## Word card type (Kiku/Lapis)
+
+Word cards get a card-type flag when SubMiner fills their sentence, whether that comes from Yomitan auto-enrichment, a manual clipboard update, or stats-dashboard word mining. By default the flag is `IsWordAndSentenceCard`; pick a different one with `ankiConnect.lapisKiku.wordCardKind`.
+
+```jsonc
+"ankiConnect": {
+  "isKiku": { "enabled": true },
+  "lapisKiku": {
+    "wordCardKind": "click" // word-and-sentence (default), click, sentence, audio, none
+  }
+}
+```
+
+`click` marks `IsClickCard`, `sentence` marks `IsSentenceCard`, `audio` marks `IsAudioCard`, and `none` leaves the flags untouched for templates that manage them elsewhere. Whichever flag is chosen, the other card-type flags are cleared so the note never claims two card types. The setting is only read when `isKiku` or `isLapis` is enabled, and cards mined with Mine Sentence or Mine Audio keep their own flag.
+
+## Field grouping (Kiku/Senren)
+
+When you mine the same word multiple times, SubMiner can merge the cards instead of creating duplicates. This is designed for note types that support grouped fields: [Kiku](https://github.com/youyoumu/kiku) and [Senren](https://github.com/BrenoAqua/Senren) (which calls the feature scene switching).
+
+```jsonc
+"ankiConnect": {
+  "isKiku": {
+    "enabled": true,
+    "fieldGrouping": "manual",         // "auto", "manual", or "disabled"
+    "deleteDuplicateInAuto": true      // delete new card after auto-merge
+  }
+}
+```
+
+For Senren note types, enable `isSenren` instead. Kiku and Senren write incompatible markup into the same fields, so only one can be enabled at a time; if both are enabled, Kiku wins and a config warning is emitted.
+
+```jsonc
+"ankiConnect": {
+  "isSenren": {
+    "enabled": true,
+    "fieldGrouping": "auto",           // "auto" (default), "manual", or "disabled"
+    "deleteDuplicateInAuto": true      // delete new card after auto-merge
+  }
+}
+```
+
+### Modes
+
+**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 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 cards' sentences kept as grouped entries   |
+| Audio    | Both cards' `[sound:...]` entries kept          |
+| Image    | Both cards' images kept                         |
+| MiscInfo | Both cards' source info kept as grouped entries |
+
+Identical values from both cards are kept as separate grouped entries; the merge does not deduplicate.
+
+The merge markup depends on the note type. Kiku entries are wrapped in `<span data-group-id="...">` spans ordered newest first. Senren entries follow the [scene switching](https://github.com/BrenoAqua/Senren/blob/main/docs/scene_switching.md) format: sentence, sentenceFurigana, and miscInfo entries use `group` spans when ordinal order is sufficient and numbered `groupN` spans when they need an absolute scene target. Audio and pictures are appended positionally, and the number of sentenceAudio entries drives Senren's scene count. Ungrouped legacy content is wrapped into a group span on first merge, and source `groupN` spans are rebased after the kept note's existing audio scenes.
+
+### Keyboard shortcuts in the modal
+
+| 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
+
+```jsonc
+{
+  "ankiConnect": {
+    "enabled": true,
+    "url": "http://127.0.0.1:8765",
+    "pollingRate": 3000,
+    "deck": "",
+    "tags": ["SubMiner"],
+    "proxy": {
+      "enabled": true, // default
+      "host": "127.0.0.1",
+      "port": 8766,
+      "upstreamUrl": "http://127.0.0.1:8765",
+    },
+    "fields": {
+      "word": "Expression",
+      "audio": "SentenceAudio",
+      "image": "Picture",
+      "sentence": "Sentence",
+      "miscInfo": "MiscInfo",
+    },
+    "media": {
+      "generateAudio": true,
+      "generateImage": true,
+      "imageType": "static",
+      "imageFormat": "jpg",
+      "imageQuality": 92,
+      "normalizeAudio": true,
+      "mirrorMpvVolume": true,
+      "audioPadding": 0,
+      "maxMediaDuration": 30,
+    },
+    "behavior": {
+      "overwriteAudio": true,
+      "overwriteImage": true,
+      "mediaInsertMode": "append",
+      "autoUpdateNewCards": true,
+      "notificationType": "overlay",
+    },
+    "metadata": {
+      "pattern": "[SubMiner] %f (%t)",
+    },
+    "isKiku": {
+      "enabled": false,
+      "fieldGrouping": "disabled",
+      "deleteDuplicateInAuto": true,
+    },
+    "isLapis": {
+      "enabled": false,
+      "sentenceCardModel": "Lapis",
+    },
+  },
+}
+```

docs-site/architecture.md

@@ -1,10 +1,12 @@
 # Architecture
 
+This page is a contributor-facing architecture summary. Canonical internal architecture guidance lives in `docs/architecture/README.md` at the repo root.
+
 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.
 
@@ -18,24 +20,27 @@ Within the desktop app, `src/main.ts` is a composition root that wires small run
   - services compose through explicit inputs/outputs
   - orchestration is separate from implementation
 
-## Project Structure
+## Project structure
 
 ```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 · aniskip · aniskip_match)
+                          #   binary · session_bindings · version)
 src/
   main-entry.ts           # Background-mode bootstrap wrapper before loading main.js
-  main.ts                  # Entry point — delegates to runtime composers/domain modules
+  main.ts                  # Entry point - delegates to runtime composers/domain modules
   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
     config-validation.ts   # Startup/hot-reload config error formatting and fail-fast helpers
     dependencies.ts        # Shared dependency builders for IPC/runtime services
@@ -50,6 +55,7 @@ src/
     startup-lifecycle.ts    # Lifecycle runtime runner adapter
     state.ts                # Application runtime state container + reducer transitions
     subsync-runtime.ts      # Subsync command runtime adapter
+    character-dictionary-runtime/ # Character-dictionary fetch/build/cache modules + focused tests
     runtime/
       composers/            # High-level composition clusters used by main.ts
       domains/              # Domain barrel exports (startup/overlay/mpv/jellyfin/...)
@@ -66,20 +72,20 @@ 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,
+                           #   changelog, character dictionary, playlist browser, subtitle
+                           #   sidebar, YouTube track picker, controller config/debug/select)
     positioning/           # Subtitle position controller (drag-to-reposition)
-  window-trackers/         # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS)
+  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/`)
+### Service layer (`src/core/services/`)
 
 - **Overlay/window runtime:** `overlay-manager.ts`, `overlay-window.ts`, `overlay-visibility.ts`, `overlay-bridge.ts`, `overlay-runtime-init.ts`, `overlay-content-measurement.ts`
 - **Shortcuts/input:** `shortcut.ts`, `overlay-shortcut.ts`, `overlay-shortcut-handler.ts`, `shortcut-fallback.ts`, `numeric-shortcut.ts`
@@ -87,11 +93,11 @@ 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)
 
-### Renderer Layer (`src/renderer/`)
+### Renderer layer (`src/renderer/`)
 
 The renderer keeps `renderer.ts` focused on orchestration. UI behavior is delegated to per-concern modules.
 
@@ -111,28 +117,35 @@ 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
 ```
 
-### Launcher + Plugin Runtimes
+### 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.lua` + `aniskip_match.lua` (intro-skip UX).
+- `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
+## Flow diagram
 
 The main process orchestrates a single primary overlay window plus modal surfaces: `main.ts` delegates to composition modules that wire together domain services. Subtitle layers (primary + secondary bar) are rendered in the same overlay renderer process, connected through `preload.ts`. External runtimes (launcher CLI and mpv plugin) operate independently and communicate via IPC socket or CLI passthrough.
 
 ```mermaid
-flowchart LR
+flowchart TB
   classDef entry fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:2px,font-weight:bold
   classDef comp fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
   classDef svc fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
@@ -142,43 +155,48 @@ flowchart LR
   classDef extrt fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
 
   subgraph ExtRt["External Runtimes"]
-    Launcher["launcher/<br/>CLI dispatch"]:::extrt
-    Plugin["subminer/init.lua<br/>mpv plugin"]:::extrt
+    direction LR
+    Launcher["Launcher CLI"]:::extrt
+    Plugin["mpv Plugin"]:::extrt
+  end
+
+  Main["main.ts"]:::entry
+
+  subgraph Comp["Composition"]
+    direction LR
+    Startup["Startup & Lifecycle"]:::comp
+    Wiring["Runtime Wiring"]:::comp
+    Composers["Domain Composers"]:::comp
+  end
+
+  subgraph Svc["Services"]
+    direction LR
+    Mpv["MPV Stack"]:::svc
+    OverlaySvc["Overlay Manager"]:::svc
+    Mining["Mining & Subtitles"]:::svc
+    AnkiProxy["Anki Proxy"]:::svc
+    Integrations["Integrations"]:::svc
+    Tracking["Tracking"]:::svc
+    Config["Config & Options"]:::svc
+  end
+
+  Bridge(["preload.ts"]):::bridge
+
+  subgraph Rend["Renderer"]
+    direction LR
+    OverlayWin["Overlay Window"]:::rend
+    UI["Subtitles & Modals"]:::rend
   end
 
   subgraph Ext["External Systems"]
-    mpvExt["mpv player"]:::ext
+    direction LR
+    mpvExt["mpv"]:::ext
     AnkiExt["AnkiConnect"]:::ext
-    JimakuExt["Jimaku API"]:::ext
-    TrackerExt["Window Tracker<br/>Hyprland · Sway<br/>X11 · macOS"]:::ext
-    AnilistExt["AniList API"]:::ext
+    JimakuExt["Jimaku"]:::ext
+    TrackerExt["Window Tracker"]:::ext
+    AnilistExt["AniList"]:::ext
     JellyfinExt["Jellyfin"]:::ext
-    DiscordExt["Discord RPC"]:::ext
-  end
-
-  Main["main.ts<br/>composition root"]:::entry
-
-  subgraph Comp["Composition — src/main/"]
-    Startup["Startup & Lifecycle<br/>startup · app-lifecycle<br/>startup-lifecycle · state"]:::comp
-    Wiring["Runtime Wiring<br/>ipc-runtime · cli-runtime<br/>overlay-runtime"]:::comp
-    Composers["Composers<br/>mpv · anilist<br/>jellyfin"]:::comp
-  end
-
-  subgraph Svc["Services — src/core/services/"]
-    Mpv["MPV Stack<br/>transport · protocol<br/>properties · metrics"]:::svc
-    OverlaySvc["Overlay Manager<br/>window · visibility · bridge<br/>mpv-sub-visibility"]:::svc
-    Mining["Mining & Subtitles<br/>mining · field-grouping<br/>subtitle-ws · tokenizer"]:::svc
-    AnkiProxy["Anki Integration<br/>anki-connect-proxy<br/>note-update-workflow"]:::svc
-    Integrations["Integrations<br/>jimaku · subsync<br/>texthooker · yomitan"]:::svc
-    Tracking["Tracking<br/>anilist · jellyfin<br/>immersion · discord"]:::svc
-    Config["Config & Runtime<br/>hot-reload<br/>runtime-options"]:::svc
-  end
-
-  Bridge(["preload.ts<br/>Electron IPC"]):::bridge
-
-  subgraph Rend["Renderer — src/renderer/"]
-    OverlayWin["Main overlay window<br/>primary + secondary subtitles"]:::rend
-    UI["subtitle-render<br/>positioning<br/>handlers · modals"]:::rend
+    DiscordExt["Discord"]:::ext
   end
 
   Launcher -->|"CLI"| Main
@@ -187,7 +205,10 @@ flowchart LR
   Main --> Comp
   Comp --> Svc
 
-  mpvExt <-->|"JSON socket"| Mpv
+  Svc --> Bridge
+  Bridge --> Rend
+
+  mpvExt <-->|"socket"| Mpv
   AnkiExt <-->|"HTTP"| AnkiProxy
   JimakuExt <-->|"HTTP"| Integrations
   TrackerExt <-->|"platform"| OverlaySvc
@@ -195,10 +216,6 @@ flowchart LR
   JellyfinExt <-->|"HTTP"| Tracking
   DiscordExt <-->|"RPC"| Integrations
 
-  OverlaySvc & Mining --> Bridge
-  Bridge --> OverlayWin
-  OverlayWin --> UI
-
   style Comp fill:#363a4f,stroke:#494d64,color:#cad3f5
   style Svc fill:#363a4f,stroke:#494d64,color:#cad3f5
   style Rend fill:#363a4f,stroke:#494d64,color:#cad3f5
@@ -206,7 +223,7 @@ flowchart LR
   style ExtRt fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-## Composition Pattern
+## Composition pattern
 
 Most runtime code follows a dependency-injection pattern:
 
@@ -217,17 +234,17 @@ Most runtime code follows a dependency-injection pattern:
 
 The composition root (`src/main.ts`) delegates to focused modules in `src/main/` and `src/main/runtime/composers/`:
 
-- `startup.ts` — argv/env processing and bootstrap flow
-- `app-lifecycle.ts` — Electron lifecycle event registration
-- `startup-lifecycle.ts` — app-ready initialization sequence
-- `state.ts` — centralized application runtime state container
-- `ipc-runtime.ts` — IPC channel registration and handler wiring
-- `cli-runtime.ts` — CLI command parsing and dispatch
-- `overlay-runtime.ts` — overlay window selection and modal state management
-- `subsync-runtime.ts` — subsync command orchestration
-- `runtime/composers/anilist-tracking-composer.ts` — AniList media tracking/probe/retry wiring
-- `runtime/composers/jellyfin-runtime-composer.ts` — Jellyfin config/client/playback/command/setup composition wiring
-- `runtime/composers/mpv-runtime-composer.ts` — MPV event/factory/tokenizer/warmup wiring
+- `startup.ts` - argv/env processing and bootstrap flow
+- `app-lifecycle.ts` - Electron lifecycle event registration
+- `startup-lifecycle.ts` - app-ready initialization sequence
+- `state.ts` - centralized application runtime state container
+- `ipc-runtime.ts` - IPC channel registration and handler wiring
+- `cli-runtime.ts` - CLI command parsing and dispatch
+- `overlay-runtime.ts` - overlay window selection and modal state management
+- `subsync-runtime.ts` - subsync command orchestration
+- `runtime/composers/anilist-tracking-composer.ts` - AniList media tracking/probe/retry wiring
+- `runtime/composers/jellyfin-runtime-composer.ts` - Jellyfin config/client/playback/command/setup composition wiring
+- `runtime/composers/mpv-runtime-composer.ts` - MPV event/factory/tokenizer/warmup wiring
 
 Composer modules share contract conventions via `src/main/runtime/composers/contracts.ts`:
 
@@ -243,14 +260,14 @@ Additional conventions in the current code:
 - Domain barrels in `src/main/runtime/domains/*` re-export runtime handlers + main-deps builders, while composers in `src/main/runtime/composers/*` assemble larger runtime clusters.
 - Many runtime handlers accept `*MainDeps` objects generated by `createBuild*MainDepsHandler` builders to isolate side effects and keep units testable.
 
-### IPC Contract + Validation Boundary
+### IPC contract + validation boundary
 
 - Central channel constants live in `src/shared/ipc/contracts.ts` and are consumed by both main (`ipcMain`) and renderer preload (`ipcRenderer`) wiring.
 - Runtime payload parsers/type guards live in `src/shared/ipc/validators.ts`.
 - Rule: renderer-supplied payloads must be validated at IPC entry points (`src/core/services/ipc.ts`, `src/core/services/anki-jimaku-ipc.ts`) before calling domain handlers.
 - Malformed invoke payloads return explicit structured errors (for example `{ ok: false, error: ... }`) and malformed fire-and-forget payloads are ignored safely.
 
-### Runtime State Ownership (Migrated Domains)
+### Runtime state ownership (migrated domains)
 
 For domains migrated to reducer-style transitions (for example AniList token/queue/media-guess runtime state), follow these rules:
 
@@ -260,18 +277,55 @@ For domains migrated to reducer-style transitions (for example AniList token/que
 - Reducer boundary: when a domain has transition helpers in `src/main/state.ts`, new callsites should route updates through those helpers instead of ad-hoc object mutation in `main.ts` or composers.
 - Tests for migrated domains should assert both the intended field changes and non-targeted field invariants.
 
-## Program Lifecycle
+## Playback startup flow
+
+Before the app boots, something has to launch mpv, inject the plugin, and bring the overlay up. SubMiner-managed launches own this step - the `subminer` launcher, the app's own playback, and the packaged Windows shortcut all follow the same path. The launcher reads `config.jsonc`, spawns mpv with the IPC socket and the bundled plugin, and passes runtime settings as `--script-opts`. The plugin never reads a config file: the shipped `subminer.conf` is intentionally empty so command-line opts always win.
+
+Once mpv is up, exactly one of two triggers brings up the overlay. On a first launch the plugin's `file-loaded` hook self-starts the app once the socket is ready (because the launcher injected `auto_start=yes`). When the app is already running - or for explicit `--start-overlay` and YouTube flows - the launcher instead attaches over the control socket and suppresses the plugin's auto-start, so the two never fire together. Both converge on the same app bring-up, which then runs the Program Lifecycle below.
+
+```mermaid
+flowchart TB
+  classDef entry fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:2px,font-weight:bold
+  classDef extrt fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef decision fill:#f5a97f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef proc fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef app fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef overlay fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
+
+  Entry["Managed launch<br/>subminer CLI · app · Windows shortcut"]:::entry
+  Entry --> Cfg["Launcher reads config.jsonc<br/>→ plugin runtime config"]:::extrt
+  Cfg --> Spawn["Spawn mpv<br/>--input-ipc-server=/tmp/subminer-socket<br/>--script=plugin/subminer/main.lua<br/>--script-opts=subminer-… (auto_start, backend, …)"]:::proc
+  Spawn --> Boot["Plugin boot · read_options('subminer')<br/>empty subminer.conf; CLI opts win"]:::extrt
+  Boot --> Sock["mpv IPC socket ready"]:::proc
+  Sock --> Who{"Overlay trigger"}:::decision
+
+  Who -->|"app already running, or<br/>--start-overlay / YouTube"| Attach["Launcher startOverlay()<br/>attach via control socket<br/>plugin auto-start suppressed"]:::proc
+  Who -->|"first launch, auto_start=yes"| Self["Plugin file-loaded hook<br/>polls socket → process.start_overlay()"]:::extrt
+
+  Attach --> AppUp
+  Self --> AppUp
+
+  AppUp["Spawn / attach SubMiner app<br/>--start --managed-playback --socket … --backend …"]:::app
+  AppUp --> Ctrl["App control server up<br/>/tmp/subminer-control-* dedupes a 2nd launch"]:::app
+  Ctrl --> Life["app.whenReady → Program Lifecycle (below)"]:::app
+  Life --> Conn["MpvIpcClient connects to /tmp/subminer-socket"]:::overlay
+  Conn --> Show["Transparent overlay over mpv<br/>Yomitan lookup · mine"]:::overlay
+```
+
+The runtime sockets in this flow are detailed in [IPC + Runtime Contracts](./ipc-contracts#runtime-sockets).
+
+## Program lifecycle
 
 - **Module-level init:** Before `app.ready`, the composition root registers protocols, sets platform flags, constructs all services, and wires dependency injection. `runAndApplyStartupState()` parses CLI args and detects the compositor backend.
 - **Startup:** If `--generate-config` is passed, it writes the template and exits. Otherwise `app-lifecycle.ts` acquires the single-instance lock and registers Electron lifecycle hooks.
-- **Critical-path init:** Once `app.whenReady()` fires, `composeAppReadyRuntime()` runs strict config reload, resolves keybindings, creates the `MpvIpcClient` (which immediately connects and subscribes to 26 properties), and initializes the `RuntimeOptionsManager`, `SubtitleTimingTracker`, and `ImmersionTrackerService`.
+- **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
-flowchart LR
+flowchart TB
   classDef start fill:#c6a0f6,stroke:#494d64,color:#24273a,stroke-width:2px,font-weight:bold
   classDef phase fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
   classDef decision fill:#f5a97f,stroke:#494d64,color:#24273a,stroke-width:1.5px
@@ -280,72 +334,89 @@ flowchart LR
   classDef shutdown fill:#ed8796,stroke:#494d64,color:#24273a,stroke-width:1.5px
   classDef warmup fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
 
-  CLI["CLI args &<br/>environment"]:::start
-  CLI --> Proto["Module-level init<br/>register protocols<br/>construct services<br/>wire deps"]:::phase
-  Proto --> Parse["startup.ts<br/>parse argv<br/>detect backend"]:::phase
-  Parse --> GenCheck{"--generate<br/>-config?"}:::decision
-  GenCheck -->|"yes"| GenExit["Write template<br/>& exit"]:::phase
-  GenCheck -->|"no"| Lock["app-lifecycle.ts<br/>single-instance lock<br/>lifecycle hooks"]:::phase
+  CLI["CLI + Environment"]:::start
+  CLI --> Init["Module Init"]:::phase
+  Init --> Parse["Parse argv"]:::phase
+  Parse --> GenCheck{"--generate-config?"}:::decision
+  GenCheck -->|"yes"| GenExit["Write & exit"]:::phase
+  GenCheck -->|"no"| Lock["Acquire lock"]:::phase
 
-  Lock -->|"app.whenReady()"| Ready["composeAppReady<br/>Runtime()"]:::phase
+  Lock -->|"app.whenReady()"| Ready["App Ready"]:::phase
 
-  Ready --> Config["Config reload<br/>keybindings<br/>log level"]:::init
-  Ready --> MpvInit["MpvIpcClient<br/>connect socket<br/>subscribe 26 props"]:::init
-  Ready --> Platform["RuntimeOptions<br/>timing tracker<br/>immersion tracker"]:::init
+  Ready --> Config["Config + keybindings"]:::init
+  Ready --> MpvInit["MPV socket connect"]:::init
+  Ready --> Platform["Runtime services"]:::init
 
-  Config --> OverlayInit
-  MpvInit --> OverlayInit
-  Platform --> OverlayInit
+  Config & MpvInit & Platform --> OverlayInit["Overlay Init"]:::phase
 
-  OverlayInit["initializeOverlay<br/>Runtime()"]:::phase
+  OverlayInit --> MainWin["Create window"]:::init
+  OverlayInit --> Shortcuts["Register shortcuts"]:::init
 
-  OverlayInit --> MainWin["Main overlay window<br/>primary + secondary subtitles"]:::init
-  OverlayInit --> Shortcuts["Register global<br/>shortcuts"]:::init
+  MainWin & Shortcuts --> Warmups
 
-  MainWin --> Warmups
-  Shortcuts --> Warmups
-
-  Warmups["Background<br/>warmups"]:::phase
-
-  subgraph WarmupGroup[" "]
-    direction TB
-    W1["MeCab<br/>+ worker thread"]:::warmup
-    W2["Yomitan"]:::warmup
-    W3["JLPT + freq<br/>dictionaries"]:::warmup
-    W4["Jellyfin"]:::warmup
-    W5["Discord"]:::warmup
-    W6["AniList"]:::warmup
-    W7["AnkiConnect<br/>proxy"]:::warmup
-    W1 ~~~ W2 ~~~ W3 ~~~ W4 ~~~ W5 ~~~ W6 ~~~ W7
+  subgraph Warmups["Background Warmups (parallel)"]
+    direction LR
+    W1["MeCab"]:::warmup ~~~ W2["Yomitan"]:::warmup ~~~ W3["Dictionaries"]:::warmup ~~~ W4["Jellyfin"]:::warmup ~~~ W5["Discord"]:::warmup ~~~ W6["AniList"]:::warmup ~~~ W7["Anki Proxy"]:::warmup
   end
 
-  Warmups --> WarmupGroup
+  Warmups --> Loop
 
-  subgraph Loop["Runtime — event-driven"]
+  subgraph Loop["Event Loop"]
     direction TB
-    MpvEvt["mpv events: subtitle · timing · metrics"]:::runtime
-    IpcEvt["IPC: renderer requests · CLI commands"]:::runtime
-    ExtEvt["Shortcuts · config hot-reload"]:::runtime
-    MpvEvt & IpcEvt & ExtEvt --> Route["Route via composers"]:::runtime
-    Route --> Process["SubtitlePipeline<br/>normalize → tokenize → merge"]:::runtime
-    Process --> Broadcast["Update AppState<br/>broadcast to renderer + modals"]:::runtime
+    Events["mpv · IPC · shortcuts · config"]:::runtime
+    Events --> Route["Composers"]:::runtime
+    Route --> Pipeline["Subtitle Pipeline"]:::runtime
+    Pipeline --> Broadcast["State + Renderer"]:::runtime
   end
 
-  WarmupGroup --> Loop
+  style Warmups fill:#363a4f,stroke:#494d64,color:#cad3f5
 
-  style WarmupGroup fill:transparent,stroke:none
+  Loop -->|"quit"| Quit["Shutdown"]:::shutdown
 
-  Loop -->|"quit signal"| Quit["will-quit"]:::shutdown
+  subgraph Cleanup[" "]
+    direction LR
+    T1["UI cleanup"]:::shutdown
+    T2["Socket + server teardown"]:::shutdown
+    T3["Flush tracking + state"]:::shutdown
+  end
 
-  Quit --> T1["Tray · config watcher<br/>global shortcuts"]:::shutdown
-  Quit --> T2["WebSocket · texthooker<br/>mpv socket · OSD log"]:::shutdown
-  Quit --> T3["Window tracker<br/>Yomitan parser"]:::shutdown
-  Quit --> T4["Immersion tracker<br/>Jellyfin · Discord<br/>Anki proxy · AniList"]:::shutdown
+  Quit --> Cleanup
 
+  style Cleanup fill:transparent,stroke:none
   style Loop fill:#363a4f,stroke:#494d64,color:#cad3f5
 ```
 
-## Why This Design
+## 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 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.
+
+```mermaid
+flowchart TB
+  classDef phase fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef init fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef runtime fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef warmup fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+
+  SubFile["External Sub File"]:::init
+  Parse["Cue Parser"]:::phase
+  Window["Upcoming Lines"]:::phase
+  Tokenize["Pre-tokenize"]:::warmup
+  Cache["Token Cache"]:::runtime
+  Appear["Subtitle Appears"]:::init
+  Hit["Cache Hit"]:::runtime
+  Render["Fast Render"]:::runtime
+
+  SubFile --> Parse --> Window --> Tokenize --> Cache
+  Appear --> Hit --> Render
+  Cache -.->|"warm"| Hit
+
+  style SubFile stroke-width:2px
+  style Render stroke-width:2px
+```
+
+## Why this design
 
 - **Smaller blast radius:** changing one feature usually touches one service.
 - **Better testability:** most behavior can be tested without Electron windows/mpv.
@@ -356,7 +427,7 @@ flowchart LR
 - **Split MPV service layers:** MPV internals are separated into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), and properties/render metrics modules for maintainability.
 - **Config by domain:** defaults, option registries, and resolution are split by domain under `src/config/definitions/*` and `src/config/resolve/*`, keeping config evolution localized.
 
-## Extension Rules
+## Extension rules
 
 - Add behavior to an existing service in `src/core/services/*` or create a focused runtime module under `src/main/runtime/*`; avoid ad-hoc logic in `main.ts`.
 - Add new cross-process channels in `src/shared/ipc/contracts.ts` first, validate payloads in `src/shared/ipc/validators.ts`, then wire handlers in IPC runtime modules.

docs-site/bun.lock

@@ -0,0 +1,623 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "subminer-docs",
+      "dependencies": {
+        "@catppuccin/vitepress": "^0.1.2",
+        "@fontsource/jetbrains-mono": "^5.2.8",
+        "@fontsource/manrope": "^5.2.8",
+        "mermaid": "^11.12.3",
+      },
+      "devDependencies": {
+        "vitepress": "^1.6.4",
+      },
+    },
+  },
+  "packages": {
+    "@algolia/abtesting": ["@algolia/abtesting@1.15.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-2yuIC48rUuHGhU1U5qJ9kJHaxYpJ0jpDHJVI5ekOxSMYXlH4+HP+pA31G820lsAznfmu2nzDV7n5RO44zIY1zw=="],
+
+    "@algolia/autocomplete-core": ["@algolia/autocomplete-core@1.17.7", "", { "dependencies": { "@algolia/autocomplete-plugin-algolia-insights": "1.17.7", "@algolia/autocomplete-shared": "1.17.7" } }, "sha512-BjiPOW6ks90UKl7TwMv7oNQMnzU+t/wk9mgIDi6b1tXpUek7MW0lbNOUHpvam9pe3lVCf4xPFT+lK7s+e+fs7Q=="],
+
+    "@algolia/autocomplete-plugin-algolia-insights": ["@algolia/autocomplete-plugin-algolia-insights@1.17.7", "", { "dependencies": { "@algolia/autocomplete-shared": "1.17.7" }, "peerDependencies": { "search-insights": ">= 1 < 3" } }, "sha512-Jca5Ude6yUOuyzjnz57og7Et3aXjbwCSDf/8onLHSQgw1qW3ALl9mrMWaXb5FmPVkV3EtkD2F/+NkT6VHyPu9A=="],
+
+    "@algolia/autocomplete-preset-algolia": ["@algolia/autocomplete-preset-algolia@1.17.7", "", { "dependencies": { "@algolia/autocomplete-shared": "1.17.7" }, "peerDependencies": { "@algolia/client-search": ">= 4.9.1 < 6", "algoliasearch": ">= 4.9.1 < 6" } }, "sha512-ggOQ950+nwbWROq2MOCIL71RE0DdQZsceqrg32UqnhDz8FlO9rL8ONHNsI2R1MH0tkgVIDKI/D0sMiUchsFdWA=="],
+
+    "@algolia/autocomplete-shared": ["@algolia/autocomplete-shared@1.17.7", "", { "peerDependencies": { "@algolia/client-search": ">= 4.9.1 < 6", "algoliasearch": ">= 4.9.1 < 6" } }, "sha512-o/1Vurr42U/qskRSuhBH+VKxMvkkUVTLU6WZQr+L5lGZZLYWyhdzWjW0iGXY7EkwRTjBqvN2EsR81yCTGV/kmg=="],
+
+    "@algolia/client-abtesting": ["@algolia/client-abtesting@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-h6M7HzPin+45/l09q0r2dYmocSSt2MMGOOk5c4O5K/bBBlEwf1BKfN6z+iX4b8WXcQQhf7rgQwC52kBZJt/ZZw=="],
+
+    "@algolia/client-analytics": ["@algolia/client-analytics@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-048T9/Z8OeLmTk8h76QUqaNFp7Rq2VgS2Zm6Y2tNMYGQ1uNuzePY/udB5l5krlXll7ZGflyCjFvRiOtlPZpE9g=="],
+
+    "@algolia/client-common": ["@algolia/client-common@5.49.1", "", {}, "sha512-vp5/a9ikqvf3mn9QvHN8PRekn8hW34aV9eX+O0J5mKPZXeA6Pd5OQEh2ZWf7gJY6yyfTlLp5LMFzQUAU+Fpqpg=="],
+
+    "@algolia/client-insights": ["@algolia/client-insights@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-B6N7PgkvYrul3bntTz/l6uXnhQ2bvP+M7NqTcayh681tSqPaA5cJCUBp/vrP7vpPRpej4Eeyx2qz5p0tE/2N2g=="],
+
+    "@algolia/client-personalization": ["@algolia/client-personalization@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-v+4DN+lkYfBd01Hbnb9ZrCHe7l+mvihyx218INRX/kaCXROIWUDIT1cs3urQxfE7kXBFnLsqYeOflQALv/gA5w=="],
+
+    "@algolia/client-query-suggestions": ["@algolia/client-query-suggestions@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-Un11cab6ZCv0W+Jiak8UktGIqoa4+gSNgEZNfG8m8eTsXGqwIEr370H3Rqwj87zeNSlFpH2BslMXJ/cLNS1qtg=="],
+
+    "@algolia/client-search": ["@algolia/client-search@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-Nt9hri7nbOo0RipAsGjIssHkpLMHHN/P7QqENywAq5TLsoYDzUyJGny8FEiD/9KJUxtGH8blGpMedilI6kK3rA=="],
+
+    "@algolia/ingestion": ["@algolia/ingestion@1.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-b5hUXwDqje0Y4CpU6VL481DXgPgxpTD5sYMnfQTHKgUispGnaCLCm2/T9WbJo1YNUbX3iHtYDArp804eD6CmRQ=="],
+
+    "@algolia/monitoring": ["@algolia/monitoring@1.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-bvrXwZ0WsL3rN6Q4m4QqxsXFCo6WAew7sAdrpMQMK4Efn4/W920r9ptOuckejOSSvyLr9pAWgC5rsHhR2FYuYw=="],
+
+    "@algolia/recommend": ["@algolia/recommend@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-h2yz3AGeGkQwNgbLmoe3bxYs8fac4An1CprKTypYyTU/k3Q+9FbIvJ8aS1DoBKaTjSRZVoyQS7SZQio6GaHbZw=="],
+
+    "@algolia/requester-browser-xhr": ["@algolia/requester-browser-xhr@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1" } }, "sha512-2UPyRuUR/qpqSqH8mxFV5uBZWEpxhGPHLlx9Xf6OVxr79XO2ctzZQAhsmTZ6X22x+N8MBWpB9UEky7YU2HGFgA=="],
+
+    "@algolia/requester-fetch": ["@algolia/requester-fetch@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1" } }, "sha512-N+xlE4lN+wpuT+4vhNEwPVlrfN+DWAZmSX9SYhbz986Oq8AMsqdntOqUyiOXVxYsQtfLwmiej24vbvJGYv1Qtw=="],
+
+    "@algolia/requester-node-http": ["@algolia/requester-node-http@5.49.1", "", { "dependencies": { "@algolia/client-common": "5.49.1" } }, "sha512-zA5bkUOB5PPtTr182DJmajCiizHp0rCJQ0Chf96zNFvkdESKYlDeYA3tQ7r2oyHbu/8DiohAQ5PZ85edctzbXA=="],
+
+    "@antfu/install-pkg": ["@antfu/install-pkg@1.1.0", "", { "dependencies": { "package-manager-detector": "^1.3.0", "tinyexec": "^1.0.1" } }, "sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ=="],
+
+    "@babel/helper-string-parser": ["@babel/helper-string-parser@7.27.1", "", {}, "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA=="],
+
+    "@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.28.5", "", {}, "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q=="],
+
+    "@babel/parser": ["@babel/parser@7.29.0", "", { "dependencies": { "@babel/types": "^7.29.0" }, "bin": "./bin/babel-parser.js" }, "sha512-IyDgFV5GeDUVX4YdF/3CPULtVGSXXMLh1xVIgdCgxApktqnQV0r7/8Nqthg+8YLGaAtdyIlo2qIdZrbCv4+7ww=="],
+
+    "@babel/types": ["@babel/types@7.29.0", "", { "dependencies": { "@babel/helper-string-parser": "^7.27.1", "@babel/helper-validator-identifier": "^7.28.5" } }, "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A=="],
+
+    "@braintree/sanitize-url": ["@braintree/sanitize-url@7.1.2", "", {}, "sha512-jigsZK+sMF/cuiB7sERuo9V7N9jx+dhmHHnQyDSVdpZwVutaBu7WvNYqMDLSgFgfB30n452TP3vjDAvFC973mA=="],
+
+    "@catppuccin/vitepress": ["@catppuccin/vitepress@0.1.2", "", { "peerDependencies": { "typescript": "^5.0.0" } }, "sha512-dqhgo6U6GWbgh3McAgwemUC8Y2Aj48rRcQx/9iuPzBPAgo7NA3yi7ZcR0wolAENMmoOMAHBV+rz/5DfiGxtZLA=="],
+
+    "@chevrotain/cst-dts-gen": ["@chevrotain/cst-dts-gen@11.1.2", "", { "dependencies": { "@chevrotain/gast": "11.1.2", "@chevrotain/types": "11.1.2", "lodash-es": "4.17.23" } }, "sha512-XTsjvDVB5nDZBQB8o0o/0ozNelQtn2KrUVteIHSlPd2VAV2utEb6JzyCJaJ8tGxACR4RiBNWy5uYUHX2eji88Q=="],
+
+    "@chevrotain/gast": ["@chevrotain/gast@11.1.2", "", { "dependencies": { "@chevrotain/types": "11.1.2", "lodash-es": "4.17.23" } }, "sha512-Z9zfXR5jNZb1Hlsd/p+4XWeUFugrHirq36bKzPWDSIacV+GPSVXdk+ahVWZTwjhNwofAWg/sZg58fyucKSQx5g=="],
+
+    "@chevrotain/regexp-to-ast": ["@chevrotain/regexp-to-ast@11.1.2", "", {}, "sha512-nMU3Uj8naWer7xpZTYJdxbAs6RIv/dxYzkYU8GSwgUtcAAlzjcPfX1w+RKRcYG8POlzMeayOQ/znfwxEGo5ulw=="],
+
+    "@chevrotain/types": ["@chevrotain/types@11.1.2", "", {}, "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw=="],
+
+    "@chevrotain/utils": ["@chevrotain/utils@11.1.2", "", {}, "sha512-4mudFAQ6H+MqBTfqLmU7G1ZwRzCLfJEooL/fsF6rCX5eePMbGhoy5n4g+G4vlh2muDcsCTJtL+uKbOzWxs5LHA=="],
+
+    "@docsearch/css": ["@docsearch/css@3.8.2", "", {}, "sha512-y05ayQFyUmCXze79+56v/4HpycYF3uFqB78pLPrSV5ZKAlDuIAAJNhaRi8tTdRNXh05yxX/TyNnzD6LwSM89vQ=="],
+
+    "@docsearch/js": ["@docsearch/js@3.8.2", "", { "dependencies": { "@docsearch/react": "3.8.2", "preact": "^10.0.0" } }, "sha512-Q5wY66qHn0SwA7Taa0aDbHiJvaFJLOJyHmooQ7y8hlwwQLQ/5WwCcoX0g7ii04Qi2DJlHsd0XXzJ8Ypw9+9YmQ=="],
+
+    "@docsearch/react": ["@docsearch/react@3.8.2", "", { "dependencies": { "@algolia/autocomplete-core": "1.17.7", "@algolia/autocomplete-preset-algolia": "1.17.7", "@docsearch/css": "3.8.2", "algoliasearch": "^5.14.2" }, "peerDependencies": { "@types/react": ">= 16.8.0 < 19.0.0", "react": ">= 16.8.0 < 19.0.0", "react-dom": ">= 16.8.0 < 19.0.0", "search-insights": ">= 1 < 3" }, "optionalPeers": ["@types/react", "react", "react-dom", "search-insights"] }, "sha512-xCRrJQlTt8N9GU0DG4ptwHRkfnSnD/YpdeaXe02iKfqs97TkZJv60yE+1eq/tjPcVnTW8dP5qLP7itifFVV5eg=="],
+
+    "@esbuild/aix-ppc64": ["@esbuild/aix-ppc64@0.21.5", "", { "os": "aix", "cpu": "ppc64" }, "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ=="],
+
+    "@esbuild/android-arm": ["@esbuild/android-arm@0.21.5", "", { "os": "android", "cpu": "arm" }, "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg=="],
+
+    "@esbuild/android-arm64": ["@esbuild/android-arm64@0.21.5", "", { "os": "android", "cpu": "arm64" }, "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A=="],
+
+    "@esbuild/android-x64": ["@esbuild/android-x64@0.21.5", "", { "os": "android", "cpu": "x64" }, "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA=="],
+
+    "@esbuild/darwin-arm64": ["@esbuild/darwin-arm64@0.21.5", "", { "os": "darwin", "cpu": "arm64" }, "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ=="],
+
+    "@esbuild/darwin-x64": ["@esbuild/darwin-x64@0.21.5", "", { "os": "darwin", "cpu": "x64" }, "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw=="],
+
+    "@esbuild/freebsd-arm64": ["@esbuild/freebsd-arm64@0.21.5", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g=="],
+
+    "@esbuild/freebsd-x64": ["@esbuild/freebsd-x64@0.21.5", "", { "os": "freebsd", "cpu": "x64" }, "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ=="],
+
+    "@esbuild/linux-arm": ["@esbuild/linux-arm@0.21.5", "", { "os": "linux", "cpu": "arm" }, "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA=="],
+
+    "@esbuild/linux-arm64": ["@esbuild/linux-arm64@0.21.5", "", { "os": "linux", "cpu": "arm64" }, "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q=="],
+
+    "@esbuild/linux-ia32": ["@esbuild/linux-ia32@0.21.5", "", { "os": "linux", "cpu": "ia32" }, "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg=="],
+
+    "@esbuild/linux-loong64": ["@esbuild/linux-loong64@0.21.5", "", { "os": "linux", "cpu": "none" }, "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg=="],
+
+    "@esbuild/linux-mips64el": ["@esbuild/linux-mips64el@0.21.5", "", { "os": "linux", "cpu": "none" }, "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg=="],
+
+    "@esbuild/linux-ppc64": ["@esbuild/linux-ppc64@0.21.5", "", { "os": "linux", "cpu": "ppc64" }, "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w=="],
+
+    "@esbuild/linux-riscv64": ["@esbuild/linux-riscv64@0.21.5", "", { "os": "linux", "cpu": "none" }, "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA=="],
+
+    "@esbuild/linux-s390x": ["@esbuild/linux-s390x@0.21.5", "", { "os": "linux", "cpu": "s390x" }, "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A=="],
+
+    "@esbuild/linux-x64": ["@esbuild/linux-x64@0.21.5", "", { "os": "linux", "cpu": "x64" }, "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ=="],
+
+    "@esbuild/netbsd-x64": ["@esbuild/netbsd-x64@0.21.5", "", { "os": "none", "cpu": "x64" }, "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg=="],
+
+    "@esbuild/openbsd-x64": ["@esbuild/openbsd-x64@0.21.5", "", { "os": "openbsd", "cpu": "x64" }, "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow=="],
+
+    "@esbuild/sunos-x64": ["@esbuild/sunos-x64@0.21.5", "", { "os": "sunos", "cpu": "x64" }, "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg=="],
+
+    "@esbuild/win32-arm64": ["@esbuild/win32-arm64@0.21.5", "", { "os": "win32", "cpu": "arm64" }, "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A=="],
+
+    "@esbuild/win32-ia32": ["@esbuild/win32-ia32@0.21.5", "", { "os": "win32", "cpu": "ia32" }, "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA=="],
+
+    "@esbuild/win32-x64": ["@esbuild/win32-x64@0.21.5", "", { "os": "win32", "cpu": "x64" }, "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw=="],
+
+    "@fontsource/jetbrains-mono": ["@fontsource/jetbrains-mono@5.2.8", "", {}, "sha512-6w8/SG4kqvIMu7xd7wt6x3idn1Qux3p9N62s6G3rfldOUYHpWcc2FKrqf+Vo44jRvqWj2oAtTHrZXEP23oSKwQ=="],
+
+    "@fontsource/manrope": ["@fontsource/manrope@5.2.8", "", {}, "sha512-gJHJmcuUk7qWcNCfcAri/DJQtXtBYqi9yKratr4jXhSo0I3xUtNNKI+igQIcw5c+m95g0vounk8ZnX/kb8o0TA=="],
+
+    "@iconify-json/simple-icons": ["@iconify-json/simple-icons@1.2.72", "", { "dependencies": { "@iconify/types": "*" } }, "sha512-wkcixntHvaCoqPqerGrNFcHQ3Yx1ux4ZkhscCDK0DEHpP62XCH+cxq1HTsRjbUiQl/M9K8bj03HF6Wgn5iE2rQ=="],
+
+    "@iconify/types": ["@iconify/types@2.0.0", "", {}, "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg=="],
+
+    "@iconify/utils": ["@iconify/utils@3.1.0", "", { "dependencies": { "@antfu/install-pkg": "^1.1.0", "@iconify/types": "^2.0.0", "mlly": "^1.8.0" } }, "sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw=="],
+
+    "@jridgewell/sourcemap-codec": ["@jridgewell/sourcemap-codec@1.5.5", "", {}, "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og=="],
+
+    "@mermaid-js/parser": ["@mermaid-js/parser@1.0.0", "", { "dependencies": { "langium": "^4.0.0" } }, "sha512-vvK0Hi/VWndxoh03Mmz6wa1KDriSPjS2XMZL/1l19HFwygiObEEoEwSDxOqyLzzAI6J2PU3261JjTMTO7x+BPw=="],
+
+    "@rollup/rollup-android-arm-eabi": ["@rollup/rollup-android-arm-eabi@4.59.0", "", { "os": "android", "cpu": "arm" }, "sha512-upnNBkA6ZH2VKGcBj9Fyl9IGNPULcjXRlg0LLeaioQWueH30p6IXtJEbKAgvyv+mJaMxSm1l6xwDXYjpEMiLMg=="],
+
+    "@rollup/rollup-android-arm64": ["@rollup/rollup-android-arm64@4.59.0", "", { "os": "android", "cpu": "arm64" }, "sha512-hZ+Zxj3SySm4A/DylsDKZAeVg0mvi++0PYVceVyX7hemkw7OreKdCvW2oQ3T1FMZvCaQXqOTHb8qmBShoqk69Q=="],
+
+    "@rollup/rollup-darwin-arm64": ["@rollup/rollup-darwin-arm64@4.59.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-W2Psnbh1J8ZJw0xKAd8zdNgF9HRLkdWwwdWqubSVk0pUuQkoHnv7rx4GiF9rT4t5DIZGAsConRE3AxCdJ4m8rg=="],
+
+    "@rollup/rollup-darwin-x64": ["@rollup/rollup-darwin-x64@4.59.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-ZW2KkwlS4lwTv7ZVsYDiARfFCnSGhzYPdiOU4IM2fDbL+QGlyAbjgSFuqNRbSthybLbIJ915UtZBtmuLrQAT/w=="],
+
+    "@rollup/rollup-freebsd-arm64": ["@rollup/rollup-freebsd-arm64@4.59.0", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-EsKaJ5ytAu9jI3lonzn3BgG8iRBjV4LxZexygcQbpiU0wU0ATxhNVEpXKfUa0pS05gTcSDMKpn3Sx+QB9RlTTA=="],
+
+    "@rollup/rollup-freebsd-x64": ["@rollup/rollup-freebsd-x64@4.59.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-d3DuZi2KzTMjImrxoHIAODUZYoUUMsuUiY4SRRcJy6NJoZ6iIqWnJu9IScV9jXysyGMVuW+KNzZvBLOcpdl3Vg=="],
+
+    "@rollup/rollup-linux-arm-gnueabihf": ["@rollup/rollup-linux-arm-gnueabihf@4.59.0", "", { "os": "linux", "cpu": "arm" }, "sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw=="],
+
+    "@rollup/rollup-linux-arm-musleabihf": ["@rollup/rollup-linux-arm-musleabihf@4.59.0", "", { "os": "linux", "cpu": "arm" }, "sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA=="],
+
+    "@rollup/rollup-linux-arm64-gnu": ["@rollup/rollup-linux-arm64-gnu@4.59.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA=="],
+
+    "@rollup/rollup-linux-arm64-musl": ["@rollup/rollup-linux-arm64-musl@4.59.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA=="],
+
+    "@rollup/rollup-linux-loong64-gnu": ["@rollup/rollup-linux-loong64-gnu@4.59.0", "", { "os": "linux", "cpu": "none" }, "sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg=="],
+
+    "@rollup/rollup-linux-loong64-musl": ["@rollup/rollup-linux-loong64-musl@4.59.0", "", { "os": "linux", "cpu": "none" }, "sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q=="],
+
+    "@rollup/rollup-linux-ppc64-gnu": ["@rollup/rollup-linux-ppc64-gnu@4.59.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA=="],
+
+    "@rollup/rollup-linux-ppc64-musl": ["@rollup/rollup-linux-ppc64-musl@4.59.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA=="],
+
+    "@rollup/rollup-linux-riscv64-gnu": ["@rollup/rollup-linux-riscv64-gnu@4.59.0", "", { "os": "linux", "cpu": "none" }, "sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg=="],
+
+    "@rollup/rollup-linux-riscv64-musl": ["@rollup/rollup-linux-riscv64-musl@4.59.0", "", { "os": "linux", "cpu": "none" }, "sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg=="],
+
+    "@rollup/rollup-linux-s390x-gnu": ["@rollup/rollup-linux-s390x-gnu@4.59.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w=="],
+
+    "@rollup/rollup-linux-x64-gnu": ["@rollup/rollup-linux-x64-gnu@4.59.0", "", { "os": "linux", "cpu": "x64" }, "sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg=="],
+
+    "@rollup/rollup-linux-x64-musl": ["@rollup/rollup-linux-x64-musl@4.59.0", "", { "os": "linux", "cpu": "x64" }, "sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg=="],
+
+    "@rollup/rollup-openbsd-x64": ["@rollup/rollup-openbsd-x64@4.59.0", "", { "os": "openbsd", "cpu": "x64" }, "sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ=="],
+
+    "@rollup/rollup-openharmony-arm64": ["@rollup/rollup-openharmony-arm64@4.59.0", "", { "os": "none", "cpu": "arm64" }, "sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA=="],
+
+    "@rollup/rollup-win32-arm64-msvc": ["@rollup/rollup-win32-arm64-msvc@4.59.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A=="],
+
+    "@rollup/rollup-win32-ia32-msvc": ["@rollup/rollup-win32-ia32-msvc@4.59.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA=="],
+
+    "@rollup/rollup-win32-x64-gnu": ["@rollup/rollup-win32-x64-gnu@4.59.0", "", { "os": "win32", "cpu": "x64" }, "sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA=="],
+
+    "@rollup/rollup-win32-x64-msvc": ["@rollup/rollup-win32-x64-msvc@4.59.0", "", { "os": "win32", "cpu": "x64" }, "sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA=="],
+
+    "@shikijs/core": ["@shikijs/core@2.5.0", "", { "dependencies": { "@shikijs/engine-javascript": "2.5.0", "@shikijs/engine-oniguruma": "2.5.0", "@shikijs/types": "2.5.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4", "hast-util-to-html": "^9.0.4" } }, "sha512-uu/8RExTKtavlpH7XqnVYBrfBkUc20ngXiX9NSrBhOVZYv/7XQRKUyhtkeflY5QsxC0GbJThCerruZfsUaSldg=="],
+
+    "@shikijs/engine-javascript": ["@shikijs/engine-javascript@2.5.0", "", { "dependencies": { "@shikijs/types": "2.5.0", "@shikijs/vscode-textmate": "^10.0.2", "oniguruma-to-es": "^3.1.0" } }, "sha512-VjnOpnQf8WuCEZtNUdjjwGUbtAVKuZkVQ/5cHy/tojVVRIRtlWMYVjyWhxOmIq05AlSOv72z7hRNRGVBgQOl0w=="],
+
+    "@shikijs/engine-oniguruma": ["@shikijs/engine-oniguruma@2.5.0", "", { "dependencies": { "@shikijs/types": "2.5.0", "@shikijs/vscode-textmate": "^10.0.2" } }, "sha512-pGd1wRATzbo/uatrCIILlAdFVKdxImWJGQ5rFiB5VZi2ve5xj3Ax9jny8QvkaV93btQEwR/rSz5ERFpC5mKNIw=="],
+
+    "@shikijs/langs": ["@shikijs/langs@2.5.0", "", { "dependencies": { "@shikijs/types": "2.5.0" } }, "sha512-Qfrrt5OsNH5R+5tJ/3uYBBZv3SuGmnRPejV9IlIbFH3HTGLDlkqgHymAlzklVmKBjAaVmkPkyikAV/sQ1wSL+w=="],
+
+    "@shikijs/themes": ["@shikijs/themes@2.5.0", "", { "dependencies": { "@shikijs/types": "2.5.0" } }, "sha512-wGrk+R8tJnO0VMzmUExHR+QdSaPUl/NKs+a4cQQRWyoc3YFbUzuLEi/KWK1hj+8BfHRKm2jNhhJck1dfstJpiw=="],
+
+    "@shikijs/transformers": ["@shikijs/transformers@2.5.0", "", { "dependencies": { "@shikijs/core": "2.5.0", "@shikijs/types": "2.5.0" } }, "sha512-SI494W5X60CaUwgi8u4q4m4s3YAFSxln3tzNjOSYqq54wlVgz0/NbbXEb3mdLbqMBztcmS7bVTaEd2w0qMmfeg=="],
+
+    "@shikijs/types": ["@shikijs/types@2.5.0", "", { "dependencies": { "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-ygl5yhxki9ZLNuNpPitBWvcy9fsSKKaRuO4BAlMyagszQidxcpLAr0qiW/q43DtSIDxO6hEbtYLiFZNXO/hdGw=="],
+
+    "@shikijs/vscode-textmate": ["@shikijs/vscode-textmate@10.0.2", "", {}, "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg=="],
+
+    "@types/d3": ["@types/d3@7.4.3", "", { "dependencies": { "@types/d3-array": "*", "@types/d3-axis": "*", "@types/d3-brush": "*", "@types/d3-chord": "*", "@types/d3-color": "*", "@types/d3-contour": "*", "@types/d3-delaunay": "*", "@types/d3-dispatch": "*", "@types/d3-drag": "*", "@types/d3-dsv": "*", "@types/d3-ease": "*", "@types/d3-fetch": "*", "@types/d3-force": "*", "@types/d3-format": "*", "@types/d3-geo": "*", "@types/d3-hierarchy": "*", "@types/d3-interpolate": "*", "@types/d3-path": "*", "@types/d3-polygon": "*", "@types/d3-quadtree": "*", "@types/d3-random": "*", "@types/d3-scale": "*", "@types/d3-scale-chromatic": "*", "@types/d3-selection": "*", "@types/d3-shape": "*", "@types/d3-time": "*", "@types/d3-time-format": "*", "@types/d3-timer": "*", "@types/d3-transition": "*", "@types/d3-zoom": "*" } }, "sha512-lZXZ9ckh5R8uiFVt8ogUNf+pIrK4EsWrx2Np75WvF/eTpJ0FMHNhjXk8CKEx/+gpHbNQyJWehbFaTvqmHWB3ww=="],
+
+    "@types/d3-array": ["@types/d3-array@3.2.2", "", {}, "sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw=="],
+
+    "@types/d3-axis": ["@types/d3-axis@3.0.6", "", { "dependencies": { "@types/d3-selection": "*" } }, "sha512-pYeijfZuBd87T0hGn0FO1vQ/cgLk6E1ALJjfkC0oJ8cbwkZl3TpgS8bVBLZN+2jjGgg38epgxb2zmoGtSfvgMw=="],
+
+    "@types/d3-brush": ["@types/d3-brush@3.0.6", "", { "dependencies": { "@types/d3-selection": "*" } }, "sha512-nH60IZNNxEcrh6L1ZSMNA28rj27ut/2ZmI3r96Zd+1jrZD++zD3LsMIjWlvg4AYrHn/Pqz4CF3veCxGjtbqt7A=="],
+
+    "@types/d3-chord": ["@types/d3-chord@3.0.6", "", {}, "sha512-LFYWWd8nwfwEmTZG9PfQxd17HbNPksHBiJHaKuY1XeqscXacsS2tyoo6OdRsjf+NQYeB6XrNL3a25E3gH69lcg=="],
+
+    "@types/d3-color": ["@types/d3-color@3.1.3", "", {}, "sha512-iO90scth9WAbmgv7ogoq57O9YpKmFBbmoEoCHDB2xMBY0+/KVrqAaCDyCE16dUspeOvIxFFRI+0sEtqDqy2b4A=="],
+
+    "@types/d3-contour": ["@types/d3-contour@3.0.6", "", { "dependencies": { "@types/d3-array": "*", "@types/geojson": "*" } }, "sha512-BjzLgXGnCWjUSYGfH1cpdo41/hgdWETu4YxpezoztawmqsvCeep+8QGfiY6YbDvfgHz/DkjeIkkZVJavB4a3rg=="],
+
+    "@types/d3-delaunay": ["@types/d3-delaunay@6.0.4", "", {}, "sha512-ZMaSKu4THYCU6sV64Lhg6qjf1orxBthaC161plr5KuPHo3CNm8DTHiLw/5Eq2b6TsNP0W0iJrUOFscY6Q450Hw=="],
+
+    "@types/d3-dispatch": ["@types/d3-dispatch@3.0.7", "", {}, "sha512-5o9OIAdKkhN1QItV2oqaE5KMIiXAvDWBDPrD85e58Qlz1c1kI/J0NcqbEG88CoTwJrYe7ntUCVfeUl2UJKbWgA=="],
+
+    "@types/d3-drag": ["@types/d3-drag@3.0.7", "", { "dependencies": { "@types/d3-selection": "*" } }, "sha512-HE3jVKlzU9AaMazNufooRJ5ZpWmLIoc90A37WU2JMmeq28w1FQqCZswHZ3xR+SuxYftzHq6WU6KJHvqxKzTxxQ=="],
+
+    "@types/d3-dsv": ["@types/d3-dsv@3.0.7", "", {}, "sha512-n6QBF9/+XASqcKK6waudgL0pf/S5XHPPI8APyMLLUHd8NqouBGLsU8MgtO7NINGtPBtk9Kko/W4ea0oAspwh9g=="],
+
+    "@types/d3-ease": ["@types/d3-ease@3.0.2", "", {}, "sha512-NcV1JjO5oDzoK26oMzbILE6HW7uVXOHLQvHshBUW4UMdZGfiY6v5BeQwh9a9tCzv+CeefZQHJt5SRgK154RtiA=="],
+
+    "@types/d3-fetch": ["@types/d3-fetch@3.0.7", "", { "dependencies": { "@types/d3-dsv": "*" } }, "sha512-fTAfNmxSb9SOWNB9IoG5c8Hg6R+AzUHDRlsXsDZsNp6sxAEOP0tkP3gKkNSO/qmHPoBFTxNrjDprVHDQDvo5aA=="],
+
+    "@types/d3-force": ["@types/d3-force@3.0.10", "", {}, "sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw=="],
+
+    "@types/d3-format": ["@types/d3-format@3.0.4", "", {}, "sha512-fALi2aI6shfg7vM5KiR1wNJnZ7r6UuggVqtDA+xiEdPZQwy/trcQaHnwShLuLdta2rTymCNpxYTiMZX/e09F4g=="],
+
+    "@types/d3-geo": ["@types/d3-geo@3.1.0", "", { "dependencies": { "@types/geojson": "*" } }, "sha512-856sckF0oP/diXtS4jNsiQw/UuK5fQG8l/a9VVLeSouf1/PPbBE1i1W852zVwKwYCBkFJJB7nCFTbk6UMEXBOQ=="],
+
+    "@types/d3-hierarchy": ["@types/d3-hierarchy@3.1.7", "", {}, "sha512-tJFtNoYBtRtkNysX1Xq4sxtjK8YgoWUNpIiUee0/jHGRwqvzYxkq0hGVbbOGSz+JgFxxRu4K8nb3YpG3CMARtg=="],
+
+    "@types/d3-interpolate": ["@types/d3-interpolate@3.0.4", "", { "dependencies": { "@types/d3-color": "*" } }, "sha512-mgLPETlrpVV1YRJIglr4Ez47g7Yxjl1lj7YKsiMCb27VJH9W8NVM6Bb9d8kkpG/uAQS5AmbA48q2IAolKKo1MA=="],
+
+    "@types/d3-path": ["@types/d3-path@3.1.1", "", {}, "sha512-VMZBYyQvbGmWyWVea0EHs/BwLgxc+MKi1zLDCONksozI4YJMcTt8ZEuIR4Sb1MMTE8MMW49v0IwI5+b7RmfWlg=="],
+
+    "@types/d3-polygon": ["@types/d3-polygon@3.0.2", "", {}, "sha512-ZuWOtMaHCkN9xoeEMr1ubW2nGWsp4nIql+OPQRstu4ypeZ+zk3YKqQT0CXVe/PYqrKpZAi+J9mTs05TKwjXSRA=="],
+
+    "@types/d3-quadtree": ["@types/d3-quadtree@3.0.6", "", {}, "sha512-oUzyO1/Zm6rsxKRHA1vH0NEDG58HrT5icx/azi9MF1TWdtttWl0UIUsjEQBBh+SIkrpd21ZjEv7ptxWys1ncsg=="],
+
+    "@types/d3-random": ["@types/d3-random@3.0.3", "", {}, "sha512-Imagg1vJ3y76Y2ea0871wpabqp613+8/r0mCLEBfdtqC7xMSfj9idOnmBYyMoULfHePJyxMAw3nWhJxzc+LFwQ=="],
+
+    "@types/d3-scale": ["@types/d3-scale@4.0.9", "", { "dependencies": { "@types/d3-time": "*" } }, "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw=="],
+
+    "@types/d3-scale-chromatic": ["@types/d3-scale-chromatic@3.1.0", "", {}, "sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ=="],
+
+    "@types/d3-selection": ["@types/d3-selection@3.0.11", "", {}, "sha512-bhAXu23DJWsrI45xafYpkQ4NtcKMwWnAC/vKrd2l+nxMFuvOT3XMYTIj2opv8vq8AO5Yh7Qac/nSeP/3zjTK0w=="],
+
+    "@types/d3-shape": ["@types/d3-shape@3.1.8", "", { "dependencies": { "@types/d3-path": "*" } }, "sha512-lae0iWfcDeR7qt7rA88BNiqdvPS5pFVPpo5OfjElwNaT2yyekbM0C9vK+yqBqEmHr6lDkRnYNoTBYlAgJa7a4w=="],
+
+    "@types/d3-time": ["@types/d3-time@3.0.4", "", {}, "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g=="],
+
+    "@types/d3-time-format": ["@types/d3-time-format@4.0.3", "", {}, "sha512-5xg9rC+wWL8kdDj153qZcsJ0FWiFt0J5RB6LYUNZjwSnesfblqrI/bJ1wBdJ8OQfncgbJG5+2F+qfqnqyzYxyg=="],
+
+    "@types/d3-timer": ["@types/d3-timer@3.0.2", "", {}, "sha512-Ps3T8E8dZDam6fUyNiMkekK3XUsaUEik+idO9/YjPtfj2qruF8tFBXS7XhtE4iIXBLxhmLjP3SXpLhVf21I9Lw=="],
+
+    "@types/d3-transition": ["@types/d3-transition@3.0.9", "", { "dependencies": { "@types/d3-selection": "*" } }, "sha512-uZS5shfxzO3rGlu0cC3bjmMFKsXv+SmZZcgp0KD22ts4uGXp5EVYGzu/0YdwZeKmddhcAccYtREJKkPfXkZuCg=="],
+
+    "@types/d3-zoom": ["@types/d3-zoom@3.0.8", "", { "dependencies": { "@types/d3-interpolate": "*", "@types/d3-selection": "*" } }, "sha512-iqMC4/YlFCSlO8+2Ii1GGGliCAY4XdeG748w5vQUbevlbDu0zSjH/+jojorQVBK/se0j6DUFNPBGSqD3YWYnDw=="],
+
+    "@types/estree": ["@types/estree@1.0.8", "", {}, "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w=="],
+
+    "@types/geojson": ["@types/geojson@7946.0.16", "", {}, "sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg=="],
+
+    "@types/hast": ["@types/hast@3.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ=="],
+
+    "@types/linkify-it": ["@types/linkify-it@5.0.0", "", {}, "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q=="],
+
+    "@types/markdown-it": ["@types/markdown-it@14.1.2", "", { "dependencies": { "@types/linkify-it": "^5", "@types/mdurl": "^2" } }, "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog=="],
+
+    "@types/mdast": ["@types/mdast@4.0.4", "", { "dependencies": { "@types/unist": "*" } }, "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA=="],
+
+    "@types/mdurl": ["@types/mdurl@2.0.0", "", {}, "sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg=="],
+
+    "@types/trusted-types": ["@types/trusted-types@2.0.7", "", {}, "sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw=="],
+
+    "@types/unist": ["@types/unist@3.0.3", "", {}, "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q=="],
+
+    "@types/web-bluetooth": ["@types/web-bluetooth@0.0.21", "", {}, "sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA=="],
+
+    "@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g=="],
+
+    "@vitejs/plugin-vue": ["@vitejs/plugin-vue@5.2.4", "", { "peerDependencies": { "vite": "^5.0.0 || ^6.0.0", "vue": "^3.2.25" } }, "sha512-7Yx/SXSOcQq5HiiV3orevHUFn+pmMB4cgbEkDYgnkUWb0WfeQ/wa2yFv6D5ICiCQOVpjA7vYDXrC7AGO8yjDHA=="],
+
+    "@vue/compiler-core": ["@vue/compiler-core@3.5.29", "", { "dependencies": { "@babel/parser": "^7.29.0", "@vue/shared": "3.5.29", "entities": "^7.0.1", "estree-walker": "^2.0.2", "source-map-js": "^1.2.1" } }, "sha512-cuzPhD8fwRHk8IGfmYaR4eEe4cAyJEL66Ove/WZL7yWNL134nqLddSLwNRIsFlnnW1kK+p8Ck3viFnC0chXCXw=="],
+
+    "@vue/compiler-dom": ["@vue/compiler-dom@3.5.29", "", { "dependencies": { "@vue/compiler-core": "3.5.29", "@vue/shared": "3.5.29" } }, "sha512-n0G5o7R3uBVmVxjTIYcz7ovr8sy7QObFG8OQJ3xGCDNhbG60biP/P5KnyY8NLd81OuT1WJflG7N4KWYHaeeaIg=="],
+
+    "@vue/compiler-sfc": ["@vue/compiler-sfc@3.5.29", "", { "dependencies": { "@babel/parser": "^7.29.0", "@vue/compiler-core": "3.5.29", "@vue/compiler-dom": "3.5.29", "@vue/compiler-ssr": "3.5.29", "@vue/shared": "3.5.29", "estree-walker": "^2.0.2", "magic-string": "^0.30.21", "postcss": "^8.5.6", "source-map-js": "^1.2.1" } }, "sha512-oJZhN5XJs35Gzr50E82jg2cYdZQ78wEwvRO6Y63TvLVTc+6xICzJHP1UIecdSPPYIbkautNBanDiWYa64QSFIA=="],
+
+    "@vue/compiler-ssr": ["@vue/compiler-ssr@3.5.29", "", { "dependencies": { "@vue/compiler-dom": "3.5.29", "@vue/shared": "3.5.29" } }, "sha512-Y/ARJZE6fpjzL5GH/phJmsFwx3g6t2KmHKHx5q+MLl2kencADKIrhH5MLF6HHpRMmlRAYBRSvv347Mepf1zVNw=="],
+
+    "@vue/devtools-api": ["@vue/devtools-api@7.7.9", "", { "dependencies": { "@vue/devtools-kit": "^7.7.9" } }, "sha512-kIE8wvwlcZ6TJTbNeU2HQNtaxLx3a84aotTITUuL/4bzfPxzajGBOoqjMhwZJ8L9qFYDU/lAYMEEm11dnZOD6g=="],
+
+    "@vue/devtools-kit": ["@vue/devtools-kit@7.7.9", "", { "dependencies": { "@vue/devtools-shared": "^7.7.9", "birpc": "^2.3.0", "hookable": "^5.5.3", "mitt": "^3.0.1", "perfect-debounce": "^1.0.0", "speakingurl": "^14.0.1", "superjson": "^2.2.2" } }, "sha512-PyQ6odHSgiDVd4hnTP+aDk2X4gl2HmLDfiyEnn3/oV+ckFDuswRs4IbBT7vacMuGdwY/XemxBoh302ctbsptuA=="],
+
+    "@vue/devtools-shared": ["@vue/devtools-shared@7.7.9", "", { "dependencies": { "rfdc": "^1.4.1" } }, "sha512-iWAb0v2WYf0QWmxCGy0seZNDPdO3Sp5+u78ORnyeonS6MT4PC7VPrryX2BpMJrwlDeaZ6BD4vP4XKjK0SZqaeA=="],
+
+    "@vue/reactivity": ["@vue/reactivity@3.5.29", "", { "dependencies": { "@vue/shared": "3.5.29" } }, "sha512-zcrANcrRdcLtmGZETBxWqIkoQei8HaFpZWx/GHKxx79JZsiZ8j1du0VUJtu4eJjgFvU/iKL5lRXFXksVmI+5DA=="],
+
+    "@vue/runtime-core": ["@vue/runtime-core@3.5.29", "", { "dependencies": { "@vue/reactivity": "3.5.29", "@vue/shared": "3.5.29" } }, "sha512-8DpW2QfdwIWOLqtsNcds4s+QgwSaHSJY/SUe04LptianUQ/0xi6KVsu/pYVh+HO3NTVvVJjIPL2t6GdeKbS4Lg=="],
+
+    "@vue/runtime-dom": ["@vue/runtime-dom@3.5.29", "", { "dependencies": { "@vue/reactivity": "3.5.29", "@vue/runtime-core": "3.5.29", "@vue/shared": "3.5.29", "csstype": "^3.2.3" } }, "sha512-AHvvJEtcY9tw/uk+s/YRLSlxxQnqnAkjqvK25ZiM4CllCZWzElRAoQnCM42m9AHRLNJ6oe2kC5DCgD4AUdlvXg=="],
+
+    "@vue/server-renderer": ["@vue/server-renderer@3.5.29", "", { "dependencies": { "@vue/compiler-ssr": "3.5.29", "@vue/shared": "3.5.29" }, "peerDependencies": { "vue": "3.5.29" } }, "sha512-G/1k6WK5MusLlbxSE2YTcqAAezS+VuwHhOvLx2KnQU7G2zCH6KIb+5Wyt6UjMq7a3qPzNEjJXs1hvAxDclQH+g=="],
+
+    "@vue/shared": ["@vue/shared@3.5.29", "", {}, "sha512-w7SR0A5zyRByL9XUkCfdLs7t9XOHUyJ67qPGQjOou3p6GvBeBW+AVjUUmlxtZ4PIYaRvE+1LmK44O4uajlZwcg=="],
+
+    "@vueuse/core": ["@vueuse/core@12.8.2", "", { "dependencies": { "@types/web-bluetooth": "^0.0.21", "@vueuse/metadata": "12.8.2", "@vueuse/shared": "12.8.2", "vue": "^3.5.13" } }, "sha512-HbvCmZdzAu3VGi/pWYm5Ut+Kd9mn1ZHnn4L5G8kOQTPs/IwIAmJoBrmYk2ckLArgMXZj0AW3n5CAejLUO+PhdQ=="],
+
+    "@vueuse/integrations": ["@vueuse/integrations@12.8.2", "", { "dependencies": { "@vueuse/core": "12.8.2", "@vueuse/shared": "12.8.2", "vue": "^3.5.13" }, "peerDependencies": { "async-validator": "^4", "axios": "^1", "change-case": "^5", "drauu": "^0.4", "focus-trap": "^7", "fuse.js": "^7", "idb-keyval": "^6", "jwt-decode": "^4", "nprogress": "^0.2", "qrcode": "^1.5", "sortablejs": "^1", "universal-cookie": "^7" }, "optionalPeers": ["async-validator", "axios", "change-case", "drauu", "focus-trap", "fuse.js", "idb-keyval", "jwt-decode", "nprogress", "qrcode", "sortablejs", "universal-cookie"] }, "sha512-fbGYivgK5uBTRt7p5F3zy6VrETlV9RtZjBqd1/HxGdjdckBgBM4ugP8LHpjolqTj14TXTxSK1ZfgPbHYyGuH7g=="],
+
+    "@vueuse/metadata": ["@vueuse/metadata@12.8.2", "", {}, "sha512-rAyLGEuoBJ/Il5AmFHiziCPdQzRt88VxR+Y/A/QhJ1EWtWqPBBAxTAFaSkviwEuOEZNtW8pvkPgoCZQ+HxqW1A=="],
+
+    "@vueuse/shared": ["@vueuse/shared@12.8.2", "", { "dependencies": { "vue": "^3.5.13" } }, "sha512-dznP38YzxZoNloI0qpEfpkms8knDtaoQ6Y/sfS0L7Yki4zh40LFHEhur0odJC6xTHG5dxWVPiUWBXn+wCG2s5w=="],
+
+    "acorn": ["acorn@8.16.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw=="],
+
+    "algoliasearch": ["algoliasearch@5.49.1", "", { "dependencies": { "@algolia/abtesting": "1.15.1", "@algolia/client-abtesting": "5.49.1", "@algolia/client-analytics": "5.49.1", "@algolia/client-common": "5.49.1", "@algolia/client-insights": "5.49.1", "@algolia/client-personalization": "5.49.1", "@algolia/client-query-suggestions": "5.49.1", "@algolia/client-search": "5.49.1", "@algolia/ingestion": "1.49.1", "@algolia/monitoring": "1.49.1", "@algolia/recommend": "5.49.1", "@algolia/requester-browser-xhr": "5.49.1", "@algolia/requester-fetch": "5.49.1", "@algolia/requester-node-http": "5.49.1" } }, "sha512-X3Pp2aRQhg4xUC6PQtkubn5NpRKuUPQ9FPDQlx36SmpFwwH2N0/tw4c+NXV3nw3PsgeUs+BuWGP0gjz3TvENLQ=="],
+
+    "birpc": ["birpc@2.9.0", "", {}, "sha512-KrayHS5pBi69Xi9JmvoqrIgYGDkD6mcSe/i6YKi3w5kekCLzrX4+nawcXqrj2tIp50Kw/mT/s3p+GVK0A0sKxw=="],
+
+    "ccount": ["ccount@2.0.1", "", {}, "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg=="],
+
+    "character-entities-html4": ["character-entities-html4@2.1.0", "", {}, "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA=="],
+
+    "character-entities-legacy": ["character-entities-legacy@3.0.0", "", {}, "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ=="],
+
+    "chevrotain": ["chevrotain@11.1.2", "", { "dependencies": { "@chevrotain/cst-dts-gen": "11.1.2", "@chevrotain/gast": "11.1.2", "@chevrotain/regexp-to-ast": "11.1.2", "@chevrotain/types": "11.1.2", "@chevrotain/utils": "11.1.2", "lodash-es": "4.17.23" } }, "sha512-opLQzEVriiH1uUQ4Kctsd49bRoFDXGGSC4GUqj7pGyxM3RehRhvTlZJc1FL/Flew2p5uwxa1tUDWKzI4wNM8pg=="],
+
+    "chevrotain-allstar": ["chevrotain-allstar@0.3.1", "", { "dependencies": { "lodash-es": "^4.17.21" }, "peerDependencies": { "chevrotain": "^11.0.0" } }, "sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw=="],
+
+    "comma-separated-tokens": ["comma-separated-tokens@2.0.3", "", {}, "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg=="],
+
+    "commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="],
+
+    "confbox": ["confbox@0.1.8", "", {}, "sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w=="],
+
+    "copy-anything": ["copy-anything@4.0.5", "", { "dependencies": { "is-what": "^5.2.0" } }, "sha512-7Vv6asjS4gMOuILabD3l739tsaxFQmC+a7pLZm02zyvs8p977bL3zEgq3yDk5rn9B0PbYgIv++jmHcuUab4RhA=="],
+
+    "cose-base": ["cose-base@1.0.3", "", { "dependencies": { "layout-base": "^1.0.0" } }, "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg=="],
+
+    "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
+
+    "cytoscape": ["cytoscape@3.33.1", "", {}, "sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ=="],
+
+    "cytoscape-cose-bilkent": ["cytoscape-cose-bilkent@4.1.0", "", { "dependencies": { "cose-base": "^1.0.0" }, "peerDependencies": { "cytoscape": "^3.2.0" } }, "sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ=="],
+
+    "cytoscape-fcose": ["cytoscape-fcose@2.2.0", "", { "dependencies": { "cose-base": "^2.2.0" }, "peerDependencies": { "cytoscape": "^3.2.0" } }, "sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ=="],
+
+    "d3": ["d3@7.9.0", "", { "dependencies": { "d3-array": "3", "d3-axis": "3", "d3-brush": "3", "d3-chord": "3", "d3-color": "3", "d3-contour": "4", "d3-delaunay": "6", "d3-dispatch": "3", "d3-drag": "3", "d3-dsv": "3", "d3-ease": "3", "d3-fetch": "3", "d3-force": "3", "d3-format": "3", "d3-geo": "3", "d3-hierarchy": "3", "d3-interpolate": "3", "d3-path": "3", "d3-polygon": "3", "d3-quadtree": "3", "d3-random": "3", "d3-scale": "4", "d3-scale-chromatic": "3", "d3-selection": "3", "d3-shape": "3", "d3-time": "3", "d3-time-format": "4", "d3-timer": "3", "d3-transition": "3", "d3-zoom": "3" } }, "sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA=="],
+
+    "d3-array": ["d3-array@3.2.4", "", { "dependencies": { "internmap": "1 - 2" } }, "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg=="],
+
+    "d3-axis": ["d3-axis@3.0.0", "", {}, "sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw=="],
+
+    "d3-brush": ["d3-brush@3.0.0", "", { "dependencies": { "d3-dispatch": "1 - 3", "d3-drag": "2 - 3", "d3-interpolate": "1 - 3", "d3-selection": "3", "d3-transition": "3" } }, "sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ=="],
+
+    "d3-chord": ["d3-chord@3.0.1", "", { "dependencies": { "d3-path": "1 - 3" } }, "sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g=="],
+
+    "d3-color": ["d3-color@3.1.0", "", {}, "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA=="],
+
+    "d3-contour": ["d3-contour@4.0.2", "", { "dependencies": { "d3-array": "^3.2.0" } }, "sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA=="],
+
+    "d3-delaunay": ["d3-delaunay@6.0.4", "", { "dependencies": { "delaunator": "5" } }, "sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A=="],
+
+    "d3-dispatch": ["d3-dispatch@3.0.1", "", {}, "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg=="],
+
+    "d3-drag": ["d3-drag@3.0.0", "", { "dependencies": { "d3-dispatch": "1 - 3", "d3-selection": "3" } }, "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg=="],
+
+    "d3-dsv": ["d3-dsv@3.0.1", "", { "dependencies": { "commander": "7", "iconv-lite": "0.6", "rw": "1" }, "bin": { "csv2json": "bin/dsv2json.js", "csv2tsv": "bin/dsv2dsv.js", "dsv2dsv": "bin/dsv2dsv.js", "dsv2json": "bin/dsv2json.js", "json2csv": "bin/json2dsv.js", "json2dsv": "bin/json2dsv.js", "json2tsv": "bin/json2dsv.js", "tsv2csv": "bin/dsv2dsv.js", "tsv2json": "bin/dsv2json.js" } }, "sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q=="],
+
+    "d3-ease": ["d3-ease@3.0.1", "", {}, "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w=="],
+
+    "d3-fetch": ["d3-fetch@3.0.1", "", { "dependencies": { "d3-dsv": "1 - 3" } }, "sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw=="],
+
+    "d3-force": ["d3-force@3.0.0", "", { "dependencies": { "d3-dispatch": "1 - 3", "d3-quadtree": "1 - 3", "d3-timer": "1 - 3" } }, "sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg=="],
+
+    "d3-format": ["d3-format@3.1.2", "", {}, "sha512-AJDdYOdnyRDV5b6ArilzCPPwc1ejkHcoyFarqlPqT7zRYjhavcT3uSrqcMvsgh2CgoPbK3RCwyHaVyxYcP2Arg=="],
+
+    "d3-geo": ["d3-geo@3.1.1", "", { "dependencies": { "d3-array": "2.5.0 - 3" } }, "sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q=="],
+
+    "d3-hierarchy": ["d3-hierarchy@3.1.2", "", {}, "sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA=="],
+
+    "d3-interpolate": ["d3-interpolate@3.0.1", "", { "dependencies": { "d3-color": "1 - 3" } }, "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g=="],
+
+    "d3-path": ["d3-path@3.1.0", "", {}, "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ=="],
+
+    "d3-polygon": ["d3-polygon@3.0.1", "", {}, "sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg=="],
+
+    "d3-quadtree": ["d3-quadtree@3.0.1", "", {}, "sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw=="],
+
+    "d3-random": ["d3-random@3.0.1", "", {}, "sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ=="],
+
+    "d3-sankey": ["d3-sankey@0.12.3", "", { "dependencies": { "d3-array": "1 - 2", "d3-shape": "^1.2.0" } }, "sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ=="],
+
+    "d3-scale": ["d3-scale@4.0.2", "", { "dependencies": { "d3-array": "2.10.0 - 3", "d3-format": "1 - 3", "d3-interpolate": "1.2.0 - 3", "d3-time": "2.1.1 - 3", "d3-time-format": "2 - 4" } }, "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ=="],
+
+    "d3-scale-chromatic": ["d3-scale-chromatic@3.1.0", "", { "dependencies": { "d3-color": "1 - 3", "d3-interpolate": "1 - 3" } }, "sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ=="],
+
+    "d3-selection": ["d3-selection@3.0.0", "", {}, "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ=="],
+
+    "d3-shape": ["d3-shape@3.2.0", "", { "dependencies": { "d3-path": "^3.1.0" } }, "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA=="],
+
+    "d3-time": ["d3-time@3.1.0", "", { "dependencies": { "d3-array": "2 - 3" } }, "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q=="],
+
+    "d3-time-format": ["d3-time-format@4.1.0", "", { "dependencies": { "d3-time": "1 - 3" } }, "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg=="],
+
+    "d3-timer": ["d3-timer@3.0.1", "", {}, "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA=="],
+
+    "d3-transition": ["d3-transition@3.0.1", "", { "dependencies": { "d3-color": "1 - 3", "d3-dispatch": "1 - 3", "d3-ease": "1 - 3", "d3-interpolate": "1 - 3", "d3-timer": "1 - 3" }, "peerDependencies": { "d3-selection": "2 - 3" } }, "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w=="],
+
+    "d3-zoom": ["d3-zoom@3.0.0", "", { "dependencies": { "d3-dispatch": "1 - 3", "d3-drag": "2 - 3", "d3-interpolate": "1 - 3", "d3-selection": "2 - 3", "d3-transition": "2 - 3" } }, "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw=="],
+
+    "dagre-d3-es": ["dagre-d3-es@7.0.13", "", { "dependencies": { "d3": "^7.9.0", "lodash-es": "^4.17.21" } }, "sha512-efEhnxpSuwpYOKRm/L5KbqoZmNNukHa/Flty4Wp62JRvgH2ojwVgPgdYyr4twpieZnyRDdIH7PY2mopX26+j2Q=="],
+
+    "dayjs": ["dayjs@1.11.19", "", {}, "sha512-t5EcLVS6QPBNqM2z8fakk/NKel+Xzshgt8FFKAn+qwlD1pzZWxh0nVCrvFK7ZDb6XucZeF9z8C7CBWTRIVApAw=="],
+
+    "delaunator": ["delaunator@5.0.1", "", { "dependencies": { "robust-predicates": "^3.0.2" } }, "sha512-8nvh+XBe96aCESrGOqMp/84b13H9cdKbG5P2ejQCh4d4sK9RL4371qou9drQjMhvnPmhWl5hnmqbEE0fXr9Xnw=="],
+
+    "dequal": ["dequal@2.0.3", "", {}, "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA=="],
+
+    "devlop": ["devlop@1.1.0", "", { "dependencies": { "dequal": "^2.0.0" } }, "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA=="],
+
+    "dompurify": ["dompurify@3.3.2", "", { "optionalDependencies": { "@types/trusted-types": "^2.0.7" } }, "sha512-6obghkliLdmKa56xdbLOpUZ43pAR6xFy1uOrxBaIDjT+yaRuuybLjGS9eVBoSR/UPU5fq3OXClEHLJNGvbxKpQ=="],
+
+    "emoji-regex-xs": ["emoji-regex-xs@1.0.0", "", {}, "sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg=="],
+
+    "entities": ["entities@7.0.1", "", {}, "sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA=="],
+
+    "esbuild": ["esbuild@0.21.5", "", { "optionalDependencies": { "@esbuild/aix-ppc64": "0.21.5", "@esbuild/android-arm": "0.21.5", "@esbuild/android-arm64": "0.21.5", "@esbuild/android-x64": "0.21.5", "@esbuild/darwin-arm64": "0.21.5", "@esbuild/darwin-x64": "0.21.5", "@esbuild/freebsd-arm64": "0.21.5", "@esbuild/freebsd-x64": "0.21.5", "@esbuild/linux-arm": "0.21.5", "@esbuild/linux-arm64": "0.21.5", "@esbuild/linux-ia32": "0.21.5", "@esbuild/linux-loong64": "0.21.5", "@esbuild/linux-mips64el": "0.21.5", "@esbuild/linux-ppc64": "0.21.5", "@esbuild/linux-riscv64": "0.21.5", "@esbuild/linux-s390x": "0.21.5", "@esbuild/linux-x64": "0.21.5", "@esbuild/netbsd-x64": "0.21.5", "@esbuild/openbsd-x64": "0.21.5", "@esbuild/sunos-x64": "0.21.5", "@esbuild/win32-arm64": "0.21.5", "@esbuild/win32-ia32": "0.21.5", "@esbuild/win32-x64": "0.21.5" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw=="],
+
+    "estree-walker": ["estree-walker@2.0.2", "", {}, "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w=="],
+
+    "focus-trap": ["focus-trap@7.8.0", "", { "dependencies": { "tabbable": "^6.4.0" } }, "sha512-/yNdlIkpWbM0ptxno3ONTuf+2g318kh2ez3KSeZN5dZ8YC6AAmgeWz+GasYYiBJPFaYcSAPeu4GfhUaChzIJXA=="],
+
+    "fsevents": ["fsevents@2.3.3", "", { "os": "darwin" }, "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw=="],
+
+    "hachure-fill": ["hachure-fill@0.5.2", "", {}, "sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg=="],
+
+    "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
+
+    "hast-util-whitespace": ["hast-util-whitespace@3.0.0", "", { "dependencies": { "@types/hast": "^3.0.0" } }, "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw=="],
+
+    "hookable": ["hookable@5.5.3", "", {}, "sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ=="],
+
+    "html-void-elements": ["html-void-elements@3.0.0", "", {}, "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg=="],
+
+    "iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
+
+    "internmap": ["internmap@1.0.1", "", {}, "sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw=="],
+
+    "is-what": ["is-what@5.5.0", "", {}, "sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw=="],
+
+    "katex": ["katex@0.16.35", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-S0+riEvy1CK4VKse1ivMff8gmabe/prY7sKB3njjhyoLLsNFDQYtKNgXrbWUggGDCJBz7Fctl5i8fLCESHXzSg=="],
+
+    "khroma": ["khroma@2.1.0", "", {}, "sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw=="],
+
+    "langium": ["langium@4.2.1", "", { "dependencies": { "chevrotain": "~11.1.1", "chevrotain-allstar": "~0.3.1", "vscode-languageserver": "~9.0.1", "vscode-languageserver-textdocument": "~1.0.11", "vscode-uri": "~3.1.0" } }, "sha512-zu9QWmjpzJcomzdJQAHgDVhLGq5bLosVak1KVa40NzQHXfqr4eAHupvnPOVXEoLkg6Ocefvf/93d//SB7du4YQ=="],
+
+    "layout-base": ["layout-base@1.0.2", "", {}, "sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg=="],
+
+    "lodash-es": ["lodash-es@4.17.23", "", {}, "sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg=="],
+
+    "magic-string": ["magic-string@0.30.21", "", { "dependencies": { "@jridgewell/sourcemap-codec": "^1.5.5" } }, "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ=="],
+
+    "mark.js": ["mark.js@8.11.1", "", {}, "sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ=="],
+
+    "marked": ["marked@16.4.2", "", { "bin": { "marked": "bin/marked.js" } }, "sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA=="],
+
+    "mdast-util-to-hast": ["mdast-util-to-hast@13.2.1", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/mdast": "^4.0.0", "@ungap/structured-clone": "^1.0.0", "devlop": "^1.0.0", "micromark-util-sanitize-uri": "^2.0.0", "trim-lines": "^3.0.0", "unist-util-position": "^5.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" } }, "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA=="],
+
+    "mermaid": ["mermaid@11.12.3", "", { "dependencies": { "@braintree/sanitize-url": "^7.1.1", "@iconify/utils": "^3.0.1", "@mermaid-js/parser": "^1.0.0", "@types/d3": "^7.4.3", "cytoscape": "^3.29.3", "cytoscape-cose-bilkent": "^4.1.0", "cytoscape-fcose": "^2.2.0", "d3": "^7.9.0", "d3-sankey": "^0.12.3", "dagre-d3-es": "7.0.13", "dayjs": "^1.11.18", "dompurify": "^3.2.5", "katex": "^0.16.22", "khroma": "^2.1.0", "lodash-es": "^4.17.23", "marked": "^16.2.1", "roughjs": "^4.6.6", "stylis": "^4.3.6", "ts-dedent": "^2.2.0", "uuid": "^11.1.0" } }, "sha512-wN5ZSgJQIC+CHJut9xaKWsknLxaFBwCPwPkGTSUYrTiHORWvpT8RxGk849HPnpUAQ+/9BPRqYb80jTpearrHzQ=="],
+
+    "micromark-util-character": ["micromark-util-character@2.1.1", "", { "dependencies": { "micromark-util-symbol": "^2.0.0", "micromark-util-types": "^2.0.0" } }, "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q=="],
+
+    "micromark-util-encode": ["micromark-util-encode@2.0.1", "", {}, "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw=="],
+
+    "micromark-util-sanitize-uri": ["micromark-util-sanitize-uri@2.0.1", "", { "dependencies": { "micromark-util-character": "^2.0.0", "micromark-util-encode": "^2.0.0", "micromark-util-symbol": "^2.0.0" } }, "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ=="],
+
+    "micromark-util-symbol": ["micromark-util-symbol@2.0.1", "", {}, "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q=="],
+
+    "micromark-util-types": ["micromark-util-types@2.0.2", "", {}, "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA=="],
+
+    "minisearch": ["minisearch@7.2.0", "", {}, "sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg=="],
+
+    "mitt": ["mitt@3.0.1", "", {}, "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw=="],
+
+    "mlly": ["mlly@1.8.1", "", { "dependencies": { "acorn": "^8.16.0", "pathe": "^2.0.3", "pkg-types": "^1.3.1", "ufo": "^1.6.3" } }, "sha512-SnL6sNutTwRWWR/vcmCYHSADjiEesp5TGQQ0pXyLhW5IoeibRlF/CbSLailbB3CNqJUk9cVJ9dUDnbD7GrcHBQ=="],
+
+    "nanoid": ["nanoid@3.3.11", "", { "bin": { "nanoid": "bin/nanoid.cjs" } }, "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w=="],
+
+    "oniguruma-to-es": ["oniguruma-to-es@3.1.1", "", { "dependencies": { "emoji-regex-xs": "^1.0.0", "regex": "^6.0.1", "regex-recursion": "^6.0.2" } }, "sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ=="],
+
+    "package-manager-detector": ["package-manager-detector@1.6.0", "", {}, "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA=="],
+
+    "path-data-parser": ["path-data-parser@0.1.0", "", {}, "sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w=="],
+
+    "pathe": ["pathe@2.0.3", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="],
+
+    "perfect-debounce": ["perfect-debounce@1.0.0", "", {}, "sha512-xCy9V055GLEqoFaHoC1SoLIaLmWctgCUaBaWxDZ7/Zx4CTyX7cJQLJOok/orfjZAh9kEYpjJa4d0KcJmCbctZA=="],
+
+    "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
+
+    "pkg-types": ["pkg-types@1.3.1", "", { "dependencies": { "confbox": "^0.1.8", "mlly": "^1.7.4", "pathe": "^2.0.1" } }, "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ=="],
+
+    "points-on-curve": ["points-on-curve@0.2.0", "", {}, "sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A=="],
+
+    "points-on-path": ["points-on-path@0.2.1", "", { "dependencies": { "path-data-parser": "0.1.0", "points-on-curve": "0.2.0" } }, "sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g=="],
+
+    "postcss": ["postcss@8.5.8", "", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg=="],
+
+    "preact": ["preact@10.28.4", "", {}, "sha512-uKFfOHWuSNpRFVTnljsCluEFq57OKT+0QdOiQo8XWnQ/pSvg7OpX5eNOejELXJMWy+BwM2nobz0FkvzmnpCNsQ=="],
+
+    "property-information": ["property-information@7.1.0", "", {}, "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ=="],
+
+    "regex": ["regex@6.1.0", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg=="],
+
+    "regex-recursion": ["regex-recursion@6.0.2", "", { "dependencies": { "regex-utilities": "^2.3.0" } }, "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg=="],
+
+    "regex-utilities": ["regex-utilities@2.3.0", "", {}, "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng=="],
+
+    "rfdc": ["rfdc@1.4.1", "", {}, "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA=="],
+
+    "robust-predicates": ["robust-predicates@3.0.2", "", {}, "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg=="],
+
+    "rollup": ["rollup@4.59.0", "", { "dependencies": { "@types/estree": "1.0.8" }, "optionalDependencies": { "@rollup/rollup-android-arm-eabi": "4.59.0", "@rollup/rollup-android-arm64": "4.59.0", "@rollup/rollup-darwin-arm64": "4.59.0", "@rollup/rollup-darwin-x64": "4.59.0", "@rollup/rollup-freebsd-arm64": "4.59.0", "@rollup/rollup-freebsd-x64": "4.59.0", "@rollup/rollup-linux-arm-gnueabihf": "4.59.0", "@rollup/rollup-linux-arm-musleabihf": "4.59.0", "@rollup/rollup-linux-arm64-gnu": "4.59.0", "@rollup/rollup-linux-arm64-musl": "4.59.0", "@rollup/rollup-linux-loong64-gnu": "4.59.0", "@rollup/rollup-linux-loong64-musl": "4.59.0", "@rollup/rollup-linux-ppc64-gnu": "4.59.0", "@rollup/rollup-linux-ppc64-musl": "4.59.0", "@rollup/rollup-linux-riscv64-gnu": "4.59.0", "@rollup/rollup-linux-riscv64-musl": "4.59.0", "@rollup/rollup-linux-s390x-gnu": "4.59.0", "@rollup/rollup-linux-x64-gnu": "4.59.0", "@rollup/rollup-linux-x64-musl": "4.59.0", "@rollup/rollup-openbsd-x64": "4.59.0", "@rollup/rollup-openharmony-arm64": "4.59.0", "@rollup/rollup-win32-arm64-msvc": "4.59.0", "@rollup/rollup-win32-ia32-msvc": "4.59.0", "@rollup/rollup-win32-x64-gnu": "4.59.0", "@rollup/rollup-win32-x64-msvc": "4.59.0", "fsevents": "~2.3.2" }, "bin": { "rollup": "dist/bin/rollup" } }, "sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg=="],
+
+    "roughjs": ["roughjs@4.6.6", "", { "dependencies": { "hachure-fill": "^0.5.2", "path-data-parser": "^0.1.0", "points-on-curve": "^0.2.0", "points-on-path": "^0.2.1" } }, "sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ=="],
+
+    "rw": ["rw@1.3.3", "", {}, "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ=="],
+
+    "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
+
+    "search-insights": ["search-insights@2.17.3", "", {}, "sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ=="],
+
+    "shiki": ["shiki@2.5.0", "", { "dependencies": { "@shikijs/core": "2.5.0", "@shikijs/engine-javascript": "2.5.0", "@shikijs/engine-oniguruma": "2.5.0", "@shikijs/langs": "2.5.0", "@shikijs/themes": "2.5.0", "@shikijs/types": "2.5.0", "@shikijs/vscode-textmate": "^10.0.2", "@types/hast": "^3.0.4" } }, "sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ=="],
+
+    "source-map-js": ["source-map-js@1.2.1", "", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],
+
+    "space-separated-tokens": ["space-separated-tokens@2.0.2", "", {}, "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q=="],
+
+    "speakingurl": ["speakingurl@14.0.1", "", {}, "sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ=="],
+
+    "stringify-entities": ["stringify-entities@4.0.4", "", { "dependencies": { "character-entities-html4": "^2.0.0", "character-entities-legacy": "^3.0.0" } }, "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg=="],
+
+    "stylis": ["stylis@4.3.6", "", {}, "sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ=="],
+
+    "superjson": ["superjson@2.2.6", "", { "dependencies": { "copy-anything": "^4" } }, "sha512-H+ue8Zo4vJmV2nRjpx86P35lzwDT3nItnIsocgumgr0hHMQ+ZGq5vrERg9kJBo5AWGmxZDhzDo+WVIJqkB0cGA=="],
+
+    "tabbable": ["tabbable@6.4.0", "", {}, "sha512-05PUHKSNE8ou2dwIxTngl4EzcnsCDZGJ/iCLtDflR/SHB/ny14rXc+qU5P4mG9JkusiV7EivzY9Mhm55AzAvCg=="],
+
+    "tinyexec": ["tinyexec@1.0.2", "", {}, "sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg=="],
+
+    "trim-lines": ["trim-lines@3.0.1", "", {}, "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg=="],
+
+    "ts-dedent": ["ts-dedent@2.2.0", "", {}, "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "ufo": ["ufo@1.6.3", "", {}, "sha512-yDJTmhydvl5lJzBmy/hyOAA0d+aqCBuwl818haVdYCRrWV84o7YyeVm4QlVHStqNrrJSTb6jKuFAVqAFsr+K3Q=="],
+
+    "unist-util-is": ["unist-util-is@6.0.1", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g=="],
+
+    "unist-util-position": ["unist-util-position@5.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA=="],
+
+    "unist-util-stringify-position": ["unist-util-stringify-position@4.0.0", "", { "dependencies": { "@types/unist": "^3.0.0" } }, "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ=="],
+
+    "unist-util-visit": ["unist-util-visit@5.1.0", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0", "unist-util-visit-parents": "^6.0.0" } }, "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg=="],
+
+    "unist-util-visit-parents": ["unist-util-visit-parents@6.0.2", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-is": "^6.0.0" } }, "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ=="],
+
+    "uuid": ["uuid@11.1.0", "", { "bin": { "uuid": "dist/esm/bin/uuid" } }, "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A=="],
+
+    "vfile": ["vfile@6.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "vfile-message": "^4.0.0" } }, "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q=="],
+
+    "vfile-message": ["vfile-message@4.0.3", "", { "dependencies": { "@types/unist": "^3.0.0", "unist-util-stringify-position": "^4.0.0" } }, "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw=="],
+
+    "vite": ["vite@5.4.21", "", { "dependencies": { "esbuild": "^0.21.3", "postcss": "^8.4.43", "rollup": "^4.20.0" }, "optionalDependencies": { "fsevents": "~2.3.3" }, "peerDependencies": { "@types/node": "^18.0.0 || >=20.0.0", "less": "*", "lightningcss": "^1.21.0", "sass": "*", "sass-embedded": "*", "stylus": "*", "sugarss": "*", "terser": "^5.4.0" }, "optionalPeers": ["@types/node", "less", "lightningcss", "sass", "sass-embedded", "stylus", "sugarss", "terser"], "bin": { "vite": "bin/vite.js" } }, "sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw=="],
+
+    "vitepress": ["vitepress@1.6.4", "", { "dependencies": { "@docsearch/css": "3.8.2", "@docsearch/js": "3.8.2", "@iconify-json/simple-icons": "^1.2.21", "@shikijs/core": "^2.1.0", "@shikijs/transformers": "^2.1.0", "@shikijs/types": "^2.1.0", "@types/markdown-it": "^14.1.2", "@vitejs/plugin-vue": "^5.2.1", "@vue/devtools-api": "^7.7.0", "@vue/shared": "^3.5.13", "@vueuse/core": "^12.4.0", "@vueuse/integrations": "^12.4.0", "focus-trap": "^7.6.4", "mark.js": "8.11.1", "minisearch": "^7.1.1", "shiki": "^2.1.0", "vite": "^5.4.14", "vue": "^3.5.13" }, "peerDependencies": { "markdown-it-mathjax3": "^4", "postcss": "^8" }, "optionalPeers": ["markdown-it-mathjax3", "postcss"], "bin": { "vitepress": "bin/vitepress.js" } }, "sha512-+2ym1/+0VVrbhNyRoFFesVvBvHAVMZMK0rw60E3X/5349M1GuVdKeazuksqopEdvkKwKGs21Q729jX81/bkBJg=="],
+
+    "vscode-jsonrpc": ["vscode-jsonrpc@8.2.0", "", {}, "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA=="],
+
+    "vscode-languageserver": ["vscode-languageserver@9.0.1", "", { "dependencies": { "vscode-languageserver-protocol": "3.17.5" }, "bin": { "installServerIntoExtension": "bin/installServerIntoExtension" } }, "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g=="],
+
+    "vscode-languageserver-protocol": ["vscode-languageserver-protocol@3.17.5", "", { "dependencies": { "vscode-jsonrpc": "8.2.0", "vscode-languageserver-types": "3.17.5" } }, "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg=="],
+
+    "vscode-languageserver-textdocument": ["vscode-languageserver-textdocument@1.0.12", "", {}, "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA=="],
+
+    "vscode-languageserver-types": ["vscode-languageserver-types@3.17.5", "", {}, "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg=="],
+
+    "vscode-uri": ["vscode-uri@3.1.0", "", {}, "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ=="],
+
+    "vue": ["vue@3.5.29", "", { "dependencies": { "@vue/compiler-dom": "3.5.29", "@vue/compiler-sfc": "3.5.29", "@vue/runtime-dom": "3.5.29", "@vue/server-renderer": "3.5.29", "@vue/shared": "3.5.29" }, "peerDependencies": { "typescript": "*" }, "optionalPeers": ["typescript"] }, "sha512-BZqN4Ze6mDQVNAni0IHeMJ5mwr8VAJ3MQC9FmprRhcBYENw+wOAAjRj8jfmN6FLl0j96OXbR+CjWhmAmM+QGnA=="],
+
+    "zwitch": ["zwitch@2.0.4", "", {}, "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A=="],
+
+    "cytoscape-fcose/cose-base": ["cose-base@2.2.0", "", { "dependencies": { "layout-base": "^2.0.0" } }, "sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g=="],
+
+    "d3-dsv/commander": ["commander@7.2.0", "", {}, "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw=="],
+
+    "d3-sankey/d3-array": ["d3-array@2.12.1", "", { "dependencies": { "internmap": "^1.0.0" } }, "sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ=="],
+
+    "d3-sankey/d3-shape": ["d3-shape@1.3.7", "", { "dependencies": { "d3-path": "1" } }, "sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw=="],
+
+    "cytoscape-fcose/cose-base/layout-base": ["layout-base@2.0.1", "", {}, "sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg=="],
+
+    "d3-sankey/d3-shape/d3-path": ["d3-path@1.0.9", "", {}, "sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg=="],
+  }
+}

docs-site/character-dictionary.md

@@ -0,0 +1,313 @@
+# Character dictionary
+
+SubMiner builds a Yomitan-compatible dictionary of a show's characters from [AniList](https://anilist.co), the online anime and manga database. Once it is loaded, character names in subtitles get recognized and highlighted, and hovering one shows the portrait, role, voice actor, and biography without leaving the overlay.
+
+Proper names rarely appear in ordinary dictionaries, so without this every character name reads as an unknown word. That wrecks N+1 highlighting, since a line naming two characters looks like a line with two unknowns. Recognizing them keeps the highlighting pointed at real vocabulary.
+
+The dictionary is generated per-media, merged across your recently-watched titles, and auto-imported into Yomitan. When a character name appears in a subtitle line, it gets highlighted and becomes available for hover-driven Yomitan profile lookup.
+
+## How it works
+
+The feature has three stages: **snapshot**, **merge**, and **match**.
+
+1. **Snapshot** - When you start watching a new title, SubMiner queries the AniList GraphQL API for the media's character list. Each character's names, reading, role, description, birthday, voice actors, and portrait are fetched and saved as a local JSON snapshot in `character-dictionaries/snapshots/anilist-{mediaId}.json`. Images are downloaded and base64-encoded into the snapshot.
+
+2. **Merge** - SubMiner maintains a most-recently-used list of media IDs (default: 3). Snapshots from those titles are merged into a single Yomitan ZIP - `character-dictionaries/merged.zip` - which is always named "SubMiner Character Dictionary" so Yomitan treats it as a single stable dictionary across rebuilds.
+
+3. **Match** - During subtitle rendering, Yomitan scans subtitle text against all loaded dictionaries including the character dictionary. SubMiner only accepts character entries for the current AniList media when that media ID is known, then flags matching tokens with `isNameMatch` and highlights them in the overlay with a distinct color.
+
+## Enabling the feature
+
+Character dictionary sync is disabled by default. To turn it on:
+
+1. Enable **Name Match** in Settings → Subtitle Style, or set `subtitleStyle.nameMatchEnabled: true` in your config.
+2. Start watching. SubMiner queries AniList's public GraphQL API, which needs no authentication, and imports the merged dictionary into Yomitan.
+3. Optionally enable **Name Match Images** (Settings → Subtitle Style) to show inline circular character portraits next to matched names in subtitles.
+
+```jsonc
+{
+  "subtitleStyle": {
+    "nameMatchEnabled": true,
+    "nameMatchImagesEnabled": true, // optional - inline portraits
+  },
+}
+```
+
+::: tip
+The first sync for a media title takes a few seconds while character data and portraits are fetched from AniList. Subsequent launches reuse the cached media match and snapshot without a fresh AniList lookup.
+:::
+
+::: info
+AniList character data is fetched via public GraphQL queries - no account or access token is needed. AniList authentication is only required for the separate [watch-progress sync](/anilist-integration) feature.
+:::
+
+::: warning
+If `yomitan.externalProfilePath` is set, SubMiner switches to read-only external-profile mode. In that mode SubMiner can reuse another app's installed Yomitan dictionaries/settings, but SubMiner's own character-dictionary features are fully disabled.
+:::
+
+## Name generation
+
+A single character produces many searchable terms so that names are recognized regardless of how they appear in dialogue. SubMiner generates variants for:
+
+**Spacing and combination:**
+
+- Full name with space: 須々木 心一
+- Combined form: 須々木心一
+- Family name alone: 須々木
+- Given name alone: 心一
+
+Unspaced native names (AniList often stores 渡辺真奈美 without a separator) are split into family/given parts with MeCab when it is available: person-name POS tags (姓/名) decide the boundary, validated against AniList's romanized first/last name readings. Without MeCab, a length heuristic based on the romanized readings guesses the boundary. That guess can be ambiguous, since 東紫乃 could be 東+紫乃 or 東紫+乃, so SubMiner generates terms for the top two candidate boundaries and the real surname still matches. Snapshots built without MeCab are regenerated automatically once MeCab becomes available, upgrading them to the exact splits.
+
+**Middle-dot removal** (common in katakana foreign names):
+
+- ア・リ・ス → アリス (combined), plus individual segments
+
+**Honorific suffixes** - each base name is expanded with 15 common suffixes:
+
+| Honorific | Reading    |
+| --------- | ---------- |
+| さん      | さん       |
+| 様        | さま       |
+| 先生      | せんせい   |
+| 先輩      | せんぱい   |
+| 後輩      | こうはい   |
+| 氏        | し         |
+| 君        | くん       |
+| くん      | くん       |
+| ちゃん    | ちゃん     |
+| たん      | たん       |
+| 坊        | ぼう       |
+| 殿        | どの       |
+| 博士      | はかせ     |
+| 社長      | しゃちょう |
+| 部長      | ぶちょう   |
+
+**Romanized names** - names stored in romaji on AniList are converted to kana aliases so they can match against Japanese subtitle text.
+
+This means a character like "太郎" generates entries for 太郎, 太郎さん, 太郎先生, 太郎君, 太郎ちゃん, and so on - all with correct readings.
+
+## Name matching
+
+Name matching runs inside Yomitan's scanning pipeline during subtitle tokenization.
+
+1. Yomitan receives subtitle text and scans for dictionary matches.
+2. Entries from "SubMiner Character Dictionary" are checked with exact primary-source matching - the token must match the entry's `originalText` with `isPrimary: true` and `matchType: 'exact'`.
+3. When the current AniList media ID is known, entries whose embedded media ID belongs to a different title are ignored for name matching and inline portraits.
+4. Matched tokens are flagged `isNameMatch: true` and forwarded to the renderer.
+5. If `subtitleStyle.nameMatchEnabled` is enabled, the renderer applies the name-match highlight color (default: `#f5bde6`).
+6. If `subtitleStyle.nameMatchImagesEnabled` is enabled, the renderer also injects a small circular AniList portrait from the cached snapshot image data.
+
+Older snapshot schema versions are regenerated automatically. Current-version snapshots are normally reused, but when `subtitleStyle.nameMatchImagesEnabled` is enabled SubMiner also checks whether the cached snapshot contains usable character portrait data. If it does not, the snapshot is refreshed so the merged dictionary can include images.
+
+Name matches are visually distinct from [N+1 targeting, frequency highlighting, and JLPT tags](/subtitle-annotations) so you can tell at a glance whether a highlighted word is a character name or a vocabulary target.
+
+**Key settings:**
+
+| Option                                 | Default   | Description                               |
+| -------------------------------------- | --------- | ----------------------------------------- |
+| `subtitleStyle.nameMatchEnabled`       | `false`   | Enable dictionary sync and highlighting   |
+| `subtitleStyle.nameMatchImagesEnabled` | `false`   | Show small AniList portraits beside names |
+| `subtitleStyle.nameMatchColor`         | `#f5bde6` | Highlight color for matched names         |
+
+## Inline character portraits
+
+When `subtitleStyle.nameMatchImagesEnabled` is enabled, SubMiner injects a small circular portrait image directly into the subtitle line next to each matched character name.
+
+Portraits are sourced from the local snapshot - they are embedded at snapshot-generation time and served from the cached ZIP, so no network request happens during playback. Images are downloaded from AniList CDN once per character and stored in `character-dictionaries/img/`.
+
+If a snapshot was generated before portrait data was available (e.g. during an earlier version or offline sync), SubMiner detects the missing image data on the next media match and automatically refreshes the snapshot so portraits are included in the next merged dictionary build.
+
+**To enable:**
+
+- Settings → Subtitle Style → **Name Match Images**, or
+- `subtitleStyle.nameMatchImagesEnabled: true` in config.
+
+The portrait size is controlled by the surrounding subtitle font size and renders as a circle clipped from the character's AniList cover image.
+
+::: tip
+Inline portraits help you quickly associate names with faces while building vocabulary - especially useful for shows with large casts where you're still learning who's who.
+:::
+
+## Dictionary entries
+
+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 / "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)
+- **Voiced by** - voice actor name and portrait (collapsible)
+
+The three collapsible sections can be configured to start open or closed:
+
+```jsonc
+{
+  "anilist": {
+    "characterDictionary": {
+      "collapsibleSections": {
+        "description": false,
+        "characterInformation": false,
+        "voicedBy": false,
+      },
+    },
+  },
+}
+```
+
+## Auto-sync lifecycle
+
+When `subtitleStyle.nameMatchEnabled` is `true`, SubMiner runs an auto-sync routine whenever the active media changes.
+
+These phases are emitted through the configured notification surface. Some phases are skipped when unnecessary: `generating` only appears on a cache miss, `building` only appears when the merged ZIP must be rebuilt, and `importing` only appears when Yomitan needs a new dictionary import.
+
+**Phases:**
+
+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. 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.
+
+**State tracking** is persisted in `character-dictionaries/auto-sync-state.json`. AniList media matches are cached separately in `character-dictionaries/anilist-resolution-cache.json` so snapshot hits do not need another AniList search.
+
+```jsonc
+{
+  "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
+
+You can generate a character dictionary from the command line without auto-sync:
+
+```bash
+# Generate for a file or directory
+subminer dictionary /path/to/media
+
+# Generate for current anime (AppImage)
+SubMiner.AppImage --dictionary
+```
+
+This creates a standalone dictionary ZIP for the target media and saves it alongside the snapshots.
+
+## Correcting AniList matches
+
+SubMiner uses `guessit` to infer the anime title from the active filename before searching AniList. Some filenames can still resolve to the wrong title. For example, `Re - ZERO, Starting Life in Another World (2016)` can be misread as a different `Re...` series.
+
+Use the in-app selector or CLI to pin the correct AniList media for the whole series:
+
+- In-app: open the manager with `Ctrl/Cmd+D`, use the **Override** tab/button, edit the prefilled title if needed, then search and choose the correct result.
+- CLI: `--dictionary-candidates` still lists matches for the current filename guess.
+
+```bash
+# List candidate AniList matches for a file
+subminer dictionary --candidates "/path/to/episode.mkv"
+
+# Save the correct AniList media ID for that series
+subminer dictionary --select 21355 "/path/to/episode.mkv"
+
+# Equivalent direct app flags
+SubMiner.AppImage --dictionary-candidates --dictionary-target "/path/to/episode.mkv"
+SubMiner.AppImage --dictionary-select --dictionary-anilist-id 21355 --dictionary-target "/path/to/episode.mkv"
+
+# Open the in-app selector from the running app
+subminer app --session-action '{"actionId":"openCharacterDictionaryManager"}'
+```
+
+SubMiner stores manual selections in `character-dictionaries/anilist-overrides.json`. The episode's parent directory **and detected season** define the override scope, so later episodes in the same season keep the selected AniList ID even if their filename guesses differ, while a different season never inherits the override - including when every season sits in one flat folder. When you replace a wrong match, SubMiner removes that stale media ID from the merged dictionary's active set and rebuilds/imports the merged character dictionary.
+
+An override also pins the entry used for [AniList watch progress](/anilist-integration), so correcting a wrong match once fixes both the character dictionary and progress tracking.
+
+## Managing loaded entries
+
+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; 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.
+
+## File structure
+
+All character dictionary data lives under `{userData}/character-dictionaries/`:
+
+```text
+character-dictionaries/
+  snapshots/
+    anilist-170942.json       # Per-media character snapshot
+    anilist-163134.json
+  merged.zip                  # Active merged dictionary (imported into Yomitan)
+  auto-sync-state.json        # Tracks active media IDs and revision
+  anilist-overrides.json      # Manual series-to-AniList overrides
+  img/
+    m170942-c12345.jpg        # Character portrait
+    m170942-va67890.jpg       # Voice actor portrait
+```
+
+**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", description }
+  tag_bank_1.json             # Tag definitions
+  term_bank_1.json            # Up to 10,000 terms per bank
+  term_bank_2.json
+  img/                        # Embedded character and VA portraits
+```
+
+## Configuration reference
+
+| Option                                                                 | Default   | Description                                                     |
+| ---------------------------------------------------------------------- | --------- | --------------------------------------------------------------- |
+| `anilist.characterDictionary.maxLoaded`                                | `3`       | Number of recent media snapshots kept in the merged dictionary  |
+| `anilist.characterDictionary.profileScope`                             | `"all"`   | Apply dictionary to `"all"` Yomitan profiles or `"active"` only |
+| `anilist.characterDictionary.collapsibleSections.description`          | `false`   | Start Description section expanded                              |
+| `anilist.characterDictionary.collapsibleSections.characterInformation` | `false`   | Start Character Information section expanded                    |
+| `anilist.characterDictionary.collapsibleSections.voicedBy`             | `false`   | Start Voiced By section expanded                                |
+| `subtitleStyle.nameMatchEnabled`                                       | `false`   | Enable character-dictionary sync and name highlighting          |
+| `subtitleStyle.nameMatchImagesEnabled`                                 | `false`   | Show small AniList portraits beside matched names               |
+| `subtitleStyle.nameMatchColor`                                         | `#f5bde6` | Highlight color for character-name matches                      |
+
+## Reference implementation
+
+SubMiner's character dictionary builder is inspired by the [Japanese Character Name Dictionary](https://github.com/bee-san/Japanese_Character_Name_Dictionary) project - a standalone Rust web service that generates Yomitan character dictionaries from AniList and VNDB data.
+
+The reference implementation covers the same ground: name variant generation, honorific expansion, structured Yomitan content, and portrait embedding. It also reads VNDB as a source for visual novel characters. Key differences:
+
+|                        | SubMiner                                     | Reference Implementation              |
+| ---------------------- | -------------------------------------------- | ------------------------------------- |
+| **Runtime**            | TypeScript, runs inside Electron             | Rust, standalone web service          |
+| **Data sources**       | AniList only                                 | AniList + VNDB                        |
+| **Delivery**           | Auto-synced into bundled Yomitan             | ZIP download via web UI               |
+| **Honorific strategy** | Eager generation at build time               | Lazy generation during ZIP export     |
+| **Caching**            | File-based snapshots                         | Multi-tier (memory + disk + SQLite)   |
+| **Updates**            | Revision-hashed; skips reimport if unchanged | URL-encoded settings for auto-refresh |
+
+If you work with visual novels or want a standalone dictionary generator independent of SubMiner, the reference implementation is worth checking out.
+
+## Troubleshooting
+
+- **Names not highlighting:** Confirm `subtitleStyle.nameMatchEnabled` is `true`. Check that the current media has an AniList entry - SubMiner needs a media ID to fetch characters.
+- **Inline portraits missing:** Confirm `subtitleStyle.nameMatchImagesEnabled` is `true`. On the next character dictionary sync, SubMiner refreshes current-version snapshots that do not contain usable cached character portrait data. Portraits still require AniList to return an image and the image download to succeed.
+- **Sync seems stuck:** The auto-sync debounces for 800ms after media changes and throttles image downloads at 250ms per image. Large casts (50+ characters) take longer. Check the status bar for the current sync phase.
+- **Wrong characters showing:** Open the in-app character dictionary manager (`Ctrl/Cmd+D`) to remove/reorder loaded titles, then use **Override** to correct the active AniList match. You can also run `--dictionary-candidates`, then save the correct media with `--dictionary-select --dictionary-anilist-id <id>`. SubMiner ignores character entries from other loaded titles for subtitle name matching and inline portraits once the current media ID is known.
+- **Yomitan import fails:** SubMiner waits up to 7 seconds for Yomitan to be ready for mutations. If Yomitan is still loading dictionaries or performing another import, the operation may time out. Restarting the overlay typically resolves this.
+- **Portraits missing:** Images are downloaded from AniList CDN during snapshot generation. If the network was unavailable during the initial sync, delete the snapshot file from `character-dictionaries/snapshots/` and let it regenerate.
+
+## Related
+
+- [Subtitle Annotations](/subtitle-annotations) - how name matches interact with N+1, frequency, and JLPT layers
+- [AniList Integration](/anilist-integration) - watch-progress sync and AniList authentication (separate from character dictionary)
+- [Configuration Reference](/configuration) - full config options

docs-site/demos.md

@@ -0,0 +1,73 @@
+# Feature demos
+
+Short recordings from real playback sessions.
+
+Some vocabulary for what follows. _Yomitan_ is the pop-up dictionary. _Jimaku_ is a community subtitle database. _alass_ and _ffsubsync_ retime subtitles against the audio. _Jellyfin_ is a self-hosted media server. A _texthooker_ is a web page that mirrors the current subtitle as selectable text so browser tools can read it.
+
+<script setup>
+import { withBase } from 'vitepress';
+
+const v = '20260819-1';
+</script>
+
+## Anki card mining and enrichment
+
+Mine a card from Yomitan or straight from a subtitle line. SubMiner attaches the sentence, an audio clip cut to the line timing, and a screenshot.
+
+<video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/minecard.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/minecard.mp4?v=${v}`)" type="video/mp4" />
+  <a :href="withBase(`/assets/minecard.webm?v=${v}`)" target="_blank" rel="noreferrer">
+    <img :src="withBase(`/assets/minecard.webp?v=${v}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+  </a>
+</video>
+
+## Subtitle download and sync
+
+Search Jimaku, download a track, then retime it with alass or ffsubsync without leaving SubMiner.
+
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/subtitle-sync-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/subtitle-sync.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/subtitle-sync.mp4?v=${v}`)" type="video/mp4" />
+</video> -->
+
+::: info VIDEO COMING SOON
+:::
+
+## Jellyfin integration
+
+Browse your Jellyfin library, cast to a device, and start playback from SubMiner. Watch progress goes back to the Jellyfin server.
+
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/jellyfin-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/jellyfin.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/jellyfin.mp4?v=${v}`)" type="video/mp4" />
+</video> -->
+
+::: info VIDEO COMING SOON
+:::
+
+## Texthooker
+
+Mirror subtitles to an external texthooker page so browser extensions can read them while the overlay runs.
+
+<!-- <video controls playsinline preload="metadata" :poster="withBase(`/assets/demos/texthooker-poster.jpg?v=${v}`)">
+  <source :src="withBase(`/assets/demos/texthooker.webm?v=${v}`)" type="video/webm" />
+  <source :src="withBase(`/assets/demos/texthooker.mp4?v=${v}`)" type="video/mp4" />
+</video> -->
+
+::: info VIDEO COMING SOON
+:::
+
+<style>
+video {
+  width: 100%;
+  border-radius: 12px;
+  border: 1px solid var(--vp-c-divider);
+  box-shadow: 0 18px 44px rgba(0, 0, 0, 0.28);
+  margin: 0.75rem 0 2.5rem;
+}
+
+h2 {
+  margin-top: 2.5rem !important;
+}
+</style>

docs-site/development.md

@@ -0,0 +1,246 @@
+# Building and testing
+
+Architecture and workflow guidance lives in `docs/README.md` at the repo root. This page covers build and test commands only.
+
+## 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/prepare-build-assets.mjs` (skip with `SUBMINER_SKIP_MACOS_HELPER_BUILD=1`)
+
+## Setup
+
+```bash
+git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
+cd SubMiner
+make deps
+```
+
+`make deps` initializes submodules and installs root, `stats/`, and `vendor/texthooker-ui` dependencies. The Yomitan submodule installs its own dependencies on demand during `bun run build`.
+
+## Building
+
+```bash
+# Main app build
+bun run build
+
+# Platform packages
+bun run build:appimage      # Linux AppImage
+bun run build:mac           # macOS DMG + ZIP (signed)
+bun run build:mac:unsigned  # macOS DMG + ZIP (unsigned)
+bun run build:win           # Windows NSIS installer + ZIP
+
+# Optional launcher artifact only
+make build-launcher
+# output: dist/launcher/subminer
+```
+
+`bun run build` includes the Yomitan build step. It builds the bundled Chrome extension directly from the `vendor/subminer-yomitan` submodule into `build/yomitan` using Bun.
+
+## Launcher artifact workflow
+
+- Source of truth: `launcher/*.ts`
+- Generated output: `dist/launcher/subminer`
+- Do not hand-edit generated launcher output.
+- Repo-root `./subminer` is a stale artifact path and is rejected by verification checks.
+- Install targets (`make install-linux`, `make install-macos`) copy from `dist/launcher/subminer`.
+
+Verify the workflow:
+
+```bash
+make build-launcher
+dist/launcher/subminer --help >/dev/null
+bash scripts/verify-generated-launcher.sh
+```
+
+## Running locally
+
+```bash
+bun run dev    # builds + launches with --start --dev
+electron . --start --dev --log-level debug   # equivalent Electron launch with verbose logging
+electron . --background                       # tray/background mode, minimal default logging
+make dev-start                                # build + launch via Makefile
+make dev-watch                                # watch TS + renderer and launch Electron (faster edit loop)
+make dev-watch-macos                          # same as dev-watch, forcing --backend macos
+```
+
+For mpv-plugin-driven testing without exporting `SUBMINER_BINARY_PATH` each run, set a one-time
+dev binary path with `mpv.subminerBinaryPath` in your SubMiner config. The launcher injects it into
+the mpv plugin at runtime:
+
+```json
+{
+  "mpv": {
+    "subminerBinaryPath": "/absolute/path/to/SubMiner/scripts/subminer-dev.sh"
+  }
+}
+```
+
+## Testing
+
+Default lanes:
+
+```bash
+bun run test           # alias for test:fast
+bun run test:fast      # full source lanes: src + launcher-unit + scripts + runtime compat
+bun run test:runtime:compat # compiled/runtime compatibility slice only
+bun run test:env       # launcher/plugin + env-sensitive verification
+bun run test:stats     # stats dashboard UI suite
+bun run test:immersion:sqlite # SQLite persistence lane
+bun run test:subtitle  # maintained alass/ffsubsync subtitle surface
+```
+
+Test lane membership is defined once in `scripts/test-lanes.ts` and discovered by
+directory, so new test files join their lane automatically. `scripts/run-test-lane.mjs`
+runs each test file in its own `bun test` process (per-file isolation) so a hanging
+test or leaked global in one file cannot cascade into the rest of the lane; pass
+`--jobs N` to parallelize or `--single-process` for one shared process.
+
+- `bun run test` and `bun run test:fast` cover the full discovered `src/**` suite, launcher unit tests, `scripts/**` tests, and the compiled/runtime compatibility lane.
+- `bun run test:runtime:compat` covers the compiled/runtime slice directly: `ipc`, `anki-jimaku-ipc`, `overlay-manager`, `config-validation`, `startup-config`, and `registry`.
+- `bun run test:env` covers environment-sensitive checks: launcher smoke/plugin verification plus the Bun source SQLite lane.
+- `bun run test:stats` runs the stats dashboard suite under `stats/src/**`.
+- `bun run test:immersion:sqlite` is the reproducible persistence lane when you need real DB-backed SQLite coverage under Bun.
+
+The Bun-managed discovery lanes intentionally exclude a small compiled/runtime-focused set: `src/core/services/ipc.test.ts`, `src/core/services/anki-jimaku-ipc.test.ts`, `src/core/services/overlay-manager.test.ts`, `src/main/config-validation.test.ts`, `src/main/runtime/startup-config.test.ts`, and `src/main/runtime/registry.test.ts`. `bun run test:runtime:compat` keeps them in the standard workflow via `dist/**`.
+
+Suggested local gate before handoff:
+
+```bash
+bun run typecheck
+bun run test:fast
+bun run test:env
+bun run build
+bun run test:smoke:dist
+```
+
+If you changed docs in `docs-site/`, also run:
+
+```bash
+bun run docs:test
+bun run docs:build
+```
+
+For production docs routing, run the versioned build:
+
+```bash
+bun run docs:build:versioned
+```
+
+The versioned build writes `.tmp/docs-versioned-site` with latest stable docs at `/`, development docs at `/main/`, and stable archives under `/v/<version>/`. Prerelease tags are skipped. Public assets from `docs-site/public/assets` are shared from root `/assets/` so large demo media is not duplicated into every version archive; generated VitePress CSS and JS assets stay under each version route. Stale `.tmp/docs-versioned-archive-cache` generations are pruned after a successful build, and intermediate `.tmp/docs-versioned-build` workspaces are removed.
+
+Focused commands:
+
+```bash
+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: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
+bun run test:immersion:sqlite:src # Bun source lane
+```
+
+Dist-level tests are now an explicit smoke lane used to validate compiled/runtime assumptions.
+
+Launcher smoke artifacts are written to `.tmp/launcher-smoke` locally and uploaded by CI/release workflows when the smoke step fails.
+
+Smoke and optional deep dist commands:
+
+```bash
+bun run build                 # compile dist artifacts
+bun run test:immersion:sqlite # compile + run SQLite-backed immersion tests under Bun
+bun run test:smoke:dist       # explicit smoke scope for compiled runtime
+```
+
+Use `bun run test:immersion:sqlite` when you need real DB-backed coverage for the immersion tracker.
+
+## Formatting
+
+Use the scoped formatter for normal app-repo work:
+
+```bash
+make pretty
+bun run format:check: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.
+
+## Config generation
+
+```bash
+# Generate default config to ~/.config/SubMiner/config.jsonc (or %APPDATA%\SubMiner\config.jsonc on Windows)
+bun run electron . --generate-config
+
+# Regenerate the repo's config.example.jsonc from centralized defaults
+bun run generate:config-example
+```
+
+Convenience wrappers still exist:
+
+- `make generate-config`
+- `make generate-example-config`
+
+## Documentation site
+
+The docs site now lives in `docs-site/` inside the main repo.
+
+From the SubMiner app repo:
+
+```bash
+bun --cwd docs-site install
+bun run docs:dev     # Dev server at http://localhost:5173
+bun run docs:build   # Production build into docs-site/.vitepress/dist
+bun run docs:preview # Preview built site at http://localhost:4173
+bun run docs:test    # Docs regression tests
+```
+
+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
+
+Run `make help` for a full list of targets. Key ones:
+
+| Target                      | Description                                                       |
+| --------------------------- | ----------------------------------------------------------------- |
+| `make build`                | Build platform package for detected OS                            |
+| `make build-launcher`       | Generate launcher wrappers and CLI payload in `dist/launcher/`    |
+| `make install`              | Install platform artifacts (wrapper, theme, AppImage/app bundle)  |
+| `make deps`                 | Init submodules and install root/stats/texthooker-ui deps         |
+| `make pretty`               | Run scoped Prettier formatting for maintained source/config files |
+| `make generate-config`      | Generate default config from centralized registry                 |
+| `make build-linux`          | Convenience wrapper for Linux packaging                           |
+| `make build-macos`          | Convenience wrapper for signed macOS packaging                    |
+| `make build-macos-unsigned` | Convenience wrapper for unsigned macOS packaging                  |
+
+## Contributor notes
+
+- To add/change a config default, edit the matching domain file in `src/config/definitions/defaults-*.ts`.
+- To add/change config option metadata, edit the matching domain file in `src/config/definitions/options-*.ts`.
+- To add/change generated config template blocks/comments, update `src/config/definitions/template-sections.ts`.
+- Keep `src/config/definitions.ts` as the composed public API (`DEFAULT_CONFIG`, registries, template export) that wires domain modules together.
+- Overlay window/visibility state is owned by `src/core/services/overlay-manager.ts`.
+- Runtime architecture/module-boundary conventions are summarized in [Architecture](/architecture), with canonical internal guidance in `docs/architecture/README.md` at the repo root.
+- Linux packaged desktop launches pass `--background` using electron-builder `build.linux.executableArgs` in `package.json`.
+- Prefer direct inline deps objects in `src/main/` modules for simple pass-through wiring.
+- Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping).
+
+## Environment variables
+
+| Variable                           | Description                                                                    |
+| ---------------------------------- | ------------------------------------------------------------------------------ |
+| `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                        |
+| `SUBMINER_JIMAKU_API_KEY_COMMAND`  | Command used to resolve Jimaku API key at runtime                              |
+| `SUBMINER_JIMAKU_API_BASE_URL`     | Override Jimaku API base URL                                                   |
+| `SUBMINER_JELLYFIN_ACCESS_TOKEN`   | Override Jellyfin access token (used before stored encrypted session fallback) |
+| `SUBMINER_JELLYFIN_USER_ID`        | Optional Jellyfin user ID override                                             |
+| `SUBMINER_SKIP_MACOS_HELPER_BUILD` | Set to `1` to skip building the macOS helper binary during `bun run build`     |

docs-site/docs-sync.test.ts

@@ -0,0 +1,117 @@
+import { expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+
+const rootChangelogContents = readFileSync(new URL('../CHANGELOG.md', import.meta.url), 'utf8');
+const readmeContents = readFileSync(new URL('./README.md', import.meta.url), 'utf8');
+const usageContents = readFileSync(new URL('./usage.md', import.meta.url), 'utf8');
+const installationContents = readFileSync(new URL('./installation.md', import.meta.url), 'utf8');
+const mpvPluginContents = readFileSync(new URL('./mpv-plugin.md', import.meta.url), 'utf8');
+const developmentContents = readFileSync(new URL('./development.md', import.meta.url), 'utf8');
+const changelogContents = readFileSync(new URL('./changelog.md', import.meta.url), 'utf8');
+const docsPackageContents = readFileSync(new URL('./package.json', import.meta.url), 'utf8');
+const ankiIntegrationContents = readFileSync(
+  new URL('./anki-integration.md', import.meta.url),
+  'utf8',
+);
+const configurationContents = readFileSync(new URL('./configuration.md', import.meta.url), 'utf8');
+const troubleshootingContents = readFileSync(
+  new URL('./troubleshooting.md', import.meta.url),
+  'utf8',
+);
+
+function extractReleaseHeadings(content: string, count: number): string[] {
+  return Array.from(content.matchAll(/^## v[^\n]+$/gm))
+    .map(([heading]) => heading)
+    .slice(0, count);
+}
+
+function extractCurrentMinorHeadings(content: string): string[] {
+  const allHeadings = Array.from(content.matchAll(/^## v(\d+\.\d+)\.\d+[^\n]*$/gm));
+  if (allHeadings.length === 0) return [];
+  const currentMinor = allHeadings[0]![1];
+  return allHeadings.filter(([, minor]) => minor === currentMinor).map(([heading]) => heading);
+}
+
+test('docs reflect current launcher and release surfaces', () => {
+  expect(usageContents).not.toContain('--mode preprocess');
+  expect(usageContents).not.toContain('"automatic" (default)');
+  expect(usageContents).toContain('during startup while mpv is paused');
+
+  expect(installationContents).toContain('bun run build:appimage');
+  expect(installationContents).toContain('bun run build:win');
+
+  expect(mpvPluginContents).toContain('\\\\.\\pipe\\subminer-socket');
+
+  expect(readmeContents).toContain('Automatic production and preview deployments: disabled');
+  expect(readmeContents).toContain('/main/');
+  expect(readmeContents).toContain('GitHub Actions direct upload with Wrangler');
+  expect(developmentContents).not.toContain('../subminer-docs');
+  expect(developmentContents).toContain('bun run docs:build');
+  expect(developmentContents).toContain('bun run docs:test');
+  expect(developmentContents).toContain('bun run docs:build:versioned');
+  expect(developmentContents).not.toContain('test:subtitle:dist');
+  expect(developmentContents).toContain('bun run build:win');
+
+  expect(ankiIntegrationContents).not.toContain('alwaysUseAiTranslation');
+  expect(ankiIntegrationContents).not.toContain('targetLanguage');
+  expect(configurationContents).not.toContain('youtubeSubgen": {\n    "mode"');
+  expect(configurationContents).not.toContain('youtubeSubgen.primarySubLanguages');
+  expect(configurationContents).toContain('youtube.primarySubLanguages');
+  // The AI provider still exists in src/ai and ankiConnect.ai, but it is not
+  // exposed in the Settings window and is not documented for users. Keep the
+  // user-facing docs free of it so nobody configures a hidden surface.
+  expect(configurationContents).not.toContain('Shared AI Provider');
+  expect(configurationContents).not.toContain('ankiConnect.ai');
+  expect(ankiIntegrationContents).not.toContain('AI Translation');
+  // ankiConnect.fields.translation is a LEGACY_HIDDEN_CONFIG_PATHS key, so it
+  // must not be documented as a current setting.
+  expect(configurationContents).not.toContain('fields.translation');
+  expect(ankiIntegrationContents).not.toContain('SelectionText');
+  // fields.audio holds SubMiner's generated sentence audio; examples should not
+  // point it at the field Yomitan uses for word audio.
+  expect(ankiIntegrationContents).not.toContain('"audio": "ExpressionAudio"');
+
+  expect(changelogContents).toContain('v0.5.1 (2026-03-09)');
+});
+
+test('docs document config surfaces that are easy to miss when they ship', () => {
+  // Anki maturity-based known-word highlighting (#172) landed in
+  // subtitle-annotations.md but was missing from the config reference.
+  expect(configurationContents).toContain('ankiConnect.knownWords.maturityEnabled');
+  expect(configurationContents).toContain('ankiConnect.knownWords.matureThresholdDays');
+
+  // Every top-level config block should be reachable from the config reference.
+  expect(configurationContents).toContain('### TsukiHime');
+  expect(configurationContents).toContain('tsukihime.maxSearchResults');
+
+  // xz is a hard runtime dependency of the TsukiHime download path.
+  expect(installationContents).toContain('xz');
+});
+
+test('docs state the real secondary-subtitle and Anki field-matching behavior', () => {
+  // secondarySub auto-load is off by default; the config example previously
+  // implied otherwise while youtube-integration.md documented it correctly.
+  expect(configurationContents).toContain('Secondary subtitles do **not** auto-load by default');
+  expect(configurationContents).toContain('default: `false`');
+
+  // Anki field names are matched case-insensitively (src/anki-integration.ts
+  // resolveFieldName: exact match first, then a lowercase comparison).
+  expect(usageContents).not.toContain('exactly (case-sensitive)');
+  expect(troubleshootingContents).not.toContain('exactly (case-sensitive)');
+  expect(ankiIntegrationContents).toContain('case-insensitively');
+});
+
+test('docs dev server links version navigation to local dev routes', () => {
+  expect(docsPackageContents).toContain('scripts/build-versioned-docs.ts');
+  expect(docsPackageContents).toContain(
+    'SUBMINER_DOCS_VERSION_LINK_ORIGIN=local bun run ../scripts/build-versioned-docs.ts',
+  );
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_LINK_ORIGIN=local');
+  expect(docsPackageContents).toContain('SUBMINER_DOCS_VERSION_MANIFEST');
+});
+
+test('docs changelog keeps the current minor release headings aligned with the root changelog', () => {
+  const docsHeadings = extractCurrentMinorHeadings(changelogContents);
+  expect(docsHeadings.length).toBeGreaterThan(0);
+  expect(docsHeadings).toEqual(extractReleaseHeadings(rootChangelogContents, docsHeadings.length));
+});

docs-site/immersion-tracking.md

@@ -0,0 +1,402 @@
+# Immersion tracking
+
+SubMiner logs your watching and mining activity to a local SQLite database and shows it in the built-in stats dashboard. Tracking is on by default; turn it off if you would rather not keep the data.
+
+"Immersion" here means time spent watching and reading native Japanese content. **All of it stays on your machine.** Nothing is uploaded anywhere. SQLite is a single file on disk, so there is no database server to install or run.
+
+Each session records watch time, subtitle lines seen, words encountered, and cards mined. SubMiner also keeps exact lifetime summary tables and daily and monthly rollups. Read it through the stats UI, or point any SQLite tool at the file.
+
+::: tip For most users
+Leave tracking on and use the [Stats Dashboard](#stats-dashboard). The retention, performance, SQL, and schema sections below are reference material for querying or tuning the database yourself. Skip them.
+:::
+
+Episode completion for local `watched` state uses the shared `DEFAULT_MIN_WATCH_RATIO` (`85%`) value from `src/shared/watch-threshold.ts`.
+
+## Enabling
+
+```jsonc
+{
+  "immersionTracking": {
+    "enabled": true,
+    "dbPath": "",
+  },
+}
+```
+
+- 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 instead of letting one side overwrite the other.
+
+## Stats dashboard
+
+The same immersion data powers the stats dashboard.
+
+The browser dashboard and in-app stats overlay both load from the local HTTP server.
+The server accepts loopback hosts only and rejects requests from other browser origins,
+including opaque origins such as `file://`. API clients without a browser origin can
+still use the local API. Mutation requests with a body must use `application/json`;
+bodyless deletion and Anki browse requests remain supported. Requests rejected by the
+host or origin checks receive `403`; mutation bodies without a JSON content type
+receive `415`.
+
+Use the loopback dashboard URL directly. Reverse-proxied dashboards and Tailscale
+Serve URLs are unsupported because their host or browser origin is not the local
+server's origin. SSH stats synchronization is unchanged.
+
+Scripts sending a JSON body must include the content type. For example, this
+requests a duplicate-line cleanup preview without changing the database. Replace
+the port if you configured a different `stats.serverPort`:
+
+```bash
+curl http://127.0.0.1:6969/api/stats/maintenance/duplicate-lines \
+  -H 'Content-Type: application/json' \
+  -d '{"dryRun":true}'
+```
+
+- 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 (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 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 non-destructively (recomputed from per-episode history, so lifetime totals older than the session retention window are kept); `subminer stats cleanup --duplicate-lines` collapses repeated lines left behind by typeset subtitles (see [Repeated Line Cleanup](#repeated-line-cleanup)). `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.
+
+SubMiner waits for the local server to bind before reporting that the dashboard is available. If another process already uses the configured port, the command reports the startup error and the desktop app stays open. Opening the in-app dashboard also reports startup failures through your configured status notifications.
+
+`subminer stats -s` stops a background stats server or cancels a pending background start. It leaves a foreground-only server running, so an open in-app dashboard stays connected. Shutdown gives active HTTP requests one second to finish before closing their connections and finalizing stats.
+
+### Stats API resource IDs
+
+Resource IDs in URLs must be positive safe integers written as decimal digits without leading zeros, fractions, or exponent notation. ID lists in JSON bodies must contain positive safe integer numbers. Invalid IDs or list entries return `400` before any mutation; bulk requests do not apply just the valid subset. Pagination limits keep their existing rounding and bounds.
+
+### Dashboard tabs
+
+#### Overview
+
+Recent sessions, streak calendar, watch-time history, and a tracking snapshot with completed episodes/anime totals.
+
+![Stats Overview](/screenshots/stats-overview.png)
+
+#### Library
+
+Cover-art library with search and sorting, per-series progress, episode drill-down, and direct links into mined cards.
+
+Local files and Jellyfin items with detected season numbers are split into season-specific library entries, so `Season 1` and `Season 2` folders do not merge into one show card.
+
+When older stats already grouped multiple seasons under one series entry, SubMiner moves parsed episodes into the season-specific entries on startup and rebuilds the affected summaries.
+
+**Live-action dramas and movies.** Anime covers come from AniList, which has no live-action titles. A title that AniList cannot match is looked up on [TMDB](/configuration#tmdb) instead (release builds bundle a key; source builds need your own): only a Japanese-language, non-animated result whose known titles match the parsed filename exactly is accepted, and it supplies the poster, synopsis, English and Japanese titles, and episode count. If nothing matches automatically, open the title and use **Link to TMDB** to search and pick it by hand. A TMDB show spans all of its seasons, so entries that resolve to the same TMDB title are merged into one card regardless of the season folder they came from, and the merged season titles are remembered so later episodes land on the same card. The **All Titles** / **Anime** / **Live Action** / **YouTube** selector above the grid narrows the Library to one kind, and a title's detail view shows whether it is a drama or a movie. Linking a title to AniList again turns it back into an anime entry. Changing providers downloads the replacement cover before saving the new link; a failed download leaves the previous link and artwork intact. A title without a cover clears the previous artwork. Automatic TMDB matching leaves existing AniList links unchanged.
+
+Jellyfin stream URLs are normalized to stable item links before stats titles are shown, so playback query parameters are not displayed in the dashboard.
+
+When YouTube channel metadata is available, the Library tab groups videos by creator/channel. Use the kind selector above the grid (**All Titles**, **Anime**, **Live Action**, **YouTube**) to filter the library. Channel pages show tracked videos and their stats without AniList controls. Existing channel entries are classified as YouTube automatically on startup, preserving viewing history and manual video assignments. Anime and YouTube entries with the same normalized title remain separate, including during stats sync. Channels are excluded from anime metadata matching, season repair, and duplicate recommendations.
+
+A library entry is identified by its parsed title plus any detected season, so the same show can end up on several cards when releases disagree about the title or omit the season tag. Two fixes are available:
+
+- **Merge duplicates.** Hit **Select** above the grid, tick the cards that are the same show, and choose **Merge Selected**. Pick which entry to keep in the dialog; every episode moves onto it and the other cards are removed. Nothing is deleted, so sessions, mined cards and watch time all carry over. AniList-linked and TMDB-linked entries cannot be merged together, and YouTube channels cannot be merged with anime or live-action entries. SubMiner remembers the merged title variants, so future episodes parsed with one of those names join the kept entry instead of recreating a duplicate card.
+- **Move a single episode.** Hover an episode row in a title's episode list and use the **→** button to reassign it to another library entry. Anime and live-action entries are interchangeable here, but a YouTube video can only move between channels. The correction is remembered, so later filename parsing or Jellyfin metadata cannot move that episode back. For local files, later episodes in the same directory inherit the correction when their detected seasons are compatible and every manual correction there points to the same entry; a file that parses to a title which already has its own library entry keeps that identity instead. Conflicting seasons or manual destinations are left for review. If the move empties the old entry, that card is removed and you are returned to the grid.
+
+Once cover art resolves a series to an AniList entry, cards with compatible seasons are folded together automatically only when the searched title exactly matches an AniList title or synonym. A fuzzy result that points at an AniList entry already used by another card appears as a **Possible duplicate** review above the Library grid instead. Choose **Review merge** to compare the cards and pick which one to keep, or **Not duplicates** to dismiss that suggestion permanently. Entries with conflicting explicit season numbers are left alone rather than merged or suggested.
+
+Open a title and use **Delete Entry** in its header to remove a mistakenly tracked show outright. This deletes every episode of that title along with their sessions, subtitle lines, rollups and cover art, drops the words and kanji that were only seen there, and removes the card from the Library grid. Individual episodes and sessions can still be deleted on their own from the episode list and session rows. Entry deletion is refused while that title is the one currently playing.
+
+![Stats Library](/screenshots/stats-library.png)
+
+#### Trends
+
+Grouped into Activity (per-day/month watch time, cards, words, sessions), Cumulative Totals (running totals incl. new words seen and episodes), Efficiency (words/min, cards/hour, lookups per 100 words), Patterns (watch time by day of week and hour), and per-anime Library charts. Every chart takes a configurable date range and grouping.
+
+![Stats Trends](/screenshots/stats-trends.png)
+
+#### Sessions
+
+Expandable session history with new-word activity, cumulative totals, and pause/seek/card markers. Each session row exposes a hover-revealed ↗ button that navigates to the anime media-detail view for that session; pressing the back button there returns to the Sessions tab.
+
+![Stats Sessions](/screenshots/stats-sessions.png)
+
+#### Vocabulary
+
+The summary cards show all unique vocabulary and kanji recorded in the local tracking database; **New This Week** is the only weekly figure and uses a rolling seven-day window. The word and kanji tables load first while those complete totals calculate separately. Top Repeated Words and New Words by Day use complete tracking history rather than the table's browsing page. New-word history is maintained as a permanent daily lexical rollup using the same token-visibility rules as the totals, including normalization of older timestamps stored in either seconds or milliseconds and retroactive corrections when tracked material is removed or reprocessed. On the first launch after an applicable upgrade, that history is version-rebuilt in the background and the chart refreshes when it is ready; if it remains unavailable, polling stops and an inline Retry control appears. The cards and charts also refresh automatically after the word exclusion list changes. The rest of the tab includes cross-title and frequency rank tables with Hide Known / Hide Kana filters, kanji breakdown, word exclusion list, and click-through occurrence drilldown with Mine Word / Mine Sentence / Mine Audio buttons.
+
+![Stats Vocabulary](/screenshots/stats-vocabulary.png)
+
+#### Search
+
+Realtime search across tracked primary subtitle lines and media titles. Results show the source media, session, line number, timing, and sentence text. Secondary subtitle text is not shown or searched here because separate subtitle tracks may not line up sentence-for-sentence. Sentence cards can be mined from any result with a valid local source and timing. Word and audio card buttons appear only when the searched word exactly appears in the primary sentence text; matching text is highlighted in the result.
+
+Stats server config lives under `stats`:
+
+```jsonc
+{
+  "stats": {
+    "toggleKey": "Backquote",
+    "markWatchedKey": "KeyW",
+    "serverPort": 6969,
+    "autoStartServer": true,
+    "autoOpenBrowser": false,
+  },
+}
+```
+
+- `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` decides whether `subminer stats` opens the dashboard URL in your browser once the server is up.
+- `subminer stats` forces the dashboard server to start even when `autoStartServer` is `false`.
+- `subminer stats -b` starts or reuses the dedicated background stats daemon and exits after startup acknowledgement.
+- The background stats daemon is separate from the normal SubMiner overlay app, so you can leave it running and still launch SubMiner later to watch or mine from video.
+- `subminer stats -s` stops the dedicated background stats daemon without closing any browser tabs.
+- `subminer stats` fails with an error when `immersionTracking.enabled` is `false`.
+- `subminer stats cleanup` defaults to vocabulary cleanup, repairs stale `headword`, `reading`, and `part_of_speech` values, attempts best-effort MeCab backfill for legacy rows, and removes rows that still fail vocab filtering.
+
+## Mining cards from the stats page
+
+The Search tab and the Vocabulary tab's word detail panel both mine from subtitle lines in your viewing history. Search matches sentence text and media titles, and **Search by headword** is enabled by default so dictionary-form searches such as `知らない` can find tracked subtitle lines with inflected variants. Turn that toggle off for exact text/title matching only. Each line with a valid source file offers sentence-card mining; word/audio mining is available when the selected word or searched word appears in the sentence:
+
+- **Mine Word** - performs a full Yomitan dictionary lookup for the word (definition, reading, pitch accent, etc.) via a short-lived hidden helper, then enriches the card with sentence audio, a screenshot or animated AVIF clip, the highlighted sentence, full-sentence readings in `SentenceFurigana` when that field exists, and metadata extracted from the source video file. Requires Anki and Yomitan dictionaries to be loaded.
+- **Mine Sentence** - creates a sentence card directly with the `IsSentenceCard` flag set (for Lapis/Kiku workflows), along with audio and image from the source video.
+- **Mine Audio** - creates an audio-only card with the `IsAudioCard` flag, attaching only the sentence audio clip.
+
+All three modes respect your `ankiConnect` config: deck, model, field mappings, media settings (static vs AVIF, quality, dimensions), audio padding, metadata pattern, and tags. Media generation runs in parallel for faster card creation.
+
+Secondary subtitle text is stored alongside primary subtitles during playback, but the Search tab does not use it for display or matching.
+
+### Word exclusion list
+
+The Vocabulary tab toolbar includes an **Exclusions** button for hiding words from all vocabulary views. Excluded words are stored in the immersion database, with older browser localStorage exclusions imported on first load after upgrade. They can be managed (restored or cleared) from the exclusion modal. Exclusions affect stat cards, charts, the frequency rank table, and the word list.
+
+### Repeated line cleanup
+
+Karaoke openings and animated signs are authored as one subtitle event per animation frame, all carrying the same text. Playback reports every one of those frames, so a single OP lyric could be recorded hundreds of times and dominate "Top Repeated Words".
+
+Recording now collapses those runs as they happen, matching what the subtitle sidebar shows:
+
+- When a typeset ASS file stores a clean lyric or sign in a timed authoring comment, or in full-line events surrounding generated fragments, the matching complete line is recorded once. The repeated glyph or clip-animation frames are not recorded. Dialogue spoken while such an animation is on screen records as itself, without the fragment lines beside it.
+- When karaoke styling redraws the same complete lyric across consecutive color or highlight phases, those phases are combined into one line with their full timing. Repeated ordinary dialogue remains separate.
+- When the active subtitle source has been parsed, its cue list has already had duplicate events and animation bursts merged. A line landing inside a surviving cue but after that cue's start is a frame the sidebar merged away, and is not recorded.
+- When no parsed cue covers the live timing, including while a subtitle source is changing or shifted, the strict metadata-free rule applies: a run of identical, contiguous lines each shorter than 0.1s stops being recorded after a few frames. Runs are tracked per line of text, so dual-line karaoke (a kanji and a romaji line frame-flipped together) collapses both lines. Ordinary repeated dialogue, and lines held for a normal beat, always record.
+
+For stats recorded before this, the Vocabulary tab toolbar has a **Duplicates** button:
+
+- Pick how far back to look (7 days, 30 days, 90 days, 1 year, or all time). A narrower window does less work and keeps older history untouched.
+- **Scan** reports the bursts found, the lines they added, and the word and kanji counts they inflated, without writing anything.
+- **Clean Up** applies exactly what the scan reported: each run collapses to its first line (extended to cover the run), and the removed lines' word and kanji occurrences are subtracted from the vocabulary aggregates.
+
+The same thing runs from the terminal:
+
+```bash
+subminer stats cleanup --duplicate-lines --dry-run --lookback-days 30
+subminer stats cleanup --duplicate-lines --lookback-days 30
+```
+
+`--duplicate-lines` (short: `-d`) picks the cleanup mode, so it cannot be combined with `--vocab` or `--lifetime`, and `--dry-run` and `--lookback-days <days>` only apply to it. Omitting `--lookback-days` scans all history; the value must be at least one day.
+
+The cleanup chains runs per line of text, so interleaved dual-line karaoke collapses each of its lines. It also removes the short residue the live rule stores before a run is long enough to recognize: a run one frame short of the usual minimum qualifies when every event is under the strict 0.1s bound.
+
+Runs never cross a session boundary, so rewatching an episode keeps both watches. Session telemetry (watch time, lines seen, tokens seen) and the rollups derived from it are left as recorded: they are cumulative samples taken during playback, and cannot be recomputed for sessions whose raw rows have since been pruned.
+
+## Retention defaults
+
+By default, SubMiner keeps all retention tables and raw data (`0` means keep all) while continuing daily/monthly rollup maintenance:
+
+| Data type       | Retention    |
+| --------------- | ------------ |
+| Raw events      | 0 (keep all) |
+| Telemetry       | 0 (keep all) |
+| Sessions        | 0 (keep all) |
+| Daily rollups   | 0 (keep all) |
+| Monthly rollups | 0 (keep all) |
+
+Maintenance runs on startup and every 24 hours. Vacuum runs only when `retention.vacuumIntervalDays` is non-zero.
+
+In practice:
+
+- Overview totals read from lifetime summary tables, so all-time watch time/cards/words stay exact even if raw query paths evolve.
+- Anime and episode pages keep lifetime totals from summary tables while session drill-down still reads retained sessions directly. With the current defaults, both are kept forever.
+- Trends can read the full available history because daily/monthly rollups are also kept forever by default.
+- Vocabulary and kanji totals are cumulative and not bounded by the raw session retention knobs.
+- New-word charts use their own permanent lexical daily rollups, which are not pruned by activity-rollup retention.
+
+## Storage / performance model
+
+The defaults keep everything, and the schema is shaped around that:
+
+- Exact all-time totals live in dedicated lifetime summary tables (`imm_lifetime_global`, `imm_lifetime_anime`, `imm_lifetime_media`).
+- Ended-session totals are persisted onto `imm_sessions`, so most dashboard reads do not need to rescan raw telemetry.
+- Daily and monthly rollups remain available for chart queries and coarse trend views.
+- Subtitle text is stored once in `imm_subtitle_lines`; subtitle-line event payloads keep compact metadata only.
+- Cover-art binaries are deduplicated through a shared blob store so episodes in the same series do not each carry duplicate image bytes.
+- Hot tables have dedicated indexes for session time ranges, telemetry sample windows, frequency-ranked vocabulary, and cover-art lookup keys.
+
+## Configurable knobs
+
+All policy options live under `immersionTracking` in your config:
+
+| Option                         | Description                                                        |
+| ------------------------------ | ------------------------------------------------------------------ |
+| `batchSize`                    | Writes per flush batch                                             |
+| `flushIntervalMs`              | Max delay between flushes (default: 500ms)                         |
+| `queueCap`                     | Max queued writes before oldest are dropped                        |
+| `payloadCapBytes`              | Max payload size per write                                         |
+| `maintenanceIntervalMs`        | How often maintenance runs                                         |
+| `retention.eventsDays`         | Raw event retention                                                |
+| `retention.telemetryDays`      | Telemetry retention                                                |
+| `retention.sessionsDays`       | Session retention                                                  |
+| `retention.dailyRollupsDays`   | Daily rollup retention                                             |
+| `retention.monthlyRollupsDays` | Monthly rollup retention                                           |
+| `retention.vacuumIntervalDays` | Minimum spacing between vacuums                                    |
+| `retentionMode`                | `preset` or `advanced`                                             |
+| `retentionPreset`              | `minimal`, `balanced`, or `deep-history` (used by `retentionMode`) |
+| `lifetimeSummaries.global`     | Maintain global lifetime totals                                    |
+| `lifetimeSummaries.anime`      | Maintain per-anime lifetime totals                                 |
+| `lifetimeSummaries.media`      | Maintain per-media lifetime totals                                 |
+
+## Query templates
+
+### Session timeline
+
+```sql
+SELECT
+  sample_ms,
+  total_watched_ms,
+  active_watched_ms,
+  lines_seen,
+  tokens_seen,
+  cards_mined
+FROM imm_session_telemetry
+WHERE session_id = ?
+ORDER BY sample_ms DESC, telemetry_id DESC
+LIMIT ?;
+```
+
+### Session throughput summary
+
+```sql
+SELECT
+  s.session_id,
+  s.video_id,
+  s.started_at_ms,
+  s.ended_at_ms,
+  COALESCE(s.active_watched_ms, 0) AS active_watched_ms,
+  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.tokens_seen, 0) / (COALESCE(s.active_watched_ms, 0) / 60000.0)
+    ELSE NULL
+  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)
+    ELSE NULL
+  END AS cards_per_hour
+FROM imm_sessions s
+ORDER BY s.started_at_ms DESC
+LIMIT ?;
+```
+
+### Lifetime anime totals
+
+```sql
+SELECT
+  a.anime_id,
+  a.canonical_title,
+  la.total_sessions,
+  la.total_active_ms,
+  la.total_cards,
+  la.total_tokens_seen,
+  la.total_lines_seen,
+  la.first_watched_ms,
+  la.last_watched_ms
+FROM imm_lifetime_anime la
+JOIN imm_anime a ON a.anime_id = la.anime_id
+ORDER BY la.last_watched_ms DESC
+LIMIT ?;
+```
+
+### Daily rollups
+
+```sql
+SELECT
+  rollup_day,
+  video_id,
+  total_sessions,
+  total_active_min,
+  total_lines_seen,
+  total_tokens_seen,
+  total_cards,
+  cards_per_hour,
+  tokens_per_min,
+  lookup_hit_rate
+FROM imm_daily_rollups
+ORDER BY rollup_day DESC, video_id DESC
+LIMIT ?;
+```
+
+### Monthly rollups
+
+```sql
+SELECT
+  rollup_month,
+  video_id,
+  total_sessions,
+  total_active_min,
+  total_lines_seen,
+  total_tokens_seen,
+  total_cards
+FROM imm_monthly_rollups
+ORDER BY rollup_month DESC, video_id DESC
+LIMIT ?;
+```
+
+## Technical details
+
+- Write path is asynchronous and queue-backed. Hot paths (subtitle parsing, render, token flows) enqueue telemetry and never await SQLite writes.
+- Queue overflow policy: drop oldest queued writes, keep newest.
+- SQLite tunings: `journal_mode=WAL`, `synchronous=NORMAL`, `foreign_keys=ON`, `busy_timeout=2500`, bounded WAL growth via `journal_size_limit`.
+- Maintenance executes `PRAGMA optimize` after periodic cleanup.
+- Rollups run incrementally from the last processed telemetry sample; startup performs a one-time bootstrap pass.
+- Cover-art blobs are deduplicated into `imm_cover_art_blobs` and referenced from `imm_media_art`.
+- 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 (v24)
+
+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` - series or YouTube channel metadata referenced by videos and lifetime tables, including the media kind (`anime`, `live_action` or `youtube`) and the AniList or TMDB link
+- `imm_anime_title_aliases` - alternate titles that resolve to the same anime row
+- `imm_anime_merge_recommendations` - candidate duplicate-series merges surfaced in the dashboard
+- `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:
+
+- `imm_lifetime_global`
+- `imm_lifetime_anime`
+- `imm_lifetime_media`
+- `imm_lifetime_applied_sessions`
+
+Rollup tables:
+
+- `imm_daily_rollups`
+- `imm_monthly_rollups`
+- `imm_lexical_daily_rollups` - permanent first-discovery counts for vocabulary and kanji chart history
+- `imm_rollup_state` - incremental rollup progress bookkeeping
+
+Vocabulary tables:
+
+- `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:
+
+- `imm_media_art` - per-video cover metadata plus shared blob reference
+- `imm_cover_art_blobs` - deduplicated image bytes keyed by blob hash

docs-site/index.assets.test.ts

@@ -7,18 +7,18 @@ const docsIndexContents = readFileSync(docsIndexPath, 'utf8');
 test('docs demo media uses shared cache-busting asset version token', () => {
   expect(docsIndexContents).toMatch(/const demoAssetVersion = ['"][^'"]+['"]/);
   expect(docsIndexContents).toContain(
-    ':poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`"',
+    ':poster="withBase(`/assets/minecard-poster.jpg?v=${demoAssetVersion}`)"',
   );
   expect(docsIndexContents).toContain(
-    '<source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />',
+    '<source :src="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" type="video/webm" />',
   );
   expect(docsIndexContents).toContain(
-    '<source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />',
+    '<source :src="withBase(`/assets/minecard.mp4?v=${demoAssetVersion}`)" type="video/mp4" />',
   );
   expect(docsIndexContents).toContain(
-    '<a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">',
+    '<a :href="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" target="_blank" rel="noreferrer">',
   );
   expect(docsIndexContents).toContain(
-    '<img :src="`/assets/minecard.webp?v=${demoAssetVersion}`" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />',
+    '<img :src="withBase(`/assets/minecard.webp?v=${demoAssetVersion}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />',
   );
 });

docs-site/index.md

@@ -0,0 +1,365 @@
+---
+layout: home
+
+title: SubMiner
+titleTemplate: Immersion Mining Workflow for MPV
+
+hero:
+  name: SubMiner
+  text: Immersion Mining for MPV
+  tagline: Watch, look up a word, and get an Anki card with audio and a screenshot. Without pausing your show.
+  image:
+    src: /assets/SubMiner.png
+    alt: SubMiner logo
+  actions:
+    - theme: brand
+      text: Install
+      link: /installation
+    - theme: alt
+      text: Explore workflow
+      link: /mining-workflow
+
+features:
+  - icon:
+      src: /assets/mpv.svg
+      alt: mpv icon
+    title: Built for mpv
+    details: Reads subtitle state over mpv's IPC socket. Launch with the wrapper script or the mpv plugin. There is no separate bridge process to run.
+    link: /usage
+    linkText: How it works
+  - icon:
+      src: /assets/yomitan-icon.svg
+      alt: Yomitan logo
+    title: Bundled Yomitan
+    details: A Yomitan instance is bundled and preconfigured. Hover a word in the subtitle overlay to look it up and mine it.
+    link: /mining-workflow
+    linkText: Mining workflow
+  - icon:
+      src: /assets/anki-card.svg
+      alt: Anki card icon
+    title: Anki card enrichment
+    details: New cards get the subtitle line, an audio clip cut to the line timing, and a screenshot from that moment.
+    link: /anki-integration
+    linkText: Anki integration
+  - icon:
+      src: /assets/highlight.svg
+      alt: Highlight icon
+    title: Reading annotations
+    details: N+1 targeting, character-name matching, frequency highlighting, and JLPT tagging, drawn onto the subtitle line as it plays.
+    link: /subtitle-annotations
+    linkText: Annotation details
+  - icon:
+      src: /assets/video.svg
+      alt: Video playback icon
+    title: YouTube playback
+    details: Pass a YouTube URL or a ytsearch target. SubMiner picks a subtitle track for the video and loads it.
+    link: /usage#youtube-playback
+    linkText: YouTube playback
+  - icon:
+      src: /assets/jellyfin.svg
+      alt: Jellyfin icon
+    title: Jellyfin integration
+    details: Browse your Jellyfin library from the overlay and play a title through mpv. Subtitles and mining work the same as with local files.
+    link: /jellyfin-integration
+    linkText: Jellyfin setup
+  - icon:
+      src: /assets/subtitle-download.svg
+      alt: Subtitle download icon
+    title: Subtitle download and sync
+    details: Search Jimaku or TsukiHime and download a track, then retime it with alass or ffsubsync. Both run from the overlay.
+    link: /jimaku-integration
+    linkText: Jimaku integration
+  - icon:
+      src: /assets/tokenization.svg
+      alt: Tracking chart icon
+    title: Stats dashboard
+    details: A local dashboard with session history, streak calendars, word frequency, and per-series progress. You can mine cards from lines you already watched.
+    link: /immersion-tracking
+    linkText: Dashboard & tracking
+  - icon:
+      src: /assets/cross-platform.svg
+      alt: Cross-platform icon
+    title: Cross-platform
+    details: Runs on Linux (Hyprland, Sway, X11), macOS, and Windows. Overlay positioning is handled per compositor rather than assuming one window manager.
+    link: /installation
+    linkText: Platform setup
+---
+
+<script setup>
+import { withBase } from 'vitepress';
+
+const demoAssetVersion = '20260819-1';
+</script>
+
+<div class="landing-shell">
+  <section class="workflow-section">
+    <h2>How it fits together</h2>
+    <div class="workflow-steps">
+      <div class="workflow-step" style="animation-delay: 0ms">
+        <div class="step-number">01</div>
+        <div class="step-title">Start</div>
+        <div class="step-desc">Launch through the wrapper, or from an mpv setup you already have.</div>
+      </div>
+      <div class="workflow-connector" aria-hidden="true"></div>
+      <div class="workflow-step" style="animation-delay: 60ms">
+        <div class="step-number">02</div>
+        <div class="step-title">Lookup</div>
+        <div class="step-desc">Hover a token in the overlay to open the Yomitan popup for that word.</div>
+      </div>
+      <div class="workflow-connector" aria-hidden="true"></div>
+      <div class="workflow-step" style="animation-delay: 120ms">
+        <div class="step-number">03</div>
+        <div class="step-title">Mine</div>
+        <div class="step-desc">Add the word from Yomitan, or mine the whole line as a sentence card.</div>
+      </div>
+      <div class="workflow-connector" aria-hidden="true"></div>
+      <div class="workflow-step" style="animation-delay: 180ms">
+        <div class="step-number">04</div>
+        <div class="step-title">Enrich</div>
+        <div class="step-desc">SubMiner fills in the audio clip, the sentence, and a screenshot from that moment.</div>
+      </div>
+      <div class="workflow-connector" aria-hidden="true"></div>
+      <div class="workflow-step" style="animation-delay: 240ms">
+        <div class="step-number">05</div>
+        <div class="step-title">Track</div>
+        <div class="step-desc">Review past sessions and word trends, and mine anything you missed the first time.</div>
+      </div>
+    </div>
+  </section>
+
+  <section class="demo-section">
+    <h2>See it in action</h2>
+    <p>Recorded from an actual playback session: subtitle hover, lookup, and the card that comes out the other end.</p>
+    <div class="demo-window">
+      <div class="demo-window__bar">
+        <span class="demo-window__dot"></span>
+        <span class="demo-window__dot"></span>
+        <span class="demo-window__dot"></span>
+        <span class="demo-window__title">subminer -- playback</span>
+      </div>
+      <video controls playsinline preload="metadata" :poster="withBase(`/assets/minecard-poster.jpg?v=${demoAssetVersion}`)">
+        <source :src="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" type="video/webm" />
+        <source :src="withBase(`/assets/minecard.mp4?v=${demoAssetVersion}`)" type="video/mp4" />
+        <a :href="withBase(`/assets/minecard.webm?v=${demoAssetVersion}`)" target="_blank" rel="noreferrer">
+          <img :src="withBase(`/assets/minecard.webp?v=${demoAssetVersion}`)" alt="SubMiner demo Animated fallback" style="width: 100%; height: auto;" />
+        </a>
+      </video>
+    </div>
+  </section>
+</div>
+
+<style>
+.landing-shell {
+  max-width: 1120px;
+  margin: 0 auto;
+  padding: 0.5rem 1rem 4rem;
+}
+
+.landing-shell,
+.landing-shell .step-title,
+.landing-shell h1,
+.landing-shell h2 {
+  font-family: var(--tui-font-mono);
+}
+
+.VPHome :deep(.VPFeature),
+.VPHome :deep(.VPButton),
+.landing-shell .workflow-step,
+.landing-shell .demo-window,
+.landing-shell .demo-window__bar {
+  border-radius: 8px;
+}
+
+.step-title,
+.step-number {
+  font-family: var(--tui-font-mono);
+  letter-spacing: -0.01em;
+}
+
+/* === Workflow === */
+.workflow-section {
+  margin: 2.4rem auto 0;
+  padding: 0;
+}
+
+.workflow-section h2,
+.demo-section h2 {
+  font-size: 1.45rem;
+  font-weight: 600;
+  letter-spacing: -0.01em;
+  margin-bottom: 1rem;
+  padding-bottom: 4px;
+}
+
+.workflow-section h2::after,
+.demo-section h2::after {
+  content: '';
+  display: block;
+  margin-top: 6px;
+  height: 1px;
+  background: repeating-linear-gradient(
+    to right,
+    var(--vp-c-divider) 0,
+    var(--vp-c-divider) 1ch,
+    transparent 1ch,
+    transparent 1.5ch
+  );
+}
+
+.workflow-steps {
+  display: flex;
+  align-items: stretch;
+  gap: 0;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.workflow-step {
+  flex: 1;
+  padding: 1.2rem 1.25rem;
+  background: var(--vp-c-bg-soft);
+  animation: step-enter 400ms ease-out both;
+  position: relative;
+  transition: background 180ms ease;
+}
+
+.workflow-step:hover {
+  background: var(--tui-step-hover-bg);
+}
+
+.workflow-step:hover .step-number {
+  color: var(--vp-c-brand-1);
+  text-shadow: 0 0 12px var(--tui-step-hover-glow);
+}
+
+.workflow-connector {
+  width: 1px;
+  background: var(--vp-c-divider);
+  flex-shrink: 0;
+}
+
+.workflow-step .step-number {
+  display: inline-block;
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.05em;
+  color: var(--vp-c-text-3);
+  margin-bottom: 0.5rem;
+  font-variant-numeric: tabular-nums;
+  transition: color 180ms ease, text-shadow 180ms ease;
+}
+
+.workflow-step .step-number::before {
+  content: '$ ';
+  color: var(--vp-c-text-3);
+}
+
+.workflow-step .step-title {
+  font-weight: 600;
+  font-size: 1rem;
+  margin-bottom: 0.35rem;
+}
+
+.workflow-step .step-desc {
+  font-size: 0.85rem;
+  color: var(--vp-c-text-2);
+  line-height: 1.5;
+}
+
+@keyframes step-enter {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@media (max-width: 960px) {
+  .workflow-steps {
+    display: grid;
+    grid-template-columns: repeat(2, 1fr);
+    gap: 1px;
+    background: var(--vp-c-divider);
+  }
+  .workflow-step {
+    min-width: 0;
+  }
+  .workflow-step:last-child {
+    grid-column: 1 / -1;
+  }
+  .workflow-connector {
+    display: none;
+  }
+}
+
+@media (max-width: 640px) {
+  .workflow-steps {
+    grid-template-columns: 1fr;
+  }
+  .workflow-step:last-child {
+    grid-column: auto;
+  }
+}
+
+/* === Demo === */
+.demo-section {
+  max-width: 960px;
+  margin: 3rem auto 0;
+  padding: 0;
+}
+
+.demo-section p {
+  color: var(--vp-c-text-2);
+  margin: 0 0 1.2rem;
+  line-height: 1.6;
+}
+
+.demo-window {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  overflow: hidden;
+  animation: step-enter 400ms ease-out 300ms both;
+  box-shadow:
+    0 4px 16px rgba(0, 0, 0, 0.18),
+    0 20px 48px rgba(0, 0, 0, 0.14);
+}
+
+.demo-window__bar {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 12px;
+  background: var(--vp-c-bg-soft);
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+
+.demo-window__dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+}
+
+.demo-window__dot:nth-child(1) { background: #ed8796; }
+.demo-window__dot:nth-child(2) { background: #eed49f; }
+.demo-window__dot:nth-child(3) { background: #a6da95; }
+
+.demo-window__title {
+  font-family: var(--tui-font-mono);
+  font-size: 11px;
+  color: var(--vp-c-text-3);
+  margin-left: 6px;
+}
+
+.demo-window video {
+  width: 100%;
+  display: block;
+  border: none;
+  border-radius: 0;
+  box-shadow: none;
+  margin: 0;
+}
+</style>

docs-site/installation.md

@@ -0,0 +1,487 @@
+# Installation
+
+SubMiner draws an interactive overlay on top of the [mpv](https://mpv.io) video player. While you watch Japanese media, hover any word in the subtitles to look it up, then turn it into an Anki card without switching apps.
+
+Building cards from the content you are actually watching is called **sentence mining**, and it is the whole point of SubMiner. It bundles its own copy of **Yomitan** (a pop-up dictionary) and talks to **AnkiConnect** (the add-on that lets other programs write cards into Anki), so the sentence, audio, and screenshot fields get filled in for you.
+
+Three steps to get started:
+
+1. **Install requirements** - mpv and a few optional extras
+2. **Install SubMiner** - from the AUR, or download from GitHub Releases
+3. **Launch the app** - first-run setup walks you through dictionaries, the launcher, and everything else
+
+## 1. Install requirements
+
+Only **mpv** is strictly required. Everything else is optional, though you will want ffmpeg unless you are fine with cards that have no audio or screenshot.
+
+Some rows below matter only for the `subminer` command-line launcher's picker features. On Windows, the **SubMiner mpv** shortcut remains the recommended playback entry point.
+
+[Local Japanese subtitle generation](/subtitle-generation) additionally requires whisper.cpp's `whisper-cli`, FFmpeg, and `ffprobe`. Configure their executable paths in Settings if needed. SubMiner can download a speech model explicitly, or use your existing multilingual GGML model.
+
+Optional [dialogue-focused generation](/subtitle-generation#prioritizing-spoken-dialogue) also uses whisper.cpp's speech segment detector and a separate Silero GGML VAD model.
+
+| Dependency           | Status      | Platforms    | What it does                                                                                                                                                   |
+| -------------------- | ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| mpv                  | Required    | All          | The video player SubMiner overlays on. Must support `--input-ipc-server`.                                                                                      |
+| ffmpeg               | Recommended | All          | Audio extraction and screenshots for Anki cards. Without it SubMiner still runs, but media fields will be empty.                                               |
+| MeCab + mecab-ipadic | Recommended | All          | Part-of-speech filtering for more precise N+1, JLPT, and frequency annotations. Without it annotations still render, but POS-based filtering is less accurate. |
+| yt-dlp               | Optional    | All          | YouTube playback and subtitle extraction.                                                                                                                      |
+| xz                   | Optional    | All          | Required for TsukiHime subtitle downloads (subtitles are served xz-compressed). Preinstalled on most Linux distros; not present on Windows by default.         |
+| guessit              | Optional    | All          | Better AniSkip title/season/episode parsing.                                                                                                                   |
+| alass                | Optional    | All          | Subtitle sync engine (preferred). Disabled without alass or ffsubsync.                                                                                         |
+| ffsubsync            | Optional    | All          | Audio-based subtitle sync engine. Disabled without alass or ffsubsync.                                                                                         |
+| fzf                  | Optional    | Linux, macOS | Terminal-based video picker in the `subminer` launcher.                                                                                                        |
+| rofi                 | Optional    | Linux        | GUI-based video picker in the `subminer` launcher.                                                                                                             |
+| chafa                | Optional    | Linux, macOS | Thumbnail previews in the fzf picker.                                                                                                                          |
+| ffmpegthumbnailer    | Optional    | Linux, macOS | Video thumbnail generation for the pickers.                                                                                                                    |
+| fuse2                | Required    | Linux        | Needed to run the AppImage.                                                                                                                                    |
+
+### Linux
+
+**Window backend** - you need one of these depending on your compositor:
+
+- **Hyprland** - native Wayland support (uses `hyprctl`)
+- **Sway** - native Wayland support (uses `swaymsg`)
+- **X11 / Xwayland** - for X11 sessions or any other Wayland compositor (uses `xdotool` and `xwininfo`)
+
+::: warning Wayland support is compositor-specific
+Wayland has no universal API for window positioning. Each compositor exposes its own IPC, so SubMiner needs a backend per compositor. Only Hyprland and Sway have native Wayland backends. If you run a different Wayland compositor (GNOME, KDE Plasma, river, etc.), both mpv **and** SubMiner must run under X11 or Xwayland. The `subminer` launcher handles this automatically when `--backend x11` is set or the X11 backend is auto-detected.
+:::
+
+<details>
+<summary><b>Arch Linux</b></summary>
+
+```bash
+sudo pacman -S --needed mpv ffmpeg
+# Recommended
+sudo pacman -S --needed mecab mecab-ipadic
+# Optional
+sudo pacman -S --needed yt-dlp fzf rofi chafa ffmpegthumbnailer
+# Optional: subtitle sync (at least one needed for subtitle syncing)
+paru -S --needed alass python-ffsubsync
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+sudo pacman -S --needed xdotool xorg-xwininfo
+```
+
+</details>
+
+<details>
+<summary><b>Ubuntu / Debian</b></summary>
+
+```bash
+sudo apt install mpv ffmpeg
+# Recommended
+sudo apt install mecab libmecab-dev mecab-ipadic-utf8
+# Optional
+sudo apt install yt-dlp fzf rofi chafa ffmpegthumbnailer
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+sudo apt install xdotool x11-utils
+# Optional: subtitle sync
+pip install ffsubsync
+# alass is not in apt - install via cargo: cargo install alass-cli
+```
+
+</details>
+
+<details>
+<summary><b>Fedora</b></summary>
+
+```bash
+sudo dnf install mpv ffmpeg
+# Recommended
+sudo dnf install mecab mecab-ipadic
+# Optional
+sudo dnf install yt-dlp fzf rofi chafa ffmpegthumbnailer
+# X11 / Xwayland (required for non-Hyprland/Sway compositors)
+sudo dnf install xdotool xorg-x11-utils
+# Optional: subtitle sync
+pip install ffsubsync
+# alass: cargo install alass-cli
+```
+
+</details>
+
+### macOS
+
+macOS 11 (Big Sur) or later. Accessibility permission - the macOS setting that lets one app observe and position another app's windows - is required so the overlay can follow the mpv window (see [step 2](#macos-dmg)).
+
+```bash
+brew install mpv ffmpeg
+# Recommended
+brew install mecab mecab-ipadic
+# Optional
+brew install yt-dlp fzf chafa ffmpegthumbnailer
+# Optional: subtitle sync
+brew install alass
+pip install ffsubsync
+```
+
+### Windows
+
+Windows 10 or later. No compositor tools or window helpers are needed - native window tracking is built in.
+
+You need **mpv** (required) and **ffmpeg** (strongly recommended, for card audio and screenshots). Put mpv on `PATH` or set `mpv.executablePath` during setup. ffmpeg must be on `PATH`.
+
+::: tip What is PATH?
+`PATH` is the list of folders Windows searches when a program asks to run another program by name. SubMiner uses it to find ffmpeg and, unless an executable path is configured, mpv. The routes below mostly handle `PATH` for you; the manual route explains how to add a folder yourself.
+:::
+
+You can install these with a package manager or by hand. Coverage differs, so pick based on what you need:
+
+| Dependency       | winget          | Scoop         |
+| ---------------- | --------------- | ------------- |
+| mpv (required)   | `shinchiro.mpv` | `extras/mpv`  |
+| ffmpeg           | `Gyan.FFmpeg`   | `main/ffmpeg` |
+| yt-dlp (YouTube) | `yt-dlp.yt-dlp` | `main/yt-dlp` |
+| xz (TsukiHime)   | not packaged    | `main/xz`     |
+
+Use **winget** if you want Microsoft's first-party tool and don't need TsukiHime subtitle downloads. Use **Scoop** if you want one package manager to cover everything, since it is the only one that also packages `xz`.
+
+#### Recommended: winget
+
+[winget](https://learn.microsoft.com/windows/package-manager/winget/) is Microsoft's own package manager and ships with Windows 11 and current Windows 10 (it comes with **App Installer** from the Microsoft Store). In **PowerShell** or **Command Prompt**:
+
+```powershell
+winget install shinchiro.mpv
+winget install Gyan.FFmpeg
+```
+
+Close and reopen your terminal, then check that both are found:
+
+```powershell
+mpv --version
+ffmpeg -version
+```
+
+`ffmpeg` is installed as a portable package, so winget links it into a folder that is already on your `PATH` and it should work right away.
+
+`mpv` uses a regular installer, and depending on the version it may **not** add itself to `PATH`. If `mpv --version` says `not recognized`, you have two easy options:
+
+- Note where it installed (usually `%LOCALAPPDATA%\Programs\mpv`) and add that folder to `PATH` using the manual steps below, or
+- Skip `PATH` entirely and set `mpv.executablePath` to the full path of `mpv.exe` during first-run setup.
+
+Once `mpv --version` works, or you have the full path to `mpv.exe` ready, continue to [step 2](#_2-install-subminer).
+
+<details>
+<summary><b>Alternative: Scoop (covers every dependency, no admin rights)</b></summary>
+
+[Scoop](https://scoop.sh) installs into your user profile, needs no administrator prompt, and always puts commands on `PATH`. It is the only Windows package manager that carries all of SubMiner's optional dependencies, including `xz`, so it is the best choice if you want a single tool to manage everything.
+
+```powershell
+# One-time Scoop setup (skip if you already have it)
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
+
+# mpv lives in the "extras" bucket; everything else is in "main"
+scoop bucket add extras
+scoop install extras/mpv main/ffmpeg
+
+# Optional: yt-dlp for YouTube playback, xz for TsukiHime subtitle downloads
+scoop install main/yt-dlp main/xz
+```
+
+Close and reopen your terminal, then verify with `mpv --version` and `ffmpeg -version`.
+
+</details>
+
+<details>
+<summary><b>Manual install (download the zips yourself)</b></summary>
+
+1. Download mpv from [mpv.io/installation](https://mpv.io/installation/) (the Windows builds link) and ffmpeg from [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
+2. Unzip each one somewhere permanent, for example `C:\Tools\mpv` and `C:\Tools\ffmpeg`. Note the folder that actually contains `mpv.exe` and the one containing `ffmpeg.exe` (for ffmpeg this is usually a `bin` subfolder).
+3. Press `Win`, type **Edit the system environment variables**, and open it. Click **Environment Variables…**, select **Path** under **User variables**, click **Edit…**, then use **New** to add each of those two folders. Confirm with **OK** on every dialog. Microsoft documents this in more detail under [environment variables](https://learn.microsoft.com/windows/deployment/usmt/usmt-recognized-environment-variables).
+4. Close and reopen your terminal, since `PATH` changes only apply to newly opened windows. Then check:
+
+```powershell
+mpv --version
+ffmpeg -version
+```
+
+If you see `not recognized as the name of a cmdlet`, the folder you added is not the one holding the `.exe`. Reopen the Path editor and double-check.
+
+::: tip mpv can skip PATH, ffmpeg cannot
+If you would rather not edit `PATH` for mpv, set `mpv.executablePath` to the full path of `mpv.exe` during first-run setup instead.
+
+There is no equivalent setting for ffmpeg: SubMiner invokes it by bare name when generating card audio and screenshots, so ffmpeg has to be on `PATH`. Without it, cards are still created but their audio and image fields come out empty. (`subsync.ffmpeg_path` only affects subtitle sync, not card media.)
+:::
+
+</details>
+
+**Optional extras:** [MeCab for Windows](https://taku910.github.io/mecab/#download) with the UTF-8 dictionary improves annotation accuracy; it is not in any package manager, so install it from that page. `xz` is needed only for [TsukiHime](/tsukihime-integration) subtitle downloads and is not packaged by winget or Chocolatey, so use `scoop install main/xz` or download [XZ Utils](https://tukaani.org/xz/) and add its folder to `PATH`.
+
+The launcher's picker tools (`fzf`, `rofi`, `chafa`, `ffmpegthumbnailer`) are for Linux and macOS. On Windows, use the **SubMiner mpv** shortcut for playback or install the optional `subminer` terminal wrapper during setup.
+
+## 2. Install SubMiner
+
+### Arch Linux (AUR) {#arch-aur}
+
+Install [`subminer-bin`](https://aur.archlinux.org/packages/subminer-bin) from the AUR. The package includes the SubMiner AppImage and its launcher wrapper. Bun is included with the app, so the package has no Bun dependency. Install updates through your AUR helper or package manager.
+
+```bash
+paru -S subminer-bin
+```
+
+Or manually:
+
+```bash
+git clone https://aur.archlinux.org/subminer-bin.git
+cd subminer-bin
+makepkg -si
+```
+
+### Linux (AppImage) {#linux-appimage}
+
+Download the latest AppImage from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
+
+```bash
+mkdir -p ~/.local/bin
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/SubMiner.AppImage -O ~/.local/bin/SubMiner.AppImage
+chmod +x ~/.local/bin/SubMiner.AppImage
+```
+
+::: tip Launcher install is optional
+First-run setup can install the `subminer` command-line launcher for you. It uses Bun bundled with the AppImage, so it does not need a separate Bun installation or a Bun entry on `PATH`. The downloaded wrapper works the same way. See [manual launcher install](#manual-launcher-install-linux).
+:::
+
+### macOS (DMG) {#macos-dmg}
+
+Download the DMG from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest), open it, and drag `SubMiner.app` into `/Applications`. A ZIP artifact is also available as a fallback.
+
+**Gatekeeper:** If macOS blocks SubMiner on first launch, right-click the app and select **Open** to bypass the warning. Alternatively:
+
+```bash
+xattr -d com.apple.quarantine /Applications/SubMiner.app
+```
+
+**Accessibility permission:** Grant accessibility permission so the overlay can track the mpv window:
+
+1. Open **System Settings** → **Privacy & Security** → **Accessibility**
+2. Enable SubMiner in the list (add it if it does not appear)
+
+::: tip Launcher install is optional
+First-run setup can install the `subminer` command-line launcher for you. It uses Bun bundled inside `SubMiner.app`, so it does not need a separate Bun installation or a Bun entry on `PATH`. The downloaded wrapper works the same way. See [manual launcher install](#manual-launcher-install-macos).
+:::
+
+### Windows (installer) {#windows-installer}
+
+Download the latest installer from [GitHub Releases](https://github.com/ksyasuda/SubMiner/releases/latest):
+
+- `SubMiner-<version>.exe` - installer (recommended)
+- `SubMiner-<version>-win.zip` - portable fallback
+- `subminer.cmd` - optional terminal launcher wrapper
+
+Make sure `mpv.exe` is on your `PATH`, or set `mpv.executablePath` in the config during first-run setup.
+
+### From source
+
+<details>
+<summary><b>Linux</b></summary>
+
+```bash
+git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
+cd SubMiner
+make deps
+bun run build
+
+# Optional: build AppImage
+bun run build:appimage
+```
+
+Bundled Yomitan is built during `bun run build`.
+
+Source and development commands use Bun installed on your system.
+
+</details>
+
+<details>
+<summary><b>macOS</b></summary>
+
+```bash
+git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
+cd SubMiner
+make deps
+make build-macos
+```
+
+The built app will be in the `release` directory (`.dmg` and `.zip`). For unsigned local builds: `bun run build:mac:unsigned`.
+
+</details>
+
+<details>
+<summary><b>Windows</b></summary>
+
+```powershell
+git clone https://github.com/ksyasuda/SubMiner.git
+cd SubMiner
+git submodule update --init --recursive
+bun install
+Set-Location stats
+bun install --frozen-lockfile
+Set-Location ../vendor/texthooker-ui
+bun install --frozen-lockfile
+bun run build
+Set-Location ../..
+bun run build:win
+```
+
+</details>
+
+### Bundled Bun runtime {#bundled-bun-runtime}
+
+Every package includes an unmodified copy of Bun 1.3.5 that runs the command-line launcher. Bun is MIT licensed and statically links JavaScriptCore under LGPL 2.0 and TinyCC under LGPL 2.1. The license texts, third-party notices, and a `SOURCE.md` describing the corresponding source ship inside the app under `resources/bun/licenses` (`SubMiner.app/Contents/Resources/bun/licenses` on macOS). Each GitHub release also publishes `bun-v1.3.5-source.tar.gz` with the matching Bun, WebKit, and dependency sources and instructions for rebuilding Bun against a modified JavaScriptCore.
+
+## 3. Launch and first-run setup
+
+Launch SubMiner and the setup wizard opens on its own:
+
+```bash
+# Linux (AUR install)
+subminer app --setup
+
+# Linux (AppImage directly)
+~/.local/bin/SubMiner.AppImage --setup
+
+# macOS - launch SubMiner.app from /Applications, or:
+subminer app --setup
+```
+
+On **Windows**, just run `SubMiner.exe` - the setup wizard opens automatically on first launch.
+
+The setup wizard walks you through:
+
+- **Config file** - auto-created at `~/.config/SubMiner/config.jsonc` (Linux/macOS) or `%APPDATA%\SubMiner\config.jsonc` (Windows)
+- **Yomitan dictionaries** - import at least one dictionary so word lookups work
+- **`subminer` launcher** _(optional)_ - installs a wrapper into a writable terminal PATH directory. The wrapper uses Bun packaged with the app, with no separate runtime setup. If the included runtime is unavailable, the launcher controls show an error asking you to reinstall SubMiner.
+- **Windows shortcut** _(Windows only)_ - create a `SubMiner mpv` Start Menu/Desktop shortcut
+
+The `Finish setup` button requires a config file and at least one Yomitan dictionary. The launcher is optional and never blocks setup completion.
+
+On Linux and macOS, setup selects a writable directory already on your terminal `PATH`. If it cannot find one, it creates `~/.local/bin` and shows the `export PATH=...` command to run. Add that command to your shell configuration yourself if you want it in future terminals. Setup never edits shell configuration files. On Windows, setup adds only the wrapper directory to the user `PATH`. Setup stores a custom app location so the wrapper can find an AppImage or app bundle outside the usual install directories.
+
+> [!TIP]
+> You can re-open the setup wizard at any time with `subminer app --setup` or `SubMiner.AppImage --setup`.
+
+### Play a video
+
+Once setup is complete:
+
+```bash
+subminer video.mkv
+```
+
+The overlay appears over mpv. If a subtitle track loaded, its text shows up in the overlay as hoverable words.
+
+On **Windows**, the recommended way to play video is with the **SubMiner mpv** shortcut created during setup - double-click it, or drag a video file onto it.
+
+### Verify setup
+
+Run the built-in diagnostic:
+
+```bash
+subminer doctor
+```
+
+This checks for the app binary, mpv, ffmpeg, yt-dlp, fzf, rofi, your config file, and the mpv socket path. Only the app binary and mpv are hard failures; the rest are reported as optional. Fix any hard failures before continuing.
+
+## Anki setup (recommended)
+
+If you plan to mine Anki cards:
+
+1. Install [Anki](https://apps.ankiweb.net/)
+2. Install [AnkiConnect](https://ankiweb.net/shared/info/2055492159) - open Anki → **Tools → Add-ons → Get Add-ons** → enter code `2055492159`
+3. Restart Anki and keep it running while using SubMiner
+
+AnkiConnect listens on `http://127.0.0.1:8765` by default. SubMiner connects automatically with no extra config needed.
+
+For enrichment configuration (sentence, audio, screenshot fields), see [Anki Integration](/anki-integration).
+
+## Updates
+
+```bash
+subminer -u
+# or
+subminer --update
+```
+
+SubMiner verifies AppImage, launcher, and Linux support-asset downloads against `SHA256SUMS.txt`. On Linux those support assets include the launcher-managed runtime plugin copy under `SubMiner/plugin/subminer`, the rofi theme at `SubMiner/themes/subminer.rasi`, and the scoped Matroska thumbnailer registration under `SubMiner/thumbnailers`. If the binary is in a protected path, SubMiner shows the exact command to run rather than elevating itself.
+
+The tray "Check for Updates" entry installs the new app automatically on Linux, macOS, and Windows. Current `subminer` wrappers remain small bootstraps that locate the installed app and its private runtime. On Linux the updater replaces the running `.AppImage` in place via `electron-updater` and refreshes managed support assets from `subminer-assets.tar.gz`. The next launcher invocation detects the changed AppImage fingerprint and prepares the matching Bun and CLI cache before running the command. App startup also refreshes this payload and migrates recognized writable legacy launchers, including the launcher path an update deferred. AppImages managed by a system package, for example the AUR `/opt/SubMiner/SubMiner.AppImage`, are skipped so the package manager stays in charge.
+
+On Linux, `subminer -u` updates the AppImage and managed support assets directly, even when the app is not running. The launcher cache refreshes when the app fingerprint changes. AUR installs remain under package-manager control and should be updated through the package manager.
+
+## How it all fits together
+
+SubMiner is an overlay window that sits on top of mpv. It talks to mpv over an IPC socket, renders each subtitle line as interactive text backed by the bundled Yomitan dictionary engine, and writes Anki cards through AnkiConnect when you ask it to.
+
+The `subminer` launcher handles mpv IPC socket setup automatically. If you launch mpv yourself or from another tool, you must pass `--input-ipc-server=/tmp/subminer-socket` (or `\\.\pipe\subminer-socket` on Windows) - without it the overlay starts but subtitles won't appear.
+
+SubMiner injects the bundled mpv plugin at runtime, so there is nothing to install separately. On Linux, the `subminer` launcher checks for its managed runtime plugin copy, rofi theme, and scoped thumbnailer registration before every mpv-managed launch and installs those support assets from the bundled app automatically if one is missing. For a rofi picker launch, this check runs before the picker opens. The plugin adds in-player keybindings (the `y` chord) for driving the overlay from mpv. See [MPV Plugin](/mpv-plugin) for the full keybinding and configuration reference.
+
+## Platform notes
+
+### macOS
+
+**MeCab paths (Homebrew):**
+
+- Apple Silicon (M1/M2): `/opt/homebrew/bin/mecab`
+- Intel: `/usr/local/bin/mecab`
+
+`mecab` has to be on your PATH when SubMiner launches.
+
+**Fullscreen:** The overlay follows mpv into fullscreen. If it does not, accessibility permission is the usual cause.
+
+### Windows
+
+- The **SubMiner mpv** shortcut is the recommended way to launch playback. It starts `mpv.exe` with the right IPC socket and subtitle defaults.
+- First-run setup adds only `%LOCALAPPDATA%\SubMiner\bin` to the HKCU user PATH. It does not add `SubMiner.exe` to PATH.
+- IPC socket on Windows is `\\.\pipe\subminer-socket` - do not use `/tmp/subminer-socket`.
+- Config is stored at `%APPDATA%\SubMiner\config.jsonc`.
+
+## Manual launcher install
+
+Current launcher downloads use Bun included in the SubMiner app. The wrapper searches normal install locations and honors `SUBMINER_BINARY_PATH`; Linux also honors `SUBMINER_APPIMAGE_PATH`.
+
+### Linux {#manual-launcher-install-linux}
+
+```bash
+# Download the launcher
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -O ~/.local/bin/subminer
+chmod +x ~/.local/bin/subminer
+```
+
+### macOS {#manual-launcher-install-macos}
+
+```bash
+# Download the launcher
+sudo curl -fSL https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer -o /usr/local/bin/subminer
+sudo chmod +x /usr/local/bin/subminer
+```
+
+### Windows {#manual-launcher-install-windows}
+
+Download `subminer.cmd` from GitHub Releases and place it in a directory on your user `PATH`. It finds the installed app in the normal per-user or Program Files location. Set `SUBMINER_BINARY_PATH` if you use a portable or custom install.
+
+Launchers installed before the private-runtime change may still be bundled JavaScript with a Bun shebang. Those old files need system Bun until a current app startup migrates a recognized writable launcher, or until you replace one with the current release wrapper.
+
+## Optional extras
+
+### Linux support assets
+
+SubMiner ships the Linux rofi theme, scoped Matroska thumbnailer registration, launcher-managed runtime plugin copy, and the bundled Bun license notices in `subminer-assets.tar.gz`:
+
+```bash
+wget https://github.com/ksyasuda/SubMiner/releases/latest/download/subminer-assets.tar.gz -O /tmp/subminer-assets.tar.gz
+tar -xzf /tmp/subminer-assets.tar.gz -C /tmp
+mkdir -p ~/.local/share/SubMiner/themes
+cp /tmp/assets/themes/subminer.rasi ~/.local/share/SubMiner/themes/subminer.rasi
+mkdir -p ~/.local/share/SubMiner/thumbnailers
+cp /tmp/assets/thumbnailers/subminer-ffmpegthumbnailer.thumbnailer ~/.local/share/SubMiner/thumbnailers/
+mkdir -p ~/.local/share/SubMiner/plugin
+cp -R /tmp/plugin/subminer ~/.local/share/SubMiner/plugin/subminer
+```
+
+`subminer -u` and the tray updater keep those Linux support assets in sync automatically once the `SubMiner` data dir exists. Normal Linux launcher playback also auto-installs all three assets from the bundled app if one is missing, so manual extraction is mainly useful for pre-seeding or custom setups. Rofi receives the SubMiner data path through its process-local `XDG_DATA_DIRS`, so the thumbnailer registration does not change the desktop-wide configuration.
+
+Override the theme path with `SUBMINER_ROFI_THEME=/absolute/path/to/theme.rasi`.
+
+Next: [Usage](/usage) - learn about the `subminer` wrapper, keybindings, and YouTube playback.

docs-site/ipc-contracts.md

@@ -0,0 +1,124 @@
+# IPC + runtime contracts
+
+SubMiner's Electron app runs two isolated processes, main and renderer, and IPC channels are the only way they talk. That boundary is deliberate. The renderer is an untrusted surface: it loads Yomitan, renders subtitle text SubMiner did not write, and runs in a Chromium sandbox. Every message crossing the bridge goes through a validator before any domain code sees it.
+
+Channel names, payload shapes, and validators all live together, so they change together. Touching an IPC surface means updating the contract, the validator, the preload bridge, and the handler in one commit. Drift between those four layers is a bug, not a style preference.
+
+## Message flow
+
+Renderer-initiated calls (`invoke`) pass through four boundaries before reaching a service. Fire-and-forget messages (`send`) follow the same path but skip the response leg. Malformed payloads are caught at the validator and never reach domain code.
+
+```mermaid
+flowchart TB
+  classDef rend fill:#8bd5ca,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef bridge fill:#f5a97f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef valid fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef handler fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef svc fill:#8aadf4,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef err fill:#ed8796,stroke:#494d64,color:#24273a,stroke-width:1.5px
+
+  R["Renderer"]:::rend
+  P(["preload.ts"]):::bridge
+  M["ipcMain handler"]:::handler
+  V{"Validator"}:::valid
+  S["Service"]:::svc
+  E["Structured error"]:::err
+
+  R -->|"invoke / send"| P
+  P -->|"ipcRenderer"| M
+  M --> V
+  V -->|"valid"| S
+  V -->|"malformed"| E
+  S -->|"result"| P
+  E -->|"{ ok: false }"| P
+  P -->|"return"| R
+
+  style E fill:#ed8796,stroke:#494d64,color:#24273a,stroke-width:1.5px
+```
+
+## Runtime sockets
+
+The renderer↔main bridge above lives *inside* the Electron app. A separate set of OS sockets connects the app to the other runtimes - mpv and the launcher/plugin. These carry no renderer payloads and bypass the contract/validator layer; they are command and property channels between processes.
+
+- **mpv IPC socket** (`/tmp/subminer-socket`, or `\\.\pipe\subminer-socket` on Windows): the `MpvIpcClient` in the main process connects here to send JSON commands and subscribe to playback/subtitle properties via `observe_property`. Created by mpv's `--input-ipc-server`.
+- **App control socket** (`/tmp/subminer-control-<uid>-<hash>.sock`, or a named pipe on Windows): the launcher and the mpv plugin send CLI-style commands (`--start`, `--show-visible-overlay`, `--texthooker`) to a running app here. It also dedupes a second `subminer` invocation into the existing instance instead of launching twice.
+
+```mermaid
+flowchart LR
+  classDef extrt fill:#eed49f,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef app fill:#b7bdf8,stroke:#494d64,color:#24273a,stroke-width:1.5px
+  classDef ext fill:#a6da95,stroke:#494d64,color:#24273a,stroke-width:1.5px
+
+  subgraph MpvProc["mpv process"]
+    direction TB
+    Mpv["mpv core"]:::ext
+    Plugin["SubMiner plugin (Lua)"]:::extrt
+  end
+
+  Launcher["Launcher CLI"]:::extrt
+  App["SubMiner app (Electron main)"]:::app
+
+  App <-->|"mpv IPC socket · /tmp/subminer-socket<br/>JSON commands + property observe"| Mpv
+  Launcher -->|"app control socket · /tmp/subminer-control-*<br/>--start, --show-visible-overlay, …"| App
+  Plugin -->|"app control socket<br/>spawn / attach"| App
+
+  style MpvProc fill:#363a4f,stroke:#494d64,color:#cad3f5
+```
+
+How these sockets are established during launch is covered in [Playback Startup Flow](./architecture#playback-startup-flow).
+
+## Core surfaces
+
+| File | Role |
+| --- | --- |
+| `src/shared/ipc/contracts.ts` | Canonical channel names and payload type contracts. Single source of truth for both processes. |
+| `src/shared/ipc/validators.ts` | Runtime payload parsers and type guards. Every `invoke` payload is validated here before the handler runs. |
+| `src/preload.ts` | Renderer-side bridge. Exposes a typed API surface to the renderer - only approved channels are accessible. |
+| `src/main/ipc-runtime.ts` | Main-process handler registration and routing. Wires validated channels to domain handlers. |
+| `src/core/services/ipc.ts` | Service-level invoke handling. Applies guardrails (validation, error wrapping) before calling domain logic. |
+| `src/core/services/anki-jimaku-ipc.ts` | Integration-specific IPC boundary for Anki and Jimaku operations. |
+| `src/main/cli-runtime.ts` | CLI/runtime command boundary. Handles commands that originate from the launcher or mpv plugin rather than the renderer. |
+
+## Contract rules
+
+These rules exist to prevent a class of bugs where the renderer and main process silently disagree about message shapes - which surfaces as undefined fields, swallowed errors, or state corruption.
+
+- **Use shared constants.** Channel names come from `contracts.ts`, never ad-hoc literal strings. This makes channels greppable and refactor-safe.
+- **Validate before handling.** Every `invoke` payload passes through `validators.ts` before reaching domain logic. This catches shape drift at the boundary instead of deep inside a service.
+- **Return structured failures.** Handlers return `{ ok: false, error: string }` on failure rather than throwing. The renderer can always distinguish success from failure without try/catch.
+- **Keep payloads narrow.** Send only what the handler needs. Avoid passing entire state objects across the bridge - it couples the renderer to internal main-process structure.
+- **Co-evolve all layers.** When a payload shape changes, update `contracts.ts`, `validators.ts`, `preload.ts`, and the handler in the same commit. Partial updates are treated as bugs.
+
+## Two message patterns
+
+**Invoke (request/response):** The renderer calls a typed bridge method and awaits a result. The main process validates the payload, runs the handler, and returns a structured response. Used for operations where the renderer needs a result - lookups, config reads, mining actions.
+
+**Fire-and-forget (send):** The renderer sends a message with no response. The main process validates and handles it silently. Malformed payloads are dropped. Used for notifications where the renderer doesn't need confirmation - UI state hints, focus events, position updates.
+
+## Add a new IPC action
+
+1. Add the channel constant in `src/shared/ipc/contracts.ts`.
+2. Add or extend the payload validator in `src/shared/ipc/validators.ts`.
+3. Expose a typed bridge method in `src/preload.ts`.
+4. Register the handler in `src/main/ipc-runtime.ts` (or the relevant domain runtime module).
+5. Add tests for both valid and malformed payload cases in `src/core/services/*`.
+6. Update renderer tests when behavior or state transitions change.
+
+## Runtime state notes
+
+- Prefer runtime/domain composition via `src/main/runtime/composers/*` and `src/main/runtime/domains/*`. IPC handlers should delegate to composers rather than containing orchestration logic.
+- Route shared mutable state updates through transition helpers in `src/main/state.ts` for migrated domains. Direct mutation from IPC handlers bypasses invariant checks.
+- Keep IPC handlers thin - they validate, delegate, and return. Business logic belongs in services.
+
+## Troubleshooting
+
+- **Unknown payload in handler:** The validator is not being applied before the handler runs. Check that the channel is routed through `ipc-runtime.ts` with validation, not registered directly.
+- **Renderer invoke fails:** Verify the preload bridge method exists and matches the channel constant. Check that the handler is registered and returning (not throwing).
+- **Contract drift:** When invoke calls return unexpected shapes, compare the shared contract, validator, preload bridge, and main handler signatures side by side. One of them was updated without the others.
+
+## Related docs
+
+- [Architecture](/architecture)
+- [Development](/development)
+- [Configuration](/configuration)
+- [Troubleshooting](/troubleshooting)