diff --git a/.dockerignore b/.dockerignore
new file mode 100755
index 00000000..3afd77b8
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,56 @@
+.git
+.vscode
+.github
+.venv
+venv
+__pycache__
+*.py[cod]
+.pytest_cache
+.ruff_cache
+.coverage
+htmlcov
+dist
+output
+scripts
+!website/scripts
+!website/scripts/*.js
+!website/scripts/*.ts
+docs
+tests
+testfiles
+.env
+.env.*
+!.env.example
+*.session*
+cache
+data
+downloads
+*.data
+*.log
+logs.txt
+.DS_Store
+Thumbs.db
+
+# Frontend build inputs stay in source; generated files are built in Docker.
+**/node_modules
+website/dist
+website/coverage
+**/.vite
+
+# Credentials are excluded at every directory depth.
+**/.env
+**/.env.*
+**/*.session*
+
+website/.impeccable
+.impeccable
+**/.impeccable
+
+# Local agent tools and private request tracking never enter build context.
+.agents
+.codex
+**/.agents
+**/.codex
+skills-lock.json
+**/skills-lock.json
+docs/request-tracker.md
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 00000000..c4b7770d
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,13 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.md]
+indent_size = 2
+trim_trailing_whitespace = false
diff --git a/.env.example b/.env.example
new file mode 100755
index 00000000..e1f5f00b
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,16 @@
+# Required values for a new drive. Setup: docs/setup.md
+MONGODB_URI=<mongodb-connection-uri>
+
+# Telegram application credentials and private storage channel.
+API_ID=<telegram-api-id>
+API_HASH=<telegram-api-hash>
+MAIN_BOT_TOKEN=<main-bot-token>
+TELEGRAM_ADMIN_IDS=<your-numeric-telegram-user-id>
+STORAGE_CHANNEL=<private-channel-id>
+
+# Add more storage bots in Management → Connections after setup.
+
+# Unique owner password: at least 12 characters.
+ADMIN_PASSWORD=<strong-admin-password>
+
+# Optional settings and defaults: docs/reference.md#configuration
diff --git a/.gitattributes b/.gitattributes
index dfe07704..f7bd23dd 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,2 +1,6 @@
-# Auto detect text files and perform LF normalization
-* text=auto
+# Auto-detect text files and keep repository and working-tree text on LF.
+* text=auto eol=lf
+*.sh text eol=lf
+Dockerfile text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100755
index 00000000..dc6007f0
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,46 @@
+version: 2
+
+updates:
+    - package-ecosystem: uv
+      directory: /
+      schedule:
+          interval: weekly
+          day: monday
+          time: "04:00"
+          timezone: Asia/Kolkata
+      open-pull-requests-limit: 10
+      commit-message:
+          prefix: deps
+
+    - package-ecosystem: github-actions
+      directory: /
+      schedule:
+          interval: weekly
+          day: monday
+          time: "04:15"
+          timezone: Asia/Kolkata
+      open-pull-requests-limit: 10
+      commit-message:
+          prefix: ci
+
+    - package-ecosystem: docker
+      directory: /
+      schedule:
+          interval: weekly
+          day: monday
+          time: "04:30"
+          timezone: Asia/Kolkata
+      open-pull-requests-limit: 5
+      commit-message:
+          prefix: docker
+
+    - package-ecosystem: npm
+      directory: /website
+      schedule:
+          interval: weekly
+          day: monday
+          time: "04:45"
+          timezone: Asia/Kolkata
+      open-pull-requests-limit: 5
+      commit-message:
+          prefix: frontend-deps
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100755
index 00000000..79fafb1c
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,344 @@
+name: CI
+
+on:
+    push:
+        branches:
+            - main
+            - dev
+        tags:
+            - "v*"
+        paths-ignore:
+            - "**.md"
+            - "docs/**"
+            - LICENSE
+    pull_request:
+    workflow_dispatch:
+        inputs:
+            suite:
+                description: Additional checks (core checks always run)
+                type: choice
+                default: core
+                options:
+                    - core
+                    - browser
+                    - container
+                    - release
+                    - all
+
+permissions:
+    contents: read
+
+concurrency:
+    group: ci-${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+env:
+    UV_VERSION: "0.13.4"
+
+jobs:
+    quality:
+        name: Quality and security
+        runs-on: ubuntu-latest
+        timeout-minutes: 20
+        steps:
+            - name: Check out repository
+              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+            - name: Set up Python
+              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              with:
+                  python-version-file: .python-version
+
+            - name: Check release versions
+              run: |
+                  if [ "$GITHUB_REF_TYPE" = "tag" ]; then
+                    python scripts/build_release.py --check-version --tag "$GITHUB_REF_NAME"
+                  else
+                    python scripts/build_release.py --check-version
+                  fi
+
+            - name: Set up uv
+              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              with:
+                  version: ${{ env.UV_VERSION }}
+                  enable-cache: true
+                  cache-dependency-glob: uv.lock
+
+            - name: Install locked dependencies
+              run: uv sync --frozen --python 3.14.8
+
+            - name: Ruff lint
+              run: uv run --frozen --python 3.14.8 ruff check tgdrive tests scripts
+
+            - name: Ruff format check
+              run: uv run --frozen --python 3.14.8 ruff format --check tgdrive tests scripts
+
+            - name: Bandit security scan
+              run: uv run --frozen --python 3.14.8 bandit -c pyproject.toml -r tgdrive
+
+            - name: Dependency vulnerability audit
+              run: uv run --frozen --all-groups --python 3.14.8 pip-audit --strict
+
+            - name: Frontend security smoke
+              run: uv run --frozen python -m pytest tests/web/test_frontend_security.py
+
+    frontend:
+        name: Frontend behavior
+        runs-on: ubuntu-latest
+        timeout-minutes: 10
+        steps:
+            - name: Check out repository
+              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+            - name: Set up Node.js
+              uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+              with:
+                  node-version: "24.22.0"
+
+            - name: Install locked frontend dependencies
+              run: npm ci --prefix website
+
+            - name: Typecheck, test, build, and audit frontend
+              run: |
+                  npm run typecheck --prefix website
+                  npm test --prefix website
+                  npm run build --prefix website
+                  npm audit --prefix website --audit-level=high
+
+    tests:
+        name: Backend tests
+        runs-on: ubuntu-latest
+        timeout-minutes: 20
+        steps:
+            - name: Check out repository
+              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+            - name: Set up Python
+              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              with:
+                  python-version-file: .python-version
+
+            - name: Set up uv
+              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              with:
+                  version: ${{ env.UV_VERSION }}
+                  enable-cache: true
+                  cache-dependency-glob: uv.lock
+
+            - name: Install locked dependencies
+              run: uv sync --frozen
+
+            - name: Set up Node.js for application assets
+              uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+              with:
+                  node-version: "24.22.0"
+
+            - name: Build application assets
+              run: npm ci --prefix website && npm run build --prefix website
+
+            - name: Start isolated MongoDB replica set
+              run: |
+                  docker run -d --name tgdrive-test-mongo -p 127.0.0.1:27017:27017 \
+                    mongo:8.0@sha256:4a4ab5d4834207389e0d7270fac988e21ffedccecba77991a552f755df229907 --replSet tgdrive-test --bind_ip_all
+                  for attempt in $(seq 1 60); do
+                    if docker exec tgdrive-test-mongo mongosh --quiet --eval 'db.adminCommand({ping:1})'; then
+                      break
+                    fi
+                    sleep 1
+                  done
+                  docker exec tgdrive-test-mongo mongosh --quiet --eval \
+                    'rs.initiate({_id:"tgdrive-test",members:[{_id:0,host:"localhost:27017"}]})'
+                  for attempt in $(seq 1 60); do
+                    if docker exec tgdrive-test-mongo mongosh --quiet --eval \
+                      'if (!db.hello().isWritablePrimary) { quit(1); }'; then
+                      break
+                    fi
+                    sleep 1
+                  done
+                  docker exec tgdrive-test-mongo mongosh --quiet --eval \
+                    'if (!db.hello().isWritablePrimary) { quit(1); }'
+
+            - name: Run tests with coverage
+              env:
+                  TGDRIVE_MONGO_TESTS: "1"
+                  TGDRIVE_TEST_MONGODB_URI: mongodb://127.0.0.1:27017/?replicaSet=tgdrive-test&directConnection=true
+              run: >-
+                  uv run --frozen python -m pytest
+                  --cov=tgdrive --cov-report=term-missing
+
+    browser:
+        name: Chromium end-to-end
+        if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && (inputs.suite == 'browser' || inputs.suite == 'all'))
+        runs-on: ubuntu-24.04
+        timeout-minutes: 20
+        steps:
+            - name: Check out repository
+              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+            - name: Set up Python
+              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              with:
+                  python-version-file: .python-version
+
+            - name: Set up uv
+              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              with:
+                  version: ${{ env.UV_VERSION }}
+
+            - name: Set up Node.js
+              uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+              with:
+                  node-version: "24.22.0"
+
+            - name: Build frontend
+              run: npm ci --prefix website && npm run build --prefix website
+
+            - name: Install locked browser-test environment
+              run: |
+                  uv sync --frozen --group e2e
+                  uv run --frozen --group e2e playwright install --with-deps chromium
+
+            - name: Test production frontend in Chromium
+              env:
+                  TGDRIVE_E2E: "1"
+              run: >-
+                  uv run --frozen --group e2e python -m pytest
+                  -m e2e tests/browser/test_browser_e2e.py
+                  tests/browser/test_browser_player_native.py
+                  tests/browser/test_browser_pdf_features.py
+                  tests/browser/test_browser_pdf_ranges.py
+                  tests/browser/test_browser_channel_backup.py::test_slow_backup_poll_updates_progress_before_starting_the_next_request
+
+            - name: Upload browser screenshots and traces
+              if: always()
+              uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+              with:
+                  name: chromium-e2e-evidence
+                  path: cache/browser-e2e
+                  if-no-files-found: ignore
+                  retention-days: 14
+
+    container:
+        name: Container build
+        if: github.event_name == 'workflow_dispatch' && (inputs.suite == 'container' || inputs.suite == 'release' || inputs.suite == 'all')
+        runs-on: ubuntu-latest
+        timeout-minutes: 25
+        needs:
+            - quality
+            - frontend
+            - tests
+        steps:
+            - name: Check out repository
+              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+            - name: Set up QEMU for ARM64 verification
+              uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0
+              with:
+                  platforms: arm64
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+            - name: Build AMD64 and ARM64 release layouts
+              uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+              with:
+                  context: .
+                  platforms: linux/amd64,linux/arm64
+                  push: false
+                  outputs: type=oci,dest=/tmp/tgdrive-multiarch.tar
+                  cache-from: type=gha
+                  cache-to: type=gha,mode=max
+
+            - name: Build container image
+              uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+              with:
+                  context: .
+                  file: ./Dockerfile
+                  push: false
+                  load: true
+                  tags: tgdrive:ci
+                  cache-from: type=gha
+                  cache-to: type=gha,mode=max
+
+            - name: Verify container metadata
+              run: |
+                  test "$(docker image inspect tgdrive:ci --format '{{.Config.User}}')" = "10001:10001"
+                  docker image inspect tgdrive:ci --format '{{json .Config.Healthcheck.Test}}' | grep -q healthz
+                  docker run --rm --network none --entrypoint python tgdrive:ci \
+                    -c 'import ssl; roots = str(ssl.create_default_context().get_ca_certs()); assert "emSign ECC Root CA - G3" not in roots'
+                  docker run --rm --network none --entrypoint python tgdrive:ci \
+                    -c 'import tgdrive.web.app, aiohttp, telethon, cryptg, argon2; print("runtime imports passed")'
+                  docker run --rm --network none --entrypoint sh tgdrive:ci -c \
+                    'test -w /app/data && test -w /app/cache && test ! -e /app/.env && test ! -e /app/.git'
+
+            - name: Verify the application factory and bundled assets offline
+              run: |
+                  docker run --rm -i --network none --entrypoint python tgdrive:ci - <<'PY'
+                  import asyncio
+                  from pathlib import Path
+                  from types import SimpleNamespace
+                  from tgdrive.core.config import Settings
+                  from tgdrive.web.app import create_app
+                  settings = Settings(
+                      _env_file=None, API_ID=12345, API_HASH="a" * 32,
+                      MONGODB_URI="mongodb://synthetic.invalid/tgdrive",
+                      MAIN_BOT_TOKEN="123456:" + "x" * 30,
+                      TELEGRAM_ADMIN_IDS="12345",
+                      STORAGE_CHANNEL=-1001234567890,
+                      ADMIN_PASSWORD="synthetic-container-password",
+                      SESSION_SECRET="s" * 48,
+                  )
+                  app = create_app(settings, runtime=SimpleNamespace())
+                  stream = next(route for route in app.routes if route.path == "/stream")
+                  response = asyncio.run(stream.endpoint(path="/synthetic", auth=None))
+                  assert Path(response.path).is_file()
+                  print("Application factory and bundled player assets passed; runtime startup not exercised")
+                  PY
+
+    source-release:
+        name: Verify source release archive
+        if: github.event_name == 'workflow_dispatch' && (inputs.suite == 'release' || inputs.suite == 'all')
+        runs-on: ubuntu-latest
+        timeout-minutes: 20
+        needs:
+            - container
+        steps:
+            - name: Check out repository
+              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+            - name: Set up Python
+              uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+              with:
+                  python-version-file: .python-version
+
+            - name: Set up Node.js
+              uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+              with:
+                  node-version: "24.22.0"
+
+            - name: Set up uv
+              uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+              with:
+                  version: ${{ env.UV_VERSION }}
+
+            - name: Build and verify public source archive
+              run: |
+                  python scripts/build_release.py
+                  (cd dist && sha256sum --check *.zip.sha256)
+                  unzip -q dist/tgdrive-*.zip -d "$RUNNER_TEMP/tgdrive-source"
+                  cd "$RUNNER_TEMP/tgdrive-source"/tgdrive-*
+                  uv sync --frozen
+                  npm ci --prefix website
+                  npm run build --prefix website
+                  uv run --frozen python -m pytest
+                  npm test --prefix website
+
+            - name: Upload source candidate and checksum
+              uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+              with:
+                  name: tgdrive-source-candidate
+                  path: |
+                      dist/tgdrive-*.zip
+                      dist/tgdrive-*.zip.sha256
+                  if-no-files-found: error
+                  retention-days: 14
diff --git a/.gitignore b/.gitignore
index 7648f26e..404c0abb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,8 +1,53 @@
-*.pyc
+# Python
+__pycache__/
+*.py[cod]
+*.pyd
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+output/
+
+# Secrets and Telegram sessions
+.env
+.env.*
+!.env.example
+*.session
+*.session-journal
+*.session-shm
+*.session-wal
+
+# Runtime state
+cache/
+data/
+downloads/
 *.data
-t.py
-t2.py
-cache
-config copy.py
+*.log
 logs.txt
-.env
+
+# Editors and OS files
+.idea/
+.vscode/*
+!.vscode/settings.json
+.DS_Store
+Thumbs.db
+
+node_modules/
+website/dist/
+playwright-report/
+test-results/
+
+# Downloaded manual samples have separate, unverified redistribution terms.
+testfiles/
+
+# Local agent skills and design state
+.agents/
+skills-lock.json
+.impeccable/
+
+# Private local request tracking
+/docs/request-tracker.md
diff --git a/.python-version b/.python-version
new file mode 100755
index 00000000..9b8fe2fb
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.14.8
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 00000000..c775de21
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,16 @@
+{
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/.pytest_cache": true,
+        "**/.ruff_cache": true,
+        "**/.venv": true,
+        "**/node_modules": true,
+        "**/.vite": true,
+        "website/dist": true,
+        "dist": true,
+        "output": true,
+        "htmlcov": true,
+        ".coverage": true,
+        "coverage.xml": true
+    }
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..e49b82ec
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,132 @@
+# TGDrive contributor guidance
+
+**Project rule: Make sure you are documenting important features and workings of TGDrive.**
+
+## Collaborate with independent judgment
+
+Treat the user's proposed approaches as suggestions open to discussion. If you
+disagree or see a better approach, say so plainly, explain the tradeoff and
+recommend it. Distinguish suggestions and questions from explicit requests to
+change something; do not implement every idea automatically. Continue to honor
+explicit requirements, constraints and approval boundaries.
+
+## Keep documentation current with the implementation
+
+When adding or changing an important feature, workflow, default, limit, recovery
+guarantee or architectural decision, update its documentation in the same change.
+Documentation is part of completing the feature. Internal refactors that preserve
+documented behavior do not need artificial documentation changes.
+
+Explain the user experience, how data and work move through TGDrive, why the
+policy exists, and its practical limits. Include relevant defaults, configuration,
+failure/retry behavior and when work can continue without the browser. Keep
+user-facing instructions practical; put detailed thresholds and correctness
+rules in the technical documentation.
+
+Keep documentation small and easy to scan. Lead with the steps or facts readers
+need, remove repetition, and link to the canonical explanation. Use GitHub-flavored
+Markdown tables, task lists and fenced code blocks where useful. Put optional
+troubleshooting, implementation detail and long examples in `<details>` sections
+with a clear `<summary>` and blank lines around Markdown content. Collapsing text
+is not a substitute for shortening it; do not hide essential steps or warnings.
+
+The root README is a product showcase: clear benefits, screenshots/demo media and
+links to the guides. Keep installation steps and commands in `docs/setup.md`.
+Write for readers who do not yet know Telegram or earlier TGDrive versions.
+Use normal links rather than footnotes, and label unfinished media slots clearly.
+Keep screenshot/demo replacement instructions in `docs/assets/README.md`.
+
+Verify claims against the implementation. Keep settings, API contracts, limits
+and recovery guarantees consistent with the code. Distinguish automated tests,
+synthetic browser checks and live validation; never claim unrun checks, deployment
+or universal device/network performance. Keep private evidence and credentials
+out of public documentation.
+
+## Choose a clear home for each topic
+
+Use the existing structure when it fits:
+
+| Information | Maintain here |
+| --- | --- |
+| Feature overview and discovery | `README.md`, `docs/README.md` |
+| User workflows and status meanings | `docs/usage.md` |
+| Components, data flow, scheduling and durability | `docs/architecture.md` |
+| Performance policy and bottlenecks | `docs/performance.md` |
+| Settings, defaults, limits and API contracts | `docs/configuration.md`, `docs/reference.md` |
+| Restart, failures, backup and recovery | `docs/operations.md`, `docs/backup-recovery.md` |
+| Relevant validation commands and evidence | `docs/development.md` |
+
+Prefer updating an existing guide. Create a focused file in `docs/` only when a
+distinct subject needs its own explanation and would make that guide unwieldy.
+These pages are a starting structure, not a fixed list.
+Use a descriptive filename, link the page from `docs/README.md` and relevant
+guides, and update the root README when feature discovery warrants it. Add public
+guides to `PUBLIC_DOCS` in `scripts/build_release.py` so source releases include
+them; keep private notes outside that allowlist.
+
+Give each subject one canonical explanation and cross-link it instead of copying
+the same details across guides. Update or remove obsolete text, examples and
+links when behavior changes. Check affected links and documented commands.
+
+## Ask before running tests or validation
+
+Do not run tests, typechecks, builds, linters, benchmarks or browser validation
+unless the user explicitly requests those checks for the current work or approves
+the specific proposed validation. Do not run unnecessary checks after every
+message. A fix request, clarification, status question, documentation edit or
+commit request alone is not permission to start or repeat testing.
+
+Reuse existing results while they remain applicable. Earlier permission to test
+is not standing permission for later runs. Before additional validation, explain
+the smallest useful check and why it is needed, then wait for approval. Stay
+within the approved scope; do not broaden it or repeat passing checks without
+asking. Ordinary code reading and Git status/diff inspection may continue.
+
+Report checks actually performed and remaining limitations. Never imply a change
+was tested when validation was not requested or approved.
+
+## Ask before pushing
+
+Do not push commits, branches or tags to any remote unless the user explicitly
+requests the current push or approves that specific proposed push. Earlier push
+permission applies only to that requested action; it is not standing permission
+for later changes. Requests to edit, fix, continue work or commit do not authorize
+a push.
+
+When the current push is not explicitly authorized, finish the local work first,
+summarize what would be pushed and name the remote and branch, then ask and wait
+for approval. Keep the changes local until the user answers. Do not bypass this
+rule with scripts, automation or another tool that publishes the local commits.
+
+## Version every published update
+
+Every update published to `main` must belong to a new semantic version, starting
+with `2.0.0`. Use patch versions for compatible fixes, documentation and
+maintenance, minor versions for compatible features, and major versions for
+breaking changes. Development commits may accumulate for one upcoming release.
+`main` receives stable updates after review and required checks; `dev` is ongoing
+development and may be unstable. Point user-facing documentation links to `main`
+and release downloads to their version tags. Use `dev` links only for development
+instructions.
+
+Keep `pyproject.toml` authoritative and synchronize the runtime version, frontend
+package and lockfile, Python lockfile project entry, and Docker image label.
+Name the target version in the release PR. After merging, create an immutable
+annotated `vX.Y.Z` tag on the final `main` commit and link the PR and commit in the
+GitHub release. Cloning is sufficient; custom ZIP/checksum assets are optional.
+Never move a published tag; corrections require a new version. Follow
+[the release procedure](docs/release.md).
+The testing and push approval rules above still apply.
+
+## Write useful commit titles and descriptions
+
+When committing, use a concise, specific title describing the resulting change
+in the imperative, such as `Adapt device upload concurrency to measured throughput`.
+Include a meaningful description explaining the problem and purpose, important
+behavior or architecture changes, validation actually performed, and any material
+limitations, compatibility or migration requirements. Scale the detail to the
+change; avoid vague titles, file lists and transcripts of the work.
+
+Use Git commit titles and descriptions for change history. Do not maintain or
+recreate `CHANGELOG.md`. Project documentation describes how TGDrive currently
+works; commit messages explain what changed and why.
diff --git a/Dockerfile b/Dockerfile
index 1daffd89..eb1131df 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,18 +1,70 @@
-# Use the official Python base image
-FROM python:3.11.7-slim AS base
+# syntax=docker/dockerfile:1.7@sha256:a57df69d0ea827fb7266491f2813635de6f17269be881f696fbfdf2d83dda33e
+
+
+FROM --platform=$BUILDPLATFORM node:24.22.0-bookworm-slim@sha256:a5f4366e834695d5f363b920c104953a535d3a9864d1bdf74566a0ebe01daee5 AS frontend
+
+WORKDIR /frontend
+COPY website/package.json website/package-lock.json ./
+COPY website/vendor ./vendor
+RUN --mount=type=cache,target=/root/.npm npm ci --ignore-scripts
+COPY website/ ./
+RUN npm run build
+
+FROM python:3.14.8-slim-trixie@sha256:a2b82f3c48559aa0a8446d9af49826b6e2b2016f4cd2afabfe6013ec53729170 AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:0.13.4@sha256:9f130421e930bfbdc563c00740466603f8723158e90297d07957c2294640262b /uv /uvx /usr/local/bin/
+
+ENV UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never
 
-# Set the working directory inside the container
 WORKDIR /app
 
-# Copy the requirements file to the working directory and install dependencies
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
+COPY pyproject.toml uv.lock .python-version ./
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-install-project
+
+
+FROM python:3.14.8-slim-trixie@sha256:a2b82f3c48559aa0a8446d9af49826b6e2b2016f4cd2afabfe6013ec53729170 AS runtime
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PATH="/app/.venv/bin:${PATH}" \
+    DATA_DIR=/app/data \
+    CACHE_DIR=/app/cache
+
+LABEL org.opencontainers.image.title="TGDrive" \
+    org.opencontainers.image.description="Self-hosted Telegram-backed personal file drive" \
+    org.opencontainers.image.source="https://github.com/TechShreyash/TGDrive" \
+    org.opencontainers.image.licenses="MIT" \
+    org.opencontainers.image.version="2.0.0"
+
+WORKDIR /app
+
+# Distrust the compromised emSign G3 chain in Python/MongoDB system TLS too.
+# https://github.com/astral-sh/uv/security/advisories/GHSA-hq85-5cpj-mr62
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libarchive13t64 ffmpeg poppler-utils \
+    && sed -i 's|^mozilla/emSign_ECC_Root_CA_-_G3.crt$|!mozilla/emSign_ECC_Root_CA_-_G3.crt|' /etc/ca-certificates.conf \
+    && update-ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN groupadd --gid 10001 tgdrive \
+    && useradd --uid 10001 --gid tgdrive --no-create-home --shell /usr/sbin/nologin tgdrive \
+    && mkdir -p /app/data /app/cache \
+    && chown -R tgdrive:tgdrive /app/data /app/cache
+
+COPY --from=builder /app/.venv /app/.venv
+COPY --chown=tgdrive:tgdrive LICENSE ./
+COPY --chown=tgdrive:tgdrive tgdrive ./tgdrive
+COPY --from=frontend --chown=tgdrive:tgdrive /frontend/dist ./website/dist
+
+USER 10001:10001
 
-# Copy the application code to the working directory
-COPY . .
+EXPOSE 8000
+STOPSIGNAL SIGTERM
 
-# Expose the port on which the application will run
-EXPOSE 8080
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+    CMD ["python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=3).read()"]
 
-# Run the FastAPI application using uvicorn server
-CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["/app/.venv/bin/python", "-m", "tgdrive.server"]
diff --git a/LICENSE b/LICENSE
index 33907515..2d893813 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 TechShreyash
+Copyright (c) 2024-2026 TechShreyash
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/README.md b/README.md
index b0a09570..c7838c94 100644
--- a/README.md
+++ b/README.md
@@ -1,177 +1,126 @@
-<h1>
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="website/static/brand/tgdrive-logo-dark.svg">
-    <img src="website/static/brand/tgdrive-logo.svg" alt="TGDrive" width="400">
-  </picture>
-</h1>
+# [![TGDrive v2 — Your Telegram. Your cloud drive. Upload, organize, stream and share.](docs/assets/tgdrive-v2-banner.png)](docs/showcase.md)
 
-**A Google Drive Clone with Telegram Storage**
+TGDrive brings the convenience of Google Drive to
+[Telegram's free unlimited cloud storage](https://telegram.org/faq_premium#q-is-telegram-still-free).
+Run it on your own computer or server to store files in a private Telegram
+channel, organize folders, stream videos and read documents in your browser.
+Upload large files without splitting them yourself, and share files or folders
+through links you can set to expire or revoke.
 
-Welcome to TGDrive! This web application replicates Google Drive's functionalities using Telegram as its storage backend. Manage folders and files, perform actions like uploading, renaming, and deleting, utilize trash/bin support, enable permanent deletion, and share public links. The application offers admin login and automatically backs up the database to Telegram.
+**[Try the demo](#try-the-public-demo)** · **[Set up TGDrive](docs/setup.md)** · **[Explore screenshots and videos](docs/showcase.md)**
 
-**Check out the [TGDrive Personal](https://github.com/TechShreyash/TGDrivePersonal) project for local desktop backup support.**
+> [!IMPORTANT]
+> **Must read before using TGDrive: [New-user guide and FAQs](docs/new-user-guide.md).**
+> Essential for everyone using or running TGDrive, including managed hosting:
+> storage limits, upload status, privacy and backups.
 
 ## Features
 
-- **File Management:** Upload, rename, and delete files with integrated trash/bin functionality and permanent deletion support.
-- **Folder Management:** Easily create, rename, and delete folders.
-- **Sharing:** Seamlessly share public links for files and folders.
-- **Admin Support:** Secure admin login for efficient management.
-- **Automatic Backups:** Automated database backups sent directly to Telegram.
-- **Multiple Bots/Clients:** Support for multiple bots/clients for file operations and streaming from Telegram.
-- **Large File Support:** Upload files up to 4GB using Telegram Premium accounts.
-- **Auto Pinger:** Built-in feature to keep the website active by preventing idle timeouts.
-- **URL Upload Support:** Upload files directly to TG Drive from any direct download link of a file.
-- **Bot Mode:** Upload files directly to any folder in TG Drive by sending the file to the bot on Telegram ([Know More](#tg-drives-bot-mode))
+- **No fixed total storage limit.** TGDrive does not cap the total space your files use in Telegram.
+- **Upload files larger than 2 GB without manual splitting.** TGDrive splits the upload into smaller parts and presents it as one file for playback and downloading.
+- **Resumable file and folder uploads.** Preserve folder structure and resume interrupted device uploads by reselecting the originals. Once TGDrive confirms it has received all files, Telegram uploading can finish with the tab closed while the app runs.
+- **Import from URLs or Telegram.** Paste a direct file URL, or send and forward files to your configured Telegram bot, to add them to your drive.
+- **Organize and find files.** Create folders, search by name, star favorites, switch between list and grid views, and restore items from Trash.
+- **Play videos and audio in your browser.** Stream supported media, with subtitles, audio-track selection and chapters when available.
+- **View documents, photos, ebooks and comics.** Open images, PDFs and text, and read EPUB ebooks and CBZ/CBR comics in your browser.
+- **Share files and folders with a link.** Give others read-only access, choose an expiry and revoke access when needed.
+- **Prepare files for smoother access.** Preload before watching or sharing. While file data stays cached, repeat visits and shared-link viewers can reuse it without downloading it from Telegram again.
+- **Follow transfers and server activity.** Track progress, search transfer history, and monitor server resources, traffic, Telegram activity and cache use.
+- **Backups and recovery.** Save encrypted backups of your file list, folders and settings, and optionally copy completed files to a separate Telegram channel.
 
-## Tech Stack
+[Explore features and workflows in the user guide →](docs/usage.md)
 
-- **Backend:** Python, FastAPI
-- **Frontend:** HTML, CSS, JavaScript
-- **Database:** Local storage as a class object, saved to a file using the pickle module.
-- **Storage:** Telegram
+## Try the public demo
 
-### Environment Variables
+**[Open the live demo](https://tgdrive.nexgenbots.us/)** · **Password:** `password12345`
 
-#### Required Variables
+Try TGDrive in your browser without installing anything. Explore the protected
+**Demo Files** collection, or upload disposable samples to **My Files** to try
+organizing, previews and sharing. Configuration and Management are visible, with
+changes locked.
 
-| Variable Name            | Type    | Example                   | Description                                                          |
-| ------------------------ | ------- | ------------------------- | -------------------------------------------------------------------- |
-| `API_ID`                 | integer | 123456                    | Your Telegram API ID                                                 |
-| `API_HASH`               | string  | dagsjdhgjfsahgjfh         | Your Telegram API Hash                                               |
-| `BOT_TOKENS`             | string  | 21413535:gkdshajfhjfakhjf | List of Telegram bot tokens for file operations, separated by commas |
-| `STORAGE_CHANNEL`        | integer | -100123456789             | Chat ID of the Telegram storage channel                              |
-| `DATABASE_BACKUP_MSG_ID` | integer | 123                       | Message ID of a file in the storage channel for database backups     |
+**The demo is shared.** Other visitors can change or delete files outside
+**Demo Files**. Use only disposable, non-private content.
+[Demo guide →](docs/usage.md#try-the-public-demo)
 
-> Note: All bots mentioned in the `BOT_TOKENS` variable must be added as admins in your `STORAGE_CHANNEL`.
+## See it in action
 
-> Note: `DATABASE_BACKUP_MSG_ID` should be the message ID of a file (document) in the `STORAGE_CHANNEL`.
+| Watch and read | Your drive on mobile |
+| :---: | :---: |
+| <img src="docs/assets/media-preview.png" alt="Video open in TGDrive's player" width="520"> | <img src="docs/assets/mobile-drive.png" alt="TGDrive file browser in a phone-sized browser viewport" width="240"> |
 
-#### Optional Variables
+[Explore the full screenshot gallery and video walkthroughs →](docs/showcase.md)
 
-| Variable Name          | Type                 | Default                                    | Description                                                                                                 |
-| ---------------------- | -------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
-| `ADMIN_PASSWORD`       | string               | admin                                      | Password for accessing the admin panel                                                                      |
-| `STRING_SESSIONS`      | string               | None                                       | List of Premium Telegram Account Pyrogram String Sessions for file operations                               |
-| `SLEEP_THRESHOLD`      | integer (in seconds) | 60                                         | Delay in seconds before retrying after a Telegram API floodwait error                                       |
-| `DATABASE_BACKUP_TIME` | integer (in seconds) | 60                                         | Interval in seconds for database backups to the storage channel                                             |
-| `MAX_FILE_SIZE`        | float (in GBs)       | 1.98 (3.98 if `STRING_SESSIONS` are added) | Maximum file size (in GBs) allowed for uploading to Telegram                                                |
-| `WEBSITE_URL`          | string               | None                                       | Website URL (with https/http) to auto-ping to keep the website active                                       |
-| `MAIN_BOT_TOKEN`       | string               | None                                       | Your Main Bot Token to use [TG Drive's Bot Mode](#tg-drives-bot-mode)                                       |
-| `TELEGRAM_ADMIN_IDS`   | string               | None                                       | List of Telegram User IDs of admins who can access the [bot mode](#tg-drives-bot-mode), separated by commas |
+<details>
+<summary>Watch the upload and sharing walkthrough</summary>
 
-> Note: Premium Client (`STRING_SESSIONS`) will be used only to upload files when file size is greater than 2GB.
+[![Watch the TGDrive upload and sharing walkthrough](docs/assets/drive-overview.png)](docs/assets/upload-and-share.mp4)
 
-> Note: File streaming/downloads will be handled by bots (`BOT_TOKENS`).
+[Open the video](docs/assets/upload-and-share.mp4) · [All walkthroughs](docs/showcase.md)
 
-> Note: Read more about TG Drive's Bot Mode [here](#tg-drives-bot-mode).
+Silent walkthroughs recorded at normal speed, with a visible cursor overlay,
+click highlights and step captions. The mobile image uses an emulated viewport,
+not a physical phone. See [capture notes](docs/assets/README.md).
 
-## Deploying Your Own TG Drive Application
+</details>
 
-### 1. Clone the Repository
+<details>
+<summary>Extra screenshots · uploads and transfers</summary>
 
-First, clone the repository and navigate into the project directory:
+![Expanded TGDrive upload panel showing device progress, speed and time remaining](docs/assets/upload-progress.png)
 
-```bash
-git clone https://github.com/TechShreyash/TGDrive
-cd TGDrive
-```
+</details>
 
-### 2. Set Up Your Environment Variables
+## Make it yours
 
-Create a `.env` file in the root directory and add the necessary [environment variables](#environment-variables).
+Choose where TGDrive runs. The app is free and open source, with all features
+included in every setup. You provide your own Telegram channel, bots and MongoDB
+database; hosting and database resources may have their own costs.
 
-> **Note:** Some hosting services allow you to set environment variables directly through their interface, which may eliminate the need for a `.env` file.
+| Where to run it | Get started |
+| --- | --- |
+| Your computer | [Local setup](docs/setup.md) for use while your computer is on |
+| Your own server | [Server deployment](docs/setup.md#hosting-beyond-your-machine) for a drive you can reach while your laptop is off |
+| A server we manage for you | [Optional managed hosting](docs/hosting.md#optional-managed-hosting) for help with setup and maintenance |
 
-### 3. Running TG Drive
+### Why host on a server?
 
-#### Deploying Locally
+A server lets you use your drive from other devices, share links with others and
+keep accepted transfers running while your laptop is off. TGDrive, MongoDB and
+Telegram must remain available, and recipients must be able to reach the app.
+[Compare running on your computer and a server →](docs/hosting.md#local-computer-or-server)
 
-1. Install the required Python packages:
+### Prefer help with hosting?
 
-   ```bash
-   pip install -U -r requirements.txt
-   ```
+We offer optional **managed TGDrive hosting from ₹100/month, including a
+server**. We handle deployment and ongoing maintenance, and provide a personal
+HTTPS subdomain. You keep full access to the server and TGDrive, using your own
+Telegram channel, bots and MongoDB account.
 
-2. Start the TG Drive application using Uvicorn:
+Explore [managed and server-only hosting](docs/hosting.md) for plans, capacity
+and ownership details, or [contact TechShreyash](https://t.me/TechShreyash).
 
-   ```bash
-   uvicorn main:app --host 0.0.0.0 --port 8000
-   ```
+## Find your guide
 
-#### Deploying Using Docker
+| What you want to do | Where to go |
+| --- | --- |
+| Learn the basics and find answers to common questions | [New-user guide and FAQs](docs/new-user-guide.md) (**must read**) |
+| Upload, organize, preview and share | [User guide](docs/usage.md) |
+| Back up your drive or recover after a failure | [Backup & recovery](docs/backup-recovery.md) |
+| Change settings, maintain the app or fix a problem | [Configuration](docs/configuration.md) · [Operations](docs/operations.md) |
+| Explore all guides, technical details and contributor resources | [Documentation home](docs/README.md) |
 
-1. Build the Docker image:
+## Updates and support
 
-   ```bash
-   docker build -t tgdrive .
-   ```
+Follow the [updates channel](https://t.me/TechZBots) for announcements, or join the
+[support group](https://t.me/TechZBots_Support) for help and discussion.
 
-2. Run the Docker container:
+## Contribute
 
-   ```bash
-   docker run -d -p 8000:8000 tgdrive
-   ```
+Contributions, feedback, bug reports and feature requests are always welcome.
+[Open an issue](https://github.com/TechShreyash/TGDrive/issues) or start with the
+[development guide](docs/development.md) and [contributor guidance](AGENTS.md).
+Include your release and reproduction steps in bug reports; remove credentials
+and private links.
 
-Access the application at `http://127.0.0.1:8000` or `http://your_ip:8000`.
-
-> **Note:** For more detailed information on deploying FastAPI applications, refer to online guides and resources.
-
-## Deploy Tutorials
-
-**Deploy To Render.com For Free :** https://youtu.be/S5OIi5Ur3c0
-
-<div align="center">
-
-[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/TechShreyash/TGDrive)
-
-</div>
-
-> **Note:** After updating the TG Drive code, clear your browser's cache to ensure the latest JavaScript files are loaded and run correctly.
-
-## TG Drive's Bot Mode
-
-TG Drive's Bot Mode is a new feature that allows you to upload files directly to your TG Drive website from a Telegram bot. Simply send or forward any file to the bot, and it will be uploaded to your TG Drive. You can also specify the folder where you want the files to be uploaded.
-
-To use this feature, you need to set the configuration variables `MAIN_BOT_TOKEN` and `TELEGRAM_ADMIN_IDS`. More information about these variables can be found in the [optional variables section](#optional-variables).
-
-Once these variables are set, users whose IDs are listed in `TELEGRAM_ADMIN_IDS` will have access to the bot.
-
-### Bot Commands
-
-- `/set_folder` - Set the folder for file uploads
-- `/current_folder` - Check the current folder
-
-### Quick Demo
-
-Bot Mode - Youtube Video Tutorial : https://youtu.be/XSeY2XcHdGI
-
-#### Uploading Files
-
-1. Open your main bot in Telegram.
-2. Send or forward a file to this bot, and it will be uploaded. By default, the file will be uploaded to the root folder (home page).
-
-#### Changing Folder for Uploading
-
-1. Send the `/set_folder` command and follow the instructions provided by the bot.
-
-## Important Posts Regarding TG Drive
-
-Stay informed by joining our updates channel on Telegram: [@TechZBots](https://telegram.me/TechZBots). We post updates, guides, and tips about TG Drive there.
-
-- https://telegram.me/TechZBots/891
-- https://telegram.me/TechZBots/876
-- https://telegram.me/TechZBots/874
-- https://telegram.me/TechZBots/870
-
-## Contributing
-
-Contributions are welcome! Fork the repository, make your changes, and create a pull request.
-
-## License
-
-This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
-
-## Support
-
-For inquiries or support, join our [Telegram Support Group](https://telegram.me/TechZBots_Support) or email [techshreyash123@gmail.com](mailto:techshreyash123@gmail.com).
+[MIT License](LICENSE)
diff --git a/compose.override.yaml b/compose.override.yaml
new file mode 100644
index 00000000..eceb7104
--- /dev/null
+++ b/compose.override.yaml
@@ -0,0 +1,13 @@
+# Automatically loaded by local `docker compose` commands.
+# Coolify passes -f compose.yaml, so it does not load this local-only override.
+services:
+    app:
+        image: tgdrive:local
+        # Local installations start only when requested, including after a reboot.
+        restart: ${TGDRIVE_RESTART_POLICY:-no}
+        environment:
+            COOKIE_SECURE: ${COOKIE_SECURE:-false}
+            TGDRIVE_PROXY_HOSTS: ""
+            FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-127.0.0.1}
+        ports:
+            - "${BIND_ADDRESS:-127.0.0.1}:${PORT:-8000}:8000"
diff --git a/compose.server.yaml b/compose.server.yaml
new file mode 100644
index 00000000..4be63859
--- /dev/null
+++ b/compose.server.yaml
@@ -0,0 +1,10 @@
+# For a server with its own HTTPS reverse proxy (Coolify uses compose.yaml alone).
+# Always use: docker compose -f compose.yaml -f compose.server.yaml <command>
+services:
+    app:
+        environment:
+            COOKIE_SECURE: "true"
+            TGDRIVE_PROXY_HOSTS: ""
+            FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-127.0.0.1}
+        ports:
+            - "127.0.0.1:${PORT:-8000}:8000"
diff --git a/compose.yaml b/compose.yaml
new file mode 100755
index 00000000..ff05c8b5
--- /dev/null
+++ b/compose.yaml
@@ -0,0 +1,53 @@
+# Coolify: choose Docker Compose and /compose.yaml. No host ports are published.
+# Local docker compose commands also load compose.override.yaml automatically.
+name: tgdrive
+
+services:
+    app:
+        build:
+            context: .
+            dockerfile: Dockerfile
+        restart: ${TGDRIVE_RESTART_POLICY:-unless-stopped}
+        init: true
+        expose:
+            - "8000"
+        env_file:
+            - path: .env
+              required: false
+        environment:
+            MONGODB_URI: ${MONGODB_URI:?Set MONGODB_URI}
+            API_ID: ${API_ID:?Set API_ID}
+            API_HASH: ${API_HASH:?Set API_HASH}
+            MAIN_BOT_TOKEN: ${MAIN_BOT_TOKEN:-}
+            TELEGRAM_ADMIN_IDS: ${TELEGRAM_ADMIN_IDS:-}
+            STORAGE_CHANNEL: ${STORAGE_CHANNEL:?Set STORAGE_CHANNEL}
+            ADMIN_PASSWORD: ${ADMIN_PASSWORD:-}
+            # Container paths and hosting policy stay fixed across deployments.
+            DATA_DIR: /app/data
+            CACHE_DIR: /app/cache
+            COOKIE_SECURE: "true"
+            TGDRIVE_AUTO_SECRETS: "true"
+            TGDRIVE_PROXY_HOSTS: coolify-proxy
+            FORWARDED_ALLOW_IPS: ${FORWARDED_ALLOW_IPS:-auto}
+        # Coolify attaches declared middleware to its generated domain routers.
+        # Apply at the edge too: Traefik can append HTTP/3 advertisements to app headers.
+        labels:
+            - "traefik.http.middlewares.tgdrive-alt-svc.headers.customresponseheaders.Alt-Svc=clear"
+        volumes:
+            - tgdrive-data:/app/data
+            - tgdrive-cache:/app/cache
+        stop_grace_period: 60s
+        security_opt:
+            - no-new-privileges:true
+        cap_drop:
+            - ALL
+        pids_limit: 256
+        logging:
+            driver: local
+            options:
+                max-size: "10m"
+                max-file: "3"
+
+volumes:
+    tgdrive-data:
+    tgdrive-cache:
diff --git a/config.py b/config.py
deleted file mode 100644
index 83c0b117..00000000
--- a/config.py
+++ /dev/null
@@ -1,60 +0,0 @@
-from dotenv import load_dotenv
-import os
-
-# Load environment variables from the .env file, if present
-load_dotenv()
-
-# Telegram API credentials obtained from https://my.telegram.org/auth
-API_ID = int(os.getenv("API_ID"))  # Your Telegram API ID
-API_HASH = os.getenv("API_HASH")  # Your Telegram API Hash
-
-# List of Telegram bot tokens used for file upload/download operations
-BOT_TOKENS = os.getenv("BOT_TOKENS", "").strip(", ").split(",")
-BOT_TOKENS = [token.strip() for token in BOT_TOKENS if token.strip() != ""]
-
-# List of Premium Telegram Account Pyrogram String Sessions used for file upload/download operations
-STRING_SESSIONS = os.getenv("STRING_SESSIONS", "").strip(", ").split(",")
-STRING_SESSIONS = [
-    session.strip() for session in STRING_SESSIONS if session.strip() != ""
-]
-
-# Chat ID of the Telegram storage channel where files will be stored
-STORAGE_CHANNEL = int(os.getenv("STORAGE_CHANNEL"))  # Your storage channel's chat ID
-
-# Message ID of a file in the storage channel used for storing database backups
-DATABASE_BACKUP_MSG_ID = int(
-    os.getenv("DATABASE_BACKUP_MSG_ID")
-)  # Message ID for database backup
-
-# Password used to access the website's admin panel
-ADMIN_PASSWORD = os.getenv("ADMIN_PASSWORD", "admin")  # Default to "admin" if not set
-
-# Determine the maximum file size (in bytes) allowed for uploading to Telegram
-# 1.98 GB if no premium sessions are provided, otherwise 3.98 GB
-if len(STRING_SESSIONS) == 0:
-    MAX_FILE_SIZE = 1.98 * 1024 * 1024 * 1024  # 2 GB in bytes
-else:
-    MAX_FILE_SIZE = 3.98 * 1024 * 1024 * 1024  # 4 GB in bytes
-
-# Database backup interval in seconds. Backups will be sent to the storage channel at this interval
-DATABASE_BACKUP_TIME = int(
-    os.getenv("DATABASE_BACKUP_TIME", 60)
-)  # Default to 60 seconds
-
-# Time delay in seconds before retrying after a Telegram API floodwait error
-SLEEP_THRESHOLD = int(os.getenv("SLEEP_THRESHOLD", 60))  # Default to 60 seconds
-
-# Domain to auto-ping and keep the website active
-WEBSITE_URL = os.getenv("WEBSITE_URL", None)
-
-
-# For Using TG Drive's Bot Mode
-
-# Main Bot Token for TG Drive's Bot Mode
-MAIN_BOT_TOKEN = os.getenv("MAIN_BOT_TOKEN", "")
-if MAIN_BOT_TOKEN.strip() == "":
-    MAIN_BOT_TOKEN = None
-
-# List of Telegram User IDs who have admin access to the bot mode
-TELEGRAM_ADMIN_IDS = os.getenv("TELEGRAM_ADMIN_IDS", "").strip(", ").split(",")
-TELEGRAM_ADMIN_IDS = [int(id) for id in TELEGRAM_ADMIN_IDS if id.strip() != ""]
diff --git a/docker_start.sh b/docker_start.sh
deleted file mode 100644
index eedb5dc8..00000000
--- a/docker_start.sh
+++ /dev/null
@@ -1,3 +0,0 @@
-docker stop tgdrive
-docker build -t tgdrive .
-docker run -d --name tgdrive -p 80:80 tgdrive
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..e606350f
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,50 @@
+<h1><img src="../website/public/static/brand/tgdrive-icon.svg" alt="" width="36" height="36"> TGDrive documentation</h1>
+
+**Must read before using TGDrive: [New-user guide and FAQs](new-user-guide.md).**
+Learn the basics and find answers to common questions about using TGDrive.
+Then [try the public demo](usage.md#try-the-public-demo) or follow [Setup](setup.md).
+These guides describe TGDrive 2.0.0 with MongoDB. The setup guide explains the
+stable `main` source and version-pinned release options; `dev` may be unstable.
+
+**[Explore the screenshot gallery and video walkthroughs](showcase.md)** for a
+visual tour of the file browser, transfers, previews, sharing and administration.
+
+| I want to… | Read |
+| --- | --- |
+| Learn the basics and find answers to common questions | [New-user guide and FAQs](new-user-guide.md) (**must read**) |
+| Try TGDrive before hosting it | [Live demo and password](usage.md#try-the-public-demo) |
+| Compare local use, access on the go and background processing | [Local computer or server?](hosting.md#local-computer-or-server) |
+| Run locally on Windows, macOS or Linux | [Docker installation](setup.md#before-you-start) · [TGDrive setup](setup.md#4-start-locally) |
+| Manage deployment on my own server | [Free, self-hosted Coolify](setup.md#coolify) · [Server Compose](setup.md#docker-compose-on-a-server) |
+| Get help running TGDrive | [Optional managed hosting](hosting.md#optional-managed-hosting) · [What you prepare](hosting.md#what-you-prepare) |
+| Keep my drive after hosting expires | [Move to a laptop or another server](operations.md#when-a-hosting-plan-expires) |
+| Offer a public demo with settings locked | [Public demo mode](configuration.md#public-demo-mode) |
+| Upload, browse, preview or share | [User guide](usage.md) |
+| Read ebooks/comics or understand covers | [Readers](reading.md) · [Thumbnails and rebuilds](thumbnails.md) |
+| Change settings or look up cache and transfer policies | [Configuration](configuration.md) · [Performance policies](performance.md) |
+| Diagnose load, queues or cache needs before upgrading | [Load and capacity guide](performance-tuning.md) |
+| Restart, upgrade or fix a problem | [Operations](operations.md) |
+| Protect files or recover a drive | [Backup & recovery](backup-recovery.md) |
+
+Keep originals until **Completed**. **You can close this tab** means the server
+has accepted the files; TGDrive must keep running to finish processing them.
+
+<details>
+<summary>Contributor and technical documentation</summary>
+
+| Topic | Guide |
+| --- | --- |
+| Components, data flow and durability | [Architecture](architecture.md) |
+| Environment variables and API contracts | [Reference](reference.md) |
+| Source layout, build commands and validation | [Development](development.md) · [Repository map](development.md#repository-map-and-test-map) |
+| Interface styling, branding and accessibility | [Frontend contracts](development.md#frontend-contracts) |
+| Source artifacts and release checks | [Release verification](release.md) |
+| Implemented features and remaining gaps | [Roadmap](roadmap.md) |
+| Dated playback measurements | [Streaming validation](streaming-validation-2026-10-18.md) |
+| Record or replace screenshots and videos | [Media capture guide](assets/README.md) |
+
+Follow [contributor guidance](../AGENTS.md). Keep each topic in one place and link
+to it. Documentation describes behavior; [validation evidence](development.md#ci-and-release-evidence)
+records what was actually tested.
+
+</details>
diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 00000000..de987edd
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,538 @@
+# How TGDrive works
+
+[Docs home](README.md) · [API reference](reference.md#http-api) · [Performance](performance.md)
+
+Where files live, which work survives a restart, and how one drive stays consistent.
+
+For the user-facing screens around these flows, see the
+[visual walkthroughs](showcase.md).
+
+**Contents**
+
+- [The short version](#the-short-version)
+- [Components](#components)
+- [Authoritative data and identity](#authoritative-data-and-identity)
+  - [How a write becomes visible](#how-a-write-becomes-visible)
+- [Lifecycle](#lifecycle)
+- [Account identity and selection](#account-identity-and-selection)
+  - [Names and Refresh](#names-and-refresh)
+- [Connection management](#connection-management)
+- [Demo access boundaries](#demo-access-boundaries)
+- [Transfer pipeline](#transfer-pipeline)
+  - [From a browser to one drive file](#from-a-browser-to-one-drive-file)
+  - [Adaptive device upload concurrency](#adaptive-device-upload-concurrency)
+  - [Bounds and retries](#bounds-and-retries)
+  - [Cancellation and destination changes](#cancellation-and-destination-changes)
+  - [Finished history](#finished-history)
+- [Telegram transport and file responses](#telegram-transport-and-file-responses)
+- [Media and performance](#media-and-performance)
+- [Database safety copies and security](#database-safety-copies-and-security)
+  - [Independent backup pacing and verification](#independent-backup-pacing-and-verification)
+  - [Shared-link identity and re-copying](#shared-link-identity-and-re-copying)
+- [Diagnostic history](#diagnostic-history)
+
+## The short version
+
+```mermaid
+flowchart LR
+    Browser <-->|Files and API| Server["TGDrive server"]
+    Server <-->|Original file bytes| Telegram
+    Server <-->|Catalog and durable work| MongoDB
+    Server -.->|Encrypted database copies| Telegram
+```
+
+**Telegram holds file bytes; MongoDB holds the catalog, settings and durable work.**
+TGDrive also sends encrypted database copies to Telegram in the background.
+
+Run **one installation and one FastAPI worker per drive**. Background work runs
+inside that process without Redis or a separate task broker. Accepted server
+jobs continue without the browser while TGDrive stays running.
+
+## Components
+
+<details>
+<summary>Code map</summary>
+
+Backend packages are grouped by responsibility under `tgdrive/`. Import concrete
+modules from their owning package; package initializers do not load services.
+
+| Package | Responsibility |
+| --- | --- |
+| `core/` | Configuration, lifecycle, security, errors and deployment policy |
+| `web/` | Application factory, HTTP routes, schemas, guards and share links |
+| `storage/` | Catalog, MongoDB and file-part records |
+| `telegram/` | Client pools, account identity, channel access and bot mode |
+| `transfers/` | Durable jobs, upload receipts, staging, split uploads and URL imports |
+| `media/` | Range delivery, shared cache, scheduling, previews, readers and thumbnails |
+| `settings/` | Managed preferences, connection management and Premium login |
+| `recovery/` | Portable catalog validation, complete database backups and website archive restore |
+| `replication/` | Independent channel copies, private journal and recovery activation |
+| `observability/` | Resource metrics, traffic, history and performance endpoints |
+
+`server.py` launches the container's web application. Initialization runs in the
+application lifecycle; administration and recovery use the website. The frontend
+and test layout is described in the
+[repository map](development.md#repository-map-and-test-map).
+
+</details>
+
+## Authoritative data and identity
+
+**MongoDB is the source of truth**, including on laptops. The in-memory catalog
+is an immutable read cache: it speeds up reads, while MongoDB keeps the saved
+state. Durable collections hold nodes and ordered parts,
+shares, operation IDs, jobs and receipts, deletion intents, private settings and
+sessions, backup records and the runtime ownership lease.
+
+- Paths use stable item IDs: moves and renames retain identity.
+- Names are Unicode-normalized with case-insensitive sibling uniqueness.
+- Files reference one Telegram document or ordered parts with offsets, sizes
+  and checksums. Public listings hide those locations.
+- Schema version 4 tracks revision/commit generation. Catalog bounds are
+  128 levels and 250,000 items.
+
+MongoDB is required; the application has no SQLite catalog backend fallback.
+Only the current portable schema (4) is accepted for channel recovery.
+Snapshots must include their drive identity and share records. TGDrive does not
+import v1 pickle data or upgrade older catalog schemas.
+
+### How a write becomes visible
+
+1. Change an isolated working copy.
+2. In a MongoDB transaction, check ownership and generation, then commit with
+   majority acknowledgement. Unique indexes enforce active sibling names.
+3. Publish the new read cache.
+
+Failure preserves the earlier visible state. Uncertain acknowledgement reloads
+MongoDB authority before further work.
+
+## Lifecycle
+
+| Event | Behavior |
+| --- | --- |
+| Startup | Validate required MongoDB configuration and connectivity, acquire ownership, initialize a pristine database or load the existing catalog, start clients/jobs |
+| Invalid/unreachable MongoDB | Reject startup; saved local recovery settings do not bypass database access |
+| Missing catalog with prior state | Preserve it for explicit owner recovery; never replace it with an empty drive |
+| Lost ownership | Stop admitting writes; repair and restart safely |
+| Shutdown | Persist interrupted work, stop tasks, release resources/ownership |
+| Reinstall | Reuse the same MongoDB database and deployment identity |
+
+The cloud lease renews in the background and is checked inside writes.
+Recovery of unfinished uploads still requires their local staged bytes.
+Automatic initialization runs only under the ownership lock and refuses saved
+drive records or recovery state. The catalog, channel binding and initial
+connection settings commit in one transaction. Those initial connections are
+active in the same process; first setup does not ask for another restart.
+The local channel recovery journal and portable
+catalog validation helpers are internal mechanisms, not alternate live databases.
+`DATA_DIR/mongodb-drive.json` remembers that a drive has been opened; losing its
+MongoDB catalog cannot then be mistaken for a first deployment on that volume.
+
+Full archive recovery runs from the website. After authentication and archive
+validation, it pauses writers, reacquires exclusive MongoDB ownership and
+atomically restores an empty or untouched initial drive. Successful recovery
+revokes browser sessions; a service restart reloads saved credentials and state.
+
+## Account identity and selection
+
+Uploads default to **one slot per bot** (**1–4** allowed); Premium clients keep
+one each. FIFO admission selects least-active eligible clients, preferring ready
+Premium slots with bot fallback. Uploads/reads share account media/request budgets,
+channel pacing and persisted FloodWait deadlines. Demand precedes queued preloads
+without preempting running work. Download requests rotate their queued blocks
+after each admission; see [shared-download scheduling](performance.md#shared-download-load-and-queues)
+and [performance controls](performance.md#upload-pipeline-and-smaller-splits).
+
+<details>
+<summary>Identity, live limits and account failures</summary>
+
+- Slots scale with connected accounts, independently of local I/O. Lower limits
+  drain existing leases; higher limits wake eligible waiters.
+- Upload preferences load from MongoDB before recovery and enter full backups.
+- New documents use at most **2000 MiB**, including Premium; split preference
+  `0` uses that same cap. Smaller preferences reduce part size.
+- Initial lookup may prefer healthy Premium users. Independent payload windows
+  bind the same immutable media through eligible accounts.
+- Stable account IDs survive bot-token reordering. A dispatched part retains its
+  sender and request ID on retry; undispatched parts may change sender.
+- Credential/channel failures quarantine the account and wake waiters. Reads try
+  eligible accounts; dispatched uploads keep durable identities and report repair
+  errors. Verified channel repair can re-enable live clients; new credentials need
+  restart.
+
+</details>
+
+### Names and Refresh
+
+<details>
+<summary>Credential checks, cached names and retries</summary>
+
+Startup fills missing names from authenticated accounts. **Connections → Refresh**
+checks saved credentials/channel permissions through temporary sessions without
+test messages. At most two checks run at once; repeated clicks share work. Transient
+failures allow three attempts, respecting persisted waits. Cached names survive
+failure; probes remain separate from socket health. Settings changes/shutdown
+cancel obsolete checks.
+
+</details>
+
+## Connection management
+
+Temporary clients verify the owner's revision-guarded candidate accounts/channel
+permissions before an atomic private-settings save. New mutations pause until
+restart. Editing needs settled jobs/receipts and valid ownership, without requiring
+a Telegram database backup.
+
+Secrets are write-only; omitted replacements keep saved values. Premium login uses
+owner-bound five-minute in-memory challenges. Codes/passwords are not stored;
+sessions enter private settings, never the browser. Cancelled, expired or unsaved
+authorizations are revoked.
+
+## Demo access boundaries
+
+Demo mode keeps one shared drive with two session capabilities. The usual
+password grants visitor access; an optional separate demo administrator password
+grants full access. Its session signature uses a separate credential-bound key,
+so clients cannot promote a visitor cookie and credential rotation revokes the
+corresponding access. Deployment-only demo administrator credentials are
+excluded from saved bootstrap settings. See [authentication](reference.md#owner-authentication).
+
+At startup, demo mode creates a catalog folder with reserved identity
+`tgdrive-demo-files`. A request-scoped write policy reaches worker threads and
+background jobs. MongoDB checks its current ancestry within each write
+transaction, including ancestor operations that would remove or move protected
+content. Upload and job controls also preflight destinations before work starts.
+Durable jobs retain the visitor policy and restore it on resume while demo mode
+is enabled. Full-access retries can explicitly replace that policy. This keeps
+accepted work subject to the same sample protection after the browser closes
+or TGDrive restarts.
+
+The UI reads effective session permissions with uncached configuration, waits
+for them before enabling management, and clears them when a session ends.
+Once loaded, configuration refreshes preserve mounted settings drafts even on
+failure; management stays disabled until the refresh succeeds. Authentication
+errors are tied to the request's login generation, so a delayed response from
+an older session cannot dismiss a newer login.
+Protected changes return a dedicated error that opens a read-only popup.
+Visitor steps and deployment limits live in [public demo mode](configuration.md#public-demo-mode).
+
+## Transfer pipeline
+
+Browser receiving and Telegram dispatch run independently. Each completed receipt
+creates a durable job without waiting for its batch. Device receives start at two
+files and adapt between one and four; staging, disk headroom and the 1,000
+unfinished-receipt bound gate admission.
+
+Device slots rotate between eligible batches. A new receipt reuses the creation
+response; existing receipts fetch their confirmed offset and checksums before
+resuming. After the last chunk is acknowledged, the device slot admits another
+file while a separate lane runs at most two completion requests. This overlaps
+payload reception with verification and durable job handoff without unbounded
+completion requests. Files retain their local source and tab-close protection
+until the server confirms a job identity.
+
+MongoDB receipt creation reserves staging on the event loop before a worker
+synchronizes the new file and commits its receipt. Other admissions see that
+reservation while persistence is pending, preventing competing admissions from
+overbooking storage. Disconnects drain that worker; an uncertain
+database acknowledgement retains the file and reservation until reconciliation
+or expiry. Job lifecycle writes also run in workers, with acknowledgements awaited
+in journal order before dispatch continues. Job reads use memory while a write
+is pending and expose the last acknowledged lifecycle state; a new job is hidden
+until its first commit. Slow MongoDB can still delay admission and state transitions.
+Cancellation intent is saved before signalling workers; a rejected commit keeps
+the prior state authoritative. Staged receipt bytes remain until completion is
+acknowledged, including while its final job-state write is pending.
+
+Display follows a browser-wide device-first boundary: while any local upload
+still needs receipt, pending upload groups show device metrics or **Received**
+for accepted files, with Telegram metrics hidden. Once all remaining local files
+are server-owned, their Telegram metrics appear together. Telegram jobs run
+throughout; this presentation boundary does not delay dispatch.
+
+Batch ETA uses fresh per-file rates, falling back to a rolling measurement of the
+batch's current-stage byte counter. File handoffs do not discard that measurement;
+it expires after 15 seconds without byte progress. A stage switch, changed batch
+membership/total or regressing counter resets its baseline. Restored snapshots
+alone supply no observed rate. A byte-complete file publishing alongside other
+uploads does not suppress their estimate. Blocking retries/errors and unmeasured
+final confirmation/publication are excluded from byte-based ETA claims.
+
+### From a browser to one drive file
+
+1. Receive fixed-size chunks into local staging.
+2. Flush bytes, then commit the offset/checksum receipt in MongoDB.
+3. Verify chunks and create or reuse one durable job.
+4. Send one Telegram document or ordered parts.
+5. Publish the logical file once using its stable operation ID.
+6. Confirm the database state, report completion and release staging.
+
+A lost response resumes at the acknowledged offset; reselected files must match
+saved checksums, not just names and sizes. Fully received files finish verification
+and enqueue after a completion-request disconnect; polling recovers their job ID.
+The job's first durable record includes its staged path, destination, name and
+upload identity. A restart between job creation and receipt handoff can therefore
+resume the existing job while the staged bytes survive.
+
+Browser recovery metadata is saved per transfer, and finished-job dismissals per
+job, so another tab cannot replace the whole recovery list. Malformed entries
+produce a warning without hiding valid transfers. This metadata does not contain
+the original device files; clearing browser storage or losing staged bytes can
+still require selecting the originals again.
+
+| Signal | Guarantee |
+| --- | --- |
+| Full device progress | Bytes sent; handoff may still be pending |
+| **You can close this tab** | All remaining uploads have accepted server jobs |
+| **Completed** | Safe point for deleting local originals |
+
+Database backups exclude unfinished staged bytes.
+
+Receipt code: [uploads.py](../tgdrive/transfers/uploads.py). Browser handoff:
+[transfers.ts](../website/src/features/transfers/transfers.ts),
+[deviceUploadStatus.ts](../website/src/features/transfers/deviceUploadStatus.ts).
+
+### Adaptive device upload concurrency
+
+The browser measures aggregate payload throughput independently of Telegram slots.
+Freed slots admit eligible files immediately; reductions let active files finish.
+
+<details>
+<summary>Controller thresholds</summary>
+
+| Policy | Value |
+| --- | --- |
+| Start/range/reset after queue drains | 2 / 1–4 / 2 files |
+| Sample | 4-second HTTP PATCH payload windows; confirmed-byte fallback |
+| Eligible window | Ready backlog; payload occupies ≥70% of receive slots |
+| Probe | After 2 stable windows (within 25% of baseline), add one file |
+| Keep increase | Next 2 eligible windows gain ≥10% aggregate throughput |
+| Degradation | Reduce after 2 nonzero windows below 65% of baseline |
+| Stall | Reduce after 15 seconds without previously observed payload progress |
+| Pressure | Network errors or HTTP 408/429/500/502/503/504 before handoff |
+| Settle before another probe | 30 seconds after pressure/failed probe; 12 after success |
+| Discard measurements | Hidden/paused, sample gaps or windows >12 seconds |
+
+Waiting for first progress or a sent body's acknowledgement is not a stall.
+Hashing, resume offsets and Telegram work are excluded. Authentication,
+cancellation, checksum and storage failures do not lower the limit.
+See [deviceUploadConcurrency.ts](../website/src/features/transfers/deviceUploadConcurrency.ts).
+
+</details>
+
+### Bounds and retries
+
+<details>
+<summary>Admission, retry identities and restart boundaries</summary>
+
+- HTTP 429 pauses new device admission globally; 507 defers only that file.
+  Both retain source/offset and retry after at least five seconds or the longer
+  `Retry-After`. The controller retains at most 2,000 unfinished batch rows.
+- Known device receipts retry network failures, HTTP 408/500/502/503/504 and
+  `UPLOAD_OFFSET_CHANGED` conflicts up to three times without further confirmed
+  byte progress. Delays are 2, 4 and 8 seconds, respecting a longer `Retry-After`.
+  Each retry checks the server offset and verifies the original file's confirmed
+  prefix; it also reconciles a lost completion response with the existing job.
+  Confirmed byte progress or a manual retry resets the retry budget. Other
+  conflicts, authentication failures and checksum mismatches need owner action.
+  Creation without a returned receipt ID is not replayed automatically.
+- Chunk requests time out after 60 seconds without increasing sent bytes or a
+  server response. Progress renews that interval, allowing slow transfers to
+  continue beyond 60 seconds in total. Resume HEAD and receipt JSON requests
+  have 60-second request deadlines. Retry requires the tab and local source;
+  closing the tab still requires reselecting the originals later.
+- Folder preparation creates an atomic, repeatable tree; its files then succeed
+  or fail independently. Listing refreshes are coalesced without losing rows,
+  selection, focus, pagination or scroll.
+- Multipart workers follow eligible account capacity and check live increases
+  each second. Database backups are separately serialized.
+- Confirmed remote identities survive retry. Catalog operation lookup reconciles
+  a committed file whose job-journal update was interrupted.
+- Bounded 512 KiB upload RPCs share request/rate admission with downloads and
+  metadata. Provider waits are respected, never bypassed by rotating identities.
+- Confirmed documents survive restart. Partial-document RPC acknowledgements can
+  survive in-process retry; unfinished payload uploads restart after process exit.
+- File finalization does not wait for an encrypted snapshot. Completed catalog
+  entries cannot be cancelled as unsent media.
+
+</details>
+
+### Cancellation and destination changes
+
+| Situation | Result |
+| --- | --- |
+| Cancel before/after dispatch | Reclaim local work / reconcile and clean up remote outcome first |
+| Destination moved | Follow stable folder ID |
+| Receiving destination trashed | Retain acknowledged bytes; restore or cancel |
+| Destination gone before commit | Cancel/reconcile unpublished remote work |
+| Database persistence fails | Retain staged bytes and remote identities for retry |
+| URL retrieval interrupted | May fetch again from byte zero; live byte progress is advisory, while reservations and lifecycle changes are journaled |
+| Bot-mode ingestion | Separate path without the browser queue's full durability contract |
+
+URL starts return a job before source I/O. A separate scheduler grants full-speed
+source slots and paces bounded waiting connections; validated ranges share an
+unpublished staging file. Promotion preserves the sequential prefix. Workers drain
+before that file can close or a fallback can truncate it. Source retrieval releases
+its slot before Telegram upload. See [URL intake](performance.md#url-import-intake)
+for scheduling, representation checks, storage claims and expiry limits.
+
+Permanent deletion journals intent, then atomically removes the subtree/shares
+and drops completed-intent message references. **Original Telegram messages remain**,
+for every file age and retry. Reconciliation, lineage and independent-backup
+barriers still apply; different selected items complete independently.
+
+### Finished history
+
+Resolved jobs stay in a paged history, separate from temporary browser popups.
+The Transfers page's **Clear history** removes finished display history;
+see [the workflow](usage.md#transfer-history).
+
+<details>
+<summary>Compaction, browser ownership and destination lookup</summary>
+
+Resolved upload/import jobs become eligible for compaction after
+`TRANSFER_TTL_SECONDS`; new admissions or explicit cleanup archive eligible live
+records. Job polling does not perform journal writes. Archives enter full
+backups, omit private recovery context and cannot
+be retried as live jobs. Folder uploads carry one explicit identity through
+receipt, job and archive; ordinary files and URL imports retain separate task
+identities. Task status and search matching are determined before pagination,
+and every member of a selected folder is returned together. Completed children
+of a running folder do not become a separate finished task.
+
+The Transfers page shows 20 finished tasks per numbered page. Browser-owned
+finished tasks consume page slots before server history; an explicit server
+offset fills the remaining slots. Folder exclusions keep a partially received
+local folder out of server-only finished counts. Grouping uses the explicit
+folder-selection metadata persisted with each current upload.
+
+Exact task totals scan archived summaries in batches on a worker, holding task
+summaries and the selected folders' members rather than every archived job.
+Numbered reads are O(history size); the indexed cursor API is also
+available. Startup does not load the full archive. Dismissing a deletion popup does
+not clear history; deletion notices stay separate.
+
+Manual history clearing deletes archived summaries and persists a hidden marker
+on terminal live jobs, preserving their recovery contexts, staged-byte ownership
+and backup barriers. Hidden jobs stay out of history and are not archived when
+pruned. Job polling marks them `history_cleared` so other browsers can reconcile
+completion before removing their rows. A job that resumes or is retried becomes
+visible again.
+Queued/running jobs and members of unfinished folders are excluded. The browser
+also excludes folders still receiving device files and removes its finished
+receipts only after the server confirms success. Failed requests leave browser
+rows available for retry; a partially completed server clear is safe to repeat.
+
+Browser `initiatedHere` markers scope floating panels; global history includes
+other browsers. URL imports retain server identity/origin across reloads without
+requesting local files. Stable node IDs and the catalog cache resolve destinations.
+Show in Folder resolves again, follows moves and rejects trashed/deleted items
+before revealing the correct list page.
+
+</details>
+
+## Telegram transport and file responses
+
+Telethon with cryptg uses MTProto, distinct from the hosted HTTP Bot API. Requests
+authenticate before origin/cache access. Logical ranges cross part boundaries;
+complete parts verify checksums, partial reads verify identity/size. Expired
+references refresh from stored messages with bounded retries. Disconnect/failure
+closes iterators and leases; missing media or failures after headers can interrupt
+responses. Successful finite playback ranges retain a logical viewer for up to
+5 seconds to bridge to the next request. Abort or expiry stops owned partial
+background warming; the existing byte and capacity bounds still apply. Every
+new HTTP request reauthorizes and validates metadata before reusing server blocks.
+
+## Media and performance
+
+Uploads retain original document bytes. Text previews read at most 256 KiB;
+local PDF.js uses bounded lazy ranges up to 256 MiB; SVG uses a passive image;
+video uses the local Movi/WASM player. Unsupported files retain original downloads.
+Quality choices exist only for representations actually present in Telegram.
+
+[Performance](performance.md) owns cache budgets, shared fills, adaptive read-ahead,
+preload qualification, eviction and diagnostics. Preloads are disposable
+acceleration, never catalog commits or backups. Authorization precedes cached
+bytes and is rechecked before future shared-stream blocks; revocation cannot
+recall bytes already sent.
+
+The player's compressed source buffer grows toward a time goal within a device
+memory budget; see the [browser buffer policy](performance.md#browser-playback-buffer).
+Growth preserves downloaded bytes. This source budget is not a decoder-memory
+cap. The custom
+player handles loading/errors, local styles, tracks, chapters and source changes;
+its buffered time estimates differ from server cache coverage. Neither extra
+bots nor a cache guarantees codec/device playback speed.
+
+## Database safety copies and security
+
+Background backups read consistent durable collections, compress/encrypt with
+AES-256-GCM, journal the encrypted source identity, and verify received ciphertext
+before confirmation. Restore requires the matching key and an empty or untouched
+automatically initialized database; it revokes browser sessions. Archives omit
+original Telegram media and staged payloads. See [recovery](operations.md#encrypted-telegram-backups),
+[independent channel protection](backup-recovery.md) and
+[security](reference.md#security-and-privacy).
+
+### Independent backup pacing and verification
+
+The optional second-channel transport uses fixed policies, separate from normal
+upload tuning. For setup, status meanings and recovery actions, use the
+[backup guide](backup-recovery.md#enable-and-confirm-the-first-copy).
+
+| Policy | Behavior |
+| --- | --- |
+| Operation pacing | One-second gap between explicit Telegram metadata reads, sends and verification calls. Each FloodWait doubles it, up to four seconds. A confirmed checkpoint resets it to one second. |
+| Retry verification | Recheck confirmed destination documents in batches of at most 32 parts, with a fresh channel inspection and grouped message read per batch. |
+| Idle checks | Recheck healthy unchanged checkpoints after one hour. Catalog, file or recovery-setting changes do not wait for that interval. |
+
+Replacement connections share the current pacer. A process restart resets its gap
+to one second, but persisted Telegram retry deadlines must still expire before
+work resumes. Telegram can require longer waits than the configured gaps.
+Recovery bundles are sent separately and downloaded for checksum verification;
+their internal chunk transfers retain Telethon's normal behavior.
+
+Missing, wrong-channel, protected or changed-size documents block confirmation.
+Only input peer references are cached within a connection; channel privacy,
+permissions and auto-delete checks remain fresh. New copies verify their
+destination documents and retain saved send identities. Confirmed mappings and
+provider deadlines survive restart.
+
+The backup bot reuses its private session under `DATA_DIR/sessions`, with
+owner-only permissions. Changing the bot token or API credentials selects a
+separate session; a missing or invalidated session can also require sign-in.
+Authorization-probe failures preserve Telegram's wait without starting another
+sign-in. Idle health-check waits retain the confirmed restore point and are
+identified separately in activity messages.
+
+Explicit **Sync** requests an earlier check but cannot bypass a saved deadline.
+A failed check's saved retry time governs the next attempt. Destructive Telegram
+operations need a fresh checkpoint check; the hourly idle check does not satisfy
+that barrier. Browser status refresh remains read-only.
+
+**Pause** and **Disable** remain effective after an in-flight failure; the retry
+deadline is still saved and **Resume** cannot bypass it. Destructive Telegram
+operations recheck backup controls after waiting and after checkpoint
+verification, so a concurrent pause keeps them blocked.
+
+### Shared-link identity and re-copying
+
+Shares resolve stable item IDs and current scope, so explicit links survive
+moves/renames. Owner listings include expired links; access and exposure warnings
+use active shares only. Secret rotation prevents reconstructing existing URLs
+without revoking them; retain those URLs or explicitly create replacements.
+
+<details>
+<summary>How TGDrive reconstructs an existing share URL</summary>
+
+Re-copying derives capabilities from a random share ID and persistent owner
+secret with domain-separated HMAC-SHA256, then verifies against the stored hash.
+
+</details>
+
+## Diagnostic history
+
+MongoDB retains 31 days of bounded minute aggregates; lifetime traffic checkpoints
+are separate. Missing samples remain gaps. Telemetry is disposable, excluded
+from encrypted catalog backups, and never required for file operations.
+See [reading the Performance page](performance.md#read-the-performance-page).
diff --git a/docs/assets/README.md b/docs/assets/README.md
new file mode 100644
index 00000000..5757d952
--- /dev/null
+++ b/docs/assets/README.md
@@ -0,0 +1,104 @@
+# Screenshots and demo videos
+
+[Docs home](../README.md) · [Visual walkthroughs](../showcase.md) · [Project README](../../README.md)
+
+The screenshots and demo videos are real captures of
+[TGDrive's public demo](../usage.md#try-the-public-demo), recorded on
+**24 October 2026** using original, disposable sample files. The
+README highlights the drive, video player and mobile layout; the
+[visual guide](../showcase.md) groups the full collection by workflow.
+
+The video captures predate the switch to Movi's native chapter/settings UI.
+Follow the [current controls guide](../usage.md#open-preview-and-download) for
+labels and behavior; replace these captures during the next live media refresh.
+
+## README banner
+
+[tgdrive-v2-banner.png](tgdrive-v2-banner.png) is AI-edited promotional artwork
+based on [drive-overview.png](drive-overview.png), not an unaltered screenshot.
+
+To replace it, use current TGDrive branding and a current screenshot without
+private information. Keep the text evergreen, avoiding launch-only labels such
+as “Now available”. Reuse the filename; if its path changes, update the
+[project README](../../README.md) and `PUBLIC_DOCS` in
+[build_release.py](../../scripts/build_release.py) together.
+
+## What is included
+
+| PNG images | Coverage |
+| --- | --- |
+| `drive-overview`, `drive-list`, `drive-dark`, `mobile-drive` | Grid/list browsing, appearance and compact layout |
+| `file-actions`, `search-and-sort`, `starred-files`, `trash-restore` | Organization, search and recovery from Trash |
+| `upload-folder`, `url-import`, `upload-progress`, `upload-completed`, `transfer-history` | Upload entry points, live device progress and finished tasks |
+| `media-preview`, `video-settings`, `image-preview`, `audio-preview`, `text-preview` | Player controls and file previews |
+| `pdf-reader`, `epub-reader`, `comic-reader` | Page/chapter navigation and reading preferences |
+| `share-link`, `shared-folder`, `shared-links` | Expiry choices, recipient view and link management |
+| `preloads`, `performance-overview`, `performance-resources` | Cache coverage, traffic and server resources |
+| `cache-settings`, `transfer-settings`, `regional-settings`, `thumbnail-rebuild` | Configuration and rebuild confirmation |
+| `connections`, `storage-backups` | Safe management entry points and backup status |
+
+Most desktop images are 1536 × 695; the recipient view is 1536 × 639. Connections
+is cropped to its identifier-free 1260 × 230 top panel. The mobile image is
+390 × 843, captured with a 390 × 844 browser viewport, not a physical phone.
+
+| Silent MP4 | Length | Recorded workflow |
+| --- | --- | --- |
+| [Organize files](organize-files.mp4) | About 3:26 | Views, search, sort, favorites, folder creation, rename and move |
+| [Upload and share](upload-and-share.mp4) | About 5:20 | Device upload, progress, history, Show in Folder, share label/expiry, copying and revocation confirmation |
+| [Previews and readers](readers-and-preview.mp4) | About 5:51 | Image/audio/text previews, PDF/EPUB/comic navigation and video playback/settings |
+
+[Find a feature by its video timestamp](../showcase.md#see-tgdrive-in-action).
+
+Videos use continuous Windows Graphics Capture of the live browser, encoded as
+H.264 MP4 at 30 fps and normal speed. A large cursor overlay follows logged click
+coordinates, with click highlights and captions in a separate 96-pixel bottom
+band. The upload video joins two chapters with a two-second title card and adds
+five-second end holds; captured actions are not accelerated. Browser audio is
+not captured. Browser suggestions are masked in the organization video, and the
+browser infobar is cropped from the sharing chapter. Raw captures and interaction
+logs remain in ignored local staging. These recordings illustrate workflows,
+not transfer benchmarks, device compatibility or recovery guarantees.
+
+The device file picker is outside the browser capture. Link generation happens
+between the upload and management chapters; the recipient view is shown in a
+screenshot. The video stops at the revocation confirmation, and the temporary
+link was revoked after recording.
+
+The folder-upload image shows the **New** menu. Directory selection could not be
+completed through the capture tool; the videos demonstrate ordinary file uploads.
+Follow the [folder-upload guide](../usage.md#upload-files-or-folders) for selection
+and confirmation. URL import, thumbnail rebuild, Telegram connections and backup
+captures show controls; they do not establish a completed import, rebuild,
+authentication or recovery. Server settings were not changed for these captures.
+
+## Replace or extend a capture
+
+1. Use an isolated collection with disposable, original or redistributable files.
+   For these captures, the image, six-second video, audio, PDF, ebook and comic
+   contents were created specifically for the demonstration.
+2. Capture the feature in a useful, settled state. Keep the navigation and controls
+   legible; dismiss unrelated notifications. Use a portrait viewport for mobile
+   examples and restore the original viewport/appearance afterward.
+   Record continuously at normal speed, keep the cursor visible and pause long
+   enough to read each step. When capture omits the cursor, base any cursor overlay
+   on the actual recorded interactions. Inspect the export for missing or duplicate
+   pointers, unreadable captions and abrupt transitions before replacing it.
+3. Exclude passwords, tokens, recovery keys, phone numbers, account names, channel
+   IDs and unrelated files. Capture sharing options before a URL is generated;
+   revoke disposable demonstration links afterward. Crop management screens to
+   safe controls rather than publishing identifiers.
+4. Save the final PNG or silent MP4 here with a descriptive name. Keep raw frames,
+   browser/session data and temporary files in ignored local staging. Preserve
+   the actual image format when converting captures.
+5. Update the relevant caption and link in the [visual guide](../showcase.md),
+   then the README or canonical user guide where it helps. Add the exact path to
+   `PUBLIC_DOCS` in [build_release.py](../../scripts/build_release.py); remove
+   obsolete assets and references together.
+
+The current PNGs and MP4s are stored in the repository and included in public
+source releases. Video posters link directly to the local MP4, so they also work
+in an extracted source archive. GitHub may open a file/download page instead of
+playing a repository-relative video inline; these are not uploaded GitHub video
+attachments. If a maintainer later uploads a video attachment through GitHub's
+Markdown editor, replace the link with that real attachment URL.
+
diff --git a/docs/assets/audio-preview.png b/docs/assets/audio-preview.png
new file mode 100644
index 00000000..a7cdb693
Binary files /dev/null and b/docs/assets/audio-preview.png differ
diff --git a/docs/assets/cache-settings.png b/docs/assets/cache-settings.png
new file mode 100644
index 00000000..efacc2bd
Binary files /dev/null and b/docs/assets/cache-settings.png differ
diff --git a/docs/assets/comic-reader.png b/docs/assets/comic-reader.png
new file mode 100644
index 00000000..e0d8ab8d
Binary files /dev/null and b/docs/assets/comic-reader.png differ
diff --git a/docs/assets/connections.png b/docs/assets/connections.png
new file mode 100644
index 00000000..ed1defbb
Binary files /dev/null and b/docs/assets/connections.png differ
diff --git a/docs/assets/drive-dark.png b/docs/assets/drive-dark.png
new file mode 100644
index 00000000..6d7d987d
Binary files /dev/null and b/docs/assets/drive-dark.png differ
diff --git a/docs/assets/drive-list.png b/docs/assets/drive-list.png
new file mode 100644
index 00000000..38f45868
Binary files /dev/null and b/docs/assets/drive-list.png differ
diff --git a/docs/assets/drive-overview.png b/docs/assets/drive-overview.png
new file mode 100644
index 00000000..f8a27cff
Binary files /dev/null and b/docs/assets/drive-overview.png differ
diff --git a/docs/assets/epub-reader.png b/docs/assets/epub-reader.png
new file mode 100644
index 00000000..31edc1d2
Binary files /dev/null and b/docs/assets/epub-reader.png differ
diff --git a/docs/assets/file-actions.png b/docs/assets/file-actions.png
new file mode 100644
index 00000000..7da99b0b
Binary files /dev/null and b/docs/assets/file-actions.png differ
diff --git a/docs/assets/image-preview.png b/docs/assets/image-preview.png
new file mode 100644
index 00000000..21b07e6c
Binary files /dev/null and b/docs/assets/image-preview.png differ
diff --git a/docs/assets/media-preview.png b/docs/assets/media-preview.png
new file mode 100644
index 00000000..15e9c164
Binary files /dev/null and b/docs/assets/media-preview.png differ
diff --git a/docs/assets/mobile-drive.png b/docs/assets/mobile-drive.png
new file mode 100644
index 00000000..4944598a
Binary files /dev/null and b/docs/assets/mobile-drive.png differ
diff --git a/docs/assets/organize-files.mp4 b/docs/assets/organize-files.mp4
new file mode 100644
index 00000000..41188459
Binary files /dev/null and b/docs/assets/organize-files.mp4 differ
diff --git a/docs/assets/pdf-reader.png b/docs/assets/pdf-reader.png
new file mode 100644
index 00000000..c072637a
Binary files /dev/null and b/docs/assets/pdf-reader.png differ
diff --git a/docs/assets/performance-overview.png b/docs/assets/performance-overview.png
new file mode 100644
index 00000000..7e5593fd
Binary files /dev/null and b/docs/assets/performance-overview.png differ
diff --git a/docs/assets/performance-resources.png b/docs/assets/performance-resources.png
new file mode 100644
index 00000000..4b80d304
Binary files /dev/null and b/docs/assets/performance-resources.png differ
diff --git a/docs/assets/preloads.png b/docs/assets/preloads.png
new file mode 100644
index 00000000..b142e41c
Binary files /dev/null and b/docs/assets/preloads.png differ
diff --git a/docs/assets/readers-and-preview.mp4 b/docs/assets/readers-and-preview.mp4
new file mode 100644
index 00000000..f47c90b5
Binary files /dev/null and b/docs/assets/readers-and-preview.mp4 differ
diff --git a/docs/assets/regional-settings.png b/docs/assets/regional-settings.png
new file mode 100644
index 00000000..edabef15
Binary files /dev/null and b/docs/assets/regional-settings.png differ
diff --git a/docs/assets/search-and-sort.png b/docs/assets/search-and-sort.png
new file mode 100644
index 00000000..242d5e38
Binary files /dev/null and b/docs/assets/search-and-sort.png differ
diff --git a/docs/assets/share-link.png b/docs/assets/share-link.png
new file mode 100644
index 00000000..273ecee6
Binary files /dev/null and b/docs/assets/share-link.png differ
diff --git a/docs/assets/shared-folder.png b/docs/assets/shared-folder.png
new file mode 100644
index 00000000..0e9a4996
Binary files /dev/null and b/docs/assets/shared-folder.png differ
diff --git a/docs/assets/shared-links.png b/docs/assets/shared-links.png
new file mode 100644
index 00000000..05fcc552
Binary files /dev/null and b/docs/assets/shared-links.png differ
diff --git a/docs/assets/starred-files.png b/docs/assets/starred-files.png
new file mode 100644
index 00000000..b209fdf6
Binary files /dev/null and b/docs/assets/starred-files.png differ
diff --git a/docs/assets/storage-backups.png b/docs/assets/storage-backups.png
new file mode 100644
index 00000000..ca5b9fcb
Binary files /dev/null and b/docs/assets/storage-backups.png differ
diff --git a/docs/assets/text-preview.png b/docs/assets/text-preview.png
new file mode 100644
index 00000000..97a62667
Binary files /dev/null and b/docs/assets/text-preview.png differ
diff --git a/docs/assets/tgdrive-v2-banner.png b/docs/assets/tgdrive-v2-banner.png
new file mode 100644
index 00000000..f0c1abc6
Binary files /dev/null and b/docs/assets/tgdrive-v2-banner.png differ
diff --git a/docs/assets/thumbnail-rebuild.png b/docs/assets/thumbnail-rebuild.png
new file mode 100644
index 00000000..94616681
Binary files /dev/null and b/docs/assets/thumbnail-rebuild.png differ
diff --git a/docs/assets/transfer-history.png b/docs/assets/transfer-history.png
new file mode 100644
index 00000000..e1c7c53d
Binary files /dev/null and b/docs/assets/transfer-history.png differ
diff --git a/docs/assets/transfer-settings.png b/docs/assets/transfer-settings.png
new file mode 100644
index 00000000..8c027317
Binary files /dev/null and b/docs/assets/transfer-settings.png differ
diff --git a/docs/assets/trash-restore.png b/docs/assets/trash-restore.png
new file mode 100644
index 00000000..6f5f045c
Binary files /dev/null and b/docs/assets/trash-restore.png differ
diff --git a/docs/assets/upload-and-share.mp4 b/docs/assets/upload-and-share.mp4
new file mode 100644
index 00000000..de5f95a2
Binary files /dev/null and b/docs/assets/upload-and-share.mp4 differ
diff --git a/docs/assets/upload-completed.png b/docs/assets/upload-completed.png
new file mode 100644
index 00000000..bdbf2484
Binary files /dev/null and b/docs/assets/upload-completed.png differ
diff --git a/docs/assets/upload-folder.png b/docs/assets/upload-folder.png
new file mode 100644
index 00000000..7d2b93f4
Binary files /dev/null and b/docs/assets/upload-folder.png differ
diff --git a/docs/assets/upload-progress.png b/docs/assets/upload-progress.png
new file mode 100644
index 00000000..bfc23ccc
Binary files /dev/null and b/docs/assets/upload-progress.png differ
diff --git a/docs/assets/url-import.png b/docs/assets/url-import.png
new file mode 100644
index 00000000..a2a78952
Binary files /dev/null and b/docs/assets/url-import.png differ
diff --git a/docs/assets/video-settings.png b/docs/assets/video-settings.png
new file mode 100644
index 00000000..a033cfc2
Binary files /dev/null and b/docs/assets/video-settings.png differ
diff --git a/docs/backup-recovery.md b/docs/backup-recovery.md
new file mode 100644
index 00000000..3ccb1246
--- /dev/null
+++ b/docs/backup-recovery.md
@@ -0,0 +1,292 @@
+# Backup & recovery
+
+[Docs home](README.md) · [Operations](operations.md)
+
+**Must read before using TGDrive: [New-user guide and FAQs](new-user-guide.md).**
+A second channel can help if one copy is lost, but both copies still use
+Telegram. Recovery is manual and needs a surviving copy with its matching keys.
+
+> [!IMPORTANT]
+> Save matching keys outside the server, wait for a **confirmed restore point**, and test recovery before relying on it. **Never replace an existing drive with an empty database as a repair.**
+
+**Contents**
+
+- [Choose the right MongoDB recovery route](#choose-the-right-mongodb-recovery-route)
+- [Set up an independent backup channel](#set-up-an-independent-backup-channel)
+  - [Prepare the Telegram accounts and channels](#prepare-the-telegram-accounts-and-channels)
+  - [Enable and confirm the first copy](#enable-and-confirm-the-first-copy)
+  - [What this copy retains](#what-this-copy-retains)
+  - [Rebuild a lost backup from the surviving main channel](#rebuild-a-lost-backup-from-the-surviving-main-channel)
+  - [Recover a lost main channel from a surviving channel](#recover-a-lost-main-channel-from-a-surviving-channel)
+  - [Recover only the database when the surviving channel is healthy](#recover-only-the-database-when-the-surviving-channel-is-healthy)
+  - [Interruptions and reports](#interruptions-and-reports)
+- [Keep the MongoDB recovery kit outside the server](#keep-the-mongodb-recovery-kit-outside-the-server)
+- [Make and check a MongoDB backup](#make-and-check-a-mongodb-backup)
+- [What the encrypted MongoDB archive contains](#what-the-encrypted-mongodb-archive-contains)
+  - [Reopen the existing MongoDB drive](#reopen-the-existing-mongodb-drive)
+  - [Restore a lost database from Telegram](#restore-a-lost-database-from-telegram)
+- [Verify your recovery kit periodically](#verify-your-recovery-kit-periodically)
+
+| Protection | Recovers | Limits |
+| --- | --- | --- |
+| Encrypted MongoDB archive | Catalog, part mappings, settings and shares | Cannot recreate deleted Telegram file bytes |
+| Optional independent channel | Completed documents/parts and matching recovery catalogs | Only confirmed copies; both channels still depend on Telegram |
+| Original files saved outside Telegram | Files you can upload again | Check that the copies open correctly |
+
+Large files need every stored part and the catalog that joins them together.
+Unfinished uploads also need their staged bytes or original device files;
+the backups below do not contain those unfinished bytes.
+
+<details>
+<summary>Find Storage & Backups in the interface</summary>
+
+![Storage & Backups showing saved catalog and temporary storage status](assets/storage-backups.png)
+
+The [administration gallery](showcase.md#connections-and-backups) shows the
+website's entry points. These captures do not demonstrate a completed backup or
+recovery; follow the confirmation and recovery steps below.
+
+</details>
+
+## Choose the right MongoDB recovery route
+
+| Situation | Route |
+| --- | --- |
+| Restart, update or redeploy | Keep MongoDB, secrets and volumes; no restore or initialization. |
+| Server or managed hosting expires | [Keep the drive and move hosts](operations.md#when-a-hosting-plan-expires); preserve the catalog, Telegram access and recovery kit. |
+| Machine/app folder lost, MongoDB survives | [Reopen the existing drive](#reopen-the-existing-mongodb-drive). |
+| MongoDB lost or deliberate rollback | [Restore a `.tgdb` archive](#restore-a-lost-database-from-telegram) into an empty database. |
+| Main Telegram channel lost | [Recover from an independent channel](#recover-a-lost-main-channel-from-a-surviving-channel). |
+| Both channels inaccessible, or no matching key | Use surviving MongoDB, another usable backup/key pair or external originals. |
+
+## Set up an independent backup channel
+
+Enable this optional feature under **Tools & settings → Storage & Backups → Independent backup channel**. Normal work continues during synchronization; an upload is not independently protected until its restore point is confirmed.
+
+### Prepare the Telegram accounts and channels
+
+1. Create a private broadcast backup channel and dedicated BotFather bot using a **separate Telegram account**. Keep independent recovery access to it.
+2. Give the backup bot administrator access to **both channels**, with **Post Messages**, **Edit Messages** and **Delete Messages**. Use a different bot from every main storage bot; a new token does not change identity.
+3. Keep both channels private, auto-delete **Off**, and **Restrict Saving Content** off where it blocks copying. Keep main bots' [standard permissions](setup.md#2-prepare-telegram).
+4. Change files through TGDrive. Do not edit/delete referenced documents, alter recovery pins or post unrelated content in these channels.
+
+Prepare accounts and permissions in Telegram. TGDrive checks channel state and bot access, but cannot prove human ownership; the separate-account acknowledgment is your responsibility. Extra bots do not remove rate limits.
+
+### Enable and confirm the first copy
+
+- [ ] Choose **Set up backup channel**; enter its negative numeric ID and backup bot token. Confirm the separate-account preparation, then **Verify and start backup**.
+- [ ] Save `tgdrive-channel-recovery-key.json` with **Save recovery key**. Keep it outside Telegram and the server.
+- [ ] Let synchronization finish. You can close the tab; the server continues. **Pause** preserves progress; **Resume** continues confirmed work.
+- [ ] Wait for **Backup confirmed**, check the revision, and save the key JSON **again**. Its `restore_point` records capsule message IDs in both channels; export again when keeping a newer point.
+
+**100% bytes is not confirmation.** Destination documents and matching encrypted recovery metadata must verify in both channels. Later changes can remain pending.
+
+Copies run sequentially and reuse Telegram document references; original file
+bytes are not downloaded and reuploaded through TGDrive. Telegram can still
+require a cooldown. Leave TGDrive running until the displayed retry deadline;
+new activity entries include the wait duration and the failed operation when
+available. A cooldown alone does not call for changing bot permissions.
+
+After confirmation, a healthy unchanged backup gets a routine health check
+hourly, rather than starting another file-copy run. The check verifies channel
+access, the saved recovery capsule and its pin. Changes to files, folders or
+saved settings can need a new recovery snapshot even without another upload;
+confirmed document mappings are reused. Browser status refreshes read saved
+progress and do not initiate Telegram logins or copies.
+
+<details>
+<summary>Retries, restarts and private bot sessions</summary>
+
+Retry/Resume verifies already copied documents before confirming a restore point.
+Missing or changed parts prevent confirmation. Saved retry deadlines and confirmed
+copies survive restart; restarting or choosing Resume does not bypass a Telegram
+cooldown. Pause and Disable remain effective if a request finishes or fails later.
+
+The backup bot reuses private session files under `DATA_DIR/sessions`. Preserve
+them across restarts and keep them private like bot tokens. Changing the bot
+token or API credentials, losing a session or having it revoked can require
+authorization again, subject to Telegram's waits. An idle health-check wait
+preserves the last confirmed restore point.
+
+See [backup pacing and verification](architecture.md#independent-backup-pacing-and-verification)
+for exact timing, batching and deletion-barrier rules.
+
+</details>
+
+### What this copy retains
+
+The copy includes completed documents and an AES-256-GCM encrypted `tgdrive-replica.tgdb` capsule: catalogs, remapped part locations, recovery credentials and supported settings/connections. It is separate from a full MongoDB archive; **do not interchange their files or keys**. Document bytes are not separately encrypted by TGDrive.
+
+| Recovery data | Main channel | Independent backup channel |
+| --- | --- | --- |
+| Encrypted channel recovery capsule | Saved | Saved and pinned |
+| Full encrypted MongoDB archive | Current archive created or reused | Same confirmed archive copied and verified before **Backup confirmed** |
+| Portable catalog | Included in channel recovery data | Included in the encrypted recovery capsule |
+
+Snapshots cover their confirmed revision. A failed setup does not establish a confirmed copy in the new backup channel. Save the recovery-key JSON outside the server and Telegram after confirmation.
+
+Old documents/capsules remain: this is not a deletion mirror. Older recovery points can restore removed records and revoked shares. Review sharing after recovery. Pausing backup can also hold permanent catalog removal until protection resumes or is explicitly disabled; ordinary browsing, uploads and metadata changes continue. See [deletion behavior](usage.md#why-permanent-deletion-keeps-the-telegram-files).
+
+### Rebuild a lost backup from the surviving main channel
+
+Preserve the working main channel/catalog. Create an empty private backup channel on the independent account and grant the backup bot access to both channels. Choose **Backup settings → Replace backup channel**, verify the new destination, wait for confirmation and save an updated key export. Replacement leaves the old remote channel/capsules intact.
+
+For permission/network trouble, repair access and Retry/Resume the existing operation instead. Disabling automatic backup stops new protection; it does not confirm pending changes or erase existing copies.
+
+### Recover a lost main channel from a surviving channel
+
+**Only files in the selected confirmed restore point can be recovered.** Keep the source, saved key JSON and persistent `DATA_DIR` intact. Recovery pauses file mutations until activation or explicit cancellation.
+
+1. Open **Independent backup channel → Recover a channel or catalog**, or the authenticated **Storage recovery** screen if the catalog cannot open.
+2. Enter the surviving channel ID, a backup bot token with access, and the JSON's 64-character **`key` value**, not the whole JSON. Leave the key empty only for a verified plain catalog checkpoint.
+3. Leave **Checkpoint message ID** empty to try the latest pinned capsule. If the original main channel's ordinary checkpoint owns the pin, enter `restore_point.source_message_id` from the export. Use `backup_message_id` for that recorded backup-channel point.
+4. Choose **Inspect recovery copy** and check its source, revision, files and bytes. Inspection does not activate a drive; a catalog cannot replace missing source documents.
+5. Create an **empty private main channel**. Add the surviving backup bot and a separate main storage bot as administrators. Enter its ID/main bot token, repeat the destination ID, then **Copy to new main channel**. The source stays unchanged.
+6. Wait for all parts and recovery metadata to verify. Repair errors and resume **the same operation** after reload/restart; preserve its server-side candidate and journal.
+7. At **Recovered drive verified**, repeat the channel ID and choose **Activate recovered drive**. Copying alone does not switch drives. Restart the service/container when instructed; browser refresh is insufficient. The former catalog/configuration remain for review.
+8. Check representative images, videos, PDFs, split downloads, Starred items, shares and Connections. Restore optional bots/sessions as needed, configure a separate independent backup, confirm it and export the current key/restore point.
+
+### Recover only the database when the surviving channel is healthy
+
+After inspecting a capsule, choose **Restore the database only on this surviving channel**. Supply a main bot distinct from the backup bot and repeat the surviving channel ID.
+
+TGDrive verifies referenced parts/sizes. Activation is still explicit and requires a service restart. The surviving channel becomes main; configure a separate backup afterwards. Use this only when the channel and required documents remain accessible.
+
+### Interruptions and reports
+
+Retry/Resume the **existing operation** after repairing the underlying problem. Preserve `DATA_DIR`, its journal, bootstrap and activation files across redeployments. Never run competing instances, delete that state or change destinations to bypass an error.
+
+Activation requires a complete current-format private record, including the
+pre-recovery key baseline. Incomplete or older records are rejected without
+changing the drive; preserve them and repeat recovery inspection.
+
+<details>
+<summary>Failure handling, key rotation and local recovery state</summary>
+
+| Problem | Action |
+| --- | --- |
+| FloodWait/network/uncertain send | Observe the retry deadline; resume confirmed work. More bots do not bypass waits. |
+| Process stopped/paused | Restart one instance or choose Resume. Later unconfirmed changes remain unprotected. |
+| Bot/access/privacy/copying failure | Repair credentials, permissions and private-channel/content settings. |
+| Missing document, wrong size, invalid key/capsule | Keep sources; select the correct key/point or another original. Never mark success manually. |
+| Disk/database failure | Repair storage/access while retaining journal/catalog, then retry. |
+
+During bot sign-in, Telegram can redirect a fresh connection to another data center. TGDrive retries authorization once after that handoff, within the 30-second sign-in deadline. If setup still fails, choose **Verify and start backup** again; for an existing backup, Retry/Resume the same operation. Message publication retries remain controlled by the saved operation journal. An unresolved numeric channel ID reports which channel needs its ID or bot access corrected.
+
+**Activity and report → Download report** gives progress and actionable failures without tokens/keys. Names and IDs may still be private; review before sharing. Never share raw private state or keys.
+
+The full MongoDB archive's revision can differ from the channel capsule's revision; they are distinct restore points. Keep both keys. In the JSON, `key` and `mongodb_backup_key` match the recorded `restore_point`; `next_backup_key` and `next_mongodb_backup_key` describe the next generation. Preserve the whole export and older pairs. If pending work captured an older MongoDB key, restore that key or verify **Backup settings** again to capture a fresh snapshot.
+
+The local journal commits each confirmed restore point and its matching keys in
+one transaction. If publication is interrupted, the export retains the prior
+complete pair or the new complete pair; it cannot combine generations. Preserve
+the journal across restarts and save an updated export after confirmation.
+
+Private `DATA_DIR/replica-bootstrap.json` retains owner recovery credentials/password hash. It does **not** provide offline login: MongoDB must be reachable with valid permissions, or startup may fail. A missing/corrupt catalog with reachable MongoDB can permit owner web recovery.
+
+Staged capsules and previous archives are retained. Monitor disk space; staging stops before the configured free-space reserve. Keep useful points off-server and rehearse recovery to a separate test destination.
+
+</details>
+
+## Keep the MongoDB recovery kit outside the server
+
+Keep these private and accessible even if TGDrive, Coolify and MongoDB are down:
+
+- [ ] A confirmed `.tgdb` archive or access to its Telegram channel.
+- [ ] Its matching **`tgdrive-recovery-key.env`**, exported via **Storage & Backups → Save Recovery Key**.
+- [ ] MongoDB URI/database name, owner login, original deployment secrets/configuration and Telegram administrator access.
+
+The `.env` export contains `MONGODB_BACKUP_KEY=` and a 64-character hexadecimal value. Store it separately from archives: anyone with both can read backed-up credentials/catalog. Your login password cannot decrypt an archive.
+
+Container setup may generate this key in `DATA_DIR/deployment-secrets.json`; it still needs an independent copy. Do not regenerate it during redeployment. After rotation, keep old keys with old archives; the export action saves only the current MongoDB key.
+
+## Make and check a MongoDB backup
+
+1. In **Storage & Backups**, choose **Back Up Now**.
+2. Wait for **Last Telegram Safety Copy** confirmation. “Saved to MongoDB” alone is not a Telegram backup.
+3. Save the matching key separately; optionally download the confirmed `.tgdb` document for an off-server copy.
+4. Rehearse restoration into a separate empty database. Stop production while checking the restored installation; keep one active instance per drive.
+
+Automatic snapshots normally run hourly (`MONGODB_BACKUP_SECONDS`). Failures leave the live database intact; check the displayed error/retry time, posting access, key and temporary disk. See [configuration](reference.md#persistence-and-initialization).
+
+## What the encrypted MongoDB archive contains
+
+| Included | Excluded |
+| --- | --- |
+| Catalog and ordered Telegram part mappings | Original Telegram file bytes |
+| Shares, settings, Telegram/owner credentials | MongoDB URI/name and machine paths |
+| Transfer, preparation, deletion and recovery records | Unfinished upload bytes, disposable caches and telemetry counters |
+
+<details>
+<summary>Archive verification and encryption limits</summary>
+
+Snapshots are compressed app records, limited to 1 GiB expanded; unrelated MongoDB collections are excluded. AES-256-GCM authenticates the archive. TGDrive downloads the uploaded ciphertext and checks SHA-256 before confirming; restore checks authentication, format and completeness before writing.
+
+The recorded revision comes from the catalog inside the exported snapshot.
+Changes committed afterwards belong to a later archive. Failed exports are
+removed; cancellation waits for the export worker before removing an archive
+that has not entered the pending-backup journal. An uncertain journal commit
+retains the ciphertext for reconciliation. Hard stops can still leave local
+files behind; this cleanup does not sweep older untracked archives.
+
+Restore validation holds the archive, expanded content and parsed records in
+memory. Peak memory can substantially exceed the archive's file size; leave
+headroom when restoring a large catalog and rehearse it on the intended host.
+
+This encryption covers database archives, not original Telegram payloads or local upload/cache bytes. A catalog cannot recreate a deleted Telegram part.
+
+</details>
+
+### Reopen the existing MongoDB drive
+
+Follow the [reinstall instructions](operations.md#reopen-after-losing-the-local-installation): reuse the existing database and original secrets, preserve volumes, and deploy. Check Connections, files, split downloads and unfinished work. Missing staged bytes still require the original source.
+
+### Restore a lost database from Telegram
+
+Use a confirmed `.tgdb` archive, its matching key and the matching TGDrive
+version or source commit. Restore into a **new empty MongoDB database with
+transaction support**. Changes after the snapshot will be absent; **older shares
+may reappear**. Use a private deployment with demo mode off; archive restore is
+disabled in demo mode, including for the demo administrator.
+
+1. Download the confirmed database `.tgdb` archive from your private Telegram
+   channel and find its matching 64-character key in the saved recovery-key file.
+   This is different from an independent channel recovery capsule/key.
+2. Prepare a **new empty MongoDB database with transaction support** and configure
+   a deployment using the normal [required environment values](setup.md#3-configure-your-drive).
+   Preserve the original channel and credentials. Deploy and sign in; automatic
+   first setup needs no terminal command. Do not upload files or change settings
+   in this temporary empty drive.
+3. Open **Storage & Backups → Recover on a New Installation → Restore database
+   archive**. The same form is available on the owner **Storage recovery** screen
+   when the catalog is missing. Select the archive, enter its matching key and
+   type `RESTORE` to confirm. Keep the browser open until the upload and result
+   finish.
+4. After success, restart/redeploy the application using Docker or Coolify's
+   controls, then sign in again. Restored browser sessions are revoked. Saved
+   backup credentials/settings apply after restart, subject to explicit
+   deployment overrides; see [reinstalling](operations.md#reopen-after-losing-the-local-installation).
+5. Check folders, representative downloads, split files, Connections and
+   **restored share permissions**. Keep the old database/archive/key until
+   verified, then make a fresh confirmed backup and export its key.
+
+<details>
+<summary>Restore limits and failure handling</summary>
+
+The website accepts archives up to 1 GiB and restores only an empty destination
+or the untouched catalog created by automatic first setup; it does not merge or
+overwrite a used drive. Invalid keys/damaged archives fail before stopping normal
+work. The archive is authenticated and the destination checked again inside the
+restore transaction. A failure after the service pauses can require a restart;
+the website reports that explicitly. Temporary uploaded ciphertext is removed
+after the attempt. Local unfinished upload bytes are not in the archive.
+
+</details>
+
+## Verify your recovery kit periodically
+
+Use the same version or source commit and a separate empty database to confirm
+the archive decrypts, the catalog opens and Telegram files remain readable.
+A filename alone is not evidence. Keep unfinished-upload originals until completion.
+
+See [exact archive/API boundaries](reference.md#security-and-privacy) and [operational troubleshooting](operations.md#troubleshooting).
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 00000000..c1369380
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,293 @@
+# Configuration and safe tuning
+
+[Docs home](README.md) · [Setup](setup.md) · [Performance diagnostics](performance.md)
+
+Use **Configuration** to change cache, transfer and timezone settings. Saved
+changes persist across restarts and apply to new work immediately. Start with
+the defaults, change one setting at a time and compare the same workload.
+
+Memory and disk budgets are ceilings, not space allocated in advance. Work
+still needs actual free resources.
+
+[See the configuration screens](showcase.md#configure-your-drive) for a visual
+tour. Use the defaults and limits below when configuring your installation.
+
+**Contents**
+
+- [Change, discard or restore](#change-discard-or-restore)
+- [Cache settings](#cache-settings)
+- [Transfer limits](#transfer-limits)
+  - [Parallel uploads](#parallel-uploads)
+  - [Upload splitting](#upload-splitting)
+  - [URL downloads](#url-downloads)
+  - [Upload size and available disk space](#upload-size-and-available-disk-space)
+  - [Advanced Telegram limits](#advanced-telegram-limits)
+- [Timezone](#timezone)
+- [A modest server and a larger server](#a-modest-server-and-a-larger-server)
+- [Deployment-only settings](#deployment-only-settings)
+- [Public demo mode](#public-demo-mode)
+  - [Keep sample files available](#keep-sample-files-available)
+  - [Return to a private deployment](#return-to-a-private-deployment)
+
+## Change, discard or restore
+
+Open **Configuration → Cache settings**, **Transfer limits** or **Timezone**.
+
+| Action | Effect |
+| --- | --- |
+| **Save changes** | Saves this page; unsaved values on other pages remain drafts. |
+| **Discard changes** | Reloads this page's saved values. |
+| **Restore defaults** | Loads built-in values for this page; review and save to apply. |
+
+**Parallel uploads** has its own save controls, described
+[below](#parallel-uploads).
+
+Saved dashboard values override startup environment values. Restoring defaults
+does not remove environment variables or reset files, accounts, credentials or
+recovery keys. If another session changes settings first, reload before saving.
+Invalid values are rejected. If applying a change fails, TGDrive attempts to
+restore the previous values and reports whether a restart is needed.
+
+## Cache settings
+
+Open **Configuration → Cache settings**.
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| Memory cache | 256 MiB | Recently read file bytes kept in memory; available RAM can lower the effective budget. 0 disables retention. |
+| Disk cache | 10 GiB | Temporary file copies for repeat access. 0 disables disk retention. |
+| Cache free-space floor | 1 GiB | Stop cache writes before free disk falls below this level. Saving with disk caching enabled requires at least 64 MiB. |
+| Disk cache retention | 24 hours | Time since last reuse; capacity pressure can remove cached data sooner. |
+| Concurrent preloads | 2 | Files prepared in the background at once; consider 1 on a small server. |
+| Preload during playback | On | Prepare bounded upcoming original audio/video bytes. Downloads do not start extra warming. |
+
+Clearing or expiring cache leaves Telegram originals and MongoDB records intact.
+Active streams and unfinished uploads have separate budgets but share the host's
+resources. Turning off playback preloading still allows requested-range
+read-ahead and manual **Preload file**.
+See [preloading](usage.md#preload-a-file-for-smoother-playback-and-downloads).
+
+**Regenerate all thumbnails** refreshes existing file covers in the background
+after confirmation. New uploads generate them automatically.
+See [rebuild progress, bandwidth and limits](thumbnails.md#rebuild-existing-thumbnails).
+
+## Transfer limits
+
+Open **Configuration → Transfer limits**. Its controls appear in the order below.
+
+### Parallel uploads
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| Simultaneous uploads per bot | 1 | Concurrent Telegram document uploads per healthy bot; choose 1–4. A large file can use multiple document-upload slots. |
+
+Start with one upload per bot; add eligible bots before increasing the value.
+Existing transfers finish when the limit is lowered. Premium accounts keep one
+upload slot each.
+
+This section has separate **Save Changes**, **Discard upload changes** and
+**Restore upload defaults** actions. Restoring its default loads 1; choose
+**Save Changes** to apply it. The page's other save controls do not save this value.
+
+### Upload splitting
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| File split size | 2000 MiB | Maximum preferred size of each Telegram document, including for Premium accounts. Choose 1–2000 MiB; 0 also uses 2000 MiB. |
+
+This controls how TGDrive stores a file in Telegram, rather than the largest
+file you can upload. Existing transfers keep their original split plan.
+For the whole-file limit, use [Upload storage](#upload-size-and-available-disk-space).
+
+### URL downloads
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| Full-speed URL downloads | 2 | URL imports downloading at full speed together; choose 1–8. |
+
+This controls the source-to-server stage. Telegram uploading uses its own slots.
+Waiting sources may receive data slowly while connection and storage limits
+permit; expired links can still fail. See [URL intake](performance.md#url-import-intake)
+for queue behavior and retries.
+
+For a startup override, set `REMOTE_DOWNLOAD_CONCURRENCY` in the private `.env`
+or hosting environment, then recreate/redeploy. A saved dashboard value takes
+precedence; see [deployment settings](#deployment-only-settings).
+
+### Upload size and available disk space
+
+Open **Transfer limits → Upload storage**.
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| Maximum file size | 16 GiB | Largest new file accepted. Telegram document splitting is separate. |
+| Temporary upload budget | 16 GiB | Space all unfinished uploads may use together; it must cover the per-file maximum. |
+| Upload free-space reserve | 1 GiB | Space uploads must leave free on their storage volume after other uploads' reservations are accounted for. Minimum configurable reserve: 64 MiB. |
+
+To upload a **32 GiB file**, raise both the file maximum and temporary budget to
+at least 32 GiB. A 64 GiB budget can reserve two such files if actual disk space
+permits. Both controls support up to **2048 GiB (2 TiB)**. Existing uploads retain
+their reservations; reducing the budget below those reservations is rejected.
+
+Browser uploads and full-speed URL imports reserve the whole file and check
+actual free space, including other uploads' unwritten reservations.
+A full-speed unknown-length URL import reserves its admitted maximum. If that
+prevents admission, use a source that reports its file size or lower the file limit.
+Waiting URL sources reserve smaller windows; see
+[URL storage policy](performance.md#url-import-intake).
+
+Space is rechecked during receipt, but other disk users can still fill it.
+Browser disk-full failures retain the confirmed resume position; URL retrieval
+may restart from zero. These settings control temporary server disk use;
+they do not set your total Telegram storage capacity.
+
+### Advanced Telegram limits
+
+<details>
+<summary>Request and media-operation controls</summary>
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| Upload pipeline | 4 | Parallel Telegram upload-part requests within one document |
+| Requests per account | 8 | Shared upload, download and metadata requests |
+| Requests per second | 48 | App pacing ceiling, not a Telegram allowance |
+| Media operations per account | 3 | Telegram uploads/downloads; cached delivery does not use these slots |
+| Maximum queued operations | 256 | Waiting Telegram work before excess requests must retry |
+
+The server rejects invalid values and enforces
+[exact bounds](reference.md#performance-and-cache-settings).
+More slots share the same bandwidth; Telegram cooldowns still apply.
+Raise one limit only after measuring throughput and provider waits.
+
+</details>
+
+## Timezone
+
+Open **Configuration → Timezone**. The default is **Asia/Kolkata (IST)**.
+Use a valid timezone name such as `Europe/London` or `UTC`, then choose
+**Save changes**. This controls displayed dates and share expiry across the
+installation; stored timestamps remain UTC.
+
+## A modest server and a larger server
+
+Start with the defaults. On a small/shared server, consider one preload and one
+upload per bot. More RAM or disk does not automatically increase the configured
+cache budgets, and larger queues do not add processing capacity.
+
+Use the [load and capacity guide](performance-tuning.md) to read website stats,
+diagnose queues and choose cache, server or bot capacity for your workload.
+Change one limit at a time and compare the same workload before keeping it.
+
+## Deployment-only settings
+
+Use the private `.env` or hosting environment for initial setup and values
+without app controls, including MongoDB access, owner credentials, session
+policy, proxy trust and demo mode. See [Setup](setup.md) and the
+[variable reference](reference.md#configuration) for exact names and bounds.
+
+After editing Docker environment values, recreate the container or redeploy.
+Restarting the existing container alone does not load the edited values.
+Saved dashboard preferences still take precedence over startup defaults.
+
+MongoDB is required for every deployment. Invalid configuration or failed
+database access stops startup; no local database is substituted. A pristine
+database is initialized automatically.
+See [startup and recovery boundaries](architecture.md#lifecycle).
+
+## Public demo mode
+
+Set `DEMO_MODE=true` in the demo deployment's environment, then recreate the
+Compose container or redeploy through Coolify. It defaults to `false`.
+Configure the demo's accounts, limits and backups before enabling it.
+
+Use the same login form with either of these passwords:
+
+| Password | Demo access |
+| --- | --- |
+| Existing `ADMIN_PASSWORD` or `ADMIN_PASSWORD_HASH` | Visitor access: settings/management stay read-only; files outside Demo Files remain editable. |
+| Separate `DEMO_ADMIN_PASSWORD` or `DEMO_ADMIN_PASSWORD_HASH` | Administrator access to settings, backups and sample files, except database archive restoration. Keep this password private. |
+
+The administrator password is optional and only works while `DEMO_MODE=true`.
+If omitted, every web login remains restricted. Use a different password of at
+least 12 characters, or supply an existing compatible Argon2id hash. See
+[password storage and reset](operations.md#forgotten-login-password). Hashes take
+precedence over their corresponding plaintext values. Both demo administrator
+variables are deployment-only; they are not restored from the database.
+
+Database archive restoration is disabled for every login while demo mode is on.
+Use a separate private deployment for a restore or recovery rehearsal; see
+[database recovery](backup-recovery.md#restore-a-lost-database-from-telegram).
+
+Plaintext environment passwords are supported; hashes are optional. For example,
+keep your existing visitor password and add a private full-access password:
+
+```dotenv
+DEMO_MODE=true
+DEMO_ADMIN_PASSWORD=<your-different-private-password>
+DEMO_ADMIN_PASSWORD_HASH=
+```
+
+Replace the placeholder, then recreate/redeploy. Keep the matching `_HASH`
+variable empty when using plaintext. A hash lets deployment configuration store
+a one-way Argon2id fingerprint instead of the actual password; at login, always
+enter the password you chose. See [password storage and reset](operations.md#forgotten-login-password).
+
+Coolify may prevent deleting a variable declared by Compose. To switch to a
+plaintext password, clear the corresponding hash variable's **Value**, save it
+and redeploy. A populated hash always takes precedence over plaintext.
+
+“Visitor” access describes permissions, not a separate account or an automatic
+content reset. Both login types use the configured session lifetime (24 hours
+by default). Logging out and using the other password switches access.
+
+Restricted visitors can open every **Configuration** and **Management** page
+and inspect the current values and status, but cannot change settings, add/remove accounts,
+start Premium login, refresh Telegram connections, or run backup/recovery
+management actions. Recovery-key downloads are also disabled; credentials
+remain private. The server rejects these requests even when sent outside the UI.
+If deployment configuration cannot load, these pages offer **Try Again** before
+showing controls; file features remain accessible.
+
+Uploads, URL imports, browsing, organizing, previews, downloads, sharing and
+manual preloads keep their normal behavior and limits. Automatic backups and
+other configured background work continue while TGDrive runs. Demo mode does
+not bypass login: give visitors the demo deployment's password separately.
+
+### Keep sample files available
+
+TGDrive creates **Demo Files** in **My Files** when demo mode starts. Sign in
+with the full-access password to populate it with sample videos, images,
+documents and other file types. Visitors can browse, preview and download its
+contents. Attempts to upload, rename, move, delete or otherwise edit this folder
+or its descendants are rejected, with a popup directing visitors to **My Files**
+for their own changes. These restrictions also apply to direct API requests.
+
+The protected identity survives a full-access user's rename or move. Keep it in
+the root with its default name so visitors can find it. Only a full-access user
+can remove its samples; demo mode does not supply or regenerate sample content.
+If the reserved folder is missing, the next demo startup recreates an empty one.
+If another file or folder already uses the name **Demo Files**,
+[return to a private deployment safely](#return-to-a-private-deployment), rename
+that item, then enable demo mode again. Existing content is preserved.
+
+Use a separate MongoDB database, Telegram storage channel and credentials for
+the public demo. Visitors share one drive and can change or permanently delete
+files outside the protected sample folder, so use disposable content there.
+Demo mode does not isolate visitors, reset content or add quotas. Closing a visitor's browser follows
+the [usual transfer rules](usage.md#what-upload-progress-means).
+
+### Return to a private deployment
+
+1. Restrict public access and replace any published visitor credential with a
+   private owner password or hash. Follow the
+   [password-change instructions](operations.md#forgotten-login-password).
+2. Set `DEMO_MODE=false` and recreate/redeploy. Sign in with the private owner
+   password.
+
+The usual owner password grants full access once demo mode is off. The separate
+`DEMO_ADMIN_*` password does not become the normal owner credential. Demo variables
+cannot be changed in the app.
+
+Keep the public address and visitor sign-in instructions in the
+[public demo guide](usage.md#try-the-public-demo). Keep the full-access password
+private.
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 00000000..7a54e870
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,862 @@
+# Develop and release TGDrive
+
+[Docs home](README.md) · [Architecture](architecture.md) · [Release verification](release.md)
+
+Deployment uses [Docker Compose](setup.md). This page covers contributor builds,
+tests and development servers **inside WSL Ubuntu**, using the Linux checkout.
+
+Develop on `dev`; it contains work in progress and may be unstable. `main`
+receives reviewed, tested stable updates through versioned release PRs. Normal
+installations use a published tag or `main`; see [source selection](setup.md#get-the-source)
+and [release verification](release.md) for the checks required before promotion.
+
+The [showcase](showcase.md) documents live illustrative captures. Follow the
+[media guide](assets/README.md) when replacing them; captures do not replace the
+automated and live validation described below.
+
+**Contents**
+
+- [Install the development environment](#install-the-development-environment)
+- [Run while editing](#run-while-editing)
+- [Preview with sample content](#preview-with-sample-content)
+- [Latest validation](#latest-validation)
+- [Validation commands](#validation-commands)
+  - [Live Telegram testing](#live-telegram-testing)
+- [CI and release evidence](#ci-and-release-evidence)
+  - [When GitHub checks run](#when-github-checks-run)
+  - [Recorded results](#recorded-results)
+- [Version baseline and dependency policy](#version-baseline-and-dependency-policy)
+- [Code conventions](#code-conventions)
+- [Repository map and test map](#repository-map-and-test-map)
+- [Frontend contracts](#frontend-contracts)
+  - [Shared-links interface](#shared-links-interface)
+  - [UI Audit Contracts](#ui-audit-contracts)
+- [Source releases](#source-releases)
+- [Documentation maintenance](#documentation-maintenance)
+- [Independent channel backup contracts](#independent-channel-backup-contracts)
+  - [Selective book pages and shared PDF resources](#selective-book-pages-and-shared-pdf-resources)
+
+## Install the development environment
+
+```bash
+uv sync --frozen --all-groups --python 3.14.8
+npm ci --prefix website
+npm run build --prefix website
+```
+
+Keep lockfiles. Ordinary tests inject fake resources and need no live Telegram credentials.
+
+Use the [supported runtimes](#version-baseline-and-dependency-policy) and run the
+commands in this guide only when the current task authorizes the relevant checks,
+as required by [contributor guidance](../AGENTS.md#ask-before-running-tests-or-validation).
+
+## Run while editing
+
+With private configuration and an existing drive:
+
+```bash
+COOKIE_SECURE=false uv run --frozen python -m uvicorn tgdrive.web.app:create_app --factory \
+  --host 127.0.0.1 --port 8000 --workers 1 \
+  --timeout-graceful-shutdown 45 --no-access-log
+```
+
+In another WSL terminal:
+
+```bash
+npm run dev --prefix website
+```
+
+Vite normally serves 5173 and proxies API/media to 8000; production builds use 8000.
+
+> [!IMPORTANT]
+> Run one owner per drive. Avoid reload during real uploads unless testing
+> interruption recovery.
+
+## Preview with sample content
+
+```bash
+npm run build --prefix website
+TGDRIVE_UI_SHOWCASE=1 uv run --frozen --group e2e python -m uvicorn \
+  tests.support.browser_transfer_app:app --host 0.0.0.0 --port 18767
+```
+
+Open [localhost:18767](http://localhost:18767/) with `offline browser test password`.
+The fixture seeds files, transfers, shares, caches, performance and reading samples
+without Telegram credentials. Restart resets it. CBR needs
+[libarchive](reading.md), included in Docker. Showcase uses the production
+16 GiB file cap; ordinary browser tests use 32 MiB. Never publicly deploy the
+fixture or its `/__test__` endpoints.
+
+## Latest validation
+
+Recorded evidence describes a tested snapshot, not the state of a later checkout.
+
+<details>
+<summary>Reader HTTP compression — 2026-10-26</summary>
+
+The focused `bookImage.test.ts` Vitest file passed **12 tests** on Node **24.22.0**.
+Coverage includes decoded gzip/Brotli responses, unknown progress totals,
+uncompressed truncation checks and cancellation above the 64 MiB image limit.
+These are mocked Fetch responses; no browser/proxy validation, full suite,
+typecheck or build was run for this correction. See [reader behavior](reading.md#bandwidth-and-compatibility).
+
+</details>
+
+<details>
+<summary>Audit fixes: durability, concurrency and browser state — 2026-10-26</summary>
+
+The offline run passed **1,930 cases and 36 subtests** in **83.18 seconds**, with
+78 opt-in skips. Two failures came from one missed `await` in a test fixture;
+after correction, its complete 12-case module passed. The complete Vitest suite
+ran through the Python bridge. Ten additional journal-boundary cases passed,
+including blocked commits, crash recovery, cancellation and staging limits.
+
+The MongoDB parity group passed **98 cases**, using a disposable local replica
+set for live database cases. Four Chromium cases verified preserved drafts after
+configuration failure and initial permission gating. The production build and
+TypeScript checks passed on Node **24.22.0**, with existing viewer bundle warnings.
+Ruff lint/format passed on **264 Python files**; edited frontend formatting passed.
+
+These checks use isolated or synthetic data. They do not validate a deployment,
+live Telegram sends, hard-kill recovery or every device/network condition.
+
+</details>
+
+<details>
+<summary>Repository cleanup, viewers and settings — 2026-10-26</summary>
+
+Checks used Node **24.22.0** and Python **3.14.8**. The complete offline run passed
+**1,908 Python cases and 36 subtests**, including the complete Vitest behavior
+suite, in **87.20 seconds**. Its two fixture setup errors passed after repair;
+an additional directory-authorization regression also passed. The 78 skips
+covered opt-in browser and live MongoDB cases, checked separately below.
+
+All **287 Chromium cases** passed across the full run and focused failed-case
+reruns. Coverage includes native player chapters/subtitles, PDF ranges and
+passwords, book readers, transfers, sharing and responsive settings. Two policy
+gate cases also passed after fixing cross-category draft loss. Desktop/phone
+and light/dark screenshots were inspected. Native CBR checks passed after
+installing the required libarchive runtime.
+
+The disposable MongoDB replica-set run passed **103 cases** across its initial
+run and two repaired fixture reruns, including **43 live database cases**.
+No deployment database or private environment file was used.
+
+The production build, **28 viewer patch cases**, Ruff lint/format on **267 Python
+files**, authored frontend formatting, Bandit, lockfile consistency and Python/npm
+dependency audits passed. Local documentation checks found no broken references
+among 557 links, images and anchors. The AMD64 Docker build and offline factory,
+imports, bundled-resource and container-policy smoke checks passed.
+The public source archive's 522 file hashes matched its manifest; a fresh
+extraction installed its frontend dependencies and built successfully.
+
+Passing cases were reused; the entire suite was not repeated after every final
+fix. These checks do not validate live Telegram transfers, production startup,
+deployment, ARM64 or physical-device/GPU behavior. Viewer archives were generated
+from integrity-checked upstream packages; normal commands use the local archives.
+
+</details>
+
+<details>
+<summary>MongoDB-only startup and website archive recovery — 2026-10-26</summary>
+
+The final configuration, first-initialization, catalog-decoding, portable-part
+and channel-recovery checks passed **257 backend cases** across the initial run
+and failed-case reruns. Outdated local-storage fixtures and client doubles were
+corrected. Earlier focused runtime, persistence, archive API and startup-error
+checks also passed. Coverage includes atomic first setup, immediately active
+initial connections, no local database fallback, refused startup, archive
+validation, preserved destinations and recovery failure reporting.
+
+The new archive-form/transport tests passed **11 frontend tests**, and TypeScript
+`--noEmit` passed.
+
+These were synthetic checks. No live MongoDB, Docker/Coolify deployment, browser
+session, full suite or release build was run. Frontend checks used the available
+Linux Node **24.21.0**, below the declared **24.22.0** minimum; repeat them on the
+supported runtime before release. Database recovery still needs live validation.
+
+</details>
+
+<details>
+<summary>URL intake, slow queue and immediate start feedback — 2026-10-23</summary>
+
+Offline fixtures passed **156 backend tests plus 24 subtests** and **88 frontend
+tests**. After correcting intake-mode leakage into the Telegram-stage ETA, all
+**15 progress-metrics tests** passed again. TypeScript checking, Ruff lint/format
+checks on 17 changed Python files, and Prettier checks on 10 frontend files passed.
+
+Coverage includes exact range assembly, representation mismatch and single-stream
+fallback, cancellation while writing, promotion with an existing prefix, full-speed
+slot/connection bounds, slow pacing, storage windows, saved concurrency settings,
+immediate client feedback and lost-start-response reconciliation. These are
+synthetic offline checks; no live downloads, throughput benchmark, production build,
+browser visual check or deployment was performed for this change.
+
+</details>
+
+<details>
+<summary>Shared Links and simultaneous owner sessions — 2026-10-23</summary>
+
+The reviewed working tree passed **201 focused backend tests**, **335 frontend
+tests**, typechecking and the production build. Ten focused Chromium cases cover
+independent file/folder links, icon-only copy controls, unavailable/expired links,
+edit/revoke scope, exact timestamps, and desktop/phone layouts in light and dark
+themes. These use the real frontend with synthetic Telegram/storage fixtures.
+
+Backend session checks use separate client cookie jars, SQLite and mocked MongoDB
+session storage: later logins leave existing devices signed in, and logout only
+revokes that session. Client tests cover bounded retries for simultaneous login
+verification. Recovery tests enforce the destination confirmation at activation.
+These checks do not certify live provider deployments or every browser/device.
+
+</details>
+
+<details>
+<summary>Authentication, shares and outbound-request checks — 2026-10-23</summary>
+
+The reviewed working tree passed **170 focused tests and 24 subtests**, covering
+authentication/configuration, request guards, frontend security, share edits,
+remote imports, deployment, recovery APIs, logging and access revalidation.
+Regression cases cover invalid logout cookies causing no database writes,
+omitted share fields preserving expiry/labels under concurrent edits, and shared/
+site-local IP ranges blocked through literals, DNS and redirects.
+
+Focused Ruff checks passed. Bandit reported no findings; the locked runtime
+Python dependency audit and frontend dependency audit found no known
+vulnerabilities. These are automated checks, including SQLite and mocked MongoDB
+behavior. They are not a live MongoDB, HTTPS/proxy/provider test or an independent
+penetration test. See the [remaining authentication limits](reference.md#security-and-privacy).
+
+</details>
+
+<details>
+<summary>Adaptive read-ahead and Preloads results</summary>
+
+The recorded adaptive read-ahead/Preloads snapshot passed **1,479 offline Python
+tests** (55 skipped, 15 subtests), **179 strict focused backend checks**, **321
+frontend tests** and **eight Chromium workflows**, plus TypeScript, production
+build and focused Ruff checks. Coverage includes exact range bytes, bounded
+read-ahead, distinct-viewer promotion, cache-index races and responsive Preloads
+with a capacity panel and full-width segmented file coverage.
+These fake-Telegram/synthetic checks do not measure live speed. They also do not
+certify documentation edits or a later release artifact.
+
+</details>
+
+## Validation commands
+
+Run relevant checks for a small change. Before release, run full validation and
+[artifact verification](release.md). Coverage requires opt-in isolated MongoDB;
+offline tests alone do not sufficiently exercise the production database.
+
+| Change | Checks to include |
+| --- | --- |
+| Backend behavior | Focused Python tests; MongoDB tests for persistence changes |
+| Interface | Typecheck, frontend tests/build and relevant Chromium workflows |
+| Transfer/recovery | Retry, cancellation, interruption and ownership-loss cases |
+| Release | Full checks below, then a clean extracted archive |
+
+For URL intake changes, the focused offline checks are:
+
+```bash
+uv run --frozen --all-groups python -m pytest -W error \
+  tests/transfers/test_remote.py tests/transfers/test_remote_ranges.py tests/transfers/test_remote_retries.py \
+  tests/transfers/test_remote_scheduler.py tests/transfers/test_transfers.py \
+  tests/observability/test_transfer_metrics.py tests/transfers/test_staging_admission.py -q
+```
+
+These cover fake HTTP responses, staging admission, advisory progress versus
+durable state, cancellation and handoff to fake Telegram. They do not measure
+live download speed or confirm a deployment.
+
+For Telegram download admission and request-status changes, the focused offline
+regressions are:
+
+```bash
+uv run --frozen --all-groups python -m pytest -W error \
+  tests/media/test_media_request_fairness.py tests/media/test_book_range_admission.py \
+  tests/media/test_file_status.py tests/media/test_media_scheduler.py \
+  tests/media/test_media_admission_priority.py tests/media/test_stream_delivery.py \
+  tests/media/test_multipart_streaming.py tests/web/test_app.py -q
+cd website
+npx vitest run src/features/previews/Preview.test.ts
+npm run typecheck
+```
+
+These exercise one bot sharing distinct cold files, priority and cancellation,
+one-slot thumbnail source reads, exact stream delivery, authorized status and
+bounded preview retry policy. The image retry/close and video status workflows
+are in `tests/browser/test_browser_preview_player.py`. These are synthetic
+regressions, not measurements of Telegram throughput. Run checks only with the
+approval required by `AGENTS.md`; listing commands here does not record a pass.
+
+For thumbnail regeneration and selective readers, focus on
+`tests/media/test_thumbnail_rebuild.py`, `tests/media/test_generated_thumbnails.py`,
+`tests/media/test_thumbnails.py`, `tests/media/test_books.py`, `tests/media/test_books_api.py` and
+`tests/media/test_multipart_previews.py`. The rebuild tests use generated images/books,
+a loopback range bridge and fake Telegram reads, including padded archives that
+must not be fetched in full. `tests/browser/test_browser_thumbnail_rebuild.py` covers
+confirmation, progress/reload/cancellation and image-based EPUB manga fit/direction.
+These synthetic checks do not establish live Telegram throughput or universal
+codec/device support.
+
+<details>
+<summary>Full lint, tests, security and build checks</summary>
+
+First start a [disposable MongoDB replica set](#opt-in-mongodb-replica-set-tests)
+and export its two test variables. The coverage command below needs that opt-in;
+never point it at your deployment database.
+
+```bash
+uv lock --check
+npm run typecheck --prefix website
+npm test --prefix website
+npm run build --prefix website
+uv run --frozen --all-groups ruff check tgdrive tests scripts
+uv run --frozen --all-groups ruff format --check tgdrive tests scripts
+uv run --frozen --all-groups python -m pytest -W error \
+  --cov=tgdrive --cov-report=term-missing
+uv run --frozen --all-groups bandit -c pyproject.toml -r tgdrive
+uv run --frozen --all-groups pip-audit --strict
+npm audit --prefix website --audit-level=high
+docker compose --env-file .env.example config --no-env-resolution --quiet
+```
+
+Keep the 80% coverage floor. Compose validation checks syntax, not placeholder
+credential validity. See the [recorded results](#latest-validation) for the
+environments, coverage and known limitations of earlier runs.
+
+</details>
+
+<details>
+<summary>Chromium with the synthetic backend</summary>
+
+```bash
+uv run --frozen --group e2e playwright install --with-deps chromium
+TGDRIVE_E2E=1 uv run --frozen --group e2e python -m pytest \
+  -m e2e tests/browser/
+
+# Focused explicit-refresh pending, failure and confirmation checks
+TGDRIVE_E2E=1 uv run --frozen --group e2e python -m pytest \
+  tests/browser/test_browser_refresh_feedback.py
+```
+
+Install Chromium/libraries inside WSL. Evidence stays in ignored `cache/browser-e2e`
+and feature folders. These render real UI against a test backend, without proving
+live Telegram transfers. Only dedicated tests generate image-heavy PDF fixtures.
+
+For player interaction changes, include `test_browser_player_gestures.py`,
+`test_browser_player_mobile.py` and `test_browser_player_settings.py` under
+`tests/browser/`. They use decoded media, a generated 65-second H.264/AAC gesture fixture,
+320/390 px portrait and 720 px landscape layouts, keyboard and fullscreen checks.
+Emulated touch is separate from physical-device/other-browser validation.
+
+`test_browser_player_controls.py` covers measured loading feedback, held delivery
+and decoded audio, frame stalls, retries, source-byte retention and buffered
+forward seeks during simulated network loss. The pinned-player checks in
+`website/scripts/check-movi-player.js` also exercise bitrate scaling, refill
+hysteresis, allocation failure, shared/non-shared buffer growth and hardware EOF
+drain. `website/src/features/previews/video/videoBufferMemory.test.ts` covers device-hint ceilings and the
+missing-hint fallback. Validate actual HEVC profiles on the
+target browser/OS; browser-native support alone does not validate the custom
+player. Thumbnail repair tests use cached sources and forbid origin payload reads;
+thumbnail rendering tests require FFmpeg and Poppler.
+
+</details>
+
+<details>
+<summary>Opt-in MongoDB replica-set tests</summary>
+
+Use a disposable local replica set or a dedicated test URI:
+
+```bash
+docker run -d --name tgdrive-test-mongo -p 127.0.0.1:27017:27017 \
+  mongo:8.0 --replSet tgdrive-test --bind_ip_all
+until docker exec tgdrive-test-mongo mongosh --quiet --eval 'db.adminCommand({ping:1})'; do sleep 1; done
+docker exec tgdrive-test-mongo mongosh --quiet --eval \
+  'rs.initiate({_id:"tgdrive-test",members:[{_id:0,host:"localhost:27017"}]})'
+until docker exec tgdrive-test-mongo mongosh --quiet --eval \
+  'if (!db.hello().isWritablePrimary) { quit(1); }'; do sleep 1; done
+export TGDRIVE_MONGO_TESTS=1
+export TGDRIVE_TEST_MONGODB_URI='mongodb://127.0.0.1:27017/?replicaSet=tgdrive-test&directConnection=true'
+uv run --frozen --all-groups python -Werror -m pytest tests/storage/test_mongodb.py -q
+```
+
+Tests require `TGDRIVE_TEST_MONGODB_URI`, never infer the deployment URI, and
+create/clean only exact random `tgdrive_test_` databases. CI uses its own replica
+set. Never use the application's real database. Remove the disposable server:
+
+```bash
+docker rm -f tgdrive-test-mongo
+```
+
+</details>
+
+### Live Telegram testing
+
+Use disposable channels/test credentials and owner-authorized message mutations.
+Record sizes, original-download checksums, rendered previews and confirmed remote
+outcomes privately. Never commit credentials or traces.
+
+## CI and release evidence
+
+### When GitHub checks run
+
+The [CI workflow](../.github/workflows/ci.yml) keeps routine pushes focused:
+
+| Trigger | Checks |
+| --- | --- |
+| Push to `main` or `dev` | Quality/security, frontend and backend tests with isolated MongoDB and coverage |
+| Pull request | Core checks, plus production-frontend Chromium tests |
+| Manual run | Core checks, plus the selected additional suite |
+
+All Python jobs use **3.14.8**, the sole supported runtime pinned in
+`.python-version` and the Docker image. There is no older-version test matrix.
+
+Pushes confined to Markdown, `docs/` or `LICENSE` skip automatic CI. Every pull
+request runs CI, including documentation-only changes, so required merge checks
+can finish. Documentation changes can still affect release contents; verify
+custom archives when preparing them for distribution.
+
+Release pull requests should pass `Quality and security`, `Frontend behavior`,
+`Backend tests` and `Chromium end-to-end` before merging into `main`.
+Repository branch protection is currently disabled; maintainers follow this
+release process without GitHub enforcing a merge gate.
+Manual container and source-release checks are separate from the merge gate.
+
+In **Actions → CI → Run workflow**, select the branch and additional suite:
+
+| Suite | Additional work |
+| --- | --- |
+| `core` (default) | None |
+| `browser` | Chromium workflows against the synthetic backend |
+| `container` | AMD64/ARM64 image builds and local container smoke checks |
+| `release` | Container checks, then build/extract/rebuild/test the source ZIP |
+| `all` | Browser, container and source-release checks |
+
+Container checks wait for core checks; source verification waits for the
+container. Browser failures do not prevent those independent packaging checks
+in an `all` run, but every selected check must pass before release. These checks
+do not deploy, publish an image or create a GitHub release. Browser evidence and
+source candidates are retained as Actions artifacts for 14 days.
+
+This avoids rebuilding Docker images and extracted releases for every push
+while keeping installation and packaging verification available before shipping.
+
+### Recorded results
+
+Use these records to understand coverage. Validate the exact release commit and
+clean extraction; keep its checksum with the test record.
+
+<details>
+<summary>GitHub CI failure review — 2026-10-26</summary>
+
+The push runs for `7a4ecc7`, `2321915` and `acd9ca5` passed frontend behavior
+and Python 3.14 tests but failed Bandit: B105 treated the recovery setting
+`MAIN_BOT_TOKEN=None` as a hardcoded password. That value clears the optional
+credential. A line-specific suppression preserves the value and keeps B105
+enabled elsewhere. The exact CI Bandit command passed locally on Python 3.14.8
+with no issues after this correction; it emitted unused-suppression warnings
+for other keys in the same settings mapping. No GitHub rerun or push was made.
+
+The subsequent `a5a8b1c` push passed frontend checks but
+[failed Ruff lint](https://github.com/TechShreyash/TGDrive/actions/runs/40373319271/job/121749557834)
+on four long lines and a nested condition from the download-scheduling change.
+After wrapping those lines, merging the equivalent condition and formatting one
+scheduler lambda, repository-wide Ruff lint passed and its format check reported
+**270 files already formatted**. No tests, builds or security audits were rerun
+for this correction; GitHub CI has not verified these local edits.
+
+Browser, container and source-release jobs were intentionally skipped on these
+pushes. The failed Bandit step also prevented the later Python dependency audit
+and frontend security smoke steps from running.
+
+</details>
+
+<details>
+<summary>Focused CI repair checks — 2026-10-26</summary>
+
+The local WSL checkout passed **253 affected Python tests** and the **three
+previously failing Chromium cases**, plus repository-wide Ruff lint/format,
+Bandit, Python/npm dependency audits and the production frontend build.
+Two MongoDB receipt tests skipped because the isolated database was not enabled.
+The Python audit passed after updating the locked `filelock` dependency to 4.2.4.
+
+These focused results do not establish a passing full GitHub run, full Python
+matrix, Docker build or extracted-release run. `actionlint` was unavailable.
+The frontend build still reports upstream media-bundle size/CommonJS warnings;
+Bandit reports stale suppression warnings without findings.
+
+</details>
+
+<details>
+<summary>Self-hosting snapshot and live original-byte validation</summary>
+
+These guides target **2.0.0** and fresh MongoDB deployments. On **2026-10-23**, the
+self-hosting snapshot passed 1,394 Python tests with isolated MongoDB and 84.07%
+coverage, 255 frontend tests, 53 Chromium checks, container/runtime/certificate
+checks, encrypted-archive restore into an empty database, lint/security audits.
+It did not deploy to live Coolify or use real Telegram credentials.
+
+Separately recorded live MongoDB evidence reconstructed a 4,562,805,302-byte file
+from three Telegram documents with matching SHA-256 and boundary-range checks.
+That establishes the tested original-byte path, not universal playback speed.
+
+Results apply to their tested revisions/environments. Workflow definitions are
+not proof of execution. Physical devices, multi-architecture execution, outages
+and Premium speedups need [separate evidence](roadmap.md#before-public-release).
+
+</details>
+
+## Version baseline and dependency policy
+
+| Tool/runtime | Baseline |
+| --- | --- |
+| App Python | 3.14.8 only |
+| uv | 0.13.4 |
+| Frontend Node | 24.22.0 LTS |
+| Container targets | Linux AMD64/ARM64 |
+
+Exact libraries live in [pyproject.toml](../pyproject.toml), [uv.lock](../uv.lock),
+[package.json](../website/package.json), [package-lock.json](../website/package-lock.json)
+and [Dockerfile](../Dockerfile). Do not replace locks with unconstrained installs.
+Updates need affected integration checks. CI uses Python 3.14.8 only;
+configuration alone is not executed evidence.
+
+## Code conventions
+
+Use the existing tool policies: Python follows the Ruff rules and 88-column limit
+in `pyproject.toml`; frontend TypeScript uses strict checking and the 80-column
+Prettier configuration in `website/.prettierrc.json`. Authored code uses four-space
+indentation. `.editorconfig` keeps UTF-8, LF and final newlines consistent across
+editors. After approval,
+`npm run format:check --prefix website` checks authored frontend formatting;
+`npm run format --prefix website` applies it.
+
+- Give each module a focused responsibility and name it after the behavior it owns.
+  Import its concrete owner instead of adding forwarding modules or barrel exports.
+- Use descriptive names and explicit units for time, byte counts and limits. Type
+  service boundaries and structured results; avoid spreading `Any` or type casts.
+- Keep components with their feature. Shared code serves multiple features and
+  does not import the application shell. Extract independently useful helpers
+  when they make policy or control flow clearer.
+- Prefer guard clauses and named decisions to deeply nested branches. Comments
+  explain intent, invariants and recovery limits; docstrings describe contracts.
+- Catch the errors a boundary can handle. Preserve cancellation, request identity
+  and durable-state ordering in transfer and recovery code; see the
+  [architecture contracts](architecture.md).
+
+## Repository map and test map
+
+| Location | What belongs here |
+| --- | --- |
+| `tgdrive/` | Backend domain packages; see the [backend code map](architecture.md#components) |
+| `website/src/app/` | Application shell, login, navigation and page composition |
+| `website/src/features/` | Files, shares, transfers, previews, settings/storage, performance and backup UI |
+| `website/src/shared/` | Common API client, types, controls, branding and theme |
+| `tests/` | Python tests grouped into domain packages, plus `browser/` |
+| `tests/support/` | Shared app fixtures, synthetic server and generated samples |
+| `tests/fixtures/` | Committed media fixtures shared by tests |
+| `scripts/` | Release packaging, viewer vendoring and brand asset tooling |
+| `docs/` | Public guides and their showcase assets |
+| `website/public/` | Browser assets, fonts, player and third-party notices |
+
+Keep new code in its owning domain. Frontend styles and `*.test.ts` / `*.test.tsx`
+files stay beside the module they exercise. Backend imports use concrete modules,
+for example `tgdrive.storage.store`; Python test helpers use qualified imports
+such as `tests.support.app_fixtures`. Retain lazy imports where they break
+dependency cycles; reusable fixtures belong in support modules, outside test cases.
+Use feature folders for cohesive groups of code. Single-screen code belongs with
+its existing owner: login in `app/`, and the storage/settings screen in `settings/`.
+
+Use `tgdrive.web.app:create_app` as the ASGI factory and import settings from
+`tgdrive.core.config`. `tgdrive/server.py` launches the container; startup handles
+initialization and the website provides administration and recovery.
+Keep Compose files, the Dockerfile, manifests and lockfiles at the root for tooling.
+`website/src/main.tsx` remains the frontend entrypoint.
+
+Runtime state belongs in `data/` and `cache/`; dependencies, bytecode and builds
+belong in their ignored generated directories. VS Code hides these generated
+folders through `.vscode/settings.json` without removing their contents. Existing
+`output/` captures and design drafts are ignored local development evidence;
+public showcase media belongs in `docs/assets/`.
+
+<details>
+<summary>Choose a focused test area</summary>
+
+| Area | Python test directory |
+| --- | --- |
+| Lifecycle, configuration and packaging | `tests/core/` |
+| HTTP, security, sharing, listing, connections and demo access | `tests/web/` |
+| Catalog and MongoDB | `tests/storage/` |
+| Telegram clients, bot mode and Premium login | `tests/telegram/` |
+| Jobs, uploads, split files and URL imports | `tests/transfers/` |
+| Streaming, cache, previews, books and thumbnails | `tests/media/` |
+| Checkpoints and database recovery | `tests/recovery/` |
+| Independent channel backups and activation | `tests/replication/` |
+| Performance counters, logging, request IDs and history | `tests/observability/` |
+| Real Chromium with synthetic backend | `tests/browser/` |
+
+The default pytest invocation still discovers `tests/` recursively. Browser tests
+remain opt-in through `TGDRIVE_E2E=1`; MongoDB integration tests retain their own
+opt-in configuration. For side-effect changes, cover retry, cancellation,
+interruption and ownership loss against the [architecture contracts](architecture.md).
+
+</details>
+
+## Frontend contracts
+
+Keep the file manager focused on browsing, transfers and maintenance. Use a
+compact toolbar, independently scrolling workspace and restrained bordered
+sections. The [checked-in captures](showcase.md) illustrate the interface.
+
+| Concern | Canonical source |
+| --- | --- |
+| Palette, typography and workspace layout | [Application CSS](../website/src/app/style.css) |
+| Shared control styles | [Design-system CSS](../website/src/shared/design-system.css) |
+| Mantine provider and component defaults | [DesignSystem.tsx](../website/src/shared/DesignSystem.tsx) |
+| Light, dark and system appearance | [theme.ts](../website/src/shared/theme.ts) |
+| Brand artwork | [SVG masters](../website/public/static/brand/) |
+
+- Reuse semantic tokens, self-hosted Inter and Lucide icons. Keep logo cobalt
+  separate from interface action colors. Use tabular numerals for measurements.
+- Use `BrandLogo`; preserve the SVG masters' proportions, openings
+  and clear space. Generate raster assets with `scripts/brand-assets.py`.
+- Retain native dialog and custom player behavior. Keep shared theme variables
+  in bundled external CSS and preserve the content security policy.
+- Preserve keyboard focus and saved appearance. Target 4.5:1 text contrast, 3:1
+  meaningful control/chart contrast and 44px touch targets. Respect browser zoom.
+- Keep menus and controls brief and responsive; avoid decorative entrance effects.
+  Honor reduced motion, and keep correctness independent of animation completion.
+- Show fresh-request progress and actionable errors. Announce successful saves or
+  refreshes only after completion; background polling stays quiet. Keep performance
+  measurements honest about missing data and uncertainty, and show preload coverage
+  across the available workspace width.
+
+Keep upload byte verification, stable operation IDs and atomic folder preparation
+intact. The interaction and accessibility contracts below cover individual flows.
+
+<details>
+<summary>Media compatibility and redistribution</summary>
+
+Movi and PDF.js install from committed modified npm archives in
+[`website/vendor/`](../website/vendor/README.md). The lockfile records archive
+integrity; normal installs, development and builds do not rewrite dependencies.
+New upstream releases cannot silently replace these viewer packages. Upgrades
+are deliberate: review the upstream source, update the recipes, regenerate with
+`scripts/vendor_viewers.py` and run the focused checks. Other dependencies still
+come from the locked npm installation; this is not a fully offline build.
+
+[MovTextRenderer.ts](../website/src/features/previews/video/MovTextRenderer.ts) renders MP4 mov_text/tx3g
+through the public subtitle extension as inert text: strict UTF-8/BOM UTF-16,
+no style/link boxes. Bounds are 128 KiB packets, 16 Ki-character cues, 4096 cues /
+2 Mi characters queued, eight visible overlaps. Seeking/track changes clear cues;
+Off/source cleanup removes owned DOM/styles. Test visible English/Hindi,
+HTML-looking text, seeking/Off and original bytes; MKV/SRT is a separate regression.
+
+[AdvancedVideo.tsx](../website/src/features/previews/video/AdvancedVideo.tsx) adapts Movi 0.4.1 private
+`addStyles` for local fonts and CSP. Upgrades must recheck APIs/styles using the
+real WASM fixture, EAC3 output/track changes, subtitles, seek/close and external-
+request/CSP checks. Inspect worker diagnostics as well as document CSP events.
+Keep controls reachable during startup/buffering; source coverage does not prove
+decoder readiness. Clean listeners/timers and test delayed media/reduced motion.
+
+Preserve full [third-party notices](../website/public/third-party/README.txt),
+including React/Scheduler/Lucide/Feather attribution and viewer/codec/font licenses.
+The source/relink archive includes FFmpeg/dav1d, application C/C++ and published
+static archives. Notices record upstream's stale version label, binary/header
+recipe evidence and reproduction limits; TGDrive has not independently rebuilt
+the published decoder WASM.
+
+</details>
+
+### Shared-links interface
+
+<details>
+<summary>Link identity, exposure indicators and URL recovery</summary>
+
+Key per-link state by share ID, even when links target one item. Expired links
+never produce sharing indicators; public browsers never fetch owner share data.
+Keep indicators visible beside truncated names. Unreconstructable URLs offer
+**New Link**, never silent rotation. Refresh indicators after the share dialog closes.
+
+</details>
+
+### UI Capitalization
+
+Title-case fixed labels/actions; sentence-case explanatory text. Display user
+filenames verbatim, without text transforms. Use **My Files** for TGDrive's root
+navigation label.
+
+### Quiet Overlays and Touch Controls
+
+<details>
+<summary>Shell, listing and transfer behavior</summary>
+
+- Desktop transfer popups show unfinished browser-initiated work, disappear five
+  seconds after completion and never open from history alone. Management pages
+  omit them. Phones use a reserved bottom status row opening Transfers.
+- Mobile has a top navigation/brand/New/appearance bar and independently scrolling
+  workspace. The full-height drawer has one scroller. Hide New outside My Files
+  and during dialogs; selection must not shift the list vertically.
+- Mouse opens by double-click; touch/Enter opens once. Select explicitly enables
+  selection and retains file icons. Small-screen actions have 44 px hit areas.
+- Background listing refresh preserves rows, scroll, pagination and selections;
+  failures retain the last listing and show errors. Placeholders belong to new
+  listings, not background refreshes.
+- Build batches before assigning sections/filters; retain every child and its
+  status. Running precedes queued; terminal outcomes share Finished with All,
+  Successful, Failed and Cancelled filters and server-authoritative pagination.
+- Batch disclosure is one stable button without navigation; Show Folder is a
+  separate completed action. Expanded children omit repeated locations/dates.
+  Retain disclosure state across category changes. Show device progress while any
+  local upload still needs the browser, then switch to Telegram progress after
+  every remaining file has an accepted server job. Follow the
+  [upload display rules](usage.md#what-upload-progress-means); never invent queued timers/ETAs.
+- Folder confirmation shows selection/count/size/destination/actions. Show skipped
+  files only when present. Move conflicts use explicit themed choices.
+
+</details>
+
+### UI Audit Contracts
+
+Use this checklist when changing dialogs, navigation, selection or transfer controls.
+
+- [ ] Navigation traps focus, makes covered content inert, restores focus on close
+  and closes on desktop resize. Selection exposes mixed state and visible icons.
+- [ ] Icons have accessible names; filters meet contrast. Reduced motion retains
+  loading text without spinner rotation.
+- [ ] Pagination returns to the top; reveal navigation still focuses the item.
+  Move dialogs have bounded scrolling; disable Move Here for unchanged destinations.
+- [ ] Failed loads offer Try Again instead of empty states; revocation errors stay
+  inside confirmation. Cancel All requires confirmation.
+- [ ] Drops require a visible My Files destination. Folder drops request Upload Folder,
+  never silently flatten. Use isolated browser fixtures for destructive checks.
+
+## Source releases
+
+Follow [release verification](release.md) for the canonical publication procedure.
+These commands build a reviewable artifact; use the actual version after a bump:
+
+```bash
+uv run --frozen python scripts/build_release.py
+(cd dist && sha256sum --check tgdrive-2.0.0.zip.sha256)
+unzip -l dist/tgdrive-2.0.0.zip
+```
+
+<details>
+<summary>Artifact and container checks</summary>
+
+Build twice and compare ZIP bytes. Review the public allowlist/manifest and check
+privately for secrets; an allowlist is not a scanner. Exclude credentials, state,
+staging, logs, private fixtures/evidence, installed/generated dependencies and Git
+history. Retain public docs, lockfiles, tests and full licenses/source access.
+Validate the manifest, locked install, tests/build and container from a clean
+extraction. Shipped tests must not require omitted private fixtures.
+
+```bash
+docker buildx build --platform linux/amd64 --load -t tgdrive:release-candidate .
+docker run --rm --network none --entrypoint python tgdrive:release-candidate \
+  -c 'import tgdrive.web.app, telethon, cryptg, argon2; print("runtime imports passed")'
+docker buildx build --platform linux/arm64 --load -t tgdrive:release-candidate-arm64 .
+```
+
+ARM execution needs hardware or QEMU/binfmt. Check assets, nonroot/writable
+permissions, disposable initialization, shutdown and restart. Imports do not prove
+login. Distinguish unit, synthetic browser, live Telegram, container and emulated
+execution; small files and receipt crashes do not establish near-limit/send recovery.
+
+</details>
+
+## Documentation maintenance
+
+Follow [AGENTS.md](../AGENTS.md): update important behavior with its implementation,
+keep one canonical explanation, link focused public guides from Docs home and add
+them to `PUBLIC_DOCS` in `scripts/build_release.py`. Keep guides brief, put technical
+detail in collapsible sections, and record change history in meaningful Git commits.
+Update each guide's **Contents** links when adding, renaming or moving sections.
+
+## Independent channel backup contracts
+
+<details>
+<summary>Journal guarantees and focused validation</summary>
+
+`replica_state.py` owns the private journal/authenticated capsule;
+`replica_transport.py` owns the independent bot and copy confirmation;
+`replica.py` coordinates recoverable catalog publication; `replica_api.py` and
+`ChannelBackup` expose owner/recovery controls.
+
+Keep copied media, mappings and protected revision consistent. Confirm both
+recovery metadata copies before advancing protection. Persist send identities
+before calls and reuse them after ambiguity. Restored catalogs must never replay
+old-channel jobs/deletions against new IDs. Preserve sources/prior state during activation.
+
+[Telegram account-wide random_id deduplication](https://core.telegram.org/api/updates#updatemessageid-updates)
+survives sessions. `RANDOM_ID_DUPLICATE` may mean the first send is in flight;
+retain the typed error and retry the same identity after a bounded wait. Verify
+typed update receipts and the destination document before journal confirmation.
+
+The offline transport/coordinator tests cover request pacing, fresh channel and
+document checks, bounded batch verification, ambiguous sends and durable waits:
+
+```bash
+uv run --frozen python -m pytest tests/replication/test_replica_transport.py tests/replication/test_replica.py -q
+```
+
+These tests use synthetic Telegram clients; they do not establish live Telegram
+rate limits or demonstrate production backup completion. Pacing and retry policy
+are documented in the [backup guide](backup-recovery.md#enable-and-confirm-the-first-copy).
+
+For the broader offline backup group, including journal rollback, pause races,
+session authorization waits, archive handoff and activation/bootstrap recovery:
+
+```bash
+TGDRIVE_MONGO_TESTS=0 uv run --frozen python -m pytest \
+  tests/replication/test_replica.py tests/replication/test_replica_transport.py \
+  tests/replication/test_replica_state.py tests/replication/test_replica_settings.py \
+  tests/replication/test_replica_mongo.py tests/replication/test_replica_activation.py \
+  tests/replication/test_replica_activation_mongodb.py tests/replication/test_replica_bootstrap.py \
+  tests/replication/test_replica_api.py tests/replication/test_replica_deletion_barrier.py -q
+```
+
+The opt-in live MongoDB tests are skipped by this command. It makes no live
+Telegram requests and does not replace a recovery rehearsal.
+
+```bash
+TGDRIVE_E2E=1 uv run --frozen --group e2e python -m pytest tests/browser/test_browser_channel_backup.py -q
+```
+
+This uses real auth/API/UI with a synthetic replica service at 1440/390/320 px.
+It covers configuration, progress, pause/retry, exports and explicit recovery
+activation, not live copying or independent human-account ownership. Live tests
+need disposable private source/target channels and unrelated bots; rehearse both
+directions and database-only recovery without risking the only copy.
+
+</details>
+
+### Selective book pages and shared PDF resources
+
+The vendored PDF.js worker keeps image substreams sparse during parsing, defers image
+stream bodies in page resource discovery and loads a painted image's dependencies
+after dimension/size rejection and before decoding. Its recipe is
+`website/scripts/patch-pdf-worker.js`; version/source guards reject unknown inputs
+during deliberate vendor regeneration. Normal frontend commands use the committed
+modified package. Review the recipe when updating PDF.js. Focused tests live in
+`website/scripts/check-pdf-worker.js`; the `shared` case in
+`tests/browser/test_browser_pdf_ranges.py` exercises a generated PDF with every page image
+in one shared resource dictionary. These are synthetic fixtures, not a guarantee
+for all PDFs or devices.
+
+`website/scripts/pdfjs-assets.ts` serves and emits matching local CMaps, standard
+fonts, color profiles and decoder WASM with their resource notices. These resources
+support additional character sets and image formats without an asset CDN. Keep
+sparse transport, page/image/pixel bounds and XFA/script restrictions intact.
+Password prompts pass only an in-memory value to PDF.js; passwords are never
+stored in browser preferences or sent to a TGDrive password endpoint.
+
+`tests/media/test_books.py` covers unchanged large original page bytes and bounded result
+reuse. `tests/media/test_books_api.py` covers access checks on cached/conditional responses.
+`website/src/features/previews/books/bookImage.test.ts` covers download progress, errors, retry and cancellation;
+the comic error/recovery, large original page and EPUB offscreen-image cases in
+`tests/browser/test_browser_books_shares.py` exercise the shipped UI and HTTP path.
diff --git a/docs/hosting.md b/docs/hosting.md
new file mode 100644
index 00000000..1a25129a
--- /dev/null
+++ b/docs/hosting.md
@@ -0,0 +1,205 @@
+# Run TGDrive locally or on a server
+
+[Docs home](README.md) · [Setup](setup.md) · [Using TGDrive](usage.md)
+
+**Must read before using TGDrive: [New-user guide and FAQs](new-user-guide.md).**
+Its privacy, channel and backup responsibilities also apply to managed hosting.
+
+**TGDrive is completely free and open source.** Anyone can use, modify and deploy
+it under the [MIT License](../LICENSE). All features are available whether you
+run it on your own computer, choose your own server or ask us to manage hosting.
+
+Deploy a published release tag or stable `main` source; `dev` is ongoing work and
+may be unstable. Follow [source selection](setup.md#get-the-source) for local,
+Coolify and server installations.
+
+**Contents**
+
+- [Local computer or server](#local-computer-or-server)
+- [Optional managed hosting](#optional-managed-hosting)
+- [What you prepare](#what-you-prepare)
+- [Server plans and customization](#server-plans-and-customization)
+- [Capacity and practical limits](#capacity-and-practical-limits)
+- [Keep control of your drive](#keep-control-of-your-drive)
+- [Help improve TGDrive](#help-improve-tgdrive)
+
+## Local computer or server
+
+Localhost is the default installation at `127.0.0.1:8000`, accessible from the
+computer running TGDrive. It still needs the internet to reach Telegram and
+MongoDB. A hosted server provides a reachable address while your personal
+computer is off.
+
+| Feature or workflow | Your computer, with default local access | Server with a public HTTPS address |
+| --- | --- | --- |
+| All TGDrive features | Included, free | Included, free |
+| Access on the go | This computer by default; remote access needs extra setup | Phone, tablet or computer through an internet-connected browser |
+| Multiple people using the same drive | Possible if they can reach your installation | Simultaneous access within server capacity |
+| Public file and folder links | Other people need a reachable address; localhost links do not work on their devices | Recipients can use the public address while the server is available |
+| Accepted uploads, URL imports, manual preloads, bot uploads and backups | Continue while your computer and TGDrive remain running | Continue while the server and TGDrive remain running |
+| Work while your laptop is asleep or off | Stops when the computer hosting TGDrive stops | Continues independently of your laptop |
+| Resources and maintenance | Your computer, connection and maintenance | Your chosen server; maintain it yourself or use optional management |
+
+Device uploads need the browser until **You can close this tab** appears. Keep
+originals until **Completed**. Automatic playback read-ahead follows active
+viewers; a manual whole-file preload can continue without them. The app,
+MongoDB, Telegram and network must remain available. See
+[transfer status meanings](usage.md#can-i-close-the-tab).
+
+Multiple people can sign in with the same owner password. They share full access
+to files and settings; TGDrive does not provide separate personal accounts or
+per-person permissions. Use read-only share links for selected files or folders.
+[Device access and sessions](usage.md#use-several-devices) · [Sharing](usage.md#share-and-revoke)
+
+Remote access to a computer-hosted installation needs
+[HTTPS and deployment setup](setup.md#hosting-beyond-your-machine). That computer
+must stay awake and reachable.
+
+## Optional managed hosting
+
+For help with deployment and maintenance, we offer **managed TGDrive hosting from ₹100/month
+(INR), including a server**. This is the total starting monthly price, not a
+management fee added to a separate server bill.
+
+| Included | What you receive |
+| --- | --- |
+| Server and TGDrive access | Full access to your server and TGDrive, with every TGDrive feature available |
+| Deployment and ongoing management | We configure and deploy TGDrive, handle server/deployment maintenance and updates, and help troubleshoot hosting problems |
+| Personal public HTTPS subdomain | Your own drive address for access from a browser on the go and for sharing links |
+| Your accounts and storage | Your Telegram account, private channel and bots; MongoDB in your own account |
+| Capacity choices | More server resources when you need to handle more simultaneous requests, viewers, uploads or downloads |
+
+Your HTTPS address is public, but your owner drive remains password-protected.
+You choose which files or folders to expose through read-only share links.
+
+There are **no additional hosting-plan caps on file size or upload/download
+counts**. Every plan includes the same app features. Higher payments buy more
+capacity for work happening at the same time, not feature unlocks. Configured
+upload limits, real disk space and the server's bandwidth allowance still apply;
+see [practical limits](#capacity-and-practical-limits).
+
+[Contact TechShreyash on Telegram](https://t.me/TechShreyash) to arrange setup and
+choose resources for your workload. Confirm the CPU, RAM, disk and monthly
+bandwidth included in your managed quote, any upgrade price and current
+availability. The ₹100 starting offer includes a server; the server-only table
+below is a separate set of prices, not an extra charge added to that offer.
+
+If you prefer to manage TGDrive yourself, you can also buy just a server from us.
+You are equally free to use your own server or another provider.
+
+## What you prepare
+
+Your drive belongs to you, so some account setup stays on your side. Create the
+following in accounts you control, then provide the required deployment
+credentials privately to us for managed setup.
+
+| Prepare | What is needed |
+| --- | --- |
+| MongoDB Atlas | A cluster, dedicated database, database user with read/write access and connection URI. Allow the TGDrive server's IP in Network Access. [MongoDB steps](setup.md#1-prepare-mongodb) |
+| Telegram application | Your API ID and API hash from Telegram's application page. [Telegram steps](setup.md#2-prepare-telegram) |
+| Private Telegram channel | A dedicated private broadcast channel, its numeric ID, message auto-delete off, and no unrelated message management |
+| Main bot | A bot you create through BotFather and its token; add it as a channel administrator with **Post Messages** and **Delete Messages**. It initially provides storage and the private-chat upload interface. |
+| Allowed Telegram users | Your numeric Telegram user ID, plus any other users allowed to send files to your main bot. [Find your ID](setup.md#find-your-telegram-user-id) |
+| Owner sign-in | A private TGDrive web password, kept separately from the public demo password |
+
+Add extra storage bots later through **Management → Connections**. Premium
+account sign-in and a separate backup channel are optional, not prerequisites
+for ordinary storage or large split files. Use the
+normal authorization flow if you choose Premium; basic managed deployment uses
+the credentials above, not your main Telegram account's login code/password.
+[Bot uploads](usage.md#optional-telegram-bot-interface) ·
+[Additional bots and Premium](setup.md#additional-bots-and-premium-accounts)
+
+We use the supplied credentials to configure the server, connect your channel and
+database, and publish your personal HTTPS address. Share them only through the
+private setup conversation, never in a public issue, screenshot or repository.
+Changes to database access or revoked bot credentials can interrupt the drive;
+coordinate replacements through the [connection maintenance guide](usage.md#settings-and-connections).
+
+At handoff, keep your server access, TGDrive login, MongoDB access and deployment
+configuration. Download **Storage & Backups → Save recovery key**, keep it off
+the server, and confirm a database backup before relying on recovery. Follow the
+[recovery kit guide](backup-recovery.md#keep-the-mongodb-recovery-kit-outside-the-server).
+
+## Server plans and customization
+
+These are **temporary launch-discount prices** for a server you manage yourself,
+in INR per month. Contact us for current availability and pricing.
+
+| vCPU | RAM | Server storage | Monthly bandwidth | Price/month |
+| --- | --- | --- | --- | --- |
+| 1 | 1 GB | 32 GB | 1 TB | ₹99 |
+| 1 | 2 GB | 64 GB | 2 TB | ₹149 |
+| 2 | 4 GB | 100 GB | 5 TB | ₹249 |
+| 4 | 8 GB | 180 GB | 6 TB | ₹399 |
+| 8 | 16 GB | 350 GB | 8 TB | ₹699 |
+
+Some resource customization, such as additional RAM or storage, can be arranged.
+[Contact TechShreyash](https://t.me/TechShreyash) for availability and a quote.
+Ask how bandwidth is counted and what happens if its allowance is reached;
+unlimited upload/download counts do not mean unlimited network traffic.
+
+Managed capacity upgrades are quoted separately from this server-only table.
+For self-managed deployment, follow [Setup](setup.md); the
+[self-hosted Coolify option](setup.md#coolify) can help manage deployment.
+
+## Capacity and practical limits
+
+Before choosing a larger server, use the
+[load and capacity guide](performance-tuning.md) to match CPU, RAM, disk, network
+or Telegram clients to the bottleneck shown by your workload.
+
+The same limits and scheduling rules apply on localhost and servers. The hosting
+offer adds no paid file-size or transfer-count restriction; it does not remove
+the app's technical bounds or the infrastructure's finite resources.
+
+| Resource | What it affects |
+| --- | --- |
+| CPU and RAM | How much preview, parsing and concurrent request work can fit; memory caching and background work share these resources |
+| Server disk | Unfinished uploads, caches, application files and system overhead; it is not your total Telegram library size |
+| Network and monthly bandwidth | Transfer throughput and the amount of traffic the server plan can carry |
+| Telegram and MongoDB access | Provider availability, account cooldowns, database capacity and connection health |
+| Device and viewer connections | Your upload connection and each recipient's download connection remain part of the path |
+
+New uploads default to a **16 GiB file limit and 16 GiB temporary upload budget**.
+Larger files require raising both settings and having enough actual free server
+disk; the smallest server plans cannot stage arbitrarily large files. TGDrive
+splits large files into Telegram documents and presents them as one logical file.
+Use the [configuration guide](configuration.md#upload-size-and-available-disk-space)
+for current adjustable bounds and the [reference](reference.md#file-capacity-staging-and-work-limits)
+for multipart and catalog limits.
+
+Higher server capacity can support more simultaneous users and requests when
+server resources are the bottleneck. It does not create separate user accounts,
+guarantee a particular number of active users or set a guaranteed transfer speed.
+See [performance factors](performance.md#follow-the-data-path) before choosing or
+upgrading a plan.
+
+## Keep control of your drive
+
+File bytes live in your private Telegram channel. MongoDB stores the catalog,
+folder structure, part mappings, settings and shares. Local server disk holds
+unfinished uploads, recovery state and disposable cache. Keep control of all
+three parts, plus the matching recovery keys.
+
+Managing the server requires administrative access to its deployment credentials
+and data. Keeping the accounts in your name does not make their contents
+inaccessible to the operator: Telegram payloads are not separately encrypted by
+TGDrive. Encrypted database backups protect their backup archives. See the
+[backup and security limits](backup-recovery.md) for the full model.
+
+If hosting ends, completed Telegram files remain in your channel. With the
+matching catalog, Telegram access and recovery kit, you can reopen the same drive
+on your laptop or another server without re-uploading completed files. Preserve
+your database and configuration before server access ends. Public links and
+background work need a reachable running app, and unfinished uploads still need
+their staged bytes or original device files.
+[Move or reopen your drive](operations.md#when-a-hosting-plan-expires).
+
+## Help improve TGDrive
+
+Contributions, feedback, bug reports and feature requests are welcome from
+everyone, including people running it entirely themselves. Hosting is optional.
+[Open a GitHub issue](https://github.com/TechShreyash/TGDrive/issues) or follow the
+[development guide](development.md) and [contributor guidance](../AGENTS.md).
+Keep credentials and private links out of public reports.
diff --git a/docs/new-user-guide.md b/docs/new-user-guide.md
new file mode 100644
index 00000000..f2241395
--- /dev/null
+++ b/docs/new-user-guide.md
@@ -0,0 +1,466 @@
+# New-user guide and FAQs
+
+[Docs home](README.md) · [Setup](setup.md) · [How to use TGDrive](usage.md) · [Backup & recovery](backup-recovery.md)
+
+**Must read for everyone using or running TGDrive, including managed hosting.**
+
+Learn how the drive works, prepare for your first upload and find
+answers about everyday use, storage, privacy and recovery. For installation
+steps, follow [Setup](setup.md).
+
+**Contents**
+
+- [What TGDrive is](#what-tgdrive-is)
+- [The essentials everyone must know](#the-essentials-everyone-must-know)
+- [Before your first important upload](#before-your-first-important-upload)
+- [Do and don't](#do-and-dont)
+- [Frequently asked questions](#frequently-asked-questions)
+  - [Basics and storage limits](#basics-and-storage-limits)
+  - [Privacy and backups](#privacy-and-backups)
+  - [Uploading and using files](#uploading-and-using-files)
+  - [Access, maintenance and recovery](#access-maintenance-and-recovery)
+  - [Resources, deletion and support](#resources-deletion-and-support)
+
+## What TGDrive is
+
+TGDrive is a free, open-source web app that gives files in your own Telegram
+channel a drive-style interface: folders, search, uploads, previews, readers and
+share links. It is an independent project, not an official Telegram storage service.
+The [MIT License](../LICENSE) permits use, modification and redistribution.
+
+Your drive relies on three parts working together:
+
+| Part | What TGDrive uses it for |
+| --- | --- |
+| **Private Telegram channel** | Stores completed uploads as Telegram messages. Large files may span several messages. |
+| **MongoDB database** | Saves file names, folders, settings and share links. Records which Telegram messages hold each file and how its parts fit together. |
+| **Your computer or server** | Runs the website and handles uploads, downloads and previews. Holds unfinished uploads, temporary file copies and private configuration. |
+
+To use TGDrive's website or share links, the computer or server running it
+(the **host**) must stay on and keep access to MongoDB and Telegram. Stopping
+TGDrive does not delete completed files, but its website and share links are
+unavailable until it runs again.
+
+The **catalog** is the file index kept in MongoDB. Telegram messages alone do not
+rebuild your folders or tell TGDrive how to join split files. Preserve the
+database or a usable backup of it alongside the Telegram files.
+[Where data is saved](operations.md#what-is-saved-where).
+
+**Unlimited total storage is not a promise of unlimited file size or permanent
+access.** Telegram account/channel restrictions, database capacity and server
+resources still matter. A private channel limits membership; TGDrive does not
+add end-to-end encryption to stored files.
+
+## The essentials everyone must know
+
+- **Keep valuable files outside Telegram too.** Do not make TGDrive your only
+  copy of an irreplaceable file. A second Telegram channel still uses the same provider.
+- **Wait for the right status.** Keep the upload tab open until **You can close
+  this tab**, and keep source files until **Completed**. Independent protection
+  requires its own **Backup confirmed** status.
+- **Treat the storage channel as app-managed.** Use a dedicated private broadcast
+  channel with auto-delete **Off**. Add files through TGDrive or its configured
+  upload bot, and make file changes through TGDrive. Do not edit storage messages,
+  recovery pins or channel history, or add cleanup/moderation bots.
+- **Protect the catalog and recovery material.** Preserve MongoDB, channel access,
+  private configuration and persistent volumes. Save matching recovery keys and
+  restore-point exports outside both the server and Telegram.
+- **Know who can access your drive.** The owner password grants full shared
+  access. A valid share link lets its holder read the selected file or folder.
+  Use HTTPS for remote access, a unique owner password, Telegram two-step
+  verification and secure database access. Keep credentials, channel invitations
+  and recovery keys private.
+- **Use only disposable files in the public demo.** It is a shared workspace,
+  not your private drive. Other visitors can change unprotected files.
+  [Demo instructions](usage.md#try-the-public-demo).
+
+## Before your first important upload
+
+1. Upload a non-private sample and wait for **Completed**. Download the original
+   and open it to understand the full upload/download workflow.
+2. Try a share link in a signed-out browser, then revoke it. Share a specific
+   file or folder rather than giving someone the owner password.
+3. If using independent backups, wait for **Backup confirmed** and save the
+   matching recovery export separately. An enabled backup switch or 100% copied
+   bytes alone is not confirmation. Follow the
+   [recovery-kit guidance](backup-recovery.md#verify-your-recovery-kit-periodically)
+   before relying on it.
+
+## Do and don't
+
+- Keep storage bots as channel administrators with the
+  [required permissions](setup.md#2-prepare-telegram). Follow the
+  [connection maintenance guide](operations.md#connection-changes) before replacing
+  credentials, removing bots or changing channel/database bindings. Keep unrelated
+  posts out of the storage channel.
+- Run **one active TGDrive instance per drive**. Preserve its saved data and
+  persistent volumes during updates or a move; do not delete them to clear an error.
+- Leave disk space for unfinished uploads and cached file copies. Use the existing
+  **Retry** or resume action, reselect the same originals when asked, and respect
+  displayed Telegram waits. Repeated restarts do not bypass those waits. Keep
+  unfinished upload files; they are not disposable cache.
+- Store and share only files you are entitled to use, following
+  [Telegram's terms](https://telegram.org/tos). Private channels still follow those terms.
+
+If something breaks, keep the existing state and read the error before changing
+configuration. Start with [Operations](operations.md#troubleshooting). **Never
+replace an existing drive with an empty database as a repair.**
+
+## Frequently asked questions
+
+### Basics and storage limits
+
+<details>
+<summary>Why use TGDrive if I can already upload files to a Telegram group?</summary>
+
+Uploading in Telegram is useful on its own. TGDrive adds a file/folder catalog,
+browser previews and readers, resumable uploads and scoped sharing. Its large
+uploads can span several Telegram documents while appearing as one file in TGDrive.
+
+TGDrive's storage destination must be a dedicated **private broadcast channel**,
+not an ordinary group chat. Posting files directly into that channel is not the
+supported import workflow, and existing chat history is not automatically added
+to the catalog. Use the website or the optional configured upload bot.
+
+Only Telegram users allowed by the owner's bot configuration can import files
+through a private chat with that bot. Protected forwards can fail, and bot imports
+lack the web queue's full restart/resume guarantees. Prefer the website for uploads
+needing that workflow.
+[Web uploads](usage.md#upload-files-or-folders) · [Telegram bot setup and use](usage.md#optional-telegram-bot-interface).
+
+</details>
+
+<details>
+<summary>Is it the same as Google Drive or OneDrive?</summary>
+
+It offers similar file-management tasks, using Telegram for file storage.
+That comparison does not promise identical features or service guarantees.
+TGDrive is a web drive, not an automatic desktop-folder sync client or an office
+collaboration suite. It needs a running host, Telegram access and its catalog.
+[See the features](../README.md#features) and [local versus server use](hosting.md#local-computer-or-server).
+
+</details>
+
+<details>
+<summary>Is TGDrive free and open source? Do I have to buy hosting?</summary>
+
+TGDrive is MIT-licensed and all app features are available for free. Run it on
+your computer or your chosen server. Hosting, internet access and database
+resources can have their own costs. [Managed hosting](hosting.md) is optional;
+it is help operating the same app, not a paid feature tier.
+Contributions, feedback, bug reports and feature requests are welcome on [GitHub](https://github.com/TechShreyash/TGDrive/issues).
+
+</details>
+
+<details>
+<summary>Does unlimited storage mean my files stay forever?</summary>
+
+No. TGDrive does not meter the total bytes stored in your channel, and Telegram
+advertises [free unlimited cloud storage](https://telegram.org/faq_premium#q-is-telegram-still-free).
+That does not establish a permanent-retention guarantee. Deletion, lost access,
+account or channel restrictions, provider changes and operational failures can
+make files unavailable. Keep an independent backup of important files.
+
+</details>
+
+<details>
+<summary>Can I upload any size of file? Do I need Telegram Premium?</summary>
+
+Telegram describes [2 GB uploads for ordinary accounts and 4 GB with Premium](https://telegram.org/blog/700-million-and-premium#4-gb-uploads).
+TGDrive handles larger logical files by splitting them into bounded Telegram
+documents and reconstructing reads/downloads. Premium is optional for this.
+The catalog's part mappings and all required parts must survive.
+
+TGDrive defaults to **16 GiB per file** and a **16 GiB temporary upload budget**.
+Larger files require raising the relevant limits and enough actual staging disk;
+configured and technical ceilings still apply. The catalog also has a
+**250,000 file/folder limit**. See [upload settings](configuration.md#upload-size-and-available-disk-space)
+and [exact capacity limits](reference.md#file-capacity-staging-and-work-limits).
+
+</details>
+
+<details>
+<summary>Can I rely on a 3–4 TB library working?</summary>
+
+A multi-terabyte **library** is different from one multi-terabyte **file**.
+TGDrive has no total storage cap, but its practical limits and performance still
+apply. File count, individual file sizes, database capacity, server disk, network
+and Telegram all matter.
+
+Experience with a 3–4 TB library on an older release does not establish how the
+current version will handle your workload. Start with representative files, grow
+gradually and keep separate copies. [Performance factors](performance.md#follow-the-data-path).
+
+</details>
+
+### Privacy and backups
+
+<details>
+<summary>Can Telegram see or act on files in a private channel? Can it ban an account?</summary>
+
+Private does not mean invisible to the provider. TGDrive uses Telegram cloud
+storage, not Secret Chats. Telegram's [privacy policy](https://telegram.org/privacy#3-3-1-cloud-chats)
+describes cloud storage, abuse checks and possible account restrictions or bans.
+TGDrive cannot promise ban immunity or quote a reliable ban probability or safe
+storage-size threshold. Seeing other large channels is not evidence of either.
+
+Follow [Telegram's terms](https://telegram.org/tos), keep account access secure
+and plan for a loss of access. A restriction on one account does not prove that
+every channel copy is lost, but neither does another channel guarantee recovery.
+
+</details>
+
+<details>
+<summary>Are my files end-to-end encrypted? Who else can read them?</summary>
+
+TGDrive does not encrypt your original files, unfinished uploads or cached copies.
+Its encrypted database backups do not make the original files end-to-end encrypted.
+Treat the hosting operator, people with server or storage-channel access, and
+people with owner credentials as trusted parties. See the
+[security boundaries](reference.md#security-and-privacy) and Telegram's distinction
+between [Cloud Chats and Secret Chats](https://telegram.org/faq#q-how-do-you-encrypt-data).
+
+For files needing stronger confidentiality, encrypt them yourself before upload
+and keep decryption keys separately. TGDrive will not decrypt those files for
+ordinary previews; expect to download and decrypt them locally. TGDrive also
+does not scan uploads for malware, so only open downloads you trust.
+
+</details>
+
+<details>
+<summary>Do two channels on different accounts make my data ban-proof?</summary>
+
+No. TGDrive can optionally maintain a recovery copy in a second channel using a
+separately controlled Telegram account and backup bot. Configure it explicitly,
+wait for **Backup confirmed**, and save the matching recovery-key export outside
+Telegram and the server. Newer changes can still be pending.
+
+Recovery needs an accessible copy, a confirmed backup you can restore and its
+matching recovery material. You must follow the recovery procedure; TGDrive does
+not switch channels automatically. Both channels remain on Telegram; keep another
+copy outside that provider for risks affecting both.
+[Independent backup setup and recovery](backup-recovery.md#set-up-an-independent-backup-channel).
+
+</details>
+
+<details>
+<summary>What does a database backup protect? Is Completed enough?</summary>
+
+A database backup protects the catalog, part locations and saved app state; it
+cannot recreate missing Telegram file bytes. Independent channel protection
+also copies completed documents and their recovery metadata. Neither includes
+unsent device originals or unfinished uploads as completed files.
+
+**Completed** means the upload finished, not that an independent backup is
+confirmed or the file is permanently safe. The upload no longer requires its
+local source, but valuable files should still have a separate readable copy.
+[Choose a recovery route](backup-recovery.md#choose-the-right-mongodb-recovery-route).
+
+</details>
+
+### Uploading and using files
+
+<details>
+<summary>Does uploading a folder copy everything and keep it synchronized?</summary>
+
+It uploads the selected files once; later edits on your computer do not sync.
+Each chosen folder becomes a new root rather than merging into an existing
+same-named folder. Selecting it again can create another copy; it does not update
+the previous upload or provide file-version history.
+
+Review the confirmation and skipped-file list. The picker accepts up to 1,000
+files and 1,000 discovered folders, subject to other path/request limits. Empty
+folders are not discovered; empty or oversized files are skipped. A batch marked
+**Finished** can include failed or cancelled files, so inspect its results.
+Resume the existing batch instead of choosing the whole folder again.
+[Folder upload workflow and limits](usage.md#upload-files-or-folders).
+
+</details>
+
+<details>
+<summary>Will TGDrive compress my photos, videos or other files?</summary>
+
+Web uploads preserve the original bytes. Thumbnails and lower-quality previews
+do not replace the original; use **Download Original** to retrieve it. Browser
+playback support is a separate question from whether a file can be stored.
+
+When using the Telegram upload bot, send photos **as files** to retain their
+original quality. TGDrive cannot restore quality already lost before import.
+[Preview and download options](usage.md#open-preview-and-download).
+
+</details>
+
+<details>
+<summary>Why doesn't search find text inside my PDF or document?</summary>
+
+Search matches file and folder **names**, not document contents. **My Files**
+searches names across the drive; other pages search their own inventories.
+Use descriptive filenames and folders. [Search controls and scope](usage.md#search).
+
+</details>
+
+<details>
+<summary>Can I close my browser, turn off my laptop or let hosting expire?</summary>
+
+Keep the upload tab open until **You can close this tab** appears. After that,
+the server can finish accepted work while TGDrive runs; keep source files until
+**Completed**. URL imports and manual preloads can also continue on a running host.
+
+If the laptop is the host, sleeping or stopping it stops the service. A separate
+server can keep working independently. Shared links need a reachable running
+app. Before hosting expires, preserve the database, credentials, volumes and
+recovery kit, then follow the [host-move guide](operations.md#when-a-hosting-plan-expires).
+
+</details>
+
+### Access, maintenance and recovery
+
+<details>
+<summary>Can I clean up Telegram messages, change channels or reinstall to fix an error?</summary>
+
+Do not edit/delete TGDrive's Telegram storage messages, enable auto-delete or
+change its recovery pins. Those documents may be live file parts or recovery
+material. A catalog backup cannot restore their deleted bytes.
+
+A reinstall should reopen the existing drive with its original database,
+configuration and channel access. Preserve persistent volumes and upload staging;
+do not reinitialize, prune volumes or switch channel/database IDs to bypass an
+error. Follow [channel damage](operations.md#if-someone-changed-the-telegram-channel)
+or [restart/recovery guidance](operations.md#after-a-shutdown-crash-or-network-loss).
+
+</details>
+
+<details>
+<summary>What if my Telegram owner account becomes inactive or I lose my number?</summary>
+
+Secure the owning account and its recovery methods, review active sessions and
+Telegram's inactivity-deletion setting, and keep independent recovery access.
+The [current privacy policy](https://telegram.org/privacy#10-4-account-self-destruction)
+lists a configurable 18-month default inactivity period. Do not assume bot traffic
+keeps the human owner's account active.
+
+Account deletion does not necessarily delete every channel: Telegram says created
+channels can become orphaned while other administrators retain rights. That still
+puts ownership and recovery at risk. [Telegram's account deletion explanation](https://telegram.org/faq#q-how-do-i-delete-my-account).
+
+</details>
+
+<details>
+<summary>What if I forget my TGDrive password or lose a backup key?</summary>
+
+There is no email-based password reset. The person controlling the deployment
+can replace the configured owner credential without deleting or initializing the
+drive. Managed-hosting users should contact their operator. Telegram, MongoDB
+and hosting accounts have their own recovery processes.
+[Reset owner access](operations.md#forgotten-login-password).
+
+Backup keys are different: they decrypt the matching backup archives. Your login
+password cannot replace them. Losing a key does not itself delete live files,
+but can make that backup unusable. Keep the complete recovery export and older
+key/archive pairs. Changing the owner password does not revoke share links;
+revoke those separately in **Shared Links**.
+[Keep the recovery kit separately](backup-recovery.md#keep-the-mongodb-recovery-kit-outside-the-server).
+
+</details>
+
+<details>
+<summary>Can several people use the drive? Do share links identify a particular person?</summary>
+
+People signing in with the owner password share full access, including files and
+settings. There are no separate personal accounts or per-person permissions.
+Give that password only to fully trusted co-owners. TGDrive has no built-in second
+factor for its owner login; Telegram two-step verification protects the Telegram
+account, not the TGDrive web password.
+
+To let someone read selected files without changing them, use a share link. Its
+label helps you organize links; it does not check the recipient's identity.
+Anyone with the valid URL can read the shared content. A folder link also grants
+access to files and subfolders added to it later.
+Expiry or revocation stops future access, not copies already downloaded.
+[Sharing rules](usage.md#share-and-revoke).
+
+</details>
+
+<details>
+<summary>Do recipients need Telegram? Can every file play in the browser?</summary>
+
+Recipients can use a valid TGDrive share link in a browser without the owner's
+Telegram login. The TGDrive host still needs its Telegram access and must remain
+reachable. Preview support depends on the file format, codec, browser, device
+and reader limits; storing a file does not guarantee an inline preview.
+Use **Download Original** when needed. [Preview and download guide](usage.md#open-preview-and-download).
+
+</details>
+
+### Resources, deletion and support
+
+<details>
+<summary>If files live on Telegram, why does my host need disk space and bandwidth?</summary>
+
+Uploads travel **device → TGDrive host → Telegram**; reads travel
+**Telegram/cache → TGDrive host → viewer**. The host needs disk for unfinished
+uploads and caches, and downloads use its outgoing bandwidth even on a cache hit.
+A small server disk can serve a larger stored library, but it must still fit the
+active uploads, cached bytes and any local backups, while leaving the configured
+free-space reserves.
+
+**Preload file** caches the whole original on the host. Cache is disposable
+acceleration, not extra permanent storage or an independent backup; unfinished
+upload staging is not disposable cache. Hosting traffic allowances still matter.
+[Data path](performance.md#follow-the-data-path) · [Upload disk requirements](configuration.md#upload-size-and-available-disk-space).
+
+</details>
+
+<details>
+<summary>Does unlimited storage mean unlimited speed or no waiting?</summary>
+
+No. Server resources, your connection and recipients' connections affect speed.
+Telegram's [file API](https://core.telegram.org/api/files) also describes transfer
+limits and wait responses. Respect TGDrive's displayed retry deadlines; more bots
+or higher concurrency do not cancel provider limits. Cache/preload data is
+temporary acceleration, not a backup. [Performance guide](performance.md).
+
+</details>
+
+<details>
+<summary>Does permanent deletion securely erase all copies?</summary>
+
+No. Trash supports restoration. Permanent deletion removes TGDrive catalog
+references and associated access; it cannot be undone through Trash. It does not
+erase Telegram originals, caches, old backups or recipients' copies. Older
+restore points can reintroduce records or shares; review access after recovery.
+[Deletion behavior](usage.md#why-permanent-deletion-keeps-the-telegram-files).
+
+</details>
+
+<details>
+<summary>How do I ask for help or report a bug without exposing my data?</summary>
+
+Include the TGDrive version, local/server deployment, action you tried, exact
+error, transfer stage and short steps to reproduce it. Say whether one file or
+all files are affected. A small, non-private sample can help with format problems.
+
+Review screenshots and logs before posting. Remove passwords/hashes, bot tokens,
+sessions/cookies, MongoDB connection strings, recovery keys, private filenames
+and full share/source URLs; query strings can contain credentials. Do not attach
+your `.env`, raw private state or recovery export. Automatic log redaction is not
+a substitute for that review. [Useful logs](operations.md#read-useful-logs) ·
+[Report a bug or request a feature](https://github.com/TechShreyash/TGDrive/issues).
+
+</details>
+
+<details>
+<summary>What is a clear explanation I can share with someone new?</summary>
+
+> TGDrive is a free, open-source web drive using Telegram for file storage.
+> Upload files or folders, organize them, preview media and share links in your
+> browser. It uses Telegram's free unlimited cloud storage and splits large files
+> automatically. You run it on a computer or server; file-size and resource limits
+> still apply. Keep separate backups: permanent access is not guaranteed.
+
+Send this guide with the [live demo instructions](usage.md#try-the-public-demo).
+
+</details>
+
+Telegram policy references were reviewed on **26 October 2026**. Provider rules
+can change; the linked official pages are the source for Telegram's current policy.
diff --git a/docs/operations.md b/docs/operations.md
new file mode 100644
index 00000000..269945cb
--- /dev/null
+++ b/docs/operations.md
@@ -0,0 +1,370 @@
+# Run, protect and recover TGDrive
+
+[Docs home](README.md) · [Backup guide](backup-recovery.md)
+
+> [!IMPORTANT]
+> Keep **one app instance and one worker per drive**. Preserve the database, secrets and persistent volumes across restarts and updates.
+
+**Contents**
+
+- [Run and monitor](#run-and-monitor)
+  - [Read useful logs](#read-useful-logs)
+- [After a shutdown, crash or network loss](#after-a-shutdown-crash-or-network-loss)
+- [If someone changed the Telegram channel](#if-someone-changed-the-telegram-channel)
+- [What is saved where](#what-is-saved-where)
+- [When a hosting plan expires](#when-a-hosting-plan-expires)
+- [Reopen after losing the local installation](#reopen-after-losing-the-local-installation)
+- [Encrypted Telegram backups](#encrypted-telegram-backups)
+- [Emergency database restore](#emergency-database-restore)
+- [Connection changes](#connection-changes)
+  - [Revoked tokens, removed sessions and lost channel access](#revoked-tokens-removed-sessions-and-lost-channel-access)
+- [HTTPS and private configuration](#https-and-private-configuration)
+  - [Can TGDrive run over HTTP?](#can-tgdrive-run-over-http)
+- [Forgotten login password](#forgotten-login-password)
+- [Upgrade and rollback](#upgrade-and-rollback)
+- [Troubleshooting](#troubleshooting)
+- [Disposable media cache and preloads](#disposable-media-cache-and-preloads)
+  - [Tune a busy installation](#tune-a-busy-installation)
+- [HTTP delivery and proxy configuration](#http-delivery-and-proxy-configuration)
+
+## Run and monitor
+
+[Preloads and Performance screenshots](showcase.md#preload-and-monitor) show
+where to inspect cache coverage, traffic and server resources in the website.
+
+Run these from the installation folder.
+
+| Action | Local Docker command |
+| --- | --- |
+| Start | `docker compose up -d` |
+| Stop safely | `docker compose stop` |
+| Restart | `docker compose restart app` |
+| Recent logs | `docker compose logs --tail=100 app` |
+
+Server deployments add `-f compose.yaml -f compose.server.yaml` after `docker compose` in every command. Coolify provides Stop, Restart, Logs and Redeploy controls. Keep Docker Desktop/the Docker daemon running while TGDrive is in use.
+
+Check **Connections** for Telegram health, **Storage & Backups** for database/disk/backups, and [performance controls](performance.md) for caches, queues and cooldowns. Queue times are estimates. `/health/ready` reports readiness, not a full file or public-domain check.
+
+An always-on server can keep file access, sharing and
+[background work](hosting.md#local-computer-or-server) available while your laptop
+is off. TGDrive must keep running and connected to MongoDB and Telegram; closing
+the browser does not stop accepted server jobs.
+
+### Read useful logs
+
+Keep `LOG_LEVEL=INFO` for normal operation. Logs show startup/shutdown, accepted
+device uploads and transfer starts/completion/cancellation. Match the same `id`
+across events (`job_id` links receipt acceptance to its server job) to follow one
+file without logging its name, destination or source
+URL. Byte callbacks, successful polling and routine Telegram update messages do
+not produce normal-operation entries.
+
+| Event or field | What it tells you |
+| --- | --- |
+| `Device upload accepted` | Verified server bytes were handed to a durable job; the browser is no longer needed for that file. |
+| `receipt_age_seconds` | Time since this receipt was created, including browser pauses and server handoff. Older receipts can report `unknown`. |
+| `verify_seconds`, `handoff_seconds` | Verification time and total completion-request time, including waiting for its receipt lock and committing the job. These overlap. |
+| `Transfer started`, `Transfer finished` | Bytes, time before first processing and total job lifetime, including waits. |
+| `Transfer retry scheduled` or `Transfer waiting` | The cooldown or unavailable Telegram client, automatic retry policy and suggested action. Unchanged waits are not repeated. |
+| `Transfer failed` | Job ID, phase, exception type, stable failure category and suggested repair. Inspect the user-facing error in Transfers. |
+
+Provider warnings/errors remain visible. For a reproduced problem, temporarily
+set `LOG_LEVEL=DEBUG` in private configuration and recreate/redeploy the app.
+DEBUG adds phase transitions, exception tracebacks and provider diagnostics;
+return to INFO afterwards. Raw HTTP access logs stay disabled because query
+strings can contain share credentials. Logs go to the container/process output,
+with conservative credential redaction; review diagnostic logs before sharing.
+
+<details>
+<summary>Restart policy</summary>
+
+The laptop override leaves TGDrive stopped after reboot. Server restart policy handles process exits; an `unhealthy` check alone does not restart a running container. Inspect logs before restarting. See [Docker restart policies](https://docs.docker.com/engine/containers/start-containers-automatically/).
+
+</details>
+
+## After a shutdown, crash or network loss
+
+Start the **same deployment**, then check **Transfers**, **Connections** and **Storage & Backups**. Reopen interrupted videos/downloads.
+
+| Interrupted work | Next step |
+| --- | --- |
+| Completed file | Its MongoDB catalog and Telegram documents survive a normal restart. |
+| Browser upload | Resume the existing transfer; reselect the same original if asked. A closed browser cannot send remaining bytes. |
+| Telegram upload | Preserve both volumes and retry the existing job; recovery uses staged bytes and confirmed work. |
+| URL import | Retry its server job in Transfers. Remote downloading may restart; expired URLs need replacement. |
+| Telegram outage | Restore connectivity and observe the displayed retry/cooldown time; restarting does not bypass it. |
+| Database/ownership failure | Restore MongoDB access and stop competing instances before restarting. |
+| Backup/channel copy | Check its status. Only the last confirmed restore point is protected. |
+| Full disk | Free unrelated space or disposable cache; keep staged uploads and journals. |
+
+Browser receipts normally expire after 24 hours of inactivity; longer interruptions can require a fresh upload. Restart cannot recover deleted payloads, missing keys or revoked credentials.
+
+<details>
+<summary>Ownership leases and unavailable MongoDB</summary>
+
+After an unclean stop, stop the old app, wait about a minute, then restart once. Never delete internal ownership records or disable single-instance protection.
+
+Unreachable MongoDB or insufficient permissions rejects startup and owner login.
+Restore database access first: local recovery configuration provides no offline
+login. A reachable database with a missing/corrupt catalog can permit the owner
+recovery screen.
+
+</details>
+
+## If someone changed the Telegram channel
+
+Keep storage bots as administrators, the channel private and auto-delete off. Repair tokens, membership or permissions in Telegram, then use **Connections → Refresh** and retry; replaced credentials require a restart.
+
+Missing/replaced documents are detected when checked or accessed; cached bytes can temporarily hide damage. Make changes through TGDrive rather than editing Telegram messages or captions. Restore a [confirmed independent copy](backup-recovery.md#recover-a-lost-main-channel-from-a-surviving-channel), or upload the original as a new file. **A database backup cannot recreate missing Telegram bytes.** Do not change channel/database bindings to bypass the error.
+
+<details>
+<summary>Channel checks</summary>
+
+Guarded Telegram writes check channel privacy and usable bots' permissions. Successful checks are reused for up to 30 seconds; failures block affected work and appear in Connections. This is not a continuous channel audit or a lock on Telegram settings.
+
+</details>
+
+## What is saved where
+
+| Location | Contents |
+| --- | --- |
+| Telegram | Completed files/parts and encrypted backups |
+| MongoDB | Catalog, shares, settings, transfers and recovery state |
+| Persistent data/cache volumes | Secrets, sessions, recovery state, unfinished uploads and disposable cache |
+| Private `.env` | Database access and deployment configuration |
+
+> [!WARNING]
+> **`docker compose down -v` removes persistent volumes**, risking secrets and unfinished uploads. Use `docker compose stop` to stop safely.
+
+Keep the same Compose project name to reuse its volumes. Deleting the app folder
+alone does not delete Docker volumes, Telegram documents or MongoDB records;
+preserve its private configuration so you can reconnect safely.
+
+### Save these somewhere separate
+
+Keep database access/name, owner login, private deployment configuration, Telegram access and the matching [backup keys and confirmed archives](backup-recovery.md). Back up both volumes if unfinished work must survive losing the machine. Keys decrypt their matching archives; they do not contain file bytes.
+
+## When a hosting plan expires
+
+**Your drive stays yours.** Server or managed-plan expiry does not itself delete
+completed Telegram files or prevent running TGDrive elsewhere. Reopening the same
+catalog with access to its Telegram documents does not require re-uploading them.
+
+1. Keep your MongoDB database accessible. If it is on the expiring server, move
+   it or save a confirmed encrypted archive and matching key before access ends.
+   If the database is lost, [restore a confirmed backup](backup-recovery.md#restore-a-lost-database-from-telegram);
+   only data captured in that restore point returns.
+2. Preserve Telegram channel/bot access, private deployment configuration,
+   original secrets and your off-server [recovery kit](backup-recovery.md#keep-the-mongodb-recovery-kit-outside-the-server).
+3. Stop the old instance, then run TGDrive on your laptop or a new server and
+   [reopen the existing drive](#reopen-after-losing-the-local-installation).
+   **Do not initialize a new catalog over it.**
+
+Hosting expiry interrupts sharing and background work until the app is reachable
+again. Unfinished uploads still need staged server bytes or their originals;
+disposable caches/preloads can be rebuilt. Missing Telegram originals, a lost
+catalog or missing recovery keys cannot be repaired by changing hosts alone.
+
+See [Keep control of your drive](hosting.md#keep-control-of-your-drive) for managed
+hosting access and ownership.
+
+## Reopen after losing the local installation
+
+If MongoDB survives, reconnect to the existing database. Missing staged upload
+bytes still need their originals.
+
+1. Stop the old instance. Use the same version or source commit where possible and
+   [copy the configuration template](setup.md#3-configure-your-drive) using the
+   command for your system. Use the existing values below.
+
+2. Set the **existing** `MONGODB_URI`, `MONGODB_DATABASE`, `API_ID`, `API_HASH` and
+   `STORAGE_CHANNEL`. Keep the original `MAIN_BOT_TOKEN` and `TELEGRAM_ADMIN_IDS`
+   if configured. Older `BOT_TOKENS` configurations remain supported; do not
+   replace an existing list just to reinstall. Saved Connections are reused.
+3. Remove the example password: set `ADMIN_PASSWORD=` and leave `ADMIN_PASSWORD_HASH`, `SESSION_SECRET` and `MONGODB_BACKUP_KEY` blank/omitted to reuse saved bootstrap credentials. If unavailable, supply the originals from your recovery kit; do not generate replacements.
+4. Set `COOKIE_SECURE=false` for local HTTP, `true` for HTTPS. Start normally:
+
+   ```bash
+   docker compose config --quiet
+   docker compose up -d --build
+   ```
+
+5. Sign in with the existing password. Check Connections, files, a representative download and unfinished transfers.
+
+For hosting, use [Coolify](setup.md#coolify) or [server Compose](setup.md#docker-compose-on-a-server). Retain surviving persistent volumes. If Atlas paused the cluster, [resume it](https://www.mongodb.com/docs/atlas/pause-terminate-cluster/) first.
+
+## Encrypted Telegram backups
+
+Use [Backup & recovery](backup-recovery.md) to set up independent file copies, save matching keys and rehearse recovery. Live MongoDB and confirmed Telegram backups are separate.
+
+## Emergency database restore
+
+[Restore a lost database from Telegram](backup-recovery.md#restore-a-lost-database-from-telegram) requires a confirmed archive, matching key and empty destination database. A normal reinstall reopens the existing database instead.
+
+## Connection changes
+
+Manage accounts in **Connections**, then restart. Keep an enabled bot with channel permissions. Changing channel ID does not move files; a different drive needs its own database.
+
+`MAIN_BOT_TOKEN` separately controls the Telegram chat interface. If a bot serves
+both storage and chat uploads and its token changes, update its saved token in
+**Connections** and `MAIN_BOT_TOKEN` in the deployment, then restart/redeploy.
+Changing the deployment variable alone does not replace saved storage credentials.
+
+Finish/cancel unfinished or failed transfers before changing account identities, enabled states or API credentials. While work is pending, credential repair must replace only the token/session for the **same account**, leaving those other settings unchanged. TGDrive verifies its identity.
+
+### Revoked tokens, removed sessions and lost channel access
+
+| Problem | Repair |
+| --- | --- |
+| Revoked bot token | Replace with a valid token for the same bot; restart and retry. |
+| Expired/removed Premium session | Reconnect the same account through **Connections**, restart and retry. |
+| Missing channel permissions | Restore membership/admin rights, Refresh and retry. A still-connected client can resume after a successful check. |
+| Network/Telegram wait | Follow reconnection, retry and cooldown status. |
+
+<details>
+<summary>Why an upload may need its original account</summary>
+
+Failed accounts are excluded from new work; healthy accounts can serve eligible reads. An upload part can switch accounts only before dispatch. Afterwards TGDrive preserves its sender, request ID and staged bytes to prevent duplicate sends after a lost acknowledgement. If that sender is revoked, repair it rather than repeatedly restarting. Keep the staging and journal if the account cannot be restored.
+
+The independent backup bot has separate credentials and permissions; check its [backup status](backup-recovery.md) too.
+
+</details>
+
+## HTTPS and private configuration
+
+For public access, use an HTTPS reverse proxy, `COOKIE_SECURE=true`, a private app port and trusted-proxy settings limited to your actual proxy. Preserve authorization/cache headers; avoid proxy/CDN caching of private responses or share URLs. Keep `ALLOW_PRIVATE_REMOTE_URLS=false` unless internal-network imports are intentional.
+
+### Can TGDrive run over HTTP?
+
+**Yes, on localhost.** The local Compose setup serves
+`http://127.0.0.1:8000` with `COOKIE_SECURE=false`. Browsers treat localhost and
+loopback addresses as [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Secure_Contexts),
+so the required browser APIs remain available.
+
+**Use HTTPS when opening TGDrive from another device**, including over a LAN.
+The current frontend uses secure-context browser APIs for upload IDs, resume
+verification and media actions. An ordinary HTTP server IP or `sslip.io` address
+does not qualify; these features can fail even with `COOKIE_SECURE=false`.
+Plain HTTP also leaves passwords, sessions and file traffic unencrypted.
+The hosted Compose file sets secure cookies explicitly; a dashboard or `.env`
+value alone does not override that setting.
+
+[Coolify's generated `sslip.io` address](https://coolify.io/docs/core/networking/domains)
+uses HTTP. Automatic HTTPS certificate issuance for the shared domain can hit
+[Let's Encrypt certificate limits](https://letsencrypt.org/docs/rate-limits/).
+These limits affect **creating certificates**, rather than requests to your
+TGDrive pages or files. A valid certificate can serve HTTPS normally; use your own
+domain with a valid certificate for public TGDrive access.
+
+### Protect a public deployment
+
+Use a password-manager-generated password or unique passphrase of at least 15
+characters, and protect Telegram/MongoDB accounts. TGDrive accepts a 12-character
+minimum and has no built-in second factor or passkeys. Public deployments should
+also limit login traffic at the reverse proxy; the app's per-IP throttle resets
+after restart. Keep secrets and share links out of Git/logs; review even redacted
+logs before sharing. See [security boundaries](reference.md#security-and-privacy).
+
+<details>
+<summary>Change credentials and verify public access</summary>
+
+Stop the app, update the private credential and recreate/redeploy. Use `ADMIN_PASSWORD_HASH` with `ADMIN_PASSWORD` empty, or remove a stale hash when using plaintext fallback. Verify the new login works and the old password/session fails. Ordinary restarts with unchanged credentials preserve sessions. Revoke share links separately in **Shared Links**.
+
+After exposure, rotate the affected provider credential and `SESSION_SECRET` as needed. Preserve old backup keys: rotation does not re-encrypt archives. Restores/rollbacks can reintroduce older credentials or shares.
+
+Reusing an old owner credential together with its old `SESSION_SECRET` can make
+unexpired old cookies valid again. Choose a fresh signing secret when prior
+sessions must remain invalid, and review shared links separately.
+
+After HTTPS setup, test owner login/upload, denied private access in an incognito browser, a scoped share and its revocation. Confirm the direct app port is unreachable publicly.
+
+</details>
+
+## Forgotten login password
+
+TGDrive has no email-based reset or way to reveal a password from its hash. You
+can reset access if you control the deployment's private environment or `.env`:
+
+1. Set a new private `ADMIN_PASSWORD` of at least 12 characters and clear
+   `ADMIN_PASSWORD_HASH`. TGDrive hashes the password internally. An empty hash
+   value is sufficient. Keep the replacement explicitly configured; missing owner
+   credentials can reuse the original hash saved during setup.
+2. Recreate the app container with `docker compose up -d --force-recreate app`,
+   or update the private variables and **Redeploy** in Coolify. Use your existing
+   Compose project, volumes and any server `-f` arguments. Do not initialize or
+   delete the database or volumes.
+3. Confirm the new password works in a private browser window and the old
+   password/session fails. Changing the effective credential invalidates that
+   password's existing browser sessions after restart. Shared links are separate.
+
+For the demo's private full-access password, set `DEMO_ADMIN_PASSWORD` and clear
+`DEMO_ADMIN_PASSWORD_HASH` in the deployment environment, then recreate/redeploy.
+It does not change the visitor password. Rotating or removing this credential
+invalidates elevated demo sessions; ordinary visitor sessions remain independent.
+Rotate `SESSION_SECRET` too when both session types must be invalidated, and
+avoid restoring old credentials and signing secrets together.
+
+If you also lost access to the server, recover the hosting/deployment account
+first. TGDrive cannot reset a Telegram, MongoDB or hosting provider account.
+See [password and session storage](reference.md#owner-authentication).
+
+## Upgrade and rollback
+
+Use a published release tag for a fixed version, or `main` for stable source
+updates. `dev` contains ongoing work and may be unstable. Follow
+[Get the source](setup.md#get-the-source) when choosing the next version.
+
+- [ ] Finish work, stop safely, and save a confirmed backup plus its key off-host.
+- [ ] Record the running version and source commit; review the target version's requirements.
+- [ ] **Release archive:** [verify and extract](release.md#verify-a-downloaded-source-archive) the new archive into a separate folder. Copy your private `.env` into it and retain any reviewed Compose customizations. Keep the **same Compose project name**, including any `-p` argument, so Docker reuses the existing volumes. Keep the old folder for rollback; never copy the new `.env.example` over your real configuration.
+- [ ] **Git checkout:** record `git rev-parse HEAD`. For a `main` clone, use `git switch main`, then `git pull --ff-only origin main`. For a version-pinned checkout, use `git fetch origin --tags`, then `git switch --detach v2.0.0` (choose the new published tag for later updates). Preserve local changes if Git refuses the switch or update. **Coolify:** select the chosen published release tag or `main`, retaining variables/mounts.
+- [ ] Rebuild from the updated project folder with `docker compose up -d --build` (server `-f` arguments where needed), or redeploy in Coolify. Preserve existing volumes; startup reopens the drive.
+- [ ] Start one instance; check database status, Connections and a representative file.
+
+Do not run an older app against an incompatible database format. Restore a compatible backup into a separate empty database for a data rollback.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| MongoDB cannot connect | URI/password, Atlas Network Access, cluster availability and permissions |
+| Startup exits; website unavailable | Correct MongoDB configuration, authentication, network access and replica-set transaction support. A pristine database initializes automatically; existing or incomplete state requires recovery. See [setup](setup.md). |
+| Another installation owns the database | Stop the old app and let its lease expire. |
+| Catalog missing | Verify database name and use [recovery](backup-recovery.md); preserve existing state. |
+| Connection changes pending | Restart to apply them. |
+| Backup fails/decryption fails | Matching key, intact archive, posting access, disk and retry time |
+| Upload cannot resume | Reselect its original in the existing transfer; missing staging may require re-upload. |
+| Video/download slow or fails | Check [performance](performance.md), connections and the Telegram document; unsupported codecs need original download. |
+| Browser slow, server download fast | Check [HTTP delivery](#http-delivery-and-proxy-configuration). |
+| Preload incomplete | Check effective cache tier/free space; full coverage includes integrity overhead. |
+| Copied private URL fails | Use Copy download link or an explicit share; owner URLs require its cookie. |
+| Revoked share still plays | Already received/buffered bytes cannot be recalled. |
+| URL import asks for local file | Find/retry the original server job in Transfers. |
+
+## Disposable media cache and preloads
+
+Use owner controls to inspect coverage, cancel preloads, evict files or clear disposable bytes. A completed preload does not pin bytes forever; budgets, headroom and eviction can reduce coverage. See [cache policy and defaults](performance.md).
+
+When stopped, `DATA_DIR/media-cache` can be removed and rebuilt on demand. **Never clear upload receipts, staged payloads or backup sources as cache.** Host access can expose cache contents; HTTP cache hits still require current authorization.
+
+### Tune a busy installation
+
+Use the [load and capacity guide](performance-tuning.md) to investigate queues,
+cache reuse and server/bot capacity before increasing limits.
+
+Check headroom and queues first, stop unnecessary preloads, then change one limit at a time. Compare warm/cold and shared/unrelated-file reads. Supported web preferences apply live; environment changes require recreation, credentials require restart.
+
+## HTTP delivery and proxy configuration
+
+TGDrive sends `Alt-Svc: clear`; supported Compose configurations apply it at the edge too. This clears cached alternative-service advertisements so browsers use normal origin HTTPS, ordinarily HTTP/2 through Coolify/Traefik. No extra variable or manual rule is needed.
+
+<details>
+<summary>External proxies and existing custom rules</summary>
+
+Traefik can append its own advertisement, so the Compose middleware ensures the final edge response carries the policy. An external CDN/proxy must preserve it, range/length headers and streaming delivery. Avoid compression of byte-addressed responses; TGDrive supplies `Content-Encoding: identity`.
+
+Remove temporary custom rules once the updated app/Compose supplies the policy. Redundant routers can break when domains/services change. Coolify watches dynamic files; main proxy Compose edits need restart and must be saved through its UI.
+
+The default follows one reproduced HTTP/3 delivery slowdown, not a universal QUIC claim: see the [validation report](streaming-validation-2026-10-18.md). References: [Coolify Traefik](https://coolify.io/docs/core/networking/proxy/traefik/overview), [Traefik HTTP/3](https://doc.traefik.io/traefik/reference/install-configuration/entrypoints/#http3), [Alt-Svc specification](https://www.rfc-editor.org/rfc/rfc7838.html#section-3.1).
+
+</details>
diff --git a/docs/performance-tuning.md b/docs/performance-tuning.md
new file mode 100644
index 00000000..a74fbd00
--- /dev/null
+++ b/docs/performance-tuning.md
@@ -0,0 +1,169 @@
+# Diagnose load and choose capacity
+
+[Docs home](README.md) · [Configuration](configuration.md) · [Performance policies](performance.md)
+
+Use the website's measurements to find what is slowing down before changing
+limits or buying a larger server. Cache, server resources and Telegram clients
+solve different problems; increasing the wrong one can make queues longer.
+
+**Contents**
+
+- [Start with the website stats](#start-with-the-website-stats)
+- [How cache helps](#how-cache-helps)
+  - [Cache capacity and preloading](#cache-capacity-and-preloading)
+- [Find the bottleneck](#find-the-bottleneck)
+- [What a server upgrade changes](#what-a-server-upgrade-changes)
+- [Bots and request concurrency](#bots-and-request-concurrency)
+
+## Start with the website stats
+
+1. Identify the slow stage in **Transfers**: sending from your device,
+   downloading from a URL, waiting for Telegram, uploading to Telegram or
+   publishing. A full device progress bar does not mean Telegram work is done.
+2. Open **Monitor → Performance** while the problem is happening. Compare
+   server resources, network traffic, Telegram activity and queue waits over
+   the same interval. Long averages can hide short bursts; missing samples are
+   not zero activity.
+3. Open the same file again, or compare its uncached and already cached parts.
+   A slow first access followed by a fast repeat points toward the Telegram
+   path or cache coverage. If both are slow, inspect server-to-viewer delivery
+   and the viewer's device too.
+4. Open **Monitor → Preloads** to inspect actual retained coverage. For upload
+   space problems, also check **Management → Storage & Backups → Temporary
+   Storage**. Keep unfinished upload files; they are not disposable cache.
+5. Change one setting or resource, repeat the same workload and keep the change
+   only if measured results improve. Do not increase concurrency during a
+   Telegram cooldown.
+
+| Website measurement | How to read it |
+| --- | --- |
+| Container CPU | 100% means all available container cores/quota, not one core. A labelled host-CPU fallback has a different scope. |
+| Container RAM | Includes the whole container. Process memory and the retained RAM cache are separate measurements within it. |
+| Server network | **Download to server** is incoming traffic; **Upload from server** includes delivery to viewers and Telegram uploads. Compare with the bandwidth included in your server plan. |
+| Telegram accounts and queues | Look for busy upload/download slots, active and queued part requests, reduced effective limits and provider waits. A queue estimate is not a promised start time. |
+| RAM cache lookups | Hits and misses count block lookups, including preloading. A RAM miss can still hit disk; this is not a percentage of bandwidth saved. |
+| Cache filesystem / Temporary Storage | Cache and unfinished uploads can live on different volumes. Check the relevant free-space reading before changing either budget. |
+
+Server-network, HTTP-file and Telegram counters overlap: **do not add their
+totals together**. For history, measurement scopes and retention, see
+[reading Performance](performance.md#read-the-performance-page).
+
+## How cache helps
+
+TGDrive's server cache retains file bytes already fetched from Telegram:
+
+1. A read can reuse retained bytes from RAM or verified disk cache.
+2. Missing blocks are fetched from Telegram. Overlapping readers can share
+   work already in progress instead of fetching the same blocks separately.
+3. Retained blocks can serve later authorized reads of that same stored file
+   and representation, including reads through share links.
+
+For example, if a **1 GiB file is fully cached and stays cached**, three people
+downloading that original can reuse the cached bytes. TGDrive can avoid another
+Telegram payload download for each person, while the server still sends about
+3 GiB to the viewers, plus network overhead. This is an illustration, not a
+throughput measurement or a guarantee that the file remains cached.
+
+This is reuse of the **same stored content and byte ranges**, not duplicate-file
+detection. Separately uploaded copies or different quality representations do
+not automatically share a cache entry. Authorization and metadata checks still
+apply; caching avoids repeated file-payload downloads, not every Telegram request.
+
+### Cache capacity and preloading
+
+- More available RAM can keep more frequently reused bytes in memory. More disk
+  capacity can keep a larger collection of cached files or parts.
+- More cache capacity can let you preload larger files or retain more prepared
+  files. It does not automatically increase **Concurrent preloads** or Telegram
+  request capacity. Background preparation shares capacity with real viewers
+  and uploads.
+- Hardware upgrades do not automatically raise **Configuration → Cache settings**
+  budgets. Raise them deliberately while leaving space for the app, active
+  streams, unfinished uploads and other processes. The effective RAM budget can
+  be lower than the configured value when memory is tight.
+- A whole-file preload must fit either the effective RAM tier or disk tier,
+  including overhead and competing reservations. Their budgets are not added
+  together; both tiers can hold copies of the same bytes.
+- Ordinary access may leave only part of a file cached; automatic playback
+  warming can prepare more, but does not always prepare the whole file. For a
+  file you expect many people to open, choose **Preload file**, then wait for
+  **Ready** and full coverage in **Monitor → Preloads** before sharing.
+
+Cached data can expire, be evicted, disappear with disk loss or fail an integrity
+check. Missing bytes then need Telegram again. Cache is not a backup and does not
+keep a sleeping host available. See [cache defaults and retention](performance.md#cache-limits)
+and [preloading a shared file](performance.md#prepare-a-file-before-sharing).
+
+## Find the bottleneck
+
+| What you observe | What to check or change |
+| --- | --- |
+| First access is slow, cached repeat is fast | Inspect Telegram queues, waits and cache coverage. Retain or preload popular content; consider additional clients only if account capacity is limiting cold reads. |
+| Cached files slow down with more viewers | Compare server upload bandwidth, CPU, memory and proxy limits. More bots do not carry these cached payloads to viewers. |
+| CPU stays near its available limit | Identify server processing versus a slow viewer. Reduce competing work or consider more CPU for a confirmed server bottleneck. |
+| RAM is close to its limit or effective cache shrinks | Lower memory cache or concurrency first. More RAM may provide headroom; raising the cache setting without headroom can worsen pressure. |
+| Useful cached coverage disappears between repeat accesses | Check retention, effective budgets, free space and competing files. Increase cache capacity only if reuse justifies it. |
+| Cache or upload volume is nearly full | Review its own budget and free-space reserve. Clear disposable cache or finish/cancel transfers; preserve unfinished upload data. |
+| Telegram slots are busy and queues grow, with server headroom | Separate demand from background preloads. Add eligible clients or test one concurrency change at a time. |
+| Telegram reports FloodWait or reduces effective request limits | Observe the retry deadline and reduce pressure. More queued work or higher limits do not shorten the wait. |
+| The server is delivering quickly but one viewer buffers | Inspect that viewer's connection, browser, codec support and decoding load. Server CPU and bots cannot guarantee client playback. |
+| CPU and network look quiet but requests remain slow | Check Connections, logs, proxy behavior and MongoDB health. The website does not measure every dependency's latency. |
+
+## What a server upgrade changes
+
+| Resource | When it helps | Practical limit |
+| --- | --- | --- |
+| CPU / vCPU | Server processing is saturated: transfer checksums, encryption, thumbnail generation or document extraction compete for CPU. | Much video decoding runs in the viewer's browser. Additional server CPU does not fix every codec or viewer problem. |
+| RAM | The app and concurrent streams need more headroom, or a useful working set cannot remain in RAM cache. | Configure a suitable cache budget; TGDrive still reduces retention under memory pressure. More RAM does not make all reads immediate. |
+| Storage capacity | Popular cached content or unfinished uploads do not fit. | Cache and upload staging have separate budgets/reserves. A larger disk does not automatically increase either configured budget. |
+| Storage speed | Host measurements show disk reads/writes are limiting cached delivery or staging. Faster SSD/NVMe may help. | A disk-usage bar measures capacity, not I/O performance. The website does not report disk latency or IOPS; use host/provider monitoring. |
+| Network capacity and route | Server ingress/egress or its path to Telegram/viewers is the bottleneck. | Viewers still have their own connection limits, and monthly bandwidth allowances can apply. |
+
+Also use provider/host/database monitoring when needed: TGDrive does not report
+the server's physical network-port capacity or MongoDB response latency.
+Compare improvements with the same mix of cold reads, cached reads and uploads.
+Keep **one active TGDrive installation and one app worker per drive**; increasing
+workers against the same drive is not the supported way to use a larger server.
+
+## Bots and request concurrency
+
+Additional healthy bots can provide more Telegram account capacity for cold
+downloads and uploads. They help when that capacity is the bottleneck; they do
+not multiply server bandwidth or eliminate shared channel/provider limits.
+Repeated reads served from cache need less Telegram payload capacity already.
+
+These controls affect different layers:
+
+| Control | What it changes |
+| --- | --- |
+| Telegram clients in Connections | Potential account capacity; only healthy, authorized clients with channel access can do work. |
+| Simultaneous uploads per bot | Concurrent Telegram document uploads per bot. One large file can use several document-upload slots. |
+| Media operations per account | Upload/download work sharing an account's capacity. |
+| Requests per account | Concurrent Telegram media-part and metadata requests, shared by uploads and cold downloads. |
+| Upload pipeline | Part requests in flight within one Telegram document; still constrained by the account request limit. |
+| Requests per second | TGDrive's pacing ceiling, not a rate promised by Telegram. |
+| Maximum queued operations | How much work can wait; a larger queue does not add processing capacity. |
+
+With fewer bots, increasing an appropriate per-account limit can allow more
+work at once, but can also increase contention and provider waits under sustained
+load. A higher configured value is not evidence of higher throughput. TGDrive
+reduces effective request capacity/pacing after flood feedback and gradually
+recovers it after successful work.
+
+Start at the defaults, confirm server headroom, then change one control and watch
+throughput, waits and queue growth over a representative interval. If waits grow
+without useful throughput gains, undo the increase. Add or change clients through
+the [connection maintenance workflow](usage.md#settings-and-connections), including
+its pending-work and restart requirements.
+
+Telegram documents a required wait before repeating an action after
+[`FLOOD_WAIT_X`](https://core.telegram.org/api/errors), and enforces
+[administrator and bot limits](https://core.telegram.org/method/channels.editAdmin).
+Respect those limits and TGDrive's saved retry deadlines; repeatedly restarting
+or rotating identities is not a way to bypass them. TGDrive uses Telethon/MTProto,
+so hosted HTTP Bot API broadcast limits are not its media-request capacity.
+
+For current control defaults and bounds, use
+[Transfer limits](configuration.md#transfer-limits). For scheduling details, use
+[account selection](architecture.md#account-identity-and-selection) and
+[the upload pipeline](performance.md#upload-pipeline-and-smaller-splits).
diff --git a/docs/performance.md b/docs/performance.md
new file mode 100644
index 00000000..c2df8b10
--- /dev/null
+++ b/docs/performance.md
@@ -0,0 +1,499 @@
+# Streaming, caching and transfer performance
+
+[Docs home](README.md) · [Using TGDrive](usage.md) · [Configuration](configuration.md)
+
+Find the slow stage before changing limits. **Cold** reads fetch bytes from
+Telegram; **warm** reads reuse bytes cached on the TGDrive server. Cached files
+still need a working server and a connection to the viewer.
+
+Use the [load and capacity guide](performance-tuning.md) to
+[read the website stats](performance-tuning.md#start-with-the-website-stats),
+[find the bottleneck](performance-tuning.md#find-the-bottleneck), choose
+[server upgrades](performance-tuning.md#what-a-server-upgrade-changes) or tune
+[bots and requests](performance-tuning.md#bots-and-request-concurrency).
+This page holds the detailed cache, scheduling and measurement policies.
+
+[See Preloads and Performance](showcase.md#preload-and-monitor) for screenshots of
+cache coverage, network traffic and server resources. Values in the captures are
+examples from the recorded session, not throughput benchmarks.
+
+**Contents**
+
+- [Follow the data path](#follow-the-data-path)
+- [Cache limits](#cache-limits)
+- [Automatic read-ahead](#automatic-read-ahead)
+- [Prepare a file before sharing](#prepare-a-file-before-sharing)
+- [Shared-download load and queues](#shared-download-load-and-queues)
+- [URL import intake](#url-import-intake)
+- [Device upload receipts](#device-upload-receipts)
+- [Upload pipeline and smaller splits](#upload-pipeline-and-smaller-splits)
+- [Video controls and startup](#video-controls-and-startup)
+  - [Browser playback buffer](#browser-playback-buffer)
+- [Operator checklist](#operator-checklist)
+  - [Read the Performance page](#read-the-performance-page)
+  - [Investigate a slowdown](#investigate-a-slowdown)
+  - [Browser transport with a full cache](#browser-transport-with-a-full-cache)
+  - [Distant video seeks](#distant-video-seeks)
+
+## Follow the data path
+
+| Stage | Typical constraints |
+| --- | --- |
+| Device → server | Your upload connection, server bandwidth, temporary upload disk and browser queue |
+| URL source → server | Source speed, network route, server bandwidth and temporary upload disk |
+| Server → Telegram | Telegram datacenter, request latency, upload pipeline, cooldowns and server upload bandwidth |
+| Telegram → server | Network route, available Telegram accounts, request limits and missing cached bytes |
+| Server → viewer | Server upload bandwidth, proxy, viewer connection and simultaneous downloads |
+| Video decoding | Container/codec support and browser/device capacity |
+
+TGDrive uses Telethon with cryptg, bounded upload pipelining and pooled downloads.
+Accounts and documents can use different datacenters; changing server region may
+change routing but cannot relocate a document or guarantee improvement.
+
+A server with stronger connectivity/resources can improve upload/download speeds
+when it removes the current bottleneck. Device uploads still depend on your
+uplink; shared downloads use server egress and each viewer's connection.
+
+For [managed hosting](hosting.md#optional-managed-hosting), plans scale server resources
+for concurrent visitors and transfers. All TGDrive features remain included;
+larger plans increase capacity without promising a fixed transfer speed.
+
+## Cache limits
+
+For how cached bytes serve repeat viewers and shared files, see
+[how cache helps](performance-tuning.md#how-cache-helps).
+
+Tune the running instance in **Configuration → Cache settings**. Saved MongoDB
+preferences override initial environment values. Save affects the visible category;
+**Discard changes** returns to its last saved values. After changing Docker
+environment values, recreate/redeploy the container. See
+[exact settings](reference.md#performance-and-cache-settings).
+
+| Budget | Default |
+| --- | --- |
+| Retained RAM | 256 MiB; clamped to ¼ of available host/container memory |
+| Retained disk | 10 GiB |
+| Cache free-disk reserve | 1 GiB |
+| Disk expiry | 24 hours since last reuse |
+| RAM expiry | 10 idle minutes |
+| Transient streaming payload | 32 MiB, availability-clamped with a 2 MiB floor |
+
+Budgets cover the running installation and are separate from temporary upload
+storage. Units are binary (1 GiB = 1024 MiB). **Cache is temporary, not a backup.**
+Clearing it leaves Telegram originals and the catalog intact.
+
+<details>
+<summary>Memory, disk integrity and eviction</summary>
+
+- Disk space is consumed as blocks arrive, not reserved upfront. Cache writes
+  respect their free-space floor; upload staging separately uses `MIN_FREE_BYTES`.
+  Leave headroom for the OS, uploads and backups.
+- Disk blocks include integrity overhead. RAM and disk may retain the same hot
+  bytes, so their budgets cannot be added to decide whole-file capacity.
+- A bounded asynchronous disk-write queue shares the RAM budget. Atomic files
+  and block digests reject partial/corrupt entries; entry count scales with the
+  byte budget. Disk inventory survives clean restart; updates arriving during an
+  index flush trigger another flush.
+- New blocks enter probation; reuse promotes them into a protected area,
+  normally up to 75% of a tier. Protection favors reuse but does not pin bytes.
+- Disk failure falls back to origin where possible. Whole-file preparation fails
+  if it cannot establish verified retained coverage.
+- Separate transient reservations cover queued, completed and yielded 1 MiB
+  source blocks until consumption/cancellation. New response heads can reclaim
+  other readers' speculative blocks, including from suspended consumers, while
+  awaited/yielded heads remain protected. Cancelled I/O holds its reservation
+  until cleanup finishes.
+- Transport, ASGI, TLS, kernel and decoder buffers remain outside these payload
+  budgets. The pooled reader bypasses the old per-client payload cache to avoid
+  duplicating retained-byte budgets.
+
+</details>
+
+## Automatic read-ahead
+
+TGDrive adapts reads in two places:
+
+| Kind | Scope |
+| --- | --- |
+| Inside a response | Ordered 1 MiB blocks within the requested interval; paused consumers shed speculation |
+| Beyond playback responses | Optional warming for original audio/video; excludes explicit downloads, unknown range clients, document readers and alternate-quality previews |
+
+Downloads keep speculation inside each requested interval, including parallel
+ranges and retries. Aligned cold Telegram boundary blocks may be larger than
+the requested interval; the HTTP response bytes remain exact.
+
+**Preload during playback** defaults to enabled. Disabling it leaves in-response
+read-ahead and manual whole-file preloads available. Manual preparation always
+targets the original, even when a lower-quality preview is selected.
+
+<details>
+<summary>Playback qualification and preparation thresholds</summary>
+
+In-response reads begin with a head and one probe. Delivery, backpressure and
+remote-block latency adjust the window within account capacity, 32 blocks,
+remaining requested blocks and fair transient-budget share. Beyond-response
+warming requires `preview=1` or an audio/video fetch destination.
+
+Valid Telegram duration supplies average media byte rate; otherwise sustained
+delivery cadence supplies an estimate. Fill cadence is measured per file, not
+borrowed from unrelated cache hits. Neither estimate measures device decoding
+or the bitrate of each variable-rate scene.
+
+| Policy | Threshold |
+| --- | --- |
+| Qualify playback | Deliver roughly 4 seconds at estimated media rate, clipped to 1–4 MiB; 4 MiB when duration is unknown |
+| Ahead target | 8 seconds; extend to 16 when same-file fills lag estimated demand |
+| Ahead byte bounds | Block-rounded 1–128 MiB, at most ¼ of effective preparation capacity; skip if 1 MiB cannot fit |
+| Whole-file promotion | Qualifying, overlapping runs from distinct identified viewers within 10 minutes; overlap reaches qualification threshold; file plus overhead fits ½ of an effective tier |
+| Start cooldown | 30 seconds per file; new repeated use may promote immediately |
+| Renewal | Renew after delivery reaches halfway through the warmed region |
+| Concurrent preparations | 2 by default, shared by manual/automatic jobs, with bounded block concurrency |
+
+Metadata/HEAD never qualify. Parallel requests, retries or replays by one viewer
+cannot count as distinct viewers; anonymous ranges cannot earn whole-file promotion.
+Block alignment/integrity overhead count at admission, so high-rate files can
+receive less than the target duration.
+
+Successful playback range responses keep their logical viewer eligible for up
+to 5 seconds between requests, so a finite range can warm the next one. The same
+byte/cache/job limits apply during this gap. A real response abort cancels owned
+ahead work immediately; expiry cancels unfinished work if no next range arrives.
+Distant seeks abandon stale ahead work, including pending admission; already
+justified whole-file preparation may finish. Demand precedes queued speculation.
+Closing/seeking drains unused read-ahead; cancelling one subscriber does not
+abort an in-flight fill still needed by another authorized subscriber. Clearing
+cache data isolates the previous response's tracking, so its late progress or
+cleanup cannot change a newly opened viewer's preparation.
+
+</details>
+
+Independent blocks can use different healthy bots/Premium clients and shared
+in-flight fills, while responses preserve original order. Empty or short origin
+blocks enter the bounded account retry/failover path; incomplete bytes are never
+retained as ready cache blocks. Every request must pass authorization before
+cached bytes; shared access is rechecked before future blocks. No window estimate promises buffer-free playback or recalls sent bytes.
+Reopening a preview starts a new browser transfer: file responses use private,
+non-storing HTTP cache policy. Retained server blocks can satisfy that transfer
+without another Telegram payload download; loading UI alone does not indicate a
+server-cache miss.
+
+## Prepare a file before sharing
+
+[Preload file](usage.md#preload-a-file-for-smoother-playback-and-downloads) requests
+the whole original through the same verified cache, including multipart files.
+It runs on the server without downloading to your device.
+
+1. Choose **My Files → file ⋯ → Preload file**.
+2. Open **Monitor → Preloads** and wait for **Ready** with full coverage.
+   Blue segments show partial coverage.
+
+Preloading starts only when the whole file fits the effective RAM or disk cache
+budget. Concurrent preparations reserve capacity and verify retained ranges
+before completion; bytes downloaded and then evicted do not count.
+Manual multipart preparation also checks complete
+part checksums. Cancellation/clearing does not delete the file. Eviction, expiry,
+reduced budgets, disk loss and restart can change coverage, so inspect current
+inventory before a planned viewing.
+
+## Shared-download load and queues
+
+Warm bytes avoid Telegram payload work and have no fixed four-viewer gate, but
+still need authentication, server bandwidth, sockets, memory and proxy capacity.
+Cold misses share bounded account media/request admission and origin queues;
+uploads compete within the same account budget. Demand precedes background work.
+
+Requested payloads take turns in **1 MiB blocks**. After admitting a download
+block, its request's remaining queued blocks move behind other waiting requests
+at the same priority. This keeps one file's read-ahead from taking every next
+turn. Anonymous responses get their own internal request identity; identified
+parallel ranges share their supplied identity. This is request fairness, not a
+per-person quota, and running reads are not interrupted. Shared cache fills still
+fetch each block once for their subscribers.
+
+Uploads hold an operation slot for a Telegram document part. If configured upload
+concurrency fills every combined media slot, downloads must wait for a part to
+finish; the default one upload and three combined operations leave read capacity.
+Background thumbnail source metadata does not reserve a payload slot while its
+pooled reader waits for one, including with a one-operation account limit.
+
+Queue position/wait are estimates from recent durations and eligible capacity.
+Without enough samples, no ETA is invented. Seeks, outages and cooldowns can
+change estimates; overloaded queues can reject work. Respect response status
+and retry guidance rather than opening unlimited requests.
+Positions count origin operations, not files or people. The download queue and
+request-status observations are held in memory and do not survive a restart.
+Verified disk-cache blocks can still be reused after restart.
+
+## URL import intake
+
+URL imports download to the server before uploading to Telegram. **Downloading
+from URL** shows the source-to-server rate; Telegram capacity affects the next
+stage. The browser can close after submission while the server keeps working.
+
+Large, known-length sources with a strong ETag (the source's content-version
+identifier) use parallel HTTP ranges. TGDrive starts with two streams and probes
+four, then eight when aggregate
+throughput improves. Every range must match the original representation and exact
+requested interval. Unsuitable range responses abandon the partial attempt and
+restart as a single stream within the retry budget; rate-limit responses respect
+`Retry-After`.
+Small files, unknown lengths, sources without a strong ETag, and **Compatibility
+Mode** use one stream.
+Temporary source connection failures, timeouts, incomplete bodies and HTTP
+408/429/500/502/503/504 are retried automatically, with at most **four source
+attempts per running cycle**, including a parallel-to-single-stream fallback.
+Ordinary backoff is **2, 4, then 8 seconds**; a valid `Retry-After` can make it
+longer. Unsupported ranges can fall back immediately. After a transport failure,
+remaining attempts use one stream. Invalid/unsafe URLs, TLS verification failures,
+permanent HTTP errors, size limits and local storage errors do not enter this loop.
+
+**Source interrupted · retrying automatically** shows the next attempt and wait.
+Before waiting, TGDrive drains writers, deletes the unpublished partial, and
+releases source slots and staging claims. The retry rejoins normal admission and
+checks storage again, then restarts at byte zero. It never combines bytes across
+attempts or sends a partial original to Telegram. Cancellation interrupts the wait.
+The existing total timeout includes retries and backoff. Server restart starts a
+fresh cycle, honoring a saved source retry deadline; no browser tab is required.
+Only exhausted attempts or permanent errors need user action.
+Neither mode can exceed the source, route or server capacity.
+
+**Transfer limits → URL downloads → Full-speed URL downloads** defaults to **2**,
+configurable from **1 to 8** without a restart. Lowering it lets existing full-speed
+jobs finish. This limit covers source retrieval; Telegram upload has its own
+scheduling. Eligible waiting jobs are promoted in arrival order. A job that cannot
+reserve its full staging requirement stays slow while another eligible job can run.
+
+Waiting sources use one stream paced at **64 KiB/s** each, shown as **Queued ·
+receiving slowly**. Open source jobs are bounded to the configured full-speed limit
+plus **8**; further jobs show **Waiting for a source connection**. Waiting sources
+reserve **32 MiB** staging windows as needed, capped by the file size; full-speed
+jobs reserve their entire known size, or the admitted maximum for unknown lengths.
+**Waiting for temporary storage** pauses reads until space becomes available.
+Promotion preserves received bytes and can switch the remaining body to ranges.
+Slow reception can help with idle timeouts, but does **not** extend signed-token
+expiry, guarantee a server will keep a request open, or protect links beyond the
+connection/storage bounds. Submit expiring links close to when capacity is available.
+The total operation timeout includes queuing and slow reception.
+
+Full-speed intake has no intentional bandwidth cap or per-chunk database
+transaction. Reads and receive buffers are up to **1 MiB**; waiting reads are up to
+**16 KiB**. Blocking writes and free-space checks run in workers. Parallel range
+responses have a shared **16-response** bound in addition to the source-job bound.
+Live written-byte counters reduce unwritten reservations without scanning receipts
+for every chunk; storage is checked when claims grow and before disk writes.
+
+Download progress stays in memory. Initial/window admissions, phase/status changes
+and recovery identities commit with their updates; a promotion claims space in
+memory immediately and journals it with the next progress/lifecycle update. File and directory synchronization
+remain at final publication. These counters do not promise byte-range resume:
+an interrupted URL retrieval may restart from zero. See
+[transfer durability](architecture.md#transfer-pipeline).
+
+Comparisons with a server-local downloader should use the same URL and comparable
+time windows; simultaneous downloads compete for bandwidth. These policies do not
+establish a measured speedup or guarantee the same rate as another client.
+
+## Device upload receipts
+
+Browser uploads use sequential **8 MiB** resumable chunks. Live progress counts
+sent bytes; acknowledgement follows server write, checksum, synchronization and
+MongoDB receipt commit. New files need no whole-device prehash; resumed files
+verify acknowledged chunks. Writes, hashing and receipt commits run off the HTTP
+event loop. Disconnect drains an active commit before releasing its lock.
+
+Device receipt and Telegram dispatch are separate stages. More bots cannot
+improve the device uplink or bypass a proxy. Compare device progress with HTTP
+received traffic and server load; a server-local benchmark excludes the viewer's
+route. See [transfer durability](architecture.md#transfer-pipeline).
+
+New receipts avoid redundant offset/snapshot requests. Browser payload slots are
+released after the final acknowledged chunk; up to two server completion requests
+run separately, so receipt verification does not hold the next file's device slot.
+Eligible batches rotate through those slots. Slow disk, database commits, staging
+pressure and the uplink can still limit intake.
+
+Creating an upload receipt keeps its initial file synchronization and database
+commit off the HTTP event loop, with staging reserved before it yields. See the
+[transfer pipeline](architecture.md#transfer-pipeline) for admission and retry
+boundaries.
+
+Job-state commits are awaited worker operations. A slow commit holds back its
+state transition without blocking reads of the last acknowledged job state.
+Bulk move, Trash and restore also share batch working copies rather than copying
+the full catalog for each item; name, ancestry and share checks still depend on
+catalog size.
+
+## Upload pipeline and smaller splits
+
+| Control | Default / allowed values |
+| --- | --- |
+| Concurrent uploads per bot | 1 / 1–4 |
+| Outstanding 512 KiB upload RPCs per document | 4; also bounded by account request limit |
+| Concurrent account media/metadata RPCs | 8 / 1–32 |
+| Account part/metadata pacing | 48 requests/s / 1–128 |
+| Combined upload/download operations per account | 3 / 1–16 |
+| Waiting origin operations, installation-wide | 256 / 1–4096 |
+| Preferred document split | 2000 MiB / 1–2000 MiB; 0 also means 2000 MiB |
+
+These count origin operations/RPCs, not viewers or whole files. More queue space
+permits longer waits, not throughput. Rate limits are protective application
+ceilings, not Telegram entitlements; provider waits take precedence.
+
+<details>
+<summary>Splits, Premium and tuning tradeoffs</summary>
+
+Smaller parts can engage more slots but add messages, manifests, retries and
+boundary setup. Pipelining can improve one document without splitting it.
+All new documents stay within 2000 MiB, including Premium. Very large files
+raise tiny split preferences to stay within 4096 parts; journaled plans are never
+re-split by a new preference. Staging/file-size limits still apply.
+
+Ready Premium clients are preferred for parts and payload windows, with eligible
+bot fallback when busy, cooling or unhealthy. Dispatched parts retain their
+sender on retry. Premium is a potential speed benefit, not a larger TGDrive file
+limit. [Telegram's file documentation](https://core.telegram.org/api/files) describes
+Premium throttling differences; TGDrive has not measured a live Premium multiplier.
+
+Keep one upload per bot initially. Change one limit at a time against a representative
+workload. Retain increases only when throughput improves without harming playback
+or increasing cooldowns; reduce concurrency/pacing when contention grows. Never
+rotate identities around provider waits.
+
+</details>
+
+## Video controls and startup
+
+The local custom player keeps controls available through loading, buffering,
+seeking and errors. It supports the media's available tracks/chapters and focused
+keyboard shortcuts (**K/Space**, **M**, arrows); mobile autoplay may require tapping
+Play. Slow starts offer **Try again**; unsupported codecs retain **Download Original**.
+
+The animated waiting status shows measured bytes received and current delivery
+speed when the player's HTTP source exposes them. Received bytes include repeated
+reads and seeks, so they are not a whole-file completion percentage. The compact
+status strip keeps retry inline and omits zero-speed and explanatory paragraphs;
+advancing presented frames clear a stale wait. The timeline's source-buffer time ranges are estimates,
+separate from server cache coverage. Playback does not require a whole-file preload.
+
+The pinned player applies video-decoder backpressure to video-only files rather
+than reading ahead for a nonexistent audio track. This protects decoder admission;
+it does not establish smooth playback on every codec/device.
+
+TGDrive retains its custom playback pipeline for all video previews, including
+HEVC. Native browser playback support does not establish that the custom
+WebCodecs/WASM pipeline can decode and render the same file smoothly.
+
+Fast server delivery cannot make every device decode a 4K codec smoothly. A long
+wait retains retry/download actions. Cached bytes still need delivery and decoding.
+At EOF, the hardware decoder drains pending pictures; the seek reset path must
+not recreate the HEVC decoder and discard its final pictures.
+
+### Browser playback buffer
+
+The custom player fetches compressed bytes independently of the small decoded
+picture queue. It aims for **90 seconds ahead**, using the greater of the file's
+average byte rate, declared bitrate and observed consumption rate. Higher bitrate
+sections increase that estimate. Seeks reset sampling instead of counting the
+skipped bytes as consumption. Once filled, fetching resumes below 75% of the goal
+(roughly 67 seconds), before the playhead approaches the buffer edge.
+
+The source starts with at most **32 MiB** and grows to meet that time goal as
+bitrate information becomes available. Its memory ceiling is one-sixteenth of
+the browser's approximate `navigator.deviceMemory` hint, bounded to **32–512 MiB**:
+
+| Reported device memory | Compressed source ceiling |
+| --- | --- |
+| 1 GiB | 64 MiB |
+| 2 GiB | 128 MiB |
+| 4 GiB | 256 MiB |
+| 8 GiB or more | 512 MiB |
+| Hint unavailable or invalid | 128 MiB |
+
+The hint is rounded/privacy-limited and unavailable in some browsers; it is
+**not free RAM**. The ceiling is not allocated upfront and does not cover decoder,
+GPU, WASM or transport memory. Growth preserves cached bytes, offsets and stream
+state. During growth the old and new allocations can temporarily coexist until
+garbage collection. If allocation fails, playback retains the working buffer and
+reduces its ceiling for this opening instead of retrying larger allocations.
+
+For longer videos, the time goal uses at most 80% of the allocated window to leave
+transport/compaction headroom. Very high bitrate files may still retain less than
+90 seconds on a constrained device. Clips up to two minutes that fit the device
+budget can cache completely. Non-range origins select sequential storage before
+writes and do not grow it during writes. Range requests scale with the byte goal, up to
+8 MiB; one upcoming response can already be in flight when fetching pauses.
+Neither a request size nor the decoded frame queue is the playback buffer goal.
+
+Seeking inside retained source bytes reuses them while decoding from a suitable
+keyframe. A seek outside the retained window fetches its new range. Closing the
+preview cancels its source requests. This is browser memory, separate from the
+server cache and manual whole-file preloads. Timeline coverage remains an estimate
+for variable bitrate/interleaved files, not a guarantee of decoded readiness.
+
+## Operator checklist
+
+Follow the [website-stats investigation](performance-tuning.md#start-with-the-website-stats)
+to compare cold and cached reads, inspect the affected stage and change one
+setting at a time. Keep the workload comparable before judging an improvement.
+
+### Read the Performance page
+
+**Monitor → Performance** separates server network, TGDrive HTTP file traffic
+and Telegram origin activity. They overlap: **do not add their totals**. Network
+counts include protocol/other interface traffic; Docker normally measures its
+container interface. Blue is **Download to server**; dashed is **Upload from server**.
+Hover or use the keyboard/touch sample scrubber. **Now** always means current.
+
+<details>
+<summary>History, totals and resource measurement</summary>
+
+- Live: five minutes of three-second samples. Recorded: 31 days of minute
+  aggregates, at most 360 plotted points. Presets include Last Month (30 days).
+- Averages cover observed seconds only. Missing/offline periods remain gaps;
+  incompatible scopes are not joined and earlier periods are not backfilled.
+  Custom inputs use UTC; the applied interval uses the configured timezone.
+- All-time totals are separate persistent checkpoints **since the displayed
+  tracking start date**. Network, Telegram and HTTP totals stay separate.
+  HTTP covers `/file` and resumable-upload bodies, including cached delivery
+  and receipt messages; it excludes assets/settings polling. Detailed process
+  counters reset on restart.
+- MongoDB stores history/totals without another metrics service. Checkpoints run
+  each minute and at clean shutdown; abrupt crashes can lose roughly a minute.
+  Diagnostic outages can lose observations without affecting file data. Telemetry
+  is excluded from encrypted backups.
+- CPU uses 0–100% of available container cores/quota. RAM uses cgroup usage and
+  a finite limit where present; otherwise its observed scale is explicit.
+  Host CPU is a labelled fallback. Load average is not CPU percentage; process,
+  container, host-available and cache memory are different measurements.
+
+</details>
+
+### Investigate a slowdown
+
+Use the [bottleneck table](performance-tuning.md#find-the-bottleneck) to choose
+between reducing work, changing cache, adding Telegram capacity or upgrading
+the host. A completed import can have zero current rate; inspect its historical
+interval and lifetime receive total instead.
+
+Compare graphs over the same interval. Account/request details are current/recent
+state, not a month-long request log. Cache hits/misses count lookups, not saved
+bytes. **Preloads** shows current verified coverage and jobs; clearing cached
+bytes requires confirmation and leaves originals intact.
+
+### Browser transport with a full cache
+
+A ready cache removes origin payload work, not viewer transport. Browser HTTP/3
+can differ from curl/Python HTTP/1.1 or HTTP/2. TGDrive clears alternative-service
+advertisements by default. Check [proxy configuration](operations.md#http-delivery-and-proxy-configuration)
+and [fresh-browser validation](streaming-validation-2026-10-18.md) before attributing
+warm-cache stalls to Telegram or raising budgets.
+
+### Distant video seeks
+
+Compressed read-ahead counts only bytes inside the current source window.
+Moving to a distant position must fetch its first range even while the demuxer
+still reports its old read position; skipped file bytes are not buffered data.
+The loading overlay shows time spent waiting and bytes received for that seek,
+rather than repeating a cumulative count from earlier playback. It remains a
+waiting state until actual playback frames advance. Source delivery, codec/device
+support and decoding still affect seek latency.
diff --git a/docs/reading.md b/docs/reading.md
new file mode 100644
index 00000000..ae019a53
--- /dev/null
+++ b/docs/reading.md
@@ -0,0 +1,143 @@
+# Reading books and comics
+
+[Docs home](README.md) · [All previews](usage.md#open-preview-and-download)
+
+Open a supported file from **My Files** or a shared folder. **Download** keeps the
+original available if previewing fails.
+
+**Contents**
+
+- [Choose a format](#choose-a-format)
+- [Bandwidth and compatibility](#bandwidth-and-compatibility)
+- [Reader limits](#reader-limits)
+- [Running the reader](#running-the-reader)
+
+## Choose a format
+
+| Format | Controls | How it loads |
+| --- | --- | --- |
+| PDF, up to 256 MiB | Scroll, zoom, fit, selectable text | Sections of the file as needed. |
+| EPUB | Chapters, text size/font, image-page fit, right-to-left | Book details, the selected chapter and images. |
+| CBZ / CBR | Pages, fit, right-to-left | The selected image; some RAR archives also need earlier compressed data. |
+
+EPUB/comics remember your place in this browser for up to 50 books. Use
+**Reading options** to change EPUB text size and font style, or
+comic fit and reading direction. EPUB text uses a narrower serif column by
+default; text preferences are saved in this browser. Generated resource filenames
+appear as readable cover, illustration or section labels.
+
+Choose **Enter Fullscreen** where supported. Arrow keys navigate while focused;
+right-to-left mode reverses them. Escape or browser Back closes the reader.
+
+Image-based manga works in EPUB and CBZ. Image-only EPUB chapters use the page-fit
+controls instead of the prose column. Choose **Fit width** for readable panels or
+**Fit page** for a whole page, and enable **Right to left** for reversed arrow-key
+navigation. The archive/spine order stays unchanged.
+
+<details>
+<summary>See the PDF, EPUB and comic readers</summary>
+
+![PDF reader with page navigation and zoom controls](assets/pdf-reader.png)
+
+[EPUB and comic screenshots](showcase.md#read-and-preview) ·
+[Watch the preview and reader walkthrough](assets/readers-and-preview.mp4)
+
+</details>
+
+## Bandwidth and compatibility
+
+Readers use the authorized range cache without automatically preloading the whole
+book. Small files may fit in one fetched block; solid RAR can require earlier
+entries. Byte savings vary.
+
+Pages keep their original image bytes: TGDrive does not upscale, transcode or
+recompress them. Some colour pages or spreads are much larger than the average.
+Raster pages are limited to **16 million pixels** and **32,768 pixels per edge**.
+Oversized or unreadable image headers produce a preview error; download the
+unchanged original to open it in another reader.
+The reader shows received image bytes after the server has prepared the selected
+resource. If a server or proxy compresses the response, progress shows received
+bytes without a total; the **64 MiB** image limit still applies after HTTP
+decompression. The reader retries temporary image download failures up to three
+attempts (2/4-second waits, or a longer server retry hint up to 30 seconds), and
+reports permanent errors without repeatedly requesting them. Leaving the page
+cancels that browser's download/retries. EPUB images start loading near the
+viewport; offscreen image blobs are released
+while placeholders preserve scroll space. Returning to an image revalidates its
+private browser cache entry.
+
+The server reuses extracted original pages and parsed chapters/indexes in a
+**64 MiB**, 16-result memory cache for up to **five minutes**. Requests for the same
+result wait for one extraction. Cache eviction or restart requires parsing again;
+source ranges can still be reused from the normal range cache. Browser responses
+are private and revalidated, allowing an unchanged authorized page to return 304
+without sending its image again. Every request, including cache hits and 304s,
+checks current access and source identity. Results are never publicly cached.
+
+PDF, EPUB and comics share the application-themed toolbar and page/chapter
+navigation; PDF keeps zoom/text selection and EPUB keeps text preferences. PDF.js
+loads shared image resource payloads only when used by a rendered page, instead of
+eagerly loading every image in a shared dictionary. Visible pages render before
+nearby-page overscan starts. A PDF can still require distant metadata, fonts,
+shared masks, or large images before its first page appears; there is no promise
+of a fixed number of startup bytes. All PDF rendering happens in the browser,
+without server-side page conversion.
+
+Password-protected PDFs ask for their document password in the reader. The value
+is used in memory by PDF.js and is not saved; closing the preview discards it.
+Matching fonts, character maps, color profiles and image decoders are served by
+TGDrive itself, without an external asset CDN.
+
+EPUB supports passive text, tables and raster images in TGDrive's theme.
+Publisher scripts/styles, remote resources, exact fixed layouts, SVG illustrations,
+interactive features and DRM/encryption (including encrypted font metadata) are
+unsupported. Comics accept PNG/JPEG/GIF/WebP/AVIF when the browser can decode them;
+password-protected archives are unsupported.
+
+<details>
+<summary>Reader limits and container dependencies</summary>
+
+## Reader limits
+
+EPUB chapters containing images and at most 80 characters of surrounding text
+use the illustrated-page layout. More complex publisher layouts can differ.
+
+PDF.js retains a source buffer up to the **256 MiB** file limit. HTTP requests are
+split into at most **1 MiB** ranges, with at most **two** reader requests active.
+Combined active response buffers normally stay within **64 MiB**. A larger
+PDF.js metadata request may run alone, bounded by the accepted source size;
+queued requests hold descriptors rather than response buffers. Buffer claims are
+released after each success/failure. Reading more than 64 MiB over time does not
+close the document. Canvas/page/text budgets still apply; complex PDFs can be
+slow or exceed device memory. These are bounds, not a fixed RAM reservation.
+
+| Bound | Limit |
+| --- | --- |
+| Index/chapter/thumbnail operation | 32 MiB fetched; aligned 1 MiB reads and a four-block parser cache |
+| One selected original raster image | 64 MiB encoded image; up to 96 MiB source reads, without loading unrelated ZIP entries |
+| Raster dimensions | 16 million pixels and 32,768 pixels per edge, including declared animation frames; checked before image bytes leave the parser |
+| Archive | 10,000 entries; 2 MiB ZIP directory; stored/deflate ZIP methods |
+| EPUB / entries | 5,000 spine entries; 2 MiB/text entry; 16 MiB thumbnail-source image (independent of the 64 MiB reader page limit) |
+| Parser work | Two simultaneous operations, 16 pending requests, 45-second parser timeout; 55-second total route deadline including coalesced waits |
+| Linux container parser process | 384 MiB address space, 10 CPU-seconds on every supported host |
+
+Raster image bytes cross the parser boundary as bounded binary output, avoiding
+base64 expansion. This does not change the image delivered to the browser. CBR
+may need earlier compressed bytes and can exhaust its read budget before a page.
+Unsafe/duplicate names and extreme compression ratios fail. Busy readers receive
+retry guidance. Budgets apply per operation; cached content may be reused.
+Raster checks read format headers without decoding or resizing. JPEG dimensions
+must appear within the first 1 MiB; excessive or malformed header structure is
+rejected. The pixel limit is about 61 MiB for one RGBA frame, not a total browser
+memory guarantee: animation, decoder, GPU and other reader resources add overhead.
+Authorization is rechecked during reads. Revocation stops later reads through
+that link, while independent links remain valid; delivered bytes cannot be recalled.
+
+## Running the reader
+
+The TGDrive image includes CBR's native libarchive runtime; no host library
+installation is needed. If CBR parsing fails, download the original for a
+dedicated reader. The bounded parser process is not an OS security sandbox;
+keep the deployment image updated.
+
+</details>
diff --git a/docs/reference.md b/docs/reference.md
new file mode 100644
index 00000000..b95d8c34
--- /dev/null
+++ b/docs/reference.md
@@ -0,0 +1,1461 @@
+# Configuration and API reference
+
+[Docs home](README.md) · [Settings guide](configuration.md) · [Development](development.md)
+
+Look up an exact setting, limit or request contract. Tables and examples expand
+on demand. For everyday workflows, start with [Using TGDrive](usage.md) or the
+[visual walkthroughs](showcase.md).
+
+**Contents**
+
+- [Terms used here](#terms-used-here)
+- [Configuration](#configuration)
+- [Owner administration](#owner-administration)
+- [HTTP API](#http-api)
+- [Security and privacy](#security-and-privacy)
+
+<details>
+<summary>Configuration and API sections</summary>
+
+- [Configuration](#configuration)
+  - [File syntax and secret handling](#file-syntax-and-secret-handling)
+  - [Telegram accounts](#telegram-accounts)
+  - [Performance and cache settings](#performance-and-cache-settings)
+  - [Owner authentication](#owner-authentication)
+  - [Persistence and initialization](#persistence-and-initialization)
+  - [File capacity, staging, and work limits](#file-capacity-staging-and-work-limits)
+  - [Remote HTTP(S) uploads](#remote-https-uploads)
+  - [Deployment variables outside application Settings](#deployment-variables-outside-application-settings)
+- [HTTP API](#http-api)
+  - [Conventions and authentication](#conventions-and-authentication)
+  - [Session, configuration, health, and assets](#session-configuration-health-and-assets)
+  - [Independent channel backup and recovery](#independent-channel-backup-and-recovery)
+  - [Owner connection management](#owner-connection-management)
+  - [Listing and metadata](#listing-and-metadata)
+  - [Atomic folder preparation](#atomic-folder-preparation)
+  - [Move and bulk actions](#move-and-bulk-actions)
+  - [Performance, cache inventory and preparation](#performance-cache-inventory-and-preparation)
+  - [Resumable browser receipts](#resumable-browser-receipts)
+  - [Previews and media](#previews-and-media)
+  - [Jobs](#jobs)
+  - [Transfer history](#transfer-history)
+  - [Starred items](#starred-items)
+  - [Shares, downloads, and ranges](#shares-downloads-and-ranges)
+  - [URL imports and transfer routes](#url-imports-and-transfer-routes)
+  - [Errors and retry discipline](#errors-and-retry-discipline)
+
+</details>
+
+## Terms used here
+
+| Term | Meaning |
+| --- | --- |
+| Catalog / metadata | Records describing your files and folders; not their contents |
+| Receipt | The server's record of upload bytes already received |
+| Staging | Temporary server disk holding unfinished upload bytes |
+| Manifest | The ordered list of Telegram parts making up one large file |
+| Lease / ownership | A temporary lock that keeps two installations from writing at once |
+| Share capability | A secret link/token that grants access to specific content |
+| Preload | A disposable cached copy prepared for faster access |
+| Restore point / checkpoint | A confirmed backup state that recovery can return to |
+| Idempotent request | Retrying the same request does not create a second result |
+
+## Configuration
+
+1. Start with private environment variables or `.env`.
+2. Saved MongoDB settings fill missing bootstrap values.
+3. Telegram connections edited in the web app override the original Telegram
+   credential fields and apply after a restart.
+
+Host environment values override `.env`. Blank optional bootstrap credentials
+can reuse saved MongoDB settings; explicit deployment values take precedence
+over a local recovery fallback. An edited Docker environment needs container
+recreation, rather than only a process restart. Saved dashboard performance
+preferences have their own precedence, described below.
+
+Settings are case-insensitive. Unknown names are ignored, so check for typos.
+
+The supplied `.env.example` lists the required values for a new drive.
+Optional settings use application defaults; add an override to your private `.env`
+only when needed. Compose passes this file through `env_file`; its `environment`
+block contains bootstrap inputs and fixed container paths, cookie and proxy policy.
+Local Compose overrides the hosted cookie/proxy policy for localhost HTTP.
+Environment entries override matching values from `env_file`.
+See [Docker's environment guide](https://docs.docker.com/compose/how-tos/environment-variables/set-environment-variables/).
+
+| Deployment flag | Default | Behavior |
+| --- | --- | --- |
+| `DEMO_MODE` | false | Give the usual password restricted visitor access; protect Demo Files and lock management writes/key exports. A separately configured demo administrator can bypass those restrictions. Requires container recreation/redeploy. See [public demo mode](configuration.md#public-demo-mode). |
+
+> [!IMPORTANT]
+> Keep real credentials private. Example placeholders are not working credentials.
+
+### File syntax and secret handling
+
+<details>
+<summary>Formatting, blank values and secrets</summary>
+
+Use one NAME=value assignment per line. Use true or false for booleans,
+decimal integers for byte counts, and commas for account/administrator lists.
+Whitespace around comma-separated entries is removed. Empty entries are ignored.
+
+Keep .env owner-readable and outside source control. Quote an Argon2 hash in
+single quotes because it contains dollar signs. Do not shell-source a
+configuration file or put secrets in shell command arguments. Docker's env_file
+and Python dotenv parse the file themselves.
+
+Optional does not always mean that a blank value is accepted:
+
+- Omit ADMIN_PASSWORD_HASH when unused; a blank value is treated as absent.
+- ADMIN_PASSWORD= requires a valid explicit hash or the original saved hash
+  loaded from an existing MongoDB drive.
+- STRING_SESSIONS= disables optional Premium sessions. Legacy storage-only
+  setups can omit MAIN_BOT_TOKEN. Blank/omitted bot-interface credentials can
+  reuse values saved in MongoDB, so blanks do not disable a configured interface.
+  A main bot token requires TELEGRAM_ADMIN_IDS; storage still needs a working bot.
+- MAX_FILE_SIZE= means the bounded default logical-file limit.
+- With standard Compose auto-secrets enabled, blank SESSION_SECRET and
+  MONGODB_BACKUP_KEY reuse original saved keys, or generate them for a new drive.
+
+Invalid settings fail before serving the application. Secret wrappers and
+hidden validation inputs reduce accidental disclosure in exception text; they
+do not make a configuration file safe to publish.
+
+</details>
+
+### Telegram accounts
+
+<details>
+<summary>API credentials, bot tokens and optional accounts</summary>
+
+| Variable | Required/default | Validation and behavior |
+| --- | --- | --- |
+| `API_ID` | Required unless supplied by managed settings | Positive integer Telegram application ID; the web editor bounds it to 1–2147483647. |
+| `API_HASH` | Required unless managed, secret | Exactly 32 hexadecimal characters; surrounding whitespace is removed. |
+| `MAIN_BOT_TOKEN` | Required by the new-drive setup, secret | One bot token for the Telegram chat interface; requires TELEGRAM_ADMIN_IDS. On initial setup, it also supplies the first storage bot when no legacy BOT_TOKENS list is provided. Tokens must match the expected numeric-ID and secret format; Telegram verifies actual validity on connection. |
+| `BOT_TOKENS` | Legacy bootstrap, secret | Existing comma-separated storage bot lists remain supported; duplicates are rejected. An explicit list is preserved rather than replaced by MAIN_BOT_TOKEN. For new deployments, use MAIN_BOT_TOKEN and add further storage bots through Connections. |
+| `STORAGE_CHANNEL` | Required | Negative integer private channel ID. Confirmed catalogs bind to this channel; changing it is not relocation and can trigger RECOVERY_REQUIRED. Use the membership/permissions from [Telegram setup](setup.md#2-prepare-telegram). |
+| `STRING_SESSIONS` | Empty by default, secret | Comma-separated Telethon StringSession credentials for optional Premium users; duplicates are rejected. Sessions must already be authorized and identify Premium user accounts. |
+| `PUBLIC_URL` | Omitted/empty by default | Optional HTTP(S) website origin for the bot's `/set_folder` link. Otherwise the website address is remembered when saving its bot upload folder. |
+| `TELEGRAM_ADMIN_IDS` | Required with MAIN_BOT_TOKEN | Comma-separated positive numeric Telegram user IDs allowed to use the bot in private chat; usernames are not accepted. [Find your ID](setup.md#find-your-telegram-user-id). |
+
+After initialization, saved **Connections** are authoritative for storage
+accounts. Changing MAIN_BOT_TOKEN does not replace their saved credentials; it
+changes the chat interface's token. If one bot serves both roles and its token
+changes, update both places. Existing BOT_TOKENS deployments can continue without
+enabling the chat interface.
+For legacy Compose setup, keep BOT_TOKENS in the private `.env` file; a shell
+export alone is not passed to the container.
+
+Storage bots are the required baseline. The running pool can remain ready with
+a healthy storage bot when additional bots or Premium sessions fail.
+Premium capability is checked from healthy, started clients with confirmed
+connectivity, not merely a nonempty STRING_SESSIONS value. See
+[Telegram behavior](setup.md#additional-bots-and-premium-accounts) for account selection and recovery limits.
+
+</details>
+
+### Performance and cache settings
+
+<details>
+<summary>Live preferences, defaults and cache limits</summary>
+
+Saved dashboard preferences override startup defaults, persist in MongoDB and
+apply to new work immediately. Environment changes require a restart; recreating
+a container does not override saved preferences. Telegram credential edits use
+the separate restart-based connection editor.
+
+**Discard changes** restores the last saved values. **Restore defaults** creates a
+category-scoped draft; Save validates and applies it. Defaults below use binary
+units: 1 GiB = 1024 MiB.
+
+| Variable | Default | Meaning and bounds |
+| --- | --- | --- |
+| `CACHE_MEMORY_BYTES` | 268435456 | RAM payload budget, 0–8 GiB (default 256 MiB). Zero disables RAM retention. Available host/container memory can lower the effective limit. RAM blocks expire after 10 idle minutes; reuse refreshes expiry. |
+| `CACHE_DISK_BYTES` | 10737418240 | Disk budget, 0–2 TiB. Zero disables disk retention. It does not reserve that amount of disk in advance. |
+| `CACHE_MIN_FREE_BYTES` | 1073741824 | Free-disk floor for cache writes, 0–2 TiB (default 1 GiB). This does not allocate space or constrain other disk users. Upload staging separately uses `MIN_FREE_BYTES`. |
+| `CACHE_TTL_SECONDS` | 86400 | Sliding disk retention, 60–2678400 seconds. Eviction or disk failure can remove bytes sooner. |
+| `AUTO_PRELOAD` | true | Enable extra bounded warming after delivered original audio/video playback bytes. Explicit downloads and unclassified range clients stay within requested ranges. Disabling it leaves adaptive response read-ahead and manual **Preload file** available. |
+| `PRELOAD_MAX_JOBS` | 2 | Combined manual and automatic preparation jobs, 1–8; foreground work has priority. More jobs share existing account capacity. |
+| `TELEGRAM_UPLOAD_PIPELINE` | 4 | Outstanding upload-part requests per document, 1–16. |
+| `TELEGRAM_REQUEST_LIMIT` | 8 | Shared per-account media/metadata request concurrency, 1–32. |
+| `TELEGRAM_PARTS_PER_SECOND` | 48 | Application request pacing ceiling, 1–128, including scheduled metadata work. This is not a Telegram-provided bandwidth limit. |
+| `TELEGRAM_MEDIA_PER_BOT` | 3 | Shared concurrent origin media operations per account, 1–16. Uploads also retain their separate per-bot/user lane limits. |
+| `TELEGRAM_MAX_QUEUE` | 256 | Global queued origin operations, 1–4096; overflow returns retry guidance. |
+| `UPLOAD_SPLIT_MIB` | 2000 | Default and maximum document size for every account, including Premium. Explicit 1–2000 values choose a smaller preferred cap; 0 also uses 2000 MiB. The minimum grows when needed to stay within 4096 parts, without exceeding 2000 MiB. Persisted plans keep their original boundaries. |
+| `TIMEZONE` | Asia/Kolkata | Installation-wide display timezone for owner and public dates/share expiry. Use a valid IANA name; the default is IST. |
+
+RAM includes the asynchronous disk-write backlog. Active responses have a separate
+32 MiB transient payload budget, reduced by available memory with a 2 MiB floor;
+transport/server buffers are outside these budgets. `cache.scratch` reports current,
+effective and configured bytes, peak reservations, waiting heads and active streams.
+RAM and disk may duplicate blocks, so their sum is not whole-file capacity.
+
+Preload admission counts complete aligned Telegram blocks, multipart boundaries,
+a 32-byte disk integrity prefix per block and competing reservations. Retention
+never guarantees a pin: TTL, eviction and disk failure still apply.
+
+Dashboard saves reject enabled disk caching with a free-space floor below 64 MiB
+(`422`); a zero disk budget remains valid. Existing environment values are not
+rewritten. Read-only defaults cannot be submitted as a preference.
+
+See [performance policy](performance.md), including
+[automatic read-ahead](performance.md#automatic-read-ahead), for scheduling and
+warming thresholds. Settings do not guarantee bandwidth or free disk.
+
+</details>
+
+### Owner authentication
+
+<details>
+<summary>Passwords, sessions and cookies</summary>
+
+| Variable | Required/default | Validation and behavior |
+| --- | --- | --- |
+| `ADMIN_PASSWORD_HASH` | None by default, secret | Optional existing Argon2id owner credential; memory cost 19,456–262,144 KiB, time cost 2–10, at most 16 lanes. Otherwise set `ADMIN_PASSWORD`; TGDrive hashes it internally. |
+| `ADMIN_PASSWORD` | Empty by default, secret | Plaintext fallback when no hash is configured. At least 12 characters after trimming. If a hash is present, clear the example plaintext value. A malformed nonempty plaintext value still fails validation. |
+| `DEMO_ADMIN_PASSWORD` | Empty by default, secret | Optional different password granting full access only while `DEMO_MODE=true`. At least 12 characters after trimming. Not stored/restored in bootstrap preferences. |
+| `DEMO_ADMIN_PASSWORD_HASH` | None by default, secret | Optional Argon2id alternative to `DEMO_ADMIN_PASSWORD`, with the same validation bounds as `ADMIN_PASSWORD_HASH`. Takes precedence over demo administrator plaintext. Not stored/restored in bootstrap preferences. |
+| `SESSION_SECRET` | Required, secret | Independent random signing secret of at least 32 characters after trimming. Do not reuse an account or password credential. |
+| `SESSION_TTL_SECONDS` | 86400 | Integer 300-2592000 inclusive: absolute browser session lifetime in seconds (24 hours by default). No separate idle timeout. |
+| `COOKIE_SECURE` | true | Secure cookies require HTTPS. Local Compose sets false for loopback HTTP. Disabling it does not enable full remote HTTP support; see [HTTP requirements](operations.md#can-tgdrive-run-over-http). |
+
+At least one password representation is required. The hash takes precedence
+when both valid forms are configured. The plaintext fallback is hashed in
+memory when the application is created; the .env value itself remains
+plaintext.
+
+During initial setup MongoDB's `settings` collection stores a bootstrap document
+(`_id: "bootstrap"`) containing `ADMIN_PASSWORD_HASH`, never the plaintext
+`ADMIN_PASSWORD`. A missing explicit owner credential can reuse that saved hash.
+The private `DATA_DIR/replica-bootstrap.json` recovery file also retains the
+owner hash so recovery-only login remains possible. Encrypted database backups
+can contain those saved credentials. These copies do not reveal the original
+password; plaintext remains readable wherever you configured it. Demo
+administrator credentials stay in deployment configuration, outside these
+bootstrap records. See [reset instructions](operations.md#forgotten-login-password).
+
+Blank or whitespace-only plaintext values are canonicalized to empty and
+require a valid explicit or saved bootstrap hash. Nonempty plaintext values must meet the minimum after
+trimming.
+
+Use a unique password or passphrase of **15+ characters**; the implementation's
+minimum remains 12. There is no built-in MFA or passkey login. The stronger
+length recommendation follows [OWASP authentication guidance](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)
+for password-only authentication.
+
+The owner password is not a Telegram password. Browser session signatures derive
+from SESSION_SECRET and the effective configured owner credential, and sessions
+are tracked in MongoDB's sessions collection. Loading a changed password/hash or
+signing secret invalidates existing owner cookies; an unchanged configuration
+preserves sessions across restarts. Share links are separate credentials. See
+[rotation and access recovery](operations.md#https-and-private-configuration).
+
+Each successful login creates an independent session. Different devices and
+browser profiles may use the same owner credentials concurrently; a later login
+does not replace earlier sessions. Logout revokes only the presented session.
+Tabs sharing a browser cookie jar share that session. Demo mode adds a signed
+`demo_admin` capability only for the separate full-access password. Legacy and
+ordinary-password cookies remain restricted in demo mode; clients cannot add
+this capability to their cookies. Its signature derives from a separate key
+bound to the demo administrator credential and `SESSION_SECRET`. Rotating or
+removing the demo administrator password invalidates elevated sessions without
+invalidating ordinary sessions. Outside demo mode the extra password is ignored.
+
+Password verification stays limited to one concurrent check. A simultaneous
+login can receive `429` with code `LOGIN_BUSY`; the website retries that response
+up to three total attempts, waiting 1–2 seconds between tries. Incorrect passwords,
+the five-failure throttle and network errors are not automatically retried.
+
+Set `ADMIN_PASSWORD` in the private deployment environment; TGDrive hashes it
+internally. An existing compatible Argon2id hash may instead be supplied in
+`ADMIN_PASSWORD_HASH`, with `ADMIN_PASSWORD` empty. See
+[password reset](operations.md#forgotten-login-password) and
+[website archive restore](backup-recovery.md#restore-a-lost-database-from-telegram).
+
+</details>
+
+### Persistence and initialization
+
+<details>
+<summary>MongoDB, backup keys and local paths</summary>
+
+| Variable | Default | Validation and behavior |
+| --- | --- | --- |
+| `MONGODB_URI` | Required | Secret URI beginning mongodb:// or mongodb+srv://. Missing/invalid configuration or failed database access rejects startup; no local database fallback. |
+| `MONGODB_DATABASE` | tgdrive | 1–63 ASCII letters/digits, underscores or hyphens; dedicated to one drive. |
+| `MONGODB_BACKUP_KEY` | None | Secret 64-hex-character AES-256 key. Keep a separate recovery copy. |
+| `MONGODB_BACKUP_SECONDS` | 3600 | Integer 60–604800 seconds between successful automatic safety copies. |
+| `DATA_DIR` | data | Persistent generated keys, Telegram sessions, helper locks, recovery/activation state and media cache. MongoDB holds the live catalog and durable job/receipt records. |
+| `CACHE_DIR` | cache | Persistent unfinished upload payloads and encrypted temporary database backup files. Keep unfinished bytes. |
+| `LOG_LEVEL` | INFO | DEBUG, INFO, WARNING, ERROR or CRITICAL. |
+
+DATA_DIR and CACHE_DIR must be writable distinct paths, not a filesystem
+root or account home, equal or nested. Compose sets /app/data and /app/cache.
+The container runs as UID/GID 10001:10001; custom bind mounts must allow that
+account to write. Do not replace missing writable volumes with disposable mounts.
+
+Standard Compose enables `TGDRIVE_AUTO_SECRETS=true`. Missing
+`SESSION_SECRET` and `MONGODB_BACKUP_KEY` values are generated once for a new
+drive and saved as mode 0600 in `DATA_DIR/deployment-secrets.json`. Explicit
+values and existing MongoDB bootstrap settings take precedence. Existing drives
+with missing keys fail rather than silently receiving replacement keys.
+
+The storage_channel_id binding is a nonzero signed 64-bit integer. Switching
+channels cannot silently reinterpret message IDs. Use a MongoDB replica set;
+the application uses transactions, majority writes and bounded request/pool
+settings. Startup initializes only a pristine database under the ownership lock.
+Existing records, saved settings or recovery state prevent automatic replacement
+of a missing catalog. Configuration, connection, authentication and transaction
+failures stop startup. Archive restore refuses a used drive; it accepts only an
+empty database or the untouched catalog created by automatic first setup.
+
+</details>
+
+### File capacity, staging, and work limits
+
+<details>
+<summary>Exact sizes, staging reservations and concurrency</summary>
+
+| Variable | Default | Validation and behavior |
+| --- | --- | --- |
+| `MAX_FILE_SIZE` | Unset | Optional positive logical-file byte ceiling; the runtime upload policy supports up to 2 TiB, further bounded by staging. Files above one Telegram document's limit do not require Premium. |
+| `STAGING_BUDGET_BYTES` | 17179869184 | Positive integer, at most 2 TiB in the runtime upload policy; 16 GiB total reservation budget by default. |
+| `MIN_FREE_BYTES` | 1073741824 | Nonnegative integer; preserve 1 GiB free space by default. Browser receipt admission reserves remaining bytes; URL downloads also check free space. |
+| `UPLOAD_SESSION_TTL_SECONDS` | 86400 | Integer at least 60; incomplete receipt idle lifetime in seconds, refreshed after each committed chunk. There is no declared upper bound in configuration. |
+| `MAX_CONCURRENT_TRANSFERS` | 2 | Integer 1–32; bounds local fingerprinting and receive work. Receipt handlers have a separate bound from this value. It does not cap Telegram uploads across bots. |
+| `TELEGRAM_UPLOADS_PER_BOT` | 1 | Integer 1–4; initial per-bot Telegram media limit. **Configuration → Transfer limits** saves an override in MongoDB and applies it immediately. Premium clients remain limited to one media upload each. |
+| `TRANSFER_TTL_SECONDS` | 3600 | Integer 60-86400 inclusive; terminal jobs become eligible for cleanup on admission or explicit pruning. Compact server-transfer history is kept separately; files are unaffected. |
+
+New documents use at most **2000 MiB (2,097,152,000 bytes)** for every account,
+including Premium. `UPLOAD_SPLIT_MIB=0` uses that cap. Larger logical files use
+ordered parts and appear as one item with original downloads and range seeking.
+The `/api/config` logical limit is the minimum of `STAGING_BUDGET_BYTES`, optional
+`MAX_FILE_SIZE` and 2000 MiB x 4096 parts: **16 GiB by default**, subject to disk.
+The multipart format's 4096-part ceiling is separate from the current **2 TiB**
+upload-policy maximum; it does not make larger upload settings valid.
+TGDrive has no aggregate stored-byte quota; its catalog is bounded to 250,000
+file/folder entries, including the root.
+Premium is preferred when eligible; bot fallback and existing sender identities
+remain supported.
+
+Browser chunks are 8 MiB except the last. At most 1,000 unfinished receipts and
+2,000 rows in unfinished browser batches are tracked. Finished browser history
+keeps at most 30 tasks/2,000 rows, retaining unresolved tasks. Browser bounds
+are per controller; staging and Telegram account limits apply across callers.
+Allow disk headroom for URL work, logs, metadata and backups beyond receipt
+reservations.
+
+Device receives start at two concurrent files and adapt between one and four.
+Each accepted file queues immediately. Staging/account waits still apply; reducing
+Telegram concurrency lets active uploads finish. See the canonical
+[transfer pipeline](architecture.md#transfer-pipeline) for adaptation, admission,
+retry and cancellation rules.
+
+</details>
+
+### Remote HTTP(S) uploads
+
+<details>
+<summary>URL fetching, timeouts and network settings</summary>
+
+| Variable | Default | Validation and behavior |
+| --- | --- | --- |
+| `ALLOW_PRIVATE_REMOTE_URLS` | false | Enables private/internal destinations only when explicitly true. It broadens what the authenticated owner can reach. |
+| `REMOTE_DOWNLOAD_CONCURRENCY` | 2 | Integer 1–8; full-speed source downloads. Configuration → Transfer limits saves and immediately applies an override. See [URL intake](performance.md#url-import-intake) for queued connections, pacing and storage bounds. |
+| `REMOTE_CONNECT_TIMEOUT` | 20 | Seconds, greater than 0 and at most 300. |
+| `REMOTE_READ_TIMEOUT` | 120 | Seconds, greater than 0 and at most 3600; individual read timeout. |
+| `REMOTE_TOTAL_TIMEOUT` | 21600 | Seconds, greater than 0 and at most 86400; total operation budget. |
+| `REMOTE_MAX_REDIRECTS` | 5 | Integer 0-20 inclusive; manually validated redirect count. |
+
+URL requests validate destinations and redirects, request identity encoding,
+and enforce declared and observed sizes. The configured global ceiling still
+bounds HTTP retrieval, while runtime admission applies current account
+capacity. Telegram flood waits are persisted with a server-provided retry time;
+the transport disables Telethon's automatic flood sleeping. Details and limits
+are in [transfers](architecture.md#transfer-pipeline) and [security](reference.md#security-and-privacy).
+
+With the default private-network policy, IP literals and every DNS/redirect
+destination must be globally routable. Shared/CGNAT addresses (`100.64.0.0/10`),
+IPv6 site-local addresses and IPv4-mapped versions of blocked addresses are
+rejected alongside private, loopback, link-local, multicast and reserved ranges.
+
+</details>
+
+### Deployment variables outside application Settings
+
+<details>
+<summary>Ports, proxy trust and worker settings</summary>
+
+| Variable/control | Shipped behavior |
+| --- | --- |
+| `BIND_ADDRESS` | Compose interpolation only; defaults to 127.0.0.1 for the host binding. It is not a Settings field. |
+| `PORT` | Local Compose's host port defaults to 8000; the supplied container command always listens on internal port 8000. |
+| `FORWARDED_ALLOW_IPS` | Optional explicit Uvicorn proxy trust override. The container launcher defaults to loopback plus the private IPs resolved from `TGDRIVE_PROXY_HOSTS`; the hosted Compose file sets that hostname to `coolify-proxy`. Unset or `auto` enables discovery. |
+| `TGDRIVE_PROXY_HOSTS` | Deployment-owned, comma-separated internal proxy hostnames. Only their resolved private IPs are trusted. A DNS failure retains loopback trust and logs an actionable warning; it never enables wildcard trust. |
+| `TGDRIVE_AUTO_SECRETS` | Standard Compose sets true in the container environment. Generates missing session/backup keys once for a new drive in persistent DATA_DIR. Existing drives must reuse their original keys. |
+| `TGDRIVE_RESTART_POLICY` | Compose interpolation only. Laptop override defaults to no, hosted/server mode to unless-stopped. Choose deliberately; restart policies do not restart a running container merely because it is unhealthy. |
+| --workers | Must remain 1. This is a launch argument, not an environment feature for scaling the drive. |
+
+`BIND_ADDRESS` only affects the local override. The server override always binds
+its published port to 127.0.0.1; Coolify's base Compose publishes no host port.
+`COOKIE_SECURE=true`, the internal data/cache paths, automatic first initialization and
+the single-worker launcher are enforced by the hosted Compose definitions.
+
+Compose forwards `FORWARDED_ALLOW_IPS` to the container. Trust only the reverse
+proxy addresses the app actually sees; keep direct access to the app port restricted.
+
+Apply settings using [operations](operations.md), then diagnose errors using
+[troubleshooting](operations.md#troubleshooting). The [development chapter](development.md)
+owns the version compatibility baseline.
+
+</details>
+
+## Owner administration
+
+Configure the environment, deploy and sign in. First initialization is automatic;
+TGDrive has no maintenance CLI or terminal setup wizard. Use **Connections** for
+Telegram login and repairs, **Transfers** for retries and cancellations, and
+**Storage & Backups** for protection and archive/channel recovery. Deployment
+credentials and service restarts remain in Docker Compose or Coolify; failures
+that prevent startup are explained in container logs. See
+[recovery](backup-recovery.md) and [password reset](operations.md#forgotten-login-password).
+
+## HTTP API
+
+The web app uses these owner-session and scoped-share endpoints.
+There are no API keys or multi-user accounts. Interactive OpenAPI pages are disabled.
+
+### Conventions and authentication
+
+<details>
+<summary>Cookies, ID paths, bodies and timestamps</summary>
+
+All routes are relative to the app origin. Use JSON bodies with
+`Content-Type: application/json`, except multipart uploads and chunk PATCH.
+The React client uses both versioned `/api/v1` routes and application routes such
+as `/api/getDirectory`. Both are active v2 interfaces.
+
+Drive paths contain **IDs**, not display names. Root is `/`; a nested item is
+`/<folder-id>/<item-id>`. In a listing, a node's `path` is its **parent** path;
+append `id` to address the item. The `parent_id` parameter in receipt/listing
+requests currently accepts a complete folder path despite its name.
+
+Private routes require the `tgdrive_session` cookie. Browser requests must use
+same-origin cookies. Mutations reject a supplied foreign Origin, or
+`Sec-Fetch-Site: cross-site` without an Origin. Non-browser clients may use a
+protected cookie jar. There is no general cross-origin integration mode.
+
+Metadata/share dates are ISO strings; receipt `expires_at` is Unix seconds.
+Job `current`/`total` mean bytes for media transfers and message counts for
+deletion. Additional response fields may appear. This is not a promise of
+permanent third-party API compatibility.
+
+</details>
+
+### Session, configuration, health, and assets
+
+<details>
+<summary>Login, health, backup and asset endpoints</summary>
+
+| Method and route | Access | Request | Success |
+| --- | --- | --- | --- |
+| `GET /` | Public shell | None | React HTML; build instructions if frontend source is not built. |
+| `GET /api/config` | Public | None | Includes `status`, `max_file_size` (default 16 GiB logical limit), `timezone`, `recovery_only` and `demo_mode` (default false). |
+| `POST /api/checkPassword` | Public, throttled | `{"pass":"<owner-password>"}` | `200 {"status":"ok"}` plus session cookie. |
+| `POST /api/logout` | Cookie if present | `{}` | `200 {"status":"ok"}`; revokes an active owner session and clears the cookie. Missing/invalid/expired/revoked cookies do not trigger a session database write. |
+| `GET /api/v1/session` | Public | None | `{"authenticated":true}` or false. |
+| `GET /api/v1/status` | Owner | None | Connection, capacity, committed revision, backend, encrypted snapshot history and client health. |
+| `POST /api/v1/backup` | Owner | `{}` | `{"recovery":{...}}` after an encrypted MongoDB safety copy is verified; `503` if not confirmed. |
+| GET /api/v1/backup/recovery-key | Owner | None | Private no-store download of the backup decryption key. |
+| `POST /api/v1/backup/restore` | Owner, disabled in demo | Raw `.tgdb` bytes, `Content-Type: application/octet-stream`, `X-TGDrive-Recovery-Key: <64 hex characters>`, `X-TGDrive-Confirm: RESTORE` | Authenticates and restores a full archive into an empty or untouched automatically created drive; returns `restart_required: true`. |
+| `GET /health/live` | Public | None | `200 {"status":"ok"}` if HTTP can answer. |
+| `GET /health/ready` | Public | None | `200` if runtime/pool ready, otherwise `503`. |
+| `GET /healthz` | Public | None | Readiness alias used by Docker. |
+| `GET /stream?path=...&auth=...` | Public player shell | Required path, optional share token. | Player HTML; its /file requests enforce authorization. |
+| `GET /assets/...`, `GET /static/...`, `GET /third-party/...` | Public | Asset path. | Frontend/player assets, not drive payloads. |
+
+Effective max_file_size is the configured logical-file/staging limit and does
+not require Premium. Status includes telegram_ready, demo, max_file_size,
+staging_budget_bytes, metadata_revision, backup, clients, restart_required and
+admission_paused.
+
+With `DEMO_MODE=true`, restricted visitor requests that mutate `/api/v1/settings`
+or its subroutes, `/api/v1/replica` or its subroutes, and `POST /api/v1/backup`
+return `403` with `code: "DEMO_MODE_READ_ONLY"`. This includes connection refresh
+and Premium login/cancellation. `GET /api/v1/backup/recovery-key` and
+`GET /api/v1/replica/key` return the same denial to prevent secret export.
+Status/settings reads and the secret-free replica report remain available under
+normal authentication. The status field `demo` identifies a synthetic test
+runtime; it is separate from the deployment's `demo_mode` flag. Authenticated
+full-access demo sessions can use management and key exports normally.
+
+`GET /api/config` includes `demo_read_only` and `demo_admin`, computed from the
+current signed cookie. `GET /api/v1/session` includes these permission fields
+and `demo_mode` during demo mode, alongside `authenticated`. Both responses
+use `Cache-Control: no-store` so changing access cannot reuse another session's
+permissions. No response contains either password or password hash.
+
+Demo Files has the reserved catalog ID `tgdrive-demo-files`. Restricted writes
+to it, its descendants, or ancestors whose move/delete would affect it return
+`403 DEMO_FILES_READ_ONLY`. Upload destinations, share changes and durable job
+retry/cancel are checked before side effects; catalog writes also check ancestry
+under the store transaction. Restricted jobs keep their policy in the durable
+context as `demo_read_only: true`, reapplied on resume only while demo mode is
+enabled. Full-access retries can explicitly authorize privileged work.
+
+The compatibility-named recovery object includes state:protected|pending|error,
+backend:mongodb, metadata_revision, protected_revision, last_success_at,
+backup_key_configured and optional error/backup_error. Here protected means the
+catalog is committed in MongoDB. An independent safety-copy failure does not
+make an acknowledged catalog write uncommitted.
+
+POST /api/v1/backup explicitly takes a complete encrypted snapshot. Ordinary
+uploads do not call or wait for it. The recovery-key download is owner-only
+and absent from ordinary status/configuration.
+
+Archive restore accepts at most 1 GiB of ciphertext and 1 GiB expanded data.
+It validates the archive before pausing work, then rechecks the destination
+inside the restore transaction. Existing files, jobs, shares or saved settings
+changes reject replacement with `409 RESTORE_DESTINATION_NOT_EMPTY`. Browser
+sessions are revoked after success. A failure after pausing returns
+`503 DATABASE_RESTORE_UNCONFIRMED` and requires a service restart; the website
+keeps those instructions visible. This route is available in owner recovery
+mode and is excluded from the ordinary 64 KiB JSON-body limit. See
+[website recovery steps](backup-recovery.md#restore-a-lost-database-from-telegram).
+
+The Storage & Backups page additionally accounts for unfinished transfers. Queued/active
+uploads remain pending; failed/missing-original uploads need attention.
+Client health distinguishes configured accounts from healthy started accounts.
+
+</details>
+
+### Independent channel backup and recovery
+
+<details>
+<summary>Channel copy, recovery and activation endpoints</summary>
+
+This optional feature is configured by the owner through Storage & Backups rather
+than by placing bot tokens in URLs. See the [operator guide](backup-recovery.md#set-up-an-independent-backup-channel)
+for channel preparation, private permissions, key custody and recovery drills.
+
+| Route | Request | Result |
+| --- | --- | --- |
+| `GET /api/v1/replica` | None | Current configuration state, phase, source/backup channel IDs, catalog/protected revisions, file/part/byte progress, retry guidance, bounded activity and optional recovery candidate. No bot tokens or key. |
+| `POST /api/v1/replica/configure` | `channel_id`, write-only `bot_token`, `independent_accounts: true` | Verifies private distinct channels and a separate backup bot, saves configuration, schedules initial copying. Requires an existing catalog. |
+| `POST /api/v1/replica/action` | `action`: `sync`, `pause`, `resume`, `retry` or `disable` | Durable operation control. Resume also re-enables configured protection. |
+| `GET /api/v1/replica/key` | None | Private no-store attachment `tgdrive-channel-recovery-key.json`: key plus known restore-point message IDs. Save outside Telegram/server. |
+| `GET /api/v1/replica/report` | None | Secret-free owner status/report attachment; file/channel names and IDs may still be private. |
+| `POST /api/v1/replica/recover` | `source_channel`, write-only `bot_token`, 64-hex `key`, optional positive `message_id` | Downloads/authenticates a surviving recovery capsule and records a candidate for inspection. |
+| `POST /api/v1/replica/recover` | `target_channel`, write-only `target_bot_token`, matching typed `confirm_channel`, optional `catalog_only: true` | Uses the inspected server-side candidate to copy into an empty private destination, or verify an existing surviving catalog without copying files. |
+| `POST /api/v1/replica/recover` | `activate: true`, `confirm_channel` matching the pending candidate's destination channel ID | Explicitly activates a completed candidate; service restart is required. Missing/wrong confirmation or incomplete candidates cannot be activated. |
+
+All routes require owner authentication and normal same-origin mutation checks.
+A recovery-only startup exposes the authenticated recovery surface when the local
+catalog cannot open; it must not enable ordinary file mutations against a missing
+catalog. Channel IDs are negative integers; source and copy destinations must be
+different, except an explicitly requested database-only restore.
+
+The independent channel capsule `tgdrive-replica.tgdb` is an authenticated
+AES-256-GCM document bounded to 64 MiB. It contains paired portable catalogs,
+recovery credentials, the managed connection document and all three saved policy
+records (performance, uploads and bot destination). Missing settings, a corrupt
+key, malformed paired catalogs or missing file parts prevents confirmation.
+Original payload bytes and the complete MongoDB archive are stored separately.
+Ordinary encrypted MongoDB backups and independent-channel
+capsules use different formats and recovery keys.
+
+The local `DATA_DIR/channel-backup.sqlite3` journal persists random operation IDs,
+confirmed message mappings, configuration and recovery state. Preserve the full
+persistent data directory through restarts. Status is confirmed-part progress,
+not speculative queued bytes. Old remote copied messages and capsules are
+retained; changing the configured destination is not a command to erase them.
+
+</details>
+
+### Owner connection management
+
+<details>
+<summary>Connections, Refresh, saving and Premium login</summary>
+
+Owner cookie and mutation-origin checks apply. Secrets are write-only body fields.
+These routes cannot edit the storage channel or owner credentials.
+
+| Method and route | Request | Success |
+| --- | --- | --- |
+| GET /api/v1/settings | None | Redacted saved configuration, actual running clients, statistics and recovery state. |
+| GET /api/v1/settings/uploads | None | Uploads per bot, connected bot count and available configured bot slots. Owner only; no-store. |
+| PATCH /api/v1/settings/uploads | uploads_per_bot: integer 1–4 | Save in MongoDB and apply immediately to new Telegram leases. Existing transfers finish; provider waits are preserved. |
+| PATCH /api/v1/settings | expected_revision, optional api_id/api_hash/clients | Complete redacted snapshot after isolated verification and atomic save. |
+| POST /api/v1/settings/refresh | Empty object | 202 settings snapshot; schedules bounded background saved-credential/channel-permission checks and name refreshes for enabled clients without changing configuration revision. |
+| POST /api/v1/settings/premium-login/start | expected_revision, phone, label | challenge_id, stage:code and expires_in_seconds. |
+| POST /api/v1/settings/premium-login/verify | challenge_id and exactly one code/password for the current stage | stage:password with the challenge, or stage:complete plus settings snapshot. |
+| DELETE /api/v1/settings/premium-login/{challenge_id} | No body | status:cancelled; discards an owned unfinished challenge. |
+
+**Snapshots.** Settings include `revision`, `applied_revision`, `restart_required`,
+`admission_paused`, `application_mode:restart`, API credential presence,
+`storage_channel`, `clients`, `active_clients`, `stats` and `recovery`. Client rows
+include opaque ID, label, bot/user kind, enabled/configured/connected/healthy/
+Premium state, active leases and sanitized errors. `active_clients` describes
+the applied pool, including accounts removed from the saved candidate.
+
+`connection_check` is queued/checking/waiting/passed/failed, with optional error
+and Unix `connection_checked_at`/`connection_retry_at`. Cached `display_name`,
+`username`, `identity_refreshing` and `identity_retry_at` are read-only; labels
+remain the fallback. Reading settings never calls Telegram. Refresh probes saved
+enabled accounts in isolated sessions, including failed starters; it does not
+apply pending credentials or reconnect the pool. Probe and runtime health differ.
+Account errors include `TELEGRAM_CREDENTIALS_REVOKED`, `TELEGRAM_CHANNEL_ACCESS`
+and `TELEGRAM_ACCOUNT_REMOVED`; operation failures return `503` with detail/code.
+Owner status exposes `telegram_issues`.
+
+**Saving.** `clients` is the full desired list: retain an existing `id`, omit its
+`credential` to keep the secret, and omit removed rows. New rows omit `id` and
+require a credential. Omitting `clients` or `api_hash` preserves that whole value;
+an empty credential is not a keep-secret marker.
+
+Limits: 50 managed rows, at least one enabled bot, trimmed visible labels 1-80
+characters, credentials 1-8192 characters without whitespace, API ID 1-2147483647,
+and a 32-hex API hash. Enabled accounts undergo identity/Premium/permission
+preflight; disabled rows need not authenticate. Duplicate identities fail.
+Management capacity does not imply linear Telegram throughput.
+
+Membership/API changes need settled jobs/receipts, valid database ownership and
+a committed catalog. Same-account credential repair may preserve pending work
+if API credentials, client IDs/order, kinds and enabled states stay unchanged;
+each replacement must verify its original identity. A narrow error-state repair
+requires exactly matching confirmed/protected/current revisions and no recovery
+conflict. Failed preflight never partially saves.
+
+Errors: `409 SETTINGS_CONFLICT` for revision races, `409 SETTINGS_BUSY` for blocked
+changes, `422 SETTINGS_INVALID`, `503 SETTINGS_PREFLIGHT_FAILED`. A successful
+save pauses new catalog/upload mutations with `409 SETTINGS_RESTART_REQUIRED`
+until restart. Reads, authentication, cancellation and management remain available
+unless recovery separately blocks them. Do not replay a stale full client list.
+
+**Premium login.** Owner-bound in-memory challenges last five minutes, at most
+two per service. Limits are six starts/15 minutes, one start/phone/minute and five
+verification attempts; FloodWait supplies `Retry-After`. Foreign/expired challenges
+return `410 TELEGRAM_LOGIN_EXPIRED`. Retry invalid codes/passwords while the
+challenge lives; consumed/failed-save challenges need a new login. Non-Premium
+accounts fail. Codes/passwords are not saved, and StringSessions never reach the
+browser. Cancellation, expiry and failed post-auth save revoke unsaved
+authorizations; restart loses challenges.
+
+`stats` includes active/trashed file counts and bytes, folders excluding root,
+active/queued/failed jobs, staging budget/reservations and nullable free disk.
+These are catalog/resource counts, not Telegram quota or proof of readable files.
+
+</details>
+
+### Listing and metadata
+
+<details>
+<summary>Folder listings, name search and single-item actions</summary>
+
+| Method and route | Access | Body/query | Success |
+| --- | --- | --- | --- |
+| `POST /api/getDirectory` | Owner or valid folder share | `{"path":"/","auth":null}` | `{"status":"ok","data":<directory>,"auth_home_path":null}`. |
+| `GET /api/v1/nodes` | Owner | `parent_id=/&offset=0&limit=100&sort=name` | `{"items":[...],"total":42,"offset":0}`. |
+| `GET /api/v1/trash` | Owner only | `q=report` (optional, up to 255 characters) | `{"data":{"contents":{...}}}`; actionable top-level Trash items include `parent_names` for their source folder; never includes live files. |
+| `GET /api/v1/search` | Owner only | `q=report&offset=0&limit=100&sort=name&order=asc` | `{"items":[...],"query":"report","has_more":false,"next_offset":null}`. |
+| `POST /api/createNewFolder` | Owner | `{"path":"/","name":"Photos"}` | `{"status":"ok"}`; refresh listing for new ID. |
+| `POST /api/renameFileFolder` | Owner | `{"path":"/<id>","name":"New name"}` | `{"status":"ok"}`. |
+| `POST /api/trashFileFolder` | Owner | `{"path":"/<id>","trash":true}` | Trash; false restores. Prefer v1 bulk for exposure confirmation. |
+| `POST /api/deleteFileFolder` | Owner | `{"path":"/<id>"}` | `202 {"status":"ok","id":"<deletion-job-id>"}`; top-level Trash entry required. |
+
+Special getDirectory paths are `/trash` (owner-only top-level Trash),
+`/search_<query>` (owner-only search), and `/share_<folder-id-path>` with `auth`
+(shared folder). Shared requests resolve the final ID's current location and
+check capability scope. `auth_home_path` supplies the shared-navigation boundary.
+
+- Listed nodes contain id, name, type (folder/file), path, upload_date and size.
+- File rows also include part_count (1 for ordinary storage, more for logical parts);
+  they do not expose part message IDs or checksums.
+- Folder size is stored as zero; listing records do not expose a trashed flag.
+- Internal file lookup includes remote metadata.
+- Directories have `contents`, an object keyed by child ID.
+- Listings do not recursively transfer payloads.
+
+For v1 listing, limit is 1–500, offset is nonnegative, and sort is name/size/type/date.
+Folders come first, values ascend, ID breaks ties. It currently materializes
+and sorts a folder before slicing; this is not database cursor pagination.
+
+- Search trims/NFC-normalizes q (1–255 characters), uses literal Unicode-casefolded
+  partial name matching and excludes every trashed descendant.
+- Percent signs, underscores and quotes do not become wildcard/query operators.
+- Results include files and folders across the owner's active drive, with parent_names
+  containing human-readable ancestor names; path remains the opaque ID ancestry.
+- Public share tokens cannot authorize global search.
+- Limit is 1–200 (default 100), offset is nonnegative, and sort is name/date/size.
+- Optional `order=asc|desc` sets the primary direction for every sort field. Omitting
+  it preserves the original defaults: name ascending, date-added newest first, size
+  largest first. Folders always come first; equal primary values use ascending
+  casefolded name and ID ties.
+- The catalog sorts the full matching snapshot before offset/limit
+  pagination, so changing direction affects the global result order.
+- Search pages have no computed total count.
+- The compatibility /search_ directory path is bounded to 500 results; use v1 paging for
+  a complete matching listing.
+
+</details>
+
+### Atomic folder preparation
+
+<details>
+<summary>Folder-tree request, response and retry rules</summary>
+
+`POST /api/v1/folders/tree` is owner-only. It creates a fresh upload root and
+its relative descendants atomically, before any file receipts are started:
+
+~~~json
+{
+  "destination": "/<destination-id>",
+  "root_name": "Project",
+  "folders": [["alpha"], ["beta"], ["beta", "deep"]],
+  "client_request_id": "<persisted-16-to-128-character-safe-id>"
+}
+~~~
+
+- The request ID accepts letters, digits, underscore and hyphen; the web client uses a
+  UUID.
+- Persist it before dispatch and reuse it with the same payload on an uncertain
+  response. `folders` excludes the root, includes every ancestor, has at most 999
+  entries, and each entry has 1–63 relative name segments.
+- The root makes at most 1,000 folders.
+- The normal 64 KiB JSON/body guard and the store's 128-level/item limits also apply.
+- Extra fields are rejected; name normalization is NFC with normalized sibling collision
+  checks.
+
+A `201` response contains `root:<DriveItem>` and
+`folders:{"":"/<new-root-id>","alpha":"/<new-root-id>/<alpha-id>",...}`.
+The root's `path` remains its parent path; map values are full opaque paths.
+Map keys exclude the root name and use NFC names separated by /. The root uses
+keep-both naming; descendants are strict. It never silently merges with or
+overwrites an existing sibling.
+
+Same request ID/payload returns the same prepared IDs after restart. Changed
+payload or a prepared hierarchy that was moved, renamed, trashed, deleted or
+otherwise changed returns `409`, `code:FOLDER_TREE_CONFLICT`, rather than
+creating a replacement. Adding file contents to the intact prepared folders
+does not invalidate replay.
+
+- The API prepares metadata only.
+- A successful tree request does not queue file bytes, promise all subsequent file
+  uploads succeed, or discover local empty directories.
+- The web picker separately limits the selection to 1,000 files, skips empty/over-cap
+  files, validates root-prefixed file paths, and then queues each accepted file against
+  its mapped destination.
+- A cancelled/lost response can leave an empty prepared tree; retry the original
+  request, not a new ID.
+- The current web dialog holds its preparation plan/key in memory; closing or reloading
+  before queuing does not restore that dialog.
+- Selecting again creates a new preparation.
+- Queued per-file batch metadata is persisted separately.
+- Destination ancestor shares apply as with ordinary uploads.
+
+</details>
+
+### Move and bulk actions
+
+<details>
+<summary>Request examples, conflicts and partial remote effects</summary>
+
+`POST /api/v1/nodes/move`:
+
+~~~json
+{
+  "paths": ["/<folder-id>/<file-id>"],
+  "destination": "/<destination-folder-id>",
+  "conflict": "keep_both",
+  "allow_public_exposure": false
+}
+~~~
+
+Conflict is `keep_both` or `skip`; there is no overwrite option. Results contain
+original path, status (moved/skipped), and item where available. Cycles and moves
+into oneself are rejected. The destination must be a visible folder.
+
+`POST /api/v1/nodes/bulk`:
+
+~~~json
+{
+  "paths": ["/<item-id>"],
+  "action": "trash",
+  "allow_public_exposure": false
+}
+~~~
+
+Action is trash/restore/delete. Both routes accept 1–1000 paths and collapse
+duplicate/overlapping selections. Trash/restore returns `200` with
+`results: [{path,status}]`, where status is trashed/restored. Delete returns
+`202` with result job IDs and status deleting. Poll retained jobs for completion.
+Acceptance is not database-removal confirmation. Delete requires Trash entries;
+permanent-deletion jobs cannot be cancelled.
+
+Move into a shared destination, or restore into a shared parent, can return
+`409` with code `PUBLIC_EXPOSURE_CONFIRMATION_REQUIRED` and a human-readable
+detail. After informed owner confirmation, repeat with
+`allow_public_exposure:true`. Destination folder shares can grant inherited access.
+
+Move, trash and restore run in one MongoDB transaction per request. A later
+invalid item or database failure rolls back earlier changes, revision increments
+and share revocations. Public-exposure checks belong to that same transaction.
+Skipped move conflicts remain explicit successful results.
+
+Permanent deletion validates the whole selection before scheduling, then uses
+independently durable catalog-removal intents. Each job removes its database
+subtree and shares atomically, retaining original Telegram messages for every
+file age. Completed intents no longer retain message references. This is TGDrive's
+catalog-only deletion policy; see
+[permanent deletion](usage.md#why-permanent-deletion-keeps-the-telegram-files).
+Retain/poll each accepted job and refresh actual state after an interrupted
+response; selected items do not complete atomically as one batch. Retried deletion jobs also use catalog-only removal. The single-item
+routes do not provide the `/api/v1` exposure-confirmation flow.
+
+</details>
+
+### Performance, cache inventory and preparation
+
+<details>
+<summary>Performance preferences, telemetry and preload endpoints</summary>
+
+These are owner-session endpoints; public shares do not grant operator access.
+Responses expose bounded operational state rather than credentials or raw
+Telegram authorization references. Mutations use the usual same-origin checks.
+
+| Method and route | Purpose |
+| --- | --- |
+| `GET /api/v1/settings/performance` | Saved live performance preferences, revision, read-only built-in defaults, and configuration guide link. |
+| `PATCH /api/v1/settings/performance` | Partial lowercase preferences, with returned revision in `If-Match`; persist and apply to new work. |
+| `GET /api/v1/performance` | Account activity, bounded live queues/history, request pacing/cooldowns and cache diagnostics. |
+| `GET /api/v1/performance/history?start=UNIX&end=UNIX` | Owner-only measured history within the last 31 days and persisted lifetime traffic totals; at most 360 bins. |
+| `GET /api/v1/preloads` | Owner cache/preparation inventory, current coverage, and bounded job state. |
+| `POST /api/v1/preloads` | `{"path":"/<file-id>"}`; prepare an authorized file within effective capacity. |
+| `POST /api/v1/preloads/clear` | `{"file_id":"<inventory-id>"}` evicts one file; `{}` clears cached bytes. |
+| `POST /api/v1/preloads/{id}/cancel` | Cancel the named preparation, preserving work other subscribers still need. |
+
+Preference fields use the lowercase names corresponding to the environment
+table, such as `cache_disk_bytes`, `telegram_request_limit` and `auto_preload`.
+Unknown fields are rejected. Keep and send the returned revision when editing
+from multiple tabs; a stale update returns a conflict rather than silently
+overwriting another edit.
+
+The same performance endpoint saves upload-storage fields: `max_file_size`,
+`staging_budget_bytes` and `min_free_bytes`. File size and temporary budget are
+integers from 1 byte through 2 TiB; a save requires the budget to cover the file
+maximum and all current upload reservations. Saving an upload-storage change
+also requires a free-space reserve of at least 64 MiB. These fields are separate
+from `/api/v1/settings/uploads`, which only changes uploads per bot. See the
+[upload-storage controls](configuration.md#upload-size-and-available-disk-space).
+
+Inventory reports current ready-byte coverage with half-open intervals
+`[start, end)`, including observed ordinary downloads. A ready preparation is
+not an indefinite pin. The effective memory limit can be below configuration;
+current cache coverage, active reservations and integrity overhead decide
+whether a preparation fits.
+
+Queue wait estimates are nullable until recent duration samples exist. They
+are explicitly estimates, can change with cooldowns or connection changes,
+and do not promise completion time. Queue snapshots are bounded rather than a
+permanent telemetry database. Public request-specific queue status must not
+expose unrelated visitors' identifiers.
+
+The performance snapshot's `traffic` object counts HTTP body bytes and request
+activity on `/file` and resumable-upload endpoints. Sent/received counters
+include cached file responses and receipt protocol bodies, and exclude settings
+polling/assets. Directional account request counters describe Telegram origin
+traffic separately. Both histories are process-local and reset on restart;
+derived rates are differences between measured samples.
+The application samples both histories every three seconds without dashboard
+polling. Histories are capped at 120 entries and five minutes, and reset after a
+gap longer than 30 seconds or a backward clock jump. `traffic` exposes nullable
+`download_bytes_per_second` and `upload_bytes_per_second`; an initial missing
+baseline is not a measured zero. `server.process_rss_bytes` reports current Linux
+process resident memory when available; `process_peak_rss_bytes` remains a peak.
+`server.cpu.percent` is nullable current cgroup CPU utilization, normalized to
+available cores/quota, or labelled host busy CPU when cgroup counters are unavailable.
+`server.network` exposes the selected default interface, monitor-session
+`received_bytes`/`sent_bytes`, and nullable per-second rates. These include URL
+imports and Telegram traffic that are outside the narrower `traffic` HTTP counters.
+Linux interface counters include protocol overhead; they are not per-file accounting.
+`server.history` retains measured timestamped CPU percentage/scope, current cgroup
+memory/limit, interface receive/send rates and interface name. It follows the same
+three-second/five-minute bounds. Unknown readings are null; an unlimited cgroup
+memory limit is null rather than zero. The dashboard splits plots at missing
+samples or measurement-scope changes and supports keyboard/touch sample inspection.
+
+The historical endpoint is separate from those live process histories. It validates
+finite Unix-second `start < end`, a past interval no older/wider than 31 days,
+and returns `422` for invalid bounds or a redacted retryable `503` if storage is
+unavailable. It returns actual minute-aligned boundary intervals: `start`, `end`,
+`bucket_seconds`, `retention_seconds`, `earliest_at`, `tracked_since`,
+`last_updated`, `available`, `samples`, and `totals`. Samples include `end_at`
+and per-metric `coverage_seconds`. Rates/gauges are weighted by valid observed
+seconds; null gaps are not counted as zero. Mixed interfaces or CPU scopes do
+not become a false continuous series. Long ranges are downsampled, so a bin's
+average is not its peak. The UI keeps Now readings separate from interval averages.
+
+Lifetime `totals` keys are `network_received_bytes`, `network_sent_bytes`,
+`http_upload_bytes`, `http_download_bytes`, `http_requests`, `http_errors`,
+`telegram_upload_bytes`, and `telegram_download_bytes`. Unobserved sources are
+null. These overlapping accounting layers must not be summed together. Totals
+survive process restarts and 31-day chart pruning, but only describe activity
+since `tracked_since`; no pre-installation history can be recovered.
+Laptop and hosted deployments use MongoDB `telemetry_minutes`/`telemetry_state`. Minute checkpoints and clean shutdown persist
+state; an abrupt crash may lose the latest uncheckpointed statistics. Telemetry
+is excluded from encrypted catalog backups and never gates file service.
+
+The preparation queue and ordinary media queues have separate bounds.
+Cancelling/clearing a preparation leaves originals intact and does not abort
+shared work belonging to other authorized subscribers. See
+[cache behavior](performance.md#prepare-a-file-before-sharing).
+
+</details>
+
+### Resumable browser receipts
+
+<details>
+<summary>Chunk upload protocol and recovery rules</summary>
+
+All receipt routes are owner-only. See [transfers](architecture.md#transfer-pipeline) for persistence
+and reconciliation boundaries. This is a TGDrive protocol, not tus compliance.
+
+| Route | Request | Success |
+| --- | --- | --- |
+| `POST /api/v1/uploads` | `{"name":"example.bin","parent_id":"/","total_size":8388647}` | `201` receipt. |
+| `GET /api/v1/uploads/{upload_id}` | None | Full current receipt including chunk checksums. |
+| `HEAD /api/v1/uploads/{upload_id}` | None | Upload-Offset and Upload-Length headers. |
+| `PATCH /api/v1/uploads/{upload_id}` | Raw bytes, Content-Type application/octet-stream, Upload-Offset header. | `204` and acknowledged new Upload-Offset. |
+| `POST /api/v1/uploads/{upload_id}/complete` | `{}` | `202 {"id":"<job-id>","job":{...}}`. |
+| `POST /api/v1/uploads/{upload_id}/cancel` | `{}` | Updated receipt; queued work delegates to its job. |
+
+The receipt contains:
+
+~~~json
+{
+  "id": "<32-lowercase-hex-characters>",
+  "name": "example.bin",
+  "parent_id": "/",
+  "parent_node_id": "root",
+  "total_size": 8388647,
+  "offset": 8388608,
+  "checksums": [
+    {"offset": 0, "size": 8388608, "sha256": "<64-hex-digest>"}
+  ],
+  "chunk_size": 8388608,
+  "state": "receiving",
+  "expires_at": 1792100000.0
+}
+~~~
+
+parent_id is the current resolved hierarchy path; additive parent_node_id binds
+the stable folder identity. GET/HEAD, append and complete refresh the path after
+ancestor moves. New request paths must identify an existing visible mutable
+folder. A trashed/deleting/missing folder blocks receipt writes/completion while
+retaining acknowledged bytes for restore/cancel.
+
+Create checks the current logical-file limit, folder, staging budget and free disk.
+Folder uploads may also send `folder_upload: {id, name, root_path, created_at}`
+on creation. `id` is a stable 16–128 character URL-safe selection identity,
+`name` is at most 255 characters, `root_path` identifies the uploaded root, and
+`created_at` is finite nonnegative Unix seconds. The destination must belong to
+that root. The metadata follows the receipt into job polling and archived history;
+ordinary file selections and URL imports remain separate tasks.
+Send exactly chunk_size bytes except for a smaller final chunk. Empty/oversized
+chunks and offsets different from the server's are rejected. Wait for each
+acknowledgment. After a lost response, GET/HEAD the authoritative offset before
+retransmitting. The final chunk journal is verified against staged bytes.
+An offset mismatch returns HTTP `409` with code `UPLOAD_OFFSET_CHANGED`; clients
+may recheck the receipt and resume. Other `409` failures are not offset conflicts.
+The browser uses [bounded automatic retries](architecture.md#bounds-and-retries)
+for temporary failures after it knows the receipt ID; creation without a returned
+ID still requires manual retry.
+
+- Call complete only after offset equals total_size.
+- Repeated completion returns the existing retained job rather than creating another
+  file.
+- Then poll its job: a complete browser receipt is not yet a completed protected upload.
+- The job commits file metadata and durable transfer state in MongoDB, then reports
+  completed and releases staging.
+- State values include receiving/queued/cancelling/finished/cancelled.
+- Append refreshes receipt expiry; inactive receiving sessions expire after
+  UPLOAD_SESSION_TTL_SECONDS.
+
+A re-selected file must match the committed prefix's checksums. Bytes never
+received cannot yet be verified. There is no trust-this-checksum override.
+Already accepted receipts retain append eligibility after optional account loss.
+A persisted part plan retains dispatched sender identities; retry may still need
+the recorded sender restored even though a new file could use other bots.
+
+Typical receipt failures: `409` state/offset conflict, `410` expiry/history lost,
+`413` size, `415` content type, `422` chunk shape/fields, `429` active receipt
+capacity, `507` disk/staging budget. HTTP chunking is the browser receipt layer.
+After receipt, the server chooses one Telegram document or ordered file parts
+within the logical file limit. Full download and one byte range transparently
+reconstruct the selected logical interval.
+
+</details>
+
+### Previews and media
+
+<details>
+<summary>Preview descriptors, bounds and quality selection</summary>
+
+Owner cookie or scoped file/folder capability required; supply `path` and optional
+`auth` as for `/file`.
+
+| Route | Response |
+| --- | --- |
+| GET /api/v1/books | path, optional auth and entry. Without entry: book index with format, title and ordered entries. With entry: passive EPUB chapter JSON or raster page bytes. See [reader limits](reading.md#reader-limits). |
+| GET /api/v1/preview | name, size and kind:text/pdf/video/book/unsupported. Text includes text, language, truncated and preview_bytes; PDF includes an authorized local URL; unsupported includes a reason. |
+| GET /api/v1/media | original descriptor and variants list from the actual stored message. Each descriptor has id, label, is_original, size, mime_type, width, height and duration where applicable. |
+| GET /api/v1/thumbnail | TGDrive-generated JPEG cover when cached, otherwise a provider JPEG/PNG/WebP thumbnail, at most 128 KiB; optional `If-None-Match` can return `304`. |
+| GET /api/v1/file-status | Authorized `path`, opaque `request_id`, optional `auth`; request-specific queue estimate, logical size, phase and retry guidance, without listing other callers. |
+
+`file-status` returns `queue`, `size`, `phase`, `code` and `retry_after`. Phase is
+`checking_file`, `waiting_for_telegram`, `receiving`, `retry_wait`, `error`, or
+`null` when no current phase is known. The initial file check includes metadata
+waits even when there is no origin queue entry. Queue positions count operations
+and can change as download requests take turns; they are not a file/user order
+or a completion ETA.
+
+A queue-full failure records `retry_wait`, `code: TELEGRAM_QUEUE_FULL` and
+remaining `retry_after` seconds, matching the response's `503`/`Retry-After`
+guidance. A new GET with that request ID clears the previous failure. Other
+errors expose no private exception details. Status is bound to the authorized
+file, held in a bounded in-memory registry, and may be absent before the GET,
+after eviction or after restart. For overlapping GETs with the same ID, phase
+reflects the latest GET while the queue estimate aggregates that ID's operations.
+
+**Thumbnails:** authorize before and after asynchronous reads, including cache hits
+and `304`. Responses use `Cache-Control: private, no-cache`, `Vary: Cookie` and an
+ETag. The endpoint tries a generated cover, then a small provider thumbnail;
+multipart uses the first part. If unavailable, it can render a local cover from a
+complete server-cached original up to 128 MiB, within an eight-second repair
+deadline. It never fetches original Telegram payloads for the grid. Cached misses
+are reconsidered after new data arrives for that file; positive covers remain
+reusable. Repair rechecks authorization/source identity and leaves Telegram and
+the catalog unchanged.
+`204 No Content` means an optional thumbnail is unavailable and the client should
+keep its file icon. Missing originals and authorization failures retain their HTTP
+errors. Temporary thumbnail failures return `503 THUMBNAIL_BUSY`, `Retry-After: 5`. See [generation limits](thumbnails.md).
+
+**Thumbnail rebuild:** owner-only `GET /api/v1/settings/thumbnails/rebuild`
+returns the latest run. `POST` to that route requires `{"confirmed": true}` and
+returns **202** immediately, reusing an active run rather than starting duplicates.
+`POST /api/v1/settings/thumbnails/rebuild/cancel` stops it. Public demo sessions
+can read status but cannot start/cancel management work. Snapshots include `status`,
+`phase`, `total`, `processed`, `generated`, `skipped`, `failed`, `source_bytes`,
+current filename/read bytes and up to five recent issues. Byte counts include
+cache reads, not measured network traffic. See [rebuild policy](thumbnails.md#rebuild-existing-thumbnails).
+
+**Text:** allowlisted formats return at most 256 KiB with a truncation marker.
+HTML/XML stay text. UTF-8 (optional BOM) and BOM-marked UTF-16 are supported;
+invalid/binary content falls back to download. SVG uses a passive image in the UI;
+the descriptor may expose its XML. Ambiguous `.ts`/`.mts` require repeated MPEG
+packet evidence to become video; valid TypeScript and `.cts` remain source text.
+The source-byte cap does not bound all internal Telegram transfer bytes.
+
+Book raster pages are checked against the [reader dimension limits](reading.md#reader-limits)
+before delivery; an oversized or malformed image returns a preview error without
+changing its original download.
+
+**PDF:** at most 256 MiB source, lazy reads with no cumulative session cap.
+At most two reader requests run together; HTTP ranges are up to 1 MiB. Active
+response buffers share a 64 MiB target; a larger request runs alone, bounded by
+source size. Pending work holds bounded descriptors. Local PDF.js disables streaming and
+full-file prefetch; closing aborts requests. Normal authorization, range cache and
+multipart mapping apply, without automatic background preparation. These are
+preview limits, not total browser-memory guarantees. A failed/limited preview
+retains original download. See [readers](reading.md) for EPUB/CBZ/CBR contracts.
+
+**Representations:** `/file?quality=<opaque-descriptor-id>` chooses an actual
+message-bound variant; it never grants access. Unknown variants return `404`.
+Range/HEAD describe the selected representation. `download=1` always selects the
+original attachment, overriding `quality`. Arbitrary Telegram locations are rejected.
+
+Browser uploads remain byte-preserving documents (`force_file=True`). Telegram-native
+messages may offer real video variants/photo sizes; a photo's original means its
+best stored representation, not guaranteed camera bytes. No invented transcodes
+or resolutions are exposed. See [video behavior](usage.md#open-preview-and-download)
+and [viewer notices/source](../website/public/third-party/README.txt).
+
+</details>
+
+### Jobs
+
+<details>
+<summary>Progress, retry, cancellation and retention</summary>
+
+All routes below require the owner.
+
+| Route | Request | Success |
+| --- | --- | --- |
+| `GET /api/v1/jobs` | None | `{"jobs":[...]}`. |
+| `GET /api/v1/jobs/{job_id}` | None | One job. |
+| `POST /api/v1/jobs/{job_id}/cancel` | `{}` | Updated job; remote reconciliation may keep cancellation pending. |
+| `POST /api/v1/jobs/{job_id}/retry` | `{}` | Updated/restarted job; invalid transitions return `409`. |
+
+- A v1 job contains id/status/phase/current/total/error and
+  name/kind/destination/retry_at.
+- It also includes created_at, updated_at, started_at, finished_at, progress_updated_at
+  (Unix seconds), elapsed_seconds, speed_bytes_per_second and eta_seconds.
+- `queue` adds request-specific origin admission state and nullable wait estimates;
+  it is not a reserved start time or a multi-stage completion deadline.
+- The UI does not show an elapsed clock for wholly queued uploads.
+- Rate/ETA are nullable current-phase estimates, not total multi-stage completion
+  promises; paused/non-byte/deletion/stale progress has no invented rate.
+- Samples are phase-local and stale after 15 seconds without progress.
+- Job retry_at is the effective provider deadline for uploads or database-copy
+  publication; the private lineage_retry_at context survives restart.
+- A pre-send cancellation can wake a lineage wait.
+- Kinds include upload/remote/delete.
+- A URL import retains `remote` origin through local staging and Telegram
+  upload, including after a restart. A URL job is not a browser file receipt.
+- Statuses are queued, running, cancelling, completed, error, cancelled.
+- Phase gives detail such as uploading, finalizing, retry_wait, waiting_for_telegram or
+  cleanup_pending; clients must tolerate new phases.
+- The compatibility phase backup_pending is short MongoDB commit finalization, not a
+  wait for an encrypted Telegram safety copy.
+- The job retains its stable operation identity across an interrupted commit/journal
+  handoff.
+
+Live job records are limited by retention/capacity. Unresolved send/cleanup
+effects are protected from ordinary eviction. Do not treat this as a permanent
+audit log. Retry retains operation identities. See [transfers](architecture.md#transfer-pipeline).
+
+Live job snapshots include `telegram_parts: {total, stored}`. `stored` counts
+confirmed messages; byte progress includes in-flight uploads. Sender identities
+and the recovery journal remain private.
+
+</details>
+
+### Transfer history
+
+<details>
+<summary>Owner-only task pages, filters and indexed cursors</summary>
+
+The Transfers UI uses `POST /api/v1/transfers/history/tasks`:
+
+```json
+{"status":"finished","page":1,"limit":20,"q":""}
+```
+
+Owner-only `DELETE /api/v1/transfers/history` with JSON
+`{"exclude_folders":[]}` clears completed/error/cancelled history across every
+page and search. It returns `{"cleared":N}` (individual server records, not
+folder task count) and `Cache-Control: no-store`. `exclude_folders` accepts up
+to 2,000 folder selection IDs for browser work still waiting to reach the server.
+Queued/running jobs and their folder members are always kept. Archived summaries
+are deleted; terminal live jobs are hidden without removing recovery contexts.
+Deletion jobs and stored files are unaffected. The action is safe to repeat;
+already cleared records are not counted again. Retrying/resuming a hidden job
+makes it visible again. Live job polling includes `history_cleared:true` so
+clients can settle progress and dismiss finished rows. Existing backups may
+still contain older history.
+
+The response includes `jobs`, `page`, `page_size`, `total_tasks`, `total_pages`,
+`has_more`, `offset` and `next_offset`. `jobs` contains every member of each
+selected task, so its row count can exceed `limit`. Only explicit folder uploads
+group together; ordinary files and URL imports each count once. Grouping, status
+and search matching precede pagination. Status precedence is running, queued,
+failed, then cancelled or entirely successful. Matching a folder name or one of
+its files returns the whole task. A page beyond the end clamps to the last page.
+
+| Body field | Value |
+| --- | --- |
+| `status` | Same statuses as the cursor API below; default `all` |
+| `page`, `limit` | Page starts at 1; limit 1–200, default 20 |
+| `q` | Normalized case-insensitive substring, at most 255 characters |
+| `offset` | Optional nonnegative task offset; overrides page slicing for browser-only finished tasks; callers handle page clamping |
+| `exclude_folders` | Up to 2,000 selection IDs omitted from server task totals/results while the browser owns the remaining folder work |
+
+Grouping uses saved folder-selection metadata. This owner-only request allows up
+to 256 KiB of JSON. Exact task counts scan archive summaries in bounded
+batches; see [history storage](architecture.md#finished-history).
+
+`GET /api/v1/transfers/history?page=1&limit=20` also returns numbered task pages,
+without browser exclusions. Supplying a page and cursor together is invalid.
+Omitting `page` selects the indexed cursor protocol:
+
+`GET /api/v1/transfers/history` accepts:
+
+| Query | Value |
+| --- | --- |
+| `status` | `all` (default), `queued`, `running`, `finished`, `completed`, `error`, `cancelled`; finished combines completed/error/cancelled |
+| `limit` | 1–200; default 50 |
+| `q` | Optional file-name substring, up to 255 characters; Unicode-normalized case-insensitive search across live and archived transfers before pagination |
+| `before` and `before_id` | Both cursor values from the previous page, or neither |
+
+The response contains `jobs`, `has_more`, `next_before` and `next_before_id`.
+Rows use public job fields plus `retained`: whether the live job still exists.
+`running` includes cancelling work; deletion jobs are excluded.
+
+Pages sort by creation time and ID descending. Live progress replaces duplicate
+archived IDs. Reading old history never restores a job to the active queue.
+The response requires owner authentication and uses `Cache-Control: no-store`.
+
+Resolved jobs evicted from the live registry become compact summaries. MongoDB
+keeps these in archived `jobs` documents, without the private recovery context;
+startup excludes them from live registry loading. These summaries are included
+in complete encrypted database backups. They have no automatic history TTL;
+**Clear history** removes them manually.
+Existing records are visible; history already deleted before this feature
+cannot be reconstructed.
+
+The floating panel's **Clear finished** only dismisses browser display rows.
+Dismissals survive reloads in the same browser; open tabs merge saved dismissals
+before polling/writing, with independent per-job records so simultaneous clears
+cannot replace another tab's dismissals. Server
+history and original files remain available. Browser-only queued work is
+not a durable server history record until a job exists.
+The floating panel displays this browser's uploads and URL imports; global history
+continues to show server jobs initiated on other devices.
+
+Owner-only `POST /api/v1/transfers/location` accepts `transfer_id`, `destination` and `completed`. It resolves the current folder and exact saved item without mutation; missing/trashed items return `available:false`.
+
+</details>
+
+### Starred items
+
+<details>
+<summary>Owner stars and move/restore behavior</summary>
+
+| Route | Request | Response |
+| --- | --- | --- |
+| `GET /api/v1/starred?q=...` | Optional literal filename query | `{data:{contents:{<id>:<item>}}}` with current paths and parent names. |
+| `PATCH /api/v1/starred` | `{path:"/<id-path>",starred:true}` (strict boolean) | `{item:<updated item>}`; idempotent when already set. |
+
+Owner-only, no-store. Stars follow node moves/renames, hide with trashed subtrees
+and reappear after restore. Unstarring never deletes or moves the original.
+Snapshots preserve annotations; the drive root cannot be starred.
+
+</details>
+
+### Shares, downloads, and ranges
+
+<details>
+<summary>Share tokens and exact download/range behavior</summary>
+
+| Route | Access | Request | Success |
+| --- | --- | --- | --- |
+| `GET /api/v1/shares` | Owner | None | `{"shares":[...]}` includes active and expired entries, IDs, current path/name/type/size, folder_path/folder_label, created_at/expires_at, optional label and copyable. No bearer tokens. |
+| `POST /api/v1/shares` | Owner | `{"path":"/<id>","label":"Alex","expires_in_days":7}`; optional ISO `expires_at` overrides the days. | `201 {"auth":"<bearer-token>","id":"<share-id>","path":"...","expires_at":"<ISO-date>","label":"Alex"}`. Adds an independent link. |
+| `POST /api/v1/shares/link` | Owner | `{"share_id":"<share-id>"}` | Existing active link auth/path/type/node_id; no rotation. `409` if unrecoverable, `410` if expired/revoked. Path selection returns `409` when multiple links exist. No-store response. |
+| `PATCH /api/v1/shares` | Owner | `{"share_id":"<share-id>","label":"Alex","expires_at":"<future ISO-date>"}`; omitted fields stay unchanged; explicit null expiry means never. | Updated link metadata; changes only this link. |
+| `POST /api/v1/download-links` | Owner | `{"path":"/<id>"}` | Signed attachment `url`, canonical `path`, and `expires_at`; reuse an active copyable file share labelled `Download link` or create one expiring in one day. Other recipient links are left alone. Visible in Shared Links; no-store response. |
+| `DELETE /api/v1/shares` | Owner | `{"share_id":"<share-id>"}` | `{"status":"ok"}`. Revokes one link. Alternate `{"path":"/<id>"}` revokes all direct links for that node. |
+| `POST /api/getFolderShareAuth` | Owner | `{"path":"/<folder-id>"}` | Alternate creation: status and auth. |
+| `POST /api/getFileShareAuth` | Owner | `{"path":"/<file-id>"}` | Same, for a file. |
+| `GET /file`, `HEAD /file` | Owner or scoped capability | Required path, optional auth/Range; quality selects a discovered preview, preview=1 marks a preview (including the supported PDF path and original media playback), download=1 forces the original attachment. | Bytes/headers or access/not-found error. |
+
+Share expiry accepts 1–3650 days (default 7), null for no expiry, or a future
+ISO `expires_at`. Labels are optional, at most 80 characters, and cannot contain
+control characters. Labels are organizational, not recipient authentication.
+Each item permits up to 100 independent links; reaching the limit rejects the
+new link without evicting existing ones. Link creation also appends.
+New capabilities are HMAC-SHA256
+of a random share ID under the persistent SESSION_SECRET, with the
+`tgdrive/share-link/v1` domain separator. Only the capability hash is stored
+in the catalog; the owner-only copy endpoint reconstructs it and checks that
+the stored hash matches. Listing never includes the token. Preserve SESSION_SECRET
+to retain re-copy capability across installations; changing it does not invalidate
+previously issued links, but those links then require their original URL or explicit
+creation of a separate new link. Store list_shares defaults to active entries
+for access/exposure checks; the owner listing opts into expired entries.
+The Shared Links page copies by share ID and never creates a replacement link.
+Unavailable/expired links keep a disabled copy control with an explanation. Labels
+are shown only when supplied; creation time and expiry distinguish separate rows.
+Portable backup schema is 4, with optional share
+labels and `starred: true` on bookmarked nodes. Trash
+revokes subtree shares; explicit
+complete MongoDB restore revokes owner browser sessions and preserves share scope/expiry.
+
+File URL: `/file?path=<encoded-id-path>&auth=<encoded-token>`.
+Generated folder UI URL: `/?path=%2Fshare_<folder-id>&auth=<encoded-token>`.
+The UI creates links from the stable folder ID alone; nested shared browsing
+can use ID paths beneath that root.
+Authorization resolves stable final IDs after a move; inherited folder access
+depends on the new location.
+
+An owner-only file URL without `auth` needs the owner session cookie. Copying
+it into another browser or a download tool does not make it public. The owner's
+**Copy download link** action explicitly creates or reuses a share capability;
+a newly created link lasts one day, carries the `Download link` label and is
+visible/revocable in Shared Links. It does not reuse a separately labelled recipient link.
+
+When `auth` is supplied, it must be valid for the requested scope even if an
+owner cookie is also present. Warm caches do not bypass expiry or revocation.
+Active shared streams check access again before future blocks; already sent
+or browser-buffered bytes cannot be recalled.
+
+- Downloads support full `200` and a single `206` range: `bytes=0-1023`, `bytes=1024-`,
+  `bytes=-1024`.
+- Download managers may issue several separate single-range requests in parallel
+  or resume only missing intervals. Each response returns exactly its requested
+  bytes, including across Telegram document boundaries. Cache hits and shared
+  in-flight fills avoid duplicate Telegram payload reads where possible.
+- Valid ends beyond EOF are clamped.
+- Malformed/unsupported multiple ranges return `400`.
+- Unsatisfiable ranges return `416` with `Content-Range: bytes */<size>`.
+- HEAD has the corresponding headers and no body.
+- Conditional requests support `If-None-Match` and return `304` after access
+  checks. `If-Range` requires a matching strong ETag; a stale/weak tag or date
+  returns a full `200` response so the client can restart safely. A catalog-only
+  HEAD for a single-document file has a weak ETag; use the strong ETag from an
+  actual GET when resuming.
+- Read-ahead for downloads remains inside the requested range. A cold boundary
+  can still fetch an entire aligned Telegram block (up to 1 MiB). These requests
+  do not start unrelated background preloads; manual **Preload file** remains
+  an explicit whole-file operation.
+- Cold origin work uses bounded shared admission; cached delivery still uses
+  server bandwidth and requires valid access.
+- Active document types are attachments; selected images/audio/video may render inline.
+
+</details>
+
+### URL imports and transfer routes
+
+<details>
+<summary>Application endpoints and their limits</summary>
+
+All these POST routes are owner-only.
+
+| Route | JSON body | Result |
+| --- | --- | --- |
+| `/api/getFileInfoFromUrl` | `{"url":"https://example.org/file.bin"}` | status/data with file_name, file_size, content_type; size -1 means unknown. |
+| `/api/startFileDownloadFromUrl` | `{"url":"https://example.org/file.bin","path":"/","filename":null,"singleThreaded":false,"client_request_id":"<unique-safe-id>"}` | status/id. |
+| `/api/getTransferByRequest` | `{"client_request_id":"..."}` | status/id/data compatibility start snapshot. |
+| `/api/getTransferProgress` | `{"id":"<job-id>"}` | status/data base job snapshot. |
+| `/api/cancelUpload` | Either id or client_request_id, never both. | status/id/data cancellation snapshot. |
+
+`singleThreaded` defaults to `false` for adaptive parallel ranges with safe
+single-stream fallback. `true` forces one stream. Starting a URL import creates a
+job before contacting the source: authentication and destination errors remain
+HTTP errors, while DNS/response/size/storage checks run in that job. Its initial
+phase is `checking_source`. Temporary failures use `source_retry_wait`,
+`retry_at`, `source_attempt` and `source_max_attempts` for a visible automatic retry.
+Snapshots may include `download_mode` of `queued`,
+`warm`, `full` or `waiting_storage`; queued/waiting intake has no completion ETA.
+See [URL intake](performance.md#url-import-intake) for exact bounds.
+
+Optional `client_request_id` is 16–128 letters/digits/underscore/hyphen. Reusing
+it for a different URL, destination, filename or connection mode fails with `409`. This bounded compatibility mapping is **process memory**, not the
+restart-durable receipt ID protocol. Prefer job-ID APIs after job creation.
+
+`POST /api/upload` accepts multipart fields file and path, optionally
+client_request_id. It is owner-authenticated and bounded, but receives a whole
+multipart request rather than the durable offset/checksum receipt protocol.
+
+</details>
+
+### Errors and retry discipline
+
+<details>
+<summary>HTTP statuses and safe retry actions</summary>
+
+There is no universal versioned error envelope today. Drive/remote errors often
+have status/detail; HTTP/auth errors use detail; receipt errors add
+`code:"UPLOAD_ERROR"`. Exposure confirmation, prepared-tree conflicts and
+committed-upload cancellation have explicit codes
+(`PUBLIC_EXPOSURE_CONFIRMATION_REQUIRED`, `FOLDER_TREE_CONFLICT`, `BACKUP_PENDING`,
+`RECOVERY_REQUIRED`). Do not parse
+every error phrase as a stable enum.
+
+| Status | Meaning/action |
+| --- | --- |
+| 400 | Invalid path/range/action or blocked URL; correct input. |
+| 401 | Missing/expired owner session or wrong password; log in. |
+| 403 | Invalid/out-of-scope share or foreign-origin mutation. |
+| 404 | Missing node, job, receipt, or Telegram payload. |
+| 409 | Conflict/pending state/exposure confirmation; inspect current state. |
+| 410 | Receipt or retained history expired. |
+| 413 | Body/file/chunk too large. |
+| 415 | Wrong chunk content type. |
+| 422 | Schema, empty file, or chunk-shape error. |
+| 429 | Login throttling/receipt capacity; observe Retry-After where supplied. |
+| 502 | Remote-source/network/protocol failure. |
+| 503 | Runtime not ready or compatibility request capacity full. |
+| 507 | Insufficient staging budget/free space. |
+
+The shared browser API client has a 60-second deadline, including response-body
+reading, even when navigation supplies a cancellation signal. Resource-history
+and thumbnail controls use 15 seconds; channel status uses 20 seconds; connection
+saves, Premium verification and channel-copy actions allow 120 seconds. A client
+timeout does not prove that server work stopped.
+
+After a bulk timeout, refresh before replay. After a chunk timeout, read the
+server offset. After uncertain completion, reattach to the same receipt/job.
+For permanent deletion, retry its retained job rather than submitting another
+intent. Do not log cookies, share queries, or signed remote URLs.
+
+Implementation: [app.py](../tgdrive/web/app.py), [api_v1.py](../tgdrive/web/api_v1.py),
+[request schemas](../tgdrive/web/schemas.py),
+[frontend client](../website/src/shared/api.ts). Update schemas, client types, this
+reference and relevant tests together when a contract changes. Proposed routes
+belong in [the roadmap](roadmap.md), not in this implemented API reference.
+
+</details>
+
+## Security and privacy
+
+| Boundary | What to know |
+| --- | --- |
+| Owner access | One shared drive; demo mode optionally separates visitor and full-access passwords. No built-in MFA/passkeys, public signup, teams or tenant isolation. |
+| Shared Links | Anyone with a valid scoped link can read its contents |
+| Encryption | Database backups are encrypted; original files and local staging are not encrypted by TGDrive |
+| Original file safety | A database record cannot recreate a deleted Telegram file |
+| Previews | Uploaded HTML/code is not executed; no external Office service receives files |
+| Malware | TGDrive does not scan files for malware |
+| Secrets | Keep database URIs, bot tokens, sessions, keys and share links private |
+| Public access | Use HTTPS and a restricted/trusted reverse proxy |
+
+<details>
+<summary>Authentication, browser policy and data handling</summary>
+
+- **Sessions:** HttpOnly, SameSite=Strict cookies with Secure under HTTPS, signed
+  nonces and server-side token-hash tracking. Logout revokes the record; changing
+  the effective owner credential or `SESSION_SECRET` invalidates owner cookies
+  after restart. Shares use separate credentials. Recovery can roll access back;
+  [review credentials after restore](operations.md#https-and-private-configuration).
+  Credential rotation does not erase old session rows: restoring the old
+  credential and signing key can reactivate their still-unexpired cookies.
+  Use a fresh signing secret when earlier sessions must stay invalid.
+  Sessions have an absolute 24-hour default lifetime, with no separate idle
+  timeout. Sensitive settings and recovery-key export accept an active owner
+  session without a fresh password prompt.
+- **Requests:** mutations check Origin/Fetch Metadata; private routes authenticate
+  before body processing. JSON bodies are capped at 64 KiB, receipt PATCH at
+  8 MiB. Login allows five failures per client IP in five minutes and bounds
+  expensive password verification to one concurrent check. The throttle resets
+  after restart and does not stop distributed attempts. Add login rate limiting
+  at a public deployment's trusted proxy; there are no per-share traffic quotas.
+- **Shares:** hashed bearer credentials with scope, expiry and revocation. Folder
+  links include accessible descendants; Trash revokes subtree links. MongoDB
+  restore preserves scope/expiry and revokes owner sessions. Previously delivered
+  bytes cannot be withdrawn. Compatibility single-item mutations lack v1's public
+  exposure confirmation; direct callers must check sharing themselves.
+- **Browser:** local scripts/fonts/assets use CSP, nosniff, frame and referrer
+  restrictions. The trusted video decoder permits WASM compilation, blob workers/
+  media, inline styles and `data:` decoder connections; arbitrary script eval and
+  inline scripts stay disabled. HTML/code stays passive; PDF scripts, forms and
+  annotations do not execute. Selected images/audio/video can render inline;
+  active document types download as attachments. See [preview contracts](#previews-and-media).
+- **Remote imports:** public-address and redirect validation, no URL credentials,
+  identity encoding, no inherited environment proxy, bounded time/bytes/disk.
+  `ALLOW_PRIVATE_REMOTE_URLS` explicitly broadens reachability. Signed source URLs
+  may persist in private jobs.
+- **Backups/deletion:** complete MongoDB archives use AES-256-GCM before disk or
+  Telegram storage and need their matching key. They exclude unsent staging and
+  cannot recreate missing Telegram originals. Permanent deletion removes catalog
+  references; it does not erase originals, caches, old backups or recipients'
+  copies. Old backups may restore removed records.
+
+Keep `.env`, sessions, hashes, keys, metadata and private traces out of public
+reports. Disable raw query/cookie logging at proxies. TGDrive does not encrypt
+original payloads or local staging and does not scan for malware. See
+[Operations](operations.md), [Backup & recovery](backup-recovery.md) and
+[known gaps](roadmap.md).
+
+</details>
diff --git a/docs/release.md b/docs/release.md
new file mode 100644
index 00000000..f7e0ec22
--- /dev/null
+++ b/docs/release.md
@@ -0,0 +1,204 @@
+# TGDrive v2 release verification
+
+[Docs home](README.md) · [Setup](setup.md) · [Development](development.md)
+
+TGDrive **2.0.0** targets a fresh MongoDB database and dedicated private Telegram
+channel. MongoDB is required on laptops and servers; local recovery journals do
+not replace it. Use Docker Compose for all deployments.
+
+The public source includes the [visual walkthroughs](showcase.md) and their
+[media assets](assets/README.md). Keep those files in the release allowlist when
+replacing captures.
+
+For cloning or optional source downloads, use [Get the source](setup.md#get-the-source).
+The procedures below describe preparing a versioned release and optionally
+building a downloadable archive. Cloning is sufficient to install TGDrive.
+
+**Contents**
+
+- [Choose the deployment](#choose-the-deployment)
+- [Version every published update](#version-every-published-update)
+- [Prepare the source release](#prepare-the-source-release)
+- [Verify a downloaded source archive](#verify-a-downloaded-source-archive)
+- [Fresh-install smoke checks](#fresh-install-smoke-checks)
+
+## Choose the deployment
+
+| Deployment | Runtime | Guide |
+| --- | --- | --- |
+| On-demand laptop | `compose.yaml` with automatically loaded `compose.override.yaml` | [Windows/macOS/Linux Docker](setup.md#4-start-locally) |
+| Coolify server | `compose.yaml` selected explicitly | [Coolify](setup.md#coolify) |
+| Server with an HTTPS proxy you manage | `compose.yaml` plus `compose.server.yaml` | [Server Compose](setup.md#docker-compose-on-a-server) |
+
+Follow [Setup](setup.md) for credentials, permissions and first initialization.
+Restarts and reinstalls must reuse the database, deployment identity, secrets
+and persistent storage. See [Operations](operations.md) for recovery.
+
+## Version every published update
+
+Every update published to `main` gets a new semantic version and a matching
+GitHub release, starting with **2.0.0** and tag **`v2.0.0`**. Development commits
+can accumulate on `dev` for one upcoming release; they do not each need a tag.
+`main` receives stable updates after release review and required checks. `dev`
+contains ongoing development and may be unstable; do not use it for a stable
+deployment. Prefer a published tag to reproduce an exact release.
+See the [release CI checks](development.md#when-github-checks-run) for `main`.
+
+| Change | Next version after `2.0.0` |
+| --- | --- |
+| Compatible fixes, documentation or maintenance | `2.0.1` |
+| Compatible features | `2.1.0` |
+| Breaking changes | `3.0.0` |
+
+`pyproject.toml` is the version authority. Keep `tgdrive/__init__.py`, the
+frontend `package.json` and both root version entries in `package-lock.json`,
+the TGDrive project entry in `uv.lock`, and the Docker image version label in
+sync. The release builder rejects mismatched versions before creating an
+archive; CI checks the same metadata. To inspect it without building:
+
+```bash
+python3 scripts/build_release.py --check-version
+```
+
+Name the target version in the release PR, describe the changes and compatibility
+requirements, and link the actual validation results. After merging and checking
+the final `main` commit, create an **annotated** `vX.Y.Z` tag on that commit.
+Never tag an unmerged `dev` revision as the final release. A published tag is
+immutable: fix a release with a new version instead of moving its tag.
+User-facing GitHub documentation links point to `main`; release download links
+pin the corresponding tag. Reserve `dev` links for contributor instructions.
+
+The matching GitHub release must link its PR and exact commit (and the comparison
+with the previous tag for later releases) and explain upgrade requirements and
+known limits. Git users can clone the tag; no ZIP is required. If custom source
+assets are offered, attach the ZIP and SHA-256 file from that revision together.
+Follow the checks below before publishing. Creating a PR or tag does not publish
+custom assets, and repository approval rules still apply to checks and pushes.
+
+## Prepare the source release
+
+Prepare a clean, reviewed commit and its matching tag. If distributing a custom
+source ZIP, build and validate it from the same revision. Resolve local work
+without resetting or discarding changes. Building an artifact does not publish it.
+
+<details>
+<summary>Maintainer checklist: build, validate and publish</summary>
+
+Run these from the release checkout, with the development prerequisites from
+[Development](development.md).
+
+- [ ] Choose the release version using the policy above and synchronize all
+   version metadata. For this initial release, use `2.0.0`. Review the user
+   guides against the implemented settings and defaults.
+- [ ] In **Actions → CI → Run workflow**, select the release branch and suite
+   **`all`** against the exact release commit. Review quality/security,
+   Python, frontend, Chromium, container and source-release results. Use the
+   isolated test database described in Development; never run destructive tests
+   against an operator's drive.
+- [ ] If offering custom source assets, build the public source archive:
+
+```bash
+python3 scripts/build_release.py
+(cd dist && sha256sum --check tgdrive-2.0.0.zip.sha256)
+python3 -m zipfile -t dist/tgdrive-2.0.0.zip
+```
+
+The builder includes reviewed source, public documentation and a file-hash
+manifest. Runtime data, credentials, caches and installed dependencies are
+excluded. Review the generated manifest and archive before distribution.
+
+- [ ] For custom source assets, extract into a clean directory. Repeat dependency installation,
+   frontend build, relevant tests and Docker build from the extraction using
+   [the documented commands](development.md). Confirm all three Compose modes
+   resolve and that no private `.env` or runtime data enters the image.
+- [ ] Perform the fresh-install smoke checks below from a clean clone of the
+   release revision, or the extracted archive if distributing one. Record the
+   commit, commands, environment and results (and checksum for an archive).
+- [ ] After those checks, create the annotated tag on the final merged `main`
+   commit. For the initial release (substitute the next version for later ones):
+
+```bash
+git switch main
+git pull --ff-only origin main
+python3 scripts/build_release.py --check-version --tag v2.0.0
+git tag -a v2.0.0 -m "Release TGDrive 2.0.0"
+```
+
+- [ ] With approval for the specific tag push, push `v2.0.0` to `origin` and
+   create its GitHub release. Attach matching ZIP and `.sha256` files together
+   only if offering custom source assets.
+   Tag-push CI also checks that the tag matches the metadata. Coolify users must
+   select that same revision. Record changes and limitations in the release's
+   description and Git commits.
+
+</details>
+
+## Verify a downloaded source archive
+
+For a published **2.0.0** release, download its **tgdrive-2.0.0.zip** and
+**tgdrive-2.0.0.zip.sha256** assets into the same folder. These commands verify
+the custom release assets; the development ZIP from GitHub does not have this
+companion checksum. Open a terminal in that download folder.
+
+**Windows PowerShell:**
+
+```powershell
+$expectedHash = (Get-Content .\tgdrive-2.0.0.zip.sha256 -Raw).Split(' ')[0]
+if ((Get-FileHash .\tgdrive-2.0.0.zip -Algorithm SHA256).Hash -ne $expectedHash) {
+    throw 'Checksum mismatch. Download the release files again.'
+}
+Expand-Archive .\tgdrive-2.0.0.zip -DestinationPath .
+Set-Location .\tgdrive-2.0.0
+```
+
+**macOS Terminal:**
+
+```bash
+shasum -a 256 -c tgdrive-2.0.0.zip.sha256
+```
+
+**Linux/WSL terminal:**
+
+```bash
+sha256sum --check tgdrive-2.0.0.zip.sha256
+```
+
+On macOS/Linux/WSL, continue **only after the checksum reports OK**, then extract:
+
+```bash
+unzip tgdrive-2.0.0.zip
+cd tgdrive-2.0.0
+```
+
+Your file manager can extract the ZIP if `unzip` is unavailable.
+Continue with [Setup](setup.md). A checksum verifies the download against its
+companion file; obtain both from the trusted project release.
+
+## Fresh-install smoke checks
+
+Use disposable databases, channels and files. Keep credentials and private
+evidence out of public docs and reports.
+
+<details>
+<summary>Checks with disposable databases, channels and files</summary>
+
+- [ ] **Local Docker:** on Windows, macOS and Linux, confirm automatic first setup, sign in on
+  localhost, upload/download a small file, stop/start, and reopen it. Check that
+  configuration and volumes persist. These are separate platform checks.
+- [ ] **Hosted:** verify HTTPS login, private-file denial without authentication,
+  a scoped share and revocation. Confirm the direct app port is not public.
+- [ ] **Transfers:** check a split file's original checksum, an interrupted upload,
+  retry/reselection guidance, and server processing after browser acceptance.
+- [ ] **Channel protection:** verify required bot permissions and that public or
+  auto-delete settings produce an actionable error. Restore the correct state.
+- [ ] **Recovery:** confirm an encrypted database backup, save its matching key,
+  and restore into a separate empty database. If independent channel protection
+  is enabled, verify its completed restore point and recovery flow separately.
+
+Automated tests and synthetic browser checks do not certify real Telegram,
+Coolify, DNS/TLS, every codec/device or sustained throughput. See the
+[dated evidence](development.md#ci-and-release-evidence) and
+[validation boundaries](roadmap.md#before-public-release). A documented release
+procedure is not a claim that publication or all live checks have occurred.
+
+</details>
diff --git a/docs/roadmap.md b/docs/roadmap.md
new file mode 100644
index 00000000..83c6e98c
--- /dev/null
+++ b/docs/roadmap.md
@@ -0,0 +1,64 @@
+# Status and roadmap
+
+[Docs home](README.md) · [Validation evidence](development.md#ci-and-release-evidence)
+
+TGDrive is a single-owner, self-hosted drive. This page separates available
+features from remaining validation and known limits.
+
+[See the available interface and workflows](showcase.md); the recordings are
+illustrative and do not certify the validation still listed below.
+
+## What works now
+
+| Available | Learn more |
+| --- | --- |
+| File/folder uploads, multipart storage, Trash and history | [User guide](usage.md) |
+| Previews, readers and scoped sharing | [Readers](reading.md) · [Sharing](usage.md#share-and-revoke) |
+| Monitoring and multiple Telegram accounts | [Performance](performance.md) · [Configuration](configuration.md) |
+| MongoDB persistence, encrypted database backups and optional channel protection | [Recovery](operations.md) · [Channel protection](backup-recovery.md) |
+
+Available features still have [configured limits](configuration.md) and are not
+certified for every device or network.
+
+## Before public release
+
+Use the [release procedure](release.md) against the exact commit (and extracted
+archive if offering custom source assets). Publication is a separate maintainer
+action. Remaining live validation:
+
+- [ ] Fresh laptop and hosted installs, persistent volumes, stop/start and recovery.
+- [ ] Coolify DNS/TLS, trusted forwarding and isolation of the direct app port.
+- [ ] Prolonged multi-account outages and interrupted Telegram sends.
+- [ ] Actual Premium speed, broader devices/codecs, ARM and hosting platforms.
+
+## Known correctness and recovery gaps
+
+| Area | Current limit |
+| --- | --- |
+| Authentication | Password-only owner login; no MFA/passkeys, idle session timeout or fresh reauthentication for sensitive settings/key exports. Login throttling is process-local. |
+| Credentials | Same-account token/session replacement needs restart; Refresh can apply verified channel-permission repair to a live client. |
+| Bot imports | Do not use the web queue's full durable job model. |
+| History | Compaction must preserve unresolved effects and retry identities. |
+| Large folders | Listings sort/materialize before slicing; database cursor pagination remains work. |
+| Direct API clients | Some request mappings are process-local and error formats vary; use documented v2 flows. |
+| Storage channel changes | Require verified channel recovery; editing an ID does not move files. |
+
+See [Troubleshooting](operations.md#troubleshooting) for current recovery actions.
+
+<details>
+<summary>Next improvements and scope</summary>
+
+## Next improvements
+
+Prioritize integrity, recovery and understandable status:
+
+- Broader device/codec/reader coverage; first-frame and seek measurements.
+- Empty-directory uploads and clearer emergency restore guidance.
+- Broader real-device coverage for shared-owner sessions and simultaneous changes.
+- Consider independent export, payload encryption and real modification timestamps.
+
+## Outside the current scope
+
+Multi-user accounts, teams, tenant permissions and clustered workers.
+
+</details>
diff --git a/docs/setup.md b/docs/setup.md
new file mode 100644
index 00000000..03583cfc
--- /dev/null
+++ b/docs/setup.md
@@ -0,0 +1,470 @@
+# Set up TGDrive
+
+[Docs home](README.md) · Next: [Using TGDrive](usage.md)
+
+**Must read before using TGDrive: [New-user guide and FAQs](new-user-guide.md).**
+It explains the storage model, channel rules, limits and backup responsibilities;
+these installation steps do not replace it.
+
+[See the interface before installing](showcase.md), including the file browser,
+previews, transfers and settings.
+
+**Use Docker Compose for every TGDrive deployment.** It builds the website and
+includes Python, dependencies and preview tools, with the same runtime on laptops
+and servers. TGDrive supports **Python 3.14.8 only**; the image supplies that exact
+version. No host Python or Node installation is needed for the main steps.
+
+For a **new v2 drive**, use an empty MongoDB database and a new private Telegram
+channel. v1 data and older catalog formats are not imported or upgraded.
+
+**Contents**
+
+- [Choose your installation](#choose-your-installation)
+- [Before you start](#before-you-start)
+  - [Get the source](#get-the-source)
+- [1. Prepare MongoDB](#1-prepare-mongodb)
+- [2. Prepare Telegram](#2-prepare-telegram)
+- [3. Configure your drive](#3-configure-your-drive)
+  - [Find your numeric Telegram user ID](#find-your-telegram-user-id)
+- [4. Start locally](#4-start-locally)
+- [5. Open your drive](#5-open-your-drive)
+- [Apply updates to an existing drive](#apply-updates-to-an-existing-drive)
+- [If setup stops](#if-setup-stops)
+- [Reinstall or move to another machine](#reinstall-or-move-to-another-machine)
+- [Additional bots and Premium accounts](#additional-bots-and-premium-accounts)
+- [Hosting beyond your machine](#hosting-beyond-your-machine)
+  - [Coolify](#coolify)
+  - [Docker Compose on a server](#docker-compose-on-a-server)
+  - [Other hosting](#other-hosting)
+- [Features and settings after setup](#features-and-settings-after-setup)
+- [Optional independent channel protection](#optional-independent-channel-protection)
+
+## Choose your installation
+
+| Use | Recommended setup |
+| --- | --- |
+| **Laptop, only when needed** | Docker Compose on Windows, macOS or Linux; follow steps 1–5 below. |
+| **Your own server** | [Self-hosted Coolify](#coolify), a free tool for deployment management. |
+| **Server with your own HTTPS proxy** | [Server Compose](#docker-compose-on-a-server). |
+| **Prefer help running it** | [Optional managed hosting](hosting.md#optional-managed-hosting), including the server, deployment and management. |
+
+Local Compose uses a private localhost address and runs only when you start
+it. TGDrive needs internet access to Telegram and MongoDB. A sleeping or stopped
+laptop cannot serve transfers, backups, bot requests or shared links. Keep source
+files until uploads say **Completed**.
+
+## Before you start
+
+Install a maintained Docker release with **Compose 2.24+ and Buildx**, following the
+official guide for your system:
+
+| System | Recommended installation | Terminal for this guide |
+| --- | --- | --- |
+| Windows | [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) with its default WSL 2 backend; use **Linux containers**. | PowerShell |
+| macOS | [Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) for your Apple Silicon or Intel Mac. | Terminal |
+| Linux laptop or server | [Docker Engine](https://docs.docker.com/engine/install/) from Docker's repository, with the [Compose plugin](https://docs.docker.com/compose/install/linux/) and [Buildx](https://docs.docker.com/build/concepts/overview/). | Your usual terminal |
+
+Start Docker Desktop, or the Linux Docker daemon. These commands must work before
+continuing:
+
+~~~bash
+docker info
+docker compose version
+docker buildx version
+~~~
+
+Use `docker compose` (with a space). Docker Desktop includes Compose and Buildx;
+Linux users should install them using the official repository instructions.
+You do not need to open an Ubuntu terminal on Windows for the main steps.
+For Linux permission errors, follow Docker's [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/).
+
+### Get the source
+
+The [`main` branch](https://github.com/TechShreyash/TGDrive/tree/main) receives
+reviewed, tested stable updates. The [`dev` branch](https://github.com/TechShreyash/TGDrive/tree/dev)
+is ongoing development and may be unstable; do not use it for a normal installation.
+See [release verification](release.md) for the required checks and their limits.
+
+With Git installed, open a terminal and clone the stable branch:
+
+~~~bash
+git clone --branch main https://github.com/TechShreyash/TGDrive.git
+cd TGDrive
+~~~
+
+Run the setup commands below from that folder as your normal user. `main`
+advances with reviewed versioned releases; version tags stay fixed. To pin
+**2.0.0**, use this clone command instead, once the
+[v2.0.0 tag](https://github.com/TechShreyash/TGDrive/tree/v2.0.0) is published:
+
+~~~bash
+git clone --branch v2.0.0 --depth 1 https://github.com/TechShreyash/TGDrive.git
+cd TGDrive
+~~~
+
+Without Git, download the [stable source ZIP](https://github.com/TechShreyash/TGDrive/archive/refs/heads/main.zip),
+extract it and open a terminal in `TGDrive-main`. After `v2.0.0` is published,
+its [tagged source ZIP](https://github.com/TechShreyash/TGDrive/archive/refs/tags/v2.0.0.zip)
+provides the same fixed-version option. A custom source ZIP with a matching
+checksum may also be offered on the [release page](https://github.com/TechShreyash/TGDrive/releases/tag/v2.0.0);
+follow [verify and extract](release.md#verify-a-downloaded-source-archive) for those
+optional assets. Merging to `main` does not publish a tag or release assets.
+Leave disk space for unfinished uploads and cache.
+
+If you choose to use a WSL terminal, enable Docker Desktop's
+[WSL integration](https://docs.docker.com/desktop/features/wsl/) and keep the
+project in Ubuntu's Linux filesystem. Use that same terminal/folder consistently.
+
+## 1. Prepare MongoDB
+
+[MongoDB Atlas](https://www.mongodb.com/docs/atlas/tutorial/deploy-free-tier-cluster/)
+is the simplest option. Self-hosted MongoDB must be a **replica set** for
+transactions; a standalone container is insufficient. TGDrive's Compose files
+do not supply MongoDB.
+
+1. Create an Atlas cluster and a **database user** with read/write access.
+2. In **Network Access**, allow the public IP of the TGDrive machine.
+3. Open **Connect → Drivers**, copy the URI and replace its password placeholder.
+   [Encode reserved password characters](https://www.mongodb.com/docs/manual/reference/connection-string/).
+
+Keep the URI private. Use database name `tgdrive`, or another dedicated database.
+Update the IP allowlist if your laptop changes networks; avoid allowing every IP.
+MongoDB holds catalog/settings; file contents live in Telegram.
+
+## 2. Prepare Telegram
+
+1. Open [BotFather](https://t.me/BotFather), create your main bot and keep its
+   **bot token**. It will store files and accept uploads in a private chat.
+2. Open [Telegram's API page](https://my.telegram.org/apps), create an application
+   and keep its **API ID** and **API hash**.
+3. Create a dedicated **private broadcast channel**, not a group or a public
+   channel. Give it no public username and turn message auto-delete **Off**.
+4. Add this bot as a channel administrator with **Post Messages** and
+   **Delete Messages** enabled.
+5. Send one identification message, then use **Copy Message Link**. For a link
+   like `https://t.me/c/1234567890/1`, the channel ID is `-1001234567890`:
+   prepend `-100` to the number after `/c/`. Use your own channel's ID.
+
+> [!IMPORTANT]
+> Treat the channel as app-managed storage. Make file changes in TGDrive;
+> do not edit/delete its messages, clear history, change recovery pins or add
+> moderation bots. Keep every enabled account's channel access/permissions.
+> A database backup cannot recover file bytes deleted from Telegram.
+
+**Post Messages** stores files/backups; **Delete Messages** cleans unfinished
+uploads. **Edit Messages** is only needed for independent backup recovery pins.
+Leave unrelated rights off. Reading needs channel access, not a separate
+“Read Messages” administrator switch. Setup and **Connections → Refresh** check
+access; see [channel damage recovery](operations.md#if-someone-changed-the-telegram-channel).
+
+## 3. Configure your drive
+
+Copy the template once. **Windows PowerShell**:
+
+~~~powershell
+Copy-Item .env.example .env
+~~~
+
+**Linux, WSL or macOS terminal**:
+
+~~~bash
+cp .env.example .env
+chmod 600 .env
+~~~
+
+Open `.env` in a text editor. Replace these placeholders; do not leave angle
+brackets in your values:
+
+| Setting | Value |
+| --- | --- |
+| `MONGODB_URI` | Your private Atlas/replica-set connection URI |
+| `API_ID` / `API_HASH` | From Telegram's API page |
+| `MAIN_BOT_TOKEN` | Your main bot's token from BotFather |
+| `TELEGRAM_ADMIN_IDS` | Your numeric Telegram user ID, not your `@username`; separate multiple allowed users with commas. [Find your ID](#find-your-telegram-user-id) |
+| `STORAGE_CHANNEL` | Your private channel's negative numeric ID |
+| `ADMIN_PASSWORD` | A unique web password; 15+ characters recommended, 12-character minimum |
+
+<a name="find-your-telegram-user-id"></a>
+
+<details>
+<summary>Find your numeric Telegram user ID</summary>
+
+Before starting TGDrive for the first time:
+
+1. Send `/start` in a private chat with your new bot. It does not need to reply.
+2. Open `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates` in your browser,
+   replacing `<YOUR_BOT_TOKEN>` with the token from BotFather.
+3. In `result`, find your `/start` message and copy **`message.from.id`** into
+   `TELEGRAM_ADMIN_IDS`. Use the sender's user ID, not the bot or channel ID.
+   For multiple allowed users, have each send a private message and separate
+   their IDs with commas.
+
+This uses [Telegram's own Bot API](https://core.telegram.org/bots/api#getupdates).
+Keep the token-bearing URL and response private. If `result` is empty, send a
+fresh message and refresh; use a new bot that is not already running elsewhere.
+
+</details>
+
+The main bot starts as your first storage connection. Only the Telegram users
+listed in `TELEGRAM_ADMIN_IDS` can send it files. Add further storage bots through
+[Connections](#additional-bots-and-premium-accounts) after setup.
+
+The defaults use database `tgdrive` and allow local HTTP cookies. Session and
+backup keys are generated once and preserved in persistent storage; leave
+`SESSION_SECRET` and `MONGODB_BACKUP_KEY` unset for a new installation. Never replace
+an existing drive's keys. Save the exported recovery key after your first login.
+
+Keep `.env` private. Single-quote values containing `$`, including password
+hashes. Do not shell-source the file. For hashed passwords, explicit keys and all
+optional settings, see the [configuration reference](reference.md#configuration).
+
+## 4. Start locally
+
+Run one installation and one worker per drive. From the project folder with your
+configured `.env`, build using these same commands on Windows, macOS and Linux:
+
+~~~bash
+docker compose config --quiet
+docker compose build
+~~~
+
+Start TGDrive:
+
+~~~bash
+docker compose up -d
+docker compose ps
+~~~
+
+TGDrive connects to MongoDB before becoming available. A new, empty database is
+initialized automatically; an existing drive is reopened. Missing or invalid
+`MONGODB_URI`, failed authentication, an unreachable database or an unsupported
+MongoDB deployment stops startup. There is no SQLite fallback. Correct the
+environment or database access and start again. Existing or incomplete drive
+state is preserved for explicit recovery; it is never replaced with an empty drive.
+
+The first build can take several minutes. `config --quiet` checks syntax, not
+credentials. Plain `docker compose config` prints secrets; keep its output private.
+
+Open [http://127.0.0.1:8000](http://127.0.0.1:8000) and follow
+[first login](#5-open-your-drive). Closing the terminal keeps the containers
+running; Docker Desktop/the daemon must remain running too.
+
+| Later action | Command |
+| --- | --- |
+| Start for this session | `docker compose up -d` |
+| See whether it is ready | `docker compose ps` |
+| Finish using it | `docker compose stop` |
+| Restart after an interruption | `docker compose restart app` |
+| Apply edited .env values | `docker compose up -d --force-recreate` |
+
+Local containers do not restart automatically by default. Let Stop finish its
+graceful shutdown (up to 60 seconds). To opt into restart after Docker starts,
+set `TGDRIVE_RESTART_POLICY=unless-stopped` in `.env` and recreate.
+You can quit Docker Desktop after stopping TGDrive; keep its saved volumes.
+
+> [!WARNING]
+> Keep `.env`, both named volumes and the same Compose project name.
+> Do not use `docker compose down -v` or volume prune as a repair:
+> they remove keys, unfinished bytes and recovery journals.
+> Compose stores data inside its named volumes, not host `data/` and `cache/` folders.
+
+## 5. Open your drive
+
+1. Sign in at [http://127.0.0.1:8000](http://127.0.0.1:8000) with your web password.
+2. Open **Connections → Refresh** and check your bot.
+3. Open **Storage & Backups → Save recovery key** and store the downloaded key
+   somewhere separate from this installation.
+
+Before importing your library:
+
+- [ ] Upload and download a small test file.
+- [ ] Stop/start TGDrive and check the file still opens.
+- [ ] Choose **Back up now** and confirm an archive.
+
+Then [upload your files](usage.md#upload-files-or-folders).
+
+Before a large import, review [storage budgets](configuration.md#upload-size-and-available-disk-space):
+defaults are **16 GiB upload staging, 10 GiB disk cache and 256 MiB RAM cache**.
+These are ceilings, not preallocated space; leave room for the system and backups.
+
+Interrupted uploads may need their original files. A restart resumes recoverable
+server work; deleted Telegram bytes or missing credentials require further action.
+See [interruption recovery](operations.md#after-a-shutdown-crash-or-network-loss).
+
+## Apply updates to an existing drive
+
+Keep the database, channel, environment and persistent storage. Startup reopens
+the existing drive automatically. Choose a published release tag, or stable
+`main` source, using [the source guidance above](#get-the-source); do not follow `dev`.
+
+| Installation | Update |
+| --- | --- |
+| Local Docker | Follow [archive/Git update steps](operations.md#upgrade-and-rollback), preserving `.env` and project name; run `docker compose up -d --build`. |
+| Coolify | Redeploy the updated revision with the existing Compose configuration. |
+| Server Compose | Use the same `-f compose.yaml -f compose.server.yaml` files; run `up -d --build`. |
+
+Refresh the browser and reopen interrupted playback. Saved settings and
+persistent disk cache remain; RAM cache repopulates after restart.
+See [upgrade/rollback](operations.md#upgrade-and-rollback) for hosted installations.
+
+## If setup stops
+
+| Problem | What to check |
+| --- | --- |
+| Docker command fails | Start Docker Desktop/the daemon; on Linux check your user's Docker access |
+| Website says it needs a build | Rebuild with `docker compose up -d --build`; Docker builds the website for you |
+| Database connection fails | URI password, Atlas Network Access and cluster availability |
+| Bot cannot use the channel | Correct bot token, private broadcast channel, auto-delete off and every bot's administrator permissions |
+| Existing drive is missing | Check the database name; do not initialize a replacement |
+| Address already in use | Set a free `PORT`, such as `8001`, in `.env`, recreate the local container and open that localhost port |
+| Login works only until the page reloads | Local HTTP needs `COOKIE_SECURE=false`; recreate after editing. Hosted access needs HTTPS with secure cookies |
+| A setting edit has no effect | Recreate the container; saved dashboard preferences override matching startup defaults |
+
+More help: [Troubleshooting](operations.md#troubleshooting).
+
+## Reinstall or move to another machine
+
+Follow [reopen your existing drive](operations.md#reopen-after-losing-the-local-installation).
+Use the same MongoDB database; **do not initialize it again**.
+
+## Additional bots and Premium accounts
+
+Add extra storage bots through **Management → Connections → Add storage bot**,
+rather than editing the deployment's token list. First add each bot to the same
+private channel as an administrator with **Post Messages** and **Delete Messages**.
+More healthy bots can handle more Telegram work at once, subject to server and
+Telegram limits.
+
+[Finish pending transfers before changing accounts](usage.md#settings-and-connections),
+then save your connection changes and restart TGDrive.
+
+Premium is optional: all accounts use the same **2000 MiB** document cap and
+[automatic splitting](usage.md#files-above-2-gb). Available Premium clients are
+preferred for transfer speed, but neither Premium nor extra bots guarantee
+higher throughput or remove Telegram cooldowns. A live Premium speedup has not
+been measured. Use **Connections → Connect Premium account** to sign in, or
+import an already authorized session through its advanced controls.
+
+## Hosting beyond your machine
+
+Use [Coolify](#coolify) to manage deployment on your server, or
+[server Compose](#docker-compose-on-a-server) with an HTTPS proxy you manage.
+The [hosting guide](hosting.md) compares local and server use, explains optional
+managed hosting and server plans, and lists the accounts you need to prepare.
+
+Preserve the database, private configuration and persistent volumes. If you
+change hosts, follow [move or reopen your drive](operations.md#when-a-hosting-plan-expires).
+
+### Coolify
+
+Coolify is recommended for **managing deployment on a server you provide**.
+Its self-hosted edition is free; you pay for your own server/infrastructure.
+[Install Coolify](https://coolify.io/docs/start-with-self-hosted) if needed.
+
+You need a Docker server, domain, reachable MongoDB replica set and Telegram
+setup above.
+
+Coolify's generated `sslip.io` URL uses HTTP. For TGDrive, use a domain with a
+valid HTTPS certificate: the browser app needs a secure context away from
+localhost. See [HTTP support and certificate limits](operations.md#can-tgdrive-run-over-http).
+
+Create a public Git application from `https://github.com/TechShreyash/TGDrive`.
+Select **`main`** for stable source updates. Prefer **`v2.0.0`** once that release
+is published to pin this installation; do not deploy `dev`. Under **General →
+Build pipeline**, select **Compose** as the build strategy. Set **Base Directory**
+to `/` and **Docker Compose Location** to `/compose.yaml`, then save.
+In **Environment Variables**, enter:
+
+| Variable | Value |
+| --- | --- |
+| `MONGODB_URI` | Your private Atlas/replica-set connection URI |
+| `API_ID` | Telegram application ID |
+| `API_HASH` | Telegram application hash |
+| `MAIN_BOT_TOKEN` | Your main bot's token from BotFather |
+| `TELEGRAM_ADMIN_IDS` | Your numeric Telegram user ID; separate multiple allowed users with commas. [Find your ID](#find-your-telegram-user-id) |
+| `STORAGE_CHANNEL` | The private channel's negative numeric ID |
+| `ADMIN_PASSWORD` | Owner password, at least 12 characters |
+
+Choose **Literal** for values containing `$`. Keep secrets **unavailable during
+build**, **available at runtime**, then save. [Environment guide](https://coolify.io/docs/applications/configuration/environment-variables).
+
+1. Point your domain's DNS at the server.
+2. Under **Domains**, add an HTTPS domain for the **`app`** service, including
+   its internal port: `https://drive.example.com:8000`. Visitors use normal HTTPS.
+3. **Deploy** and wait for `app` to become healthy. If deployment fails, inspect
+   the deployment and application logs.
+4. Open your domain, sign in and save **Storage & Backups → Save recovery key**
+   somewhere separate from the server.
+
+The included Compose file creates persistent volumes at **`/app/data`** and
+**`/app/cache`**, and configures secure cookies and proxy access. Keep those volumes
+when redeploying: they hold keys, sessions and unfinished uploads as well as cache.
+TGDrive initializes an empty database automatically; an existing drive reopens
+with its saved settings and owner password.
+
+[Coolify Compose guide](https://coolify.io/docs/applications/builds/docker-compose) ·
+[TGDrive configuration](configuration.md) · [Updates and recovery](operations.md)
+
+### Docker Compose on a server
+
+Use a published release tag or the stable `main` source from
+[Get the source](#get-the-source), rather than `dev`.
+
+1. Prepare MongoDB/Telegram and private `.env` as in
+   [configuration](#3-configure-your-drive). Keep app ingress private.
+2. Name **both files explicitly** to avoid the laptop override:
+
+~~~bash
+docker compose -f compose.yaml -f compose.server.yaml config --quiet
+docker compose -f compose.yaml -f compose.server.yaml build
+~~~
+
+3. Start the server; a new, empty MongoDB database is initialized automatically:
+
+~~~bash
+docker compose -f compose.yaml -f compose.server.yaml up -d
+docker compose -f compose.yaml -f compose.server.yaml ps
+~~~
+
+4. Forward HTTPS to host `127.0.0.1:8000`, preserving Host and setting forwarded
+   scheme/client headers. A containerized proxy needs a shared private network
+   with `app:8000`, or its documented host-access route.
+5. Trust only proxy source addresses the app sees through `FORWARDED_ALLOW_IPS`;
+   never use `*` as a workaround. Follow
+   [HTTPS/proxy checks](operations.md#https-and-private-configuration).
+6. Verify the public domain, Connections and a small upload/download.
+   Save the recovery key separately and confirm a database backup.
+
+The server file keeps secure cookies on, publishes loopback only and defaults
+to `unless-stopped` restart. Keep project name/volumes and use the same
+`-f compose.yaml -f compose.server.yaml` arguments for `stop`, `restart app`
+and `up -d --build`. Health checks alone do not validate DNS, TLS or files.
+See [upgrade/rollback](operations.md#upgrade-and-rollback).
+
+### Other hosting
+
+Use Docker/Compose with persistent storage and one worker per drive. Platforms
+that sleep, replace local disks or impose short request/upload limits can break
+long transfers unless configured appropriately.
+
+## Features and settings after setup
+
+After the first upload/download works:
+
+| Feature | Configure |
+| --- | --- |
+| More bots / Premium | [Connections](usage.md#settings-and-connections) |
+| Telegram bot uploads | [Choose the upload folder and send files](usage.md#optional-telegram-bot-interface); the main bot and allowed users are configured during setup |
+| Shares | [Shared Links](usage.md#share-and-revoke); recipients need a reachable website |
+| Independent channel copy | [Setup below](#optional-independent-channel-protection) |
+| Cache, preloads, upload limits, timezone | [Configuration](configuration.md) |
+| Host a public demo with settings locked | [Public demo mode](configuration.md#public-demo-mode) |
+| Backup interval, URL policy, sessions, proxy trust | [Deployment variables](reference.md#configuration) |
+
+## Optional independent channel protection
+
+After the drive works, add a separate private channel and backup bot through
+**Storage & Backups → Independent backup channel**. Save its recovery key outside
+Telegram and wait for a confirmed restore point.
+Follow [backup-channel setup](backup-recovery.md#set-up-an-independent-backup-channel)
+for permissions, copying, recovery and same-provider limits.
diff --git a/docs/showcase.md b/docs/showcase.md
new file mode 100644
index 00000000..2f2ee8a3
--- /dev/null
+++ b/docs/showcase.md
@@ -0,0 +1,305 @@
+# See TGDrive in action
+
+[Docs home](README.md) · [User guide](usage.md) · [Live demo and password](usage.md#try-the-public-demo)
+
+Explore a feature below, then follow its linked guide for the steps and limits.
+The captures use disposable sample files in the public demo. Videos are silent
+and play at normal speed; the mobile layout uses an emulated viewport. These
+are demonstrations, not speed or physical-device tests.
+[Capture details and replacement instructions](assets/README.md).
+
+| Watch | Duration | Covers |
+| --- | --- | --- |
+| [Organize your files](assets/organize-files.mp4) | 3:26 | Views, search, sort, favorites, folder creation, rename and move |
+| [Upload and share](assets/upload-and-share.mp4) | 5:20 | Upload progress, history, Show in Folder, share label/expiry, copying and revocation confirmation |
+| [Preview and read](assets/readers-and-preview.mp4) | 5:51 | Image/audio/text previews, PDF/EPUB/comic navigation and video playback/settings |
+
+**The preview video shows earlier player controls.** Follow the
+[current playback controls](usage.md#open-preview-and-download) for today's labels
+and behavior.
+
+<details>
+<summary>Find a feature in the videos</summary>
+
+Times are **minutes:seconds**. Open a video and use the player's timeline to
+jump to the step you need.
+
+| Video | Chapters |
+| --- | --- |
+| Organize your files | **0:09** List view · **0:16** Sorting · **0:31** Search · **0:57** Favorites · **1:31** Create a folder · **2:06** Rename · **2:40** Move |
+| Upload and share | **0:14** Upload menu · **0:27** Device file selection · **1:46** Upload starts · **2:00** Transfers · **2:14** Show in Folder · **3:21** Share options · **3:56** Link label · **4:08** Expiry · **4:16** Link management · **4:50** Copy link · **5:14** Revocation confirmation |
+| Preview and read | **0:07** Images · **0:25** Audio · **0:47** PDF · **1:25** EPUB · **2:18** Comics · **4:01** Video · **4:31** Player settings · **5:23** Text preview |
+
+The device file picker is outside the browser recording; local paths stay
+hidden. Link generation happens between the upload and management chapters.
+The management chapter shows copying and the revocation confirmation; the
+temporary demonstration link was revoked after recording.
+
+</details>
+
+**Contents**
+
+- [Browse and organize](#browse-and-organize)
+- [Upload and follow transfers](#upload-and-follow-transfers)
+- [Read and preview](#read-and-preview)
+- [Share selected content](#share-selected-content)
+- [Restore from Trash](#restore-from-trash)
+- [Preload and monitor](#preload-and-monitor)
+- [Configure your drive](#configure-your-drive)
+- [Connections and backups](#connections-and-backups)
+- [Workflows beyond these recordings](#workflows-beyond-these-recordings)
+
+## Browse and organize
+
+Start in **My Files**. Open a folder, switch between **List** and **Grid**, and
+choose **Name**, **Date Added** or **File Size** to sort. Open **Select** for
+multi-item move or Trash actions. An item's menu also offers rename, star,
+sharing, downloading and preloading. [Browse and organize →](usage.md#browse-and-organize)
+
+![Desktop My Files with a sample collection](assets/drive-overview.png)
+
+<details>
+<summary>File actions, search, Starred and mobile navigation</summary>
+
+Switch to List for compact rows, or choose a darker appearance from the theme
+menu. The same sample collection is shown below in List and Dark Grid views.
+
+| List view | Dark appearance |
+| --- | --- |
+| <img src="assets/drive-list.png" alt="TGDrive sample collection in List view" width="540"> | <img src="assets/drive-dark.png" alt="TGDrive sample collection in Dark Grid view" width="540"> |
+
+![File actions menu in My Files](assets/file-actions.png)
+
+Search finds filenames across your drive and shows their locations. Press **/**
+or **Ctrl/Cmd+K** outside an editing field to focus it. Star frequently used
+items from their menu, then open **Starred**. Stars follow moves and renames.
+
+![Filename search and sort controls](assets/search-and-sort.png)
+
+![Starred sample files and folders](assets/starred-files.png)
+
+On a narrow screen, tap a file once to open it; use the navigation menu to switch
+pages and **View and sort** to adjust the listing.
+
+<img src="assets/mobile-drive.png" alt="TGDrive file browser in a phone-sized viewport" width="360">
+
+</details>
+
+[Watch file organization](assets/organize-files.mp4).
+
+## Upload and follow transfers
+
+Open the destination, then use **New → Upload files** or **Upload folder**.
+Review the folder summary before starting. Follow **Transfers** and keep the
+browser open until **You can close this tab** appears. Keep originals until
+**Completed**. [Upload instructions and status meanings →](usage.md#upload-files-or-folders)
+
+![Expanded device upload with progress, speed, time remaining and Keep this tab open](assets/upload-progress.png)
+
+![Completed uploads in the transfer panel](assets/upload-completed.png)
+
+<details>
+<summary>Folder upload entry point, URL imports and transfer history</summary>
+
+![New menu with the Upload folder action](assets/upload-folder.png)
+
+The capture shows where to start a folder upload. Follow the
+[written folder-upload steps](usage.md#upload-files-or-folders) for the picker and
+confirmation; the recordings demonstrate a single-file upload.
+
+Nested folders stay together in an expandable upload task. Ordinary files and
+URL imports have separate tasks. **New → Upload from URL** receives a public
+HTTP(S) file on the server; source checks and subsequent stages appear in Transfers.
+Accepted URL work can continue with the browser closed while TGDrive runs.
+
+![Upload from URL controls](assets/url-import.png)
+
+Finished history has **All / Successful / Failed / Cancelled** filters, search
+and pages. Use **Show in folder** to locate a completed upload. For interrupted
+device uploads, reselect the originals in the existing task to resume from the
+confirmed offset. [History →](usage.md#transfer-history) ·
+[Retries and resuming →](usage.md#can-i-close-the-tab)
+
+![Finished transfer history and filters](assets/transfer-history.png)
+
+</details>
+
+[Watch upload and sharing](assets/upload-and-share.mp4).
+
+## Read and preview
+
+Double-click a file with a mouse or tap it on touch. **Download Original** keeps
+the original available; **Escape** or browser **Back** closes the preview.
+Preview support depends on the file and browser. [All preview formats and controls →](usage.md#open-preview-and-download)
+
+![Video open in TGDrive's custom player](assets/media-preview.png)
+
+The player includes seeking, volume and settings. Available audio tracks,
+subtitles, chapters and quality choices depend on the source. Use fullscreen
+where your browser supports it; touch controls include double-tap seeking.
+
+![Video player settings menu](assets/video-settings.png)
+
+<details>
+<summary>Images, audio and read-only text</summary>
+
+![Sample image in the image viewer](assets/image-preview.png)
+
+![Sample audio in the audio player](assets/audio-preview.png)
+
+![Read-only sample text in the text preview](assets/text-preview.png)
+
+Text previews show the first 256 KiB. Unsupported formats retain their original
+download action.
+
+</details>
+
+<details>
+<summary>PDF, EPUB and comic readers</summary>
+
+PDFs have page navigation, continuous scrolling, zoom, **Fit width**, **Fit page**
+and selectable text. EPUB adds chapters and text size/typeface options. Comics
+and illustrated EPUB pages offer page fit and right-to-left navigation.
+[Reader instructions, remembered position and limits →](reading.md)
+
+![PDF page with navigation and fit controls](assets/pdf-reader.png)
+
+![EPUB chapter reader and reading controls](assets/epub-reader.png)
+
+![Comic reader and page controls](assets/comic-reader.png)
+
+</details>
+
+[Watch previews and readers](assets/readers-and-preview.mp4); its player controls
+predate the [current version](usage.md#open-preview-and-download).
+
+## Share selected content
+
+Choose **Share Link** from a file or folder's menu. Add an optional label, select
+an expiry and create the link. Anyone holding it can read the shared content;
+folder links include accessible descendants. [Create, edit and revoke links →](usage.md#share-and-revoke)
+
+![Sharing dialog with a label and expiry choices](assets/share-link.png)
+
+<details>
+<summary>Recipient folder and Shared Links inventory</summary>
+
+![A shared folder as a recipient sees it](assets/shared-folder.png)
+
+Open **Shared Links** to find each labelled link, change its expiry, copy an
+active link or revoke it. Independent links can have different purposes and
+expiries. Moving or renaming an item preserves explicit links.
+
+![Shared Links inventory with labels and expiry information](assets/shared-links.png)
+
+**Copy Download Link** creates or reuses a separate download capability for
+download managers. Keep it private and revoke it from Shared Links when finished.
+Revocation cannot recall copies already downloaded.
+
+</details>
+
+## Restore from Trash
+
+Use an item's **Move to Trash** action, then open **Trash**. **Deleted from**
+shows its previous folder; choose **Restore** to return it. Permanent deletion
+requires confirmation, removes the catalog records and cannot be undone from
+Trash. Telegram originals remain in the storage channel.
+[Trash and deletion behavior →](usage.md#trash-and-permanent-deletion)
+
+![Trash showing a disposable item and its original folder](assets/trash-restore.png)
+
+## Preload and monitor
+
+For a movie, large download or busy share, choose **Preload file** from its menu.
+Open **Monitor → Preloads** to follow the queue and inspect server cache coverage.
+Preloading can continue with the browser closed while the server runs. Cache is
+disposable and is not a backup. [Preload instructions →](usage.md#preload-a-file-for-smoother-playback-and-downloads)
+
+![Preloads showing cache capacity and file coverage](assets/preloads.png)
+
+<details>
+<summary>Performance overview and server resources</summary>
+
+Open **Monitor → Performance**. **Overview** shows network traffic and live
+transfers; **Accounts** shows Telegram activity and capacity; **Resources** shows
+CPU, RAM, storage and cache. Select a time range for recorded measurements.
+[How to interpret the readings →](performance.md#read-the-performance-page)
+
+![Performance Overview with traffic measurements](assets/performance-overview.png)
+
+![Performance Resources with CPU, memory and cache readings](assets/performance-resources.png)
+
+Values reflect this capture session and its deployment. They do not establish
+speed or memory requirements for other devices or servers.
+
+</details>
+
+## Configure your drive
+
+Open **Configuration** to inspect cache budgets, preloading, upload limits and
+timezone. Use defaults first, change one category, and save that category to
+apply it. The public visitor demo keeps these settings read-only.
+[Settings, defaults and bounds →](configuration.md)
+
+<details>
+<summary>Cache, transfer and regional settings</summary>
+
+![Cache settings for memory, disk and preloading](assets/cache-settings.png)
+
+**Regenerate all thumbnails** rebuilds existing covers in the background after
+confirmation. It can consume bandwidth; the screenshots show its entry point,
+not a completed rebuild. [Thumbnail generation →](thumbnails.md)
+
+![Thumbnail rebuild entry point](assets/thumbnail-rebuild.png)
+
+**Transfer limits** includes uploads per bot, split size, temporary upload storage,
+URL download concurrency and Telegram request budgets. Large files are split
+automatically and still appear as one file. The screenshots do not demonstrate
+a multi-gigabyte transfer or prove its recovery behavior.
+
+![Upload, storage and Telegram transfer settings](assets/transfer-settings.png)
+
+![Regional timezone settings](assets/regional-settings.png)
+
+Appearance supports **Light**, **Dark** and **System** through its menu. Timezone
+affects displayed times; stored timestamps remain UTC.
+
+</details>
+
+## Connections and backups
+
+**Management → Connections** lists configured Telegram storage clients and
+connection controls. Adding a bot, signing in a Premium account or replacing
+credentials requires your own Telegram setup. These captures show website entry
+points; they do not demonstrate a new Telegram authentication.
+[Connections and credential changes →](usage.md#settings-and-connections)
+
+<details>
+<summary>Connections and Storage & Backups screens</summary>
+
+![Connections management entry points without private credentials](assets/connections.png)
+
+**Storage & Backups** distinguishes the saved catalog from temporary upload space.
+Database backups protect the catalog; optional independent channel protection
+copies completed documents too. A displayed screen is not proof of successful
+backup or recovery. Follow the guide, confirm restore points and keep matching
+keys outside the server. [Backup and recovery →](backup-recovery.md)
+
+![Storage & Backups status and management entry points](assets/storage-backups.png)
+
+</details>
+
+## Workflows beyond these recordings
+
+| Feature | How to use it |
+| --- | --- |
+| Telegram bot uploads | The standard setup configures your main bot and allowed users. Choose a destination in **Transfer limits → Bot uploads**, then send files privately to the bot. [Bot instructions](usage.md#optional-telegram-bot-interface) |
+| Multiple devices | Log in using the same owner password. Sessions are independent; logging out closes only that session. [Device access](usage.md#use-several-devices) |
+| Protected public samples | Browse **Demo Files**; create disposable uploads in **My Files**. Configuration and Management changes remain locked for visitors. [Demo guide](usage.md#try-the-public-demo) |
+| Background processing | Once server receipt is accepted, uploads can finish without the tab. URL imports and manual preloads also continue while TGDrive runs. [When to close the tab](usage.md#can-i-close-the-tab) |
+| Independent channel recovery | Prepare separate recovery access, wait for a confirmed restore point, then inspect and verify before activation. [Recovery procedures](backup-recovery.md) |
+| Install, upgrade or move hosts | Preserve MongoDB, Telegram access, secrets and persistent data. [Setup](setup.md) · [Operations](operations.md) |
+
+No bot messages, Premium sign-in, destructive recovery, full-drive cache clearing
+or full-library thumbnail rebuild are performed for these demonstrations.
+For capture provenance and replacement instructions, see the [media guide](assets/README.md).
diff --git a/docs/streaming-validation-2026-10-18.md b/docs/streaming-validation-2026-10-18.md
new file mode 100644
index 00000000..b8020f0e
--- /dev/null
+++ b/docs/streaming-validation-2026-10-18.md
@@ -0,0 +1,179 @@
+# Streaming validation — 18 October 2026
+
+[Docs home](README.md) · [Current performance guide](performance.md)
+
+This dated report reproduces a 17 MB playback failure, separating browser cache,
+server cache and delivery protocol. Results and deployment status describe
+**18 October 2026**; use the [performance guide](performance.md) for current guidance.
+
+> [!NOTE]
+> Live browser checks and synthetic server checks are identified separately below.
+> These results establish behavior on the tested paths, not performance on every network or device.
+
+**Contents**
+
+- [Findings](#findings)
+- [Fresh-browser controls](#fresh-browser-controls)
+- [Server-side integrity and backpressure](#server-side-integrity-and-backpressure)
+- [Player behavior and coverage](#player-behavior-and-coverage)
+- [Deployment and limits](#deployment-and-limits)
+
+## Findings
+
+Two independent problems were reproduced:
+
+1. **Delivery protocol.** The same 17,839,845-byte MP4 downloaded in **93.668 seconds over HTTP/3** and
+   **1.028 seconds over HTTP/2**. A direct IPv4 control reproduced the difference:
+   a 4 MiB range took 20.487 seconds over HTTP/3 and 0.436 seconds over HTTP/2.
+   All checksums matched. This isolates a QUIC-path bottleneck on the tested
+   connection, without identifying the responsible network component or claiming
+   that HTTP/3 is slow everywhere.
+2. **Transient buffer contention.** A suspended response could retain the entire global transient buffer. New
+   cached seeks and metadata reads then waited for that older client. The new
+   regression fails against the old reader and passes with reclamation of
+   speculative frames. Awaited/yielded frames and shared fills remain protected.
+
+Increasing retained RAM cannot fix either condition: retained cache and transient
+stream-delivery memory serve different purposes.
+
+## Fresh-browser controls
+
+<details>
+<summary>Cache isolation and test media</summary>
+
+Each browser run used a fresh Chromium context, disabled browser network caching
+through CDP and bypassed service workers. Recorded browser cache hits were zero.
+Server-cache state was recorded separately. Targeted eviction for cold runs
+removed only this disposable cache entry, preserving the original Telegram file,
+catalog and shares.
+
+The MP4 is 30.526667 seconds of 1920×1080 H.264 High/yuv420p with stereo AAC.
+Its SHA-256 is
+`d6617a009c0c6c9aebf7398d43cad6d1985ddc1b9ab0479e2ea977362b8af5b0`.
+
+</details>
+
+| Test | Ready after | First complete playback, wall time | Mid-play buffering | Frames |
+| --- | ---: | ---: | ---: | ---: |
+| Existing deployment, server warm, default HTTP/3 | 17.808 s | 63.295 s | 8 events | Frame freezes observed |
+| Existing deployment, Telegram cold, controlled HTTP/2 | 1.978 s | 30.626 s | 0 | 901 |
+| Corrected local app, disposable cache cold | 0.798 s | 30.571 s | 0 | 901 |
+| Existing deployment after proxy mitigation, server warm, default browser | 1.719 s | 30.597 s | 0 | 901 |
+| Existing deployment after mitigation, Telegram cold, default browser | 2.070 s | 30.623 s | 0 | 900/901 presented |
+
+The local case uses a synthetic Telegram transport over the exact actual bytes.
+The public Telegram-cold case uses the real deployed Telegram transport. Each
+transferred all 17,839,845 bytes across the browser network. Replay and seeks to
+14/28 seconds also worked in the smooth cases.
+
+A reversible domain-scoped proxy mitigation returned `Alt-Svc: clear`. A fresh
+default browser, with no transport flags, selected HTTP/2: the full GET took
+**0.835 seconds** and a 4 MiB range took **0.448 seconds**. TLS, original upstream
+services and existing gzip rules were preserved. No app/proxy restart was needed.
+The application default and both included Compose files carry this policy for
+ordinary deployments. A separate isolated Traefik probe caught duplicated
+advertisements with backend headers alone, so the Compose middleware applies
+the policy at the edge too. Coolify's installed route generator discovers it
+automatically; users do not need to supply router names or manual labels.
+
+## Server-side integrity and backpressure
+
+Bulk work ran entirely on the server in an isolated, loopback-only candidate
+limited to two CPUs and 4 GiB RAM. Source bytes came from a checksum-verified copy
+of a fully cached production MKV. The real HTTP/cache/preload/player paths used a
+read-only synthetic Telegram transport. These are server-local HTTP measurements,
+not public viewer bandwidth or Telegram-cold throughput.
+
+The actual file contains **1,644,186,037 bytes**. A second logical file exposes
+those same bytes through four parts of at most 512 MiB.
+
+| Check | Result |
+| --- | --- |
+| Full single-document download | 3.738 s; 419.498 MiB/s |
+| Full four-part download | 4.083 s; 384.059 MiB/s |
+| Whole-file integrity | Both match SHA-256 `7292f1239f3d3c223f41e9090ce455e125036820814eddf188a704431c5bfddc` |
+| All three part boundaries | Correct 206, lengths, ranges and matching 2 MiB checksums |
+| Five cached seeks with an older unread response still active | 37–48 ms; zero extra source reads |
+| Disk-only cached metadata seek | 7.96 ms; zero extra source reads |
+| Resume with strong If-Range validator | Correct 206, 8 MiB and checksum |
+| Unsatisfiable range | Correct 416 and total |
+| Full-file HEAD | Correct size/range headers; zero body |
+| Scratch memory | Peak 32 MiB; final bytes/streams/waiters all zero |
+
+The older unread response stayed active while new requests completed. Automated
+regressions also verify that the original reader resumes in byte order.
+
+Fresh-browser playback of both candidate MKVs verified actual 1080p H.264 frames,
+audible Japanese/English AAC tracks, English SRT/ASS cues and seeks to 120 seconds,
+the middle, near the end and back to ten seconds. These used bounded windows
+(approximately 327 MB/318 MB), rather than copying either entire MKV to the PC.
+Browser cache hits were zero and scratch memory returned to zero afterward.
+Initial readiness took 11.52 seconds for the single-document case and 7.79 seconds
+for the split case over the private SSH/browser test path. These checks establish
+working playback and seeking, not instant startup or public-route startup latency
+for large MKVs.
+The separate ASS track labelled Forced had no packets in the sampled dialogue
+windows; the full English ASS track rendered actual dialogue correctly.
+
+## Player behavior and coverage
+
+The custom player stays visible and usable while opening/seeking. The separate
+Start Playback gate and native Compatibility Playback fallback are removed.
+Normal play controls respect browser gesture requirements. Unsupported codecs
+produce an explicit in-player error; downloading the original remains available.
+
+Loading feedback shows received bytes/rate and estimated buffered coverage/ahead
+time. The timeline paints the engine's public buffered ranges, including while
+paused. These estimates describe media time, separately from server cache byte
+coverage; variable bitrate and decoder state can affect immediate playability.
+
+Browser fixtures now use production-shaped Telegram document identities and
+initialize the shared cache. Tests cover RAM/disk cache, actual Uvicorn/TCP
+backpressure, disconnect/resume, concurrent readers, multipart seams, conditional
+responses and resource cleanup.
+
+**Automated results recorded for this validation:**
+
+| Automated check | Result |
+| --- | --- |
+| Integrated Python suite, including isolated MongoDB and Node bridge | 947 passed; 15 subtests passed |
+| Final browser workflows with pooled-cache fixtures | 62 passed |
+| Frontend behavior | 180 Vitest tests passed |
+| TypeScript and production frontend build | Passed |
+| Packaging/setup/configuration audit | 71 passed |
+| Both supported Compose configurations | Validated with Docker Compose |
+| Public release packaging after adding this report | 3 passed |
+| Changed Python lint/format and whitespace checks | Passed |
+
+<details>
+<summary>Cancellation regression synchronization</summary>
+
+A cancellation regression originally waited for 100 zero-delay event-loop turns,
+which could finish before a filesystem worker ran. It now awaits an explicit
+origin-entry event before canceling; cancellation, shared-fill drainage, memory
+and lease assertions are unchanged.
+
+</details>
+
+## Deployment and limits
+
+Normal users should follow the standard setup/update flow. The build includes
+the player, delivery and response policy fixes; no debug scripts, cache migration
+or extra proxy labels are required. Keep one service instance/worker and the
+documented persistent volume. An external proxy that replaces application
+headers needs its own configuration checked.
+
+For diagnostics, distinguish browser-cold/server-warm from Telegram-cold, record
+the browser protocol/cache hits and verify actual transferred bytes. Compare
+HEAD/full GET, beginning/tail ranges, resume and a seek while an older response
+is unread. A fast Python HTTP/1.1 download alone does not prove browser delivery.
+
+This does not establish arbitrary public concurrency, every ISP, Safari/Firefox
+or physical Android/iOS behavior. Network, codec and device limits remain. No Git
+changes were pushed.
+
+The live app remained on its existing image during validation; only its temporary
+domain-scoped proxy correction was applied. Source/player/Compose fixes were
+committed locally on `dev` and still require publication and normal redeployment.
+Private validation containers, copied media/cache and the SSH test tunnel were
+removed. Production health remained successful.
diff --git a/docs/thumbnails.md b/docs/thumbnails.md
new file mode 100644
index 00000000..87da9227
--- /dev/null
+++ b/docs/thumbnails.md
@@ -0,0 +1,155 @@
+# Thumbnail generation
+
+[Docs home](README.md) · [Browse files](usage.md#browse-and-organize)
+
+TGDrive creates covers from files staged during upload. The original stays unchanged.
+
+| File | Cover |
+| --- | --- |
+| JPEG, PNG, WebP, GIF, BMP, TIFF | Scaled image; one frame for animation. |
+| MP4/M4V/MOV, MKV/WebM, AVI, WMV/ASF, MPEG | Random frame between 40% and 60% of the duration, with a first-frame fallback. |
+| PDF | First page. |
+| EPUB / CBZ / CBR | Declared EPUB raster cover (or first image); first naturally ordered comic page. |
+| MP3, FLAC, M4A, Ogg/Opus, WAV, AAC | Embedded artwork when the container and decoder expose it; otherwise an icon. |
+| DOCX/PPTX/XLSX, ODT/ODP/ODS | Embedded raster preview when the archive contains one. |
+| AVIF | Image if the installed decoder supports it. |
+
+**Contents**
+
+- [Bandwidth and storage](#bandwidth-and-storage)
+- [Rebuild existing thumbnails](#rebuild-existing-thumbnails)
+- [Existing files and fallback](#existing-files-and-fallback)
+- [Container dependencies](#container-dependencies)
+
+## Bandwidth and storage
+
+Grid view loads nearby thumbnails as needed, checking the local generated cover
+then Telegram's small thumbnail. A missing cover can also be repaired from a
+complete original already in the server cache. The grid never downloads original
+payloads from Telegram to create a cover.
+Data-saving browsers show icons. Every request checks current owner/share access,
+including cache hits and conditional responses.
+
+An optional missing cover returns **204 No Content**, keeping the format icon
+without a false missing-file error. MP3s without provider artwork and images whose
+decoding exceeds the worker budget retain icons. Giant TIFFs can exceed that
+budget even when their compressed file is available.
+
+## Rebuild existing thumbnails
+
+In **Tools & settings → Cache settings**, choose **Regenerate all thumbnails**.
+Review the warning about long runtimes and potentially substantial bandwidth,
+then confirm **Start background rebuild**. New uploads generate covers
+automatically; this action is for files already stored, including existing covers.
+
+<details>
+<summary>Find the thumbnail rebuild control</summary>
+
+![Thumbnail regeneration entry point in cache settings](assets/thumbnail-rebuild.png)
+
+This capture shows the control; it is not evidence that a full-library rebuild ran.
+
+</details>
+
+The Settings page shows files checked, regenerated/skipped/failed counts, the
+current filename, source bytes read and recent issues. It polls the server while
+open. You can leave the page, close the browser or return later; **Cancel rebuild**
+stops further work and keeps already generated covers. Source-byte counts include
+cached data and are not a network-usage meter.
+
+One run processes one file at a time and waits while transfers or media requests
+are active. New reads use the lower-priority media queue and are paced to at most
+2 MiB/s before cache/block overhead. A separate renderer at lower OS priority
+keeps manual work out of the automatic upload-thumbnail slot. Existing requests
+cannot be preempted, so shared CPU/disk/network work can still have a small cost.
+
+Videos/images use a private loopback range bridge to FFmpeg; it requests selected
+ranges through the shared cache rather than staging an entire movie. EPUB/comics
+and supported office archives read their index and chosen cover. Most sources
+have a **64 MiB cumulative read budget per file** and **four-minute file deadline**;
+book operations also retain their **32 MiB** parser budget. PDFs need a local
+seekable source, so rebuilding one may read the complete original up to **256 MiB**,
+with a free-space check and crash-cleaned private staging. Larger or more
+demanding files are skipped. Missing art,
+unsupported decoders, encrypted/solid archives and giant images may retain icons.
+
+Successful covers replace the disposable local cache and invalidate its previous
+small-image response. Originals, catalog records and Telegram messages stay
+unchanged; existing provider covers remain fallbacks. Cache limits below still
+apply, so a large run can evict earlier local covers. Failed regeneration retains
+any old cover. Files removed/changed during work are skipped; uploads arriving
+after the scan use normal automatic generation.
+
+Progress is saved locally between files and during reads when storage permits.
+After a server restart, the last run is marked **interrupted**; start another rebuild
+to continue refreshing covers. It does not silently restart a bandwidth-heavy job.
+Demo visitors cannot start or cancel a rebuild.
+
+## Existing files and fallback
+
+New uploads attach the generated cover to the first Telegram part and cache it
+locally. For an existing file with no provider cover, TGDrive can create a local
+cover when its complete original is cached and no larger than **128 MiB**.
+Choose **Preload file**, wait for full **Ready** coverage in **Preloads**, then
+return to its folder in Grid view. Repair does not upload a new Telegram cover
+or change the catalog; the disposable local JPEG can be reused afterward.
+
+For automatic warm-cache repair, cold, partial, larger, unsupported, damaged,
+encrypted or overly complex files keep provider covers/icons. Thumbnail failures never fail the original upload.
+MOV is a container: its codec, resolution and decoding cost still need to fit
+the installed decoder and rendering limits. A missing cover does not establish
+that the original file is damaged or unplayable.
+
+<details>
+<summary>Cache limits, rendering and container dependencies</summary>
+
+Generated JPEGs have a maximum 320-pixel edge and 64 KiB size. The disposable
+`CACHE_DIR/thumbnails` cache holds at most 128 MiB/4,096 entries, evicts older
+entries and avoids writes below 64 MiB free disk. It is separate from the media
+budget and excluded from metadata backups; attached Telegram covers are the fallback.
+Expired/deleted files remain inaccessible even if cached bytes survive.
+
+Warm-cache repair runs one file at a time within an eight-second copy/render
+deadline. It writes verified blocks to a private temporary file instead of joining
+the source in RAM, checks complete coverage and multipart checksums, and requires
+the source size plus the larger of 64 MiB or the configured cache free-space floor.
+Owned temporary sources stay locked through decoding; startup and later repairs
+remove unlocked crash leftovers without deleting active sources. Eviction, clearing,
+revocation or cancellation aborts safely and removes the temporary source.
+Negative thumbnail results are reconsidered when that file receives new cached
+data; metadata probes and cache hits do not trigger repeated rendering of a
+failed source. Temporary renderer/space/copy admission failures can retry without
+new source data. Ordinary missing-provider results remain briefly cached.
+
+Large JPEGs over 8 MiB use decoder downsampling before final scaling. EPUB/comic/office
+covers reuse the bounded archive parser (32 MiB read budget, 16 MiB/image), never
+extract archive paths or load remote resources, and pass recognized raster bytes through
+a forced image decoder. Existing cached covers are not automatically replaced;
+new uploads, explicit rebuilds and eligible warm-cache repairs use the updated
+renderer.
+
+Automatic rendering has one slot per process, a two-second admission wait and
+12-second operation timeout. Manual rebuilding has its own single background
+slot. Automatic video metadata probing is limited to 1.5 seconds. Extraction
+first seeks to a random position between 40% and 60% of the duration, with a
+six-second attempt timeout. If duration is unavailable, it seeks ten seconds
+into the file instead. If that attempt fails, it tries the first frame with a
+three-second timeout. This avoids most intros/credits but cannot guarantee a
+nonblack frame; partial JPEG output is rejected. Busy admission or exhausted
+rendering limits keep the provider-cover/icon fallback rather than delaying the
+upload indefinitely. The Linux renderer has an eight-second CPU limit and a 768 MiB
+virtual-address-space ceiling (including decoder reference frames, libraries and
+thread stacks, not a reserved amount of RAM), with one decoding/filter thread
+and a 64 MiB limit per allocation. These bounds accommodate tested UHD HEVC
+MOVs but do not guarantee every codec/resolution or low-memory container;
+forced demuxers and file/pipe-only local inputs block playlist/network loads.
+The manual worker accepts only its token-protected loopback HTTP source and uses
+a 120-second native deadline to accommodate paced range reads.
+
+## Container dependencies
+
+The TGDrive image includes FFmpeg and Poppler's `pdftoppm`; no host tool
+installation is needed. Rendering failures fall back to provider covers/icons.
+Keep the deployment image updated; resource bounds are not an OS security sandbox.
+
+</details>
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 00000000..28715c4e
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,655 @@
+# Using TGDrive
+
+[Docs home](README.md) · [Setup](setup.md) · [Help with problems](operations.md#troubleshooting)
+
+**Must read before using TGDrive: [New-user guide and FAQs](new-user-guide.md).**
+It covers essential limits, channel rules, privacy and backup responsibilities.
+
+Upload in **My Files**, follow progress in **Transfers**, and share only what
+you choose.
+
+Prefer a visual introduction? [Open the gallery and walkthrough videos](showcase.md).
+
+**Contents**
+
+- [Use several devices](#use-several-devices)
+- [Try the public demo](#try-the-public-demo)
+- [Find your way around](#find-your-way-around)
+- [Upload files or folders](#upload-files-or-folders)
+  - [Upload speed and queue](#upload-speed-and-queue)
+  - [Files above 2 GB](#files-above-2-gb)
+  - [What upload progress means](#what-upload-progress-means)
+  - [Can I close the tab?](#can-i-close-the-tab)
+- [Transfer history](#transfer-history)
+- [Browse and organize](#browse-and-organize)
+  - [Starred files and folders](#starred-files-and-folders)
+  - [Search](#search)
+- [Open, preview, and download](#open-preview-and-download)
+- [Preload a file for smoother playback and downloads](#preload-a-file-for-smoother-playback-and-downloads)
+  - [Parallel and resumed downloads](#parallel-and-resumed-downloads)
+- [Share and revoke](#share-and-revoke)
+- [Trash and permanent deletion](#trash-and-permanent-deletion)
+- [Import from a URL](#import-from-a-url)
+- [Settings and connections](#settings-and-connections)
+  - [Storage and backup](#storage-and-backup)
+  - [Upload through your Telegram bot](#optional-telegram-bot-interface)
+
+## Use several devices
+
+When your hosted server is reachable over the internet, open TGDrive in a browser
+on your phone, tablet or computer to use the same drive on the go.
+
+You can sign in on several devices or browsers with the same owner password and
+use them at the same time. Each login has its own session; signing in again does
+not disconnect other devices, and **Log Out** signs out only that session.
+Tabs in the same browser profile share their session.
+
+Multiple trusted people can also use the drive at once with the same owner
+password. They share full access to its files and settings, with no separate
+personal accounts or per-person permissions. Use read-only share links for people
+who should only access selected files or folders.
+
+## Try the public demo
+
+**[Open the live demo](https://tgdrive.nexgenbots.us/)** · **Password:** `password12345`
+
+Enter the public password on the sign-in page. No installation is needed.
+
+**Demo Files** contains the operator's sample collection. You can browse, preview
+and download it, but attempts to change the folder or its contents open a
+read-only notice. Choose **Open My Files** in that notice to upload or organize
+your own test files outside the protected folder.
+
+Try browsing, uploading disposable sample files, organizing folders, previews,
+downloads, sharing and preloads. **Configuration** and **Management** pages can
+be viewed, but their settings and management actions are locked. Recovery keys
+cannot be downloaded.
+
+> [!IMPORTANT]
+> Everyone shares the same files and changes. Other visitors can edit or delete
+> files outside Demo Files. Use non-private, disposable content and keep your own copy.
+> Do not rely on the demo to store files; automatic resets are not provided by demo mode.
+
+Hosting a demo? See [Public demo mode](configuration.md#public-demo-mode).
+
+## Find your way around
+
+| Sidebar page | Use it to… |
+| --- | --- |
+| **My Files** | Browse, search and organize files |
+| **Transfers** | See queued/running work and past completed, failed or cancelled transfers |
+| **Shared Links** | Review or revoke links |
+| **Starred** | Quickly find files and folders you marked |
+| **Trash** | Restore files or delete them permanently |
+| **Monitor → Performance** | Inspect current server resources, Telegram activity and measured traffic |
+| **Monitor → Preloads** | Prepare files for faster access, see which parts are cached, stop preparation or clear cached copies |
+| **Management → Connections** | Manage Telegram bots, Premium accounts and API credentials |
+| **Management → Storage & Backups** | Check saved data, temporary storage and database backups |
+| **Configuration → Cache settings** | Choose memory/disk cache limits, how long copies are kept and automatic preloading |
+| **Configuration → Transfer limits** | Set upload concurrency, splitting and shared Telegram request budgets |
+| **Configuration → Timezone** | Choose the installation's timezone |
+
+Choose Light, Dark or System in the appearance menu. **Log Out** closes this
+browser's access; server transfers continue. See [configuration](configuration.md)
+for defaults and tuning.
+
+**Refresh** and **Check Again** show progress and stay disabled until their
+requests finish. A successful refresh shows a brief confirmation; failures show
+an error so you can retry. Automatic background updates stay quiet.
+If configuration refresh fails, open settings keep their unsaved drafts while
+management controls stay disabled. Retry the refresh to continue editing.
+
+## Upload files or folders
+
+1. Open the destination folder in **My Files**.
+2. Choose **New → Upload files** or **New → Upload folder**.
+3. Select the files or folder. For a folder, confirm the short upload summary.
+4. Follow the tasks in **Transfers**. Keep the tab open until **You can close this
+   tab** appears; wait for **Completed** before deleting your originals.
+
+You can also drag files into the file area. Each ordinary file or URL is its own
+task, even when several files are selected together. Only a folder upload forms
+an expandable group; select its name/chevron for individual states, or **Show
+Folder** to reveal its directory. A folder stays **Running** while any file is active, then
+**Queued** while work remains, then **Finished** (successful, failed or cancelled).
+
+### Upload speed and queue
+
+Device-to-server and server-to-Telegram uploads run independently.
+Defaults are usually the best starting point.
+
+<details>
+<summary>Upload concurrency and large-file scheduling</summary>
+
+#### Telegram upload capacity
+
+**Configuration → Transfer limits → Parallel uploads** allows **1–4 per bot**,
+default **1**. Changes apply immediately; lowering the limit lets running work
+finish. Large-file parts use eligible slots, preferring available Premium
+clients with bot fallback. All accounts share the same split cap.
+More slots do not remove Telegram cooldowns or guarantee speed.
+Splitting controls document size; pipelining overlaps requests within a document.
+See [performance tradeoffs](performance.md).
+
+#### Automatic device upload concurrency
+
+Device uploads start with **two files**, adapting between **one and four** using
+measured total throughput. Failures/stalls reduce new concurrency; running files
+continue. Background pauses and server confirmation time are excluded.
+Each file queues for Telegram once the server has verified and accepted its
+bytes; it does not wait for the rest of the batch. If temporary upload storage
+fills, remaining files wait/retry; smaller files may proceed when they fit. Keep
+the tab open until **You can close this tab** appears. Small batches may finish
+before adaptation.
+New batches share device-upload slots fairly with existing batches, so adding a
+folder does not wait for earlier Telegram work or an entire device batch.
+See [measurement rules](architecture.md#adaptive-device-upload-concurrency).
+
+</details>
+
+### Files above 2 GB
+
+**Splitting is automatic; Premium is optional.** Files appear as one item;
+downloads reconstruct original bytes and seeking crosses part boundaries.
+Database backups retain part mappings; independent backup copies the documents.
+
+Default: **16 GiB per file**, subject to temporary upload space. Telegram documents use
+at most **2000 MiB** for every account; **File split size** can lower that
+(0 also means 2000 MiB). See [capacity limits](reference.md#file-capacity-staging-and-work-limits)
+and [backup coverage](backup-recovery.md).
+
+### What upload progress means
+
+| Stage | What is happening |
+| --- | --- |
+| Uploading from your device | Your browser is sending bytes to the TGDrive machine |
+| Queued | Waiting for an available upload slot |
+| Uploading to Telegram | Sending file contents; they may not yet be posted as channel messages |
+| Publishing to the channel | Finishing channel messages and saving the file record |
+| Completed | The file and its record are confirmed |
+
+The panel shows **device progress first** while any file from this browser still
+needs to be received and accepted by the server. Files and folders already
+accepted show **Received** without Telegram progress, speed or estimated time
+remaining. Once all remaining files are accepted, the panel switches to Telegram
+progress. Telegram work continues in the background throughout. Single-file
+uploads omit redundant file-count summaries. Running/Queued counts include only
+unfinished files; a folder's file count includes its completed files.
+
+Time remaining estimates the bytes left in the displayed stage using recent
+transfer speed. Folder measurements continue across individual file handoffs,
+including small files that finish between updates. Estimates disappear when
+progress goes stale, work is blocked or only server confirmation/publication
+remains; those waits have no reliable byte-based duration.
+
+**A full device bar alone is not a completed upload.** Keep the tab open during
+server confirmation. **You can close this tab** confirms that the remaining work
+can continue on the server; another batch still sending device bytes keeps the
+close warning active. Resuming keeps the bytes the server has already confirmed.
+
+<details>
+<summary>See upload progress</summary>
+
+![Expanded upload panel showing device progress, speed, time remaining and Keep this tab open](assets/upload-progress.png)
+
+![Completed uploads in the transfer panel](assets/upload-completed.png)
+
+[Watch the upload and sharing walkthrough](assets/upload-and-share.mp4).
+
+**Uploading to Telegram** includes unfinished parallel parts. **Parts in Channel**
+counts confirmed messages. My Files receives the item after every part is confirmed.
+Batches count bytes for the displayed stage without adding device and Telegram
+bytes together.
+
+</details>
+
+### Can I close the tab?
+
+| Upload state | Can I close the tab? |
+| --- | --- |
+| **Still sending from your device** | Keep it open, or reselect the originals later to resume. Leaving early triggers a browser warning. |
+| **You can close this tab** | Yes. Telegram uploading continues while TGDrive stays running. |
+| **Completed** | Yes. This upload no longer needs the local source. |
+
+To resume, use **Choose files / Choose folder / Choose file** in the existing
+batch and select the same originals. TGDrive checks the received bytes, then sends
+only what is still missing. Use the existing **Retry**
+action after failure to avoid duplicates.
+
+Temporary connection and server errors retry automatically once TGDrive has
+confirmed an upload session. Keep the tab open and the original files available
+while it retries. If retries stop, read the file's error and use **Retry** (or
+**Retry Failed** on a folder). An interrupted session-creation request still needs manual
+retry because the browser may not have received its session identity.
+
+Cancel may take time after Telegram work begins. **Cancel all** confirms the
+currently selected unfinished work; completed files and later uploads are kept.
+Desktop **Hide/Show** only collapses the panel; **Clear finished** only clears its list.
+
+<details>
+<summary>Folder upload limits and interrupted preparation</summary>
+
+- The chosen folder becomes a new root. An existing name is kept alongside it;
+  folders are not silently merged or overwritten.
+- Relative subfolders and same-named files in different folders are preserved.
+- The picker supports up to 1,000 files and 1,000 discovered folders, subject to
+  path and request-size limits.
+- Empty folders are not supplied by the browser's picker. Empty or oversized
+  files are listed as skipped.
+- Keep the confirmation open while TGDrive prepares the folder tree. Retry in
+  that dialog reuses the preparation. Closing before files are queued can leave
+  an empty tree; choosing again can create another root.
+- Once files are queued, use the existing batch to resume. If copied files no
+  longer match in bulk, choose them individually.
+- Files uploaded into a shared folder inherit that folder's access.
+
+[Protocol and exact bounds](reference.md#atomic-folder-preparation)
+
+</details>
+
+## Transfer history
+
+**Transfers** keeps **Running** and **Queued** above finished history.
+Filter finished work by **All / Successful / Failed / Cancelled**; search finds
+names across history pages and current browser uploads. A search/filter change
+returns to page 1. Each finished page holds up to **20 tasks**: a folder counts
+once, and each ordinary file or URL counts separately. Use the page numbers or
+arrow buttons to navigate. A folder's files stay together; matching its name or
+any child's name keeps that whole folder in the search results.
+
+Double-click a completed file or choose **Show in folder** to highlight it;
+folder batches have **Show folder**. Moves/renames are followed. Trashed or
+deleted items become unavailable; unfinished/failed rows do not navigate.
+
+Choose **Clear history** beside the finished filters, then confirm to remove
+successful, failed and cancelled entries across all pages, regardless of the
+current filter or search. This also removes entries for deleted files and cannot
+be undone. Stored files, queued/running uploads and transfers waiting for an
+original file are kept. Folders with unfinished uploads keep their member rows;
+clear again after they finish. Saved server history is cleared for all devices;
+browser-only history is cleared in the browser you use.
+
+On phones, the bottom upload status opens Transfers. The desktop floating panel
+shows this browser's work; Transfers also shows other devices' server jobs.
+Clearing the panel does not erase saved history. Finished history survives
+restart until manually cleared; previously expired records cannot be recreated.
+Start uploads in a destination in **My Files** using **New**.
+
+<details>
+<summary>History storage and limits</summary>
+
+Folder uploads save their explicit selection and grouping on the server for
+other devices and reloads. Individually selected files remain separate, including
+files with similar names or paths. Compact MongoDB summaries are included
+in encrypted backups, omit payloads/source URLs/private recovery context, and
+consume database space. Device-only work remains browser-scoped and needs originals.
+
+</details>
+
+## Browse and organize
+
+| Action | How |
+| --- | --- |
+| Select | Choose Select to turn on selection mode; icons remain visible beside checkboxes |
+| Open a file or folder with a mouse | Double-click, use Enter on its focused name, or choose Open |
+| Open on a touch screen | Tap once |
+| Select several items | Choose Select, then tap rows or check their boxes |
+| Clear selection | Done or Escape |
+| Create a folder | New → New folder |
+| Rename, move or trash | Open the item's menu, or use the selection actions |
+| Sort | Choose Name, Date Added or File Size, then Ascending or Descending |
+| Change view | Choose List view or Grid view |
+
+Folders stay first when sorting; click an active column to reverse order.
+The browser remembers list/grid view. Phones combine these controls in
+**View and sort**; Select/Done remains available.
+
+New supported uploads generate small covers without changing originals.
+Grid view fetches nearby thumbnails, not whole files; data-saving browsers use
+icons. An existing missing cover can be repaired after preloading the full original
+(up to 128 MiB), then returning to its folder in Grid view. See [thumbnail formats
+and limits](thumbnails.md). To refresh existing covers, use **Configuration →
+Cache settings → Regenerate all thumbnails**, review the bandwidth warning, and
+follow its background progress there. Name conflicts offer **keep both**
+or **skip**, without silent replacement.
+
+### Starred files and folders
+
+Use **Add to Starred / Remove from Starred** in an item's menu. Stars are owner
+bookmarks included in backups; removing one keeps the file. They follow moves/
+renames, hide while trashed and return on restore. They do not grant shared access.
+
+### Search
+
+Search finds names within the current page, not document contents:
+
+| Page | What search finds |
+| --- | --- |
+| **My Files** | File and folder names across your drive, with their locations |
+| **Transfers** | Current upload names and saved transfer names across all history pages |
+| **Trash** | Names of the trashed items available to restore or delete |
+| **Starred** | Names in your starred files and folders |
+| **Shared Links** | Names in your shared-link inventory |
+| **Preloads** | Cached filenames and preparation jobs |
+
+**Enter** searches immediately; **Escape** clears and returns My Files to the
+previous folder. Switching pages clears the query. **/** or **Ctrl/Cmd+K** focuses
+search outside an editing field. On phones, the search icon opens it; Close
+Search/Escape collapses an empty field.
+
+## Open, preview, and download
+
+Double-click with a mouse or tap on touch to preview. **Download** gets the
+original; **Escape** or browser **Back** closes the preview. Use the header's
+fullscreen control where supported. Non-video previews enter fullscreen with
+the toolbar visible; use the top-right icon to hide or show it. Video keeps its
+own player controls. Download the original if the device cannot decode it.
+
+Video playback uses available bandwidth to build about **90 seconds of buffer**,
+within a browser memory limit. Short clips can load completely. The player refills
+early so brief network dips and forward skips can use already fetched bytes;
+very high bitrate video may reach the memory limit sooner. See the
+[playback buffer policy](performance.md#browser-playback-buffer).
+
+Closing the preview releases its browser buffer. Reopening requests the file
+again; authorized requests reuse the server's cached chunks while available.
+Protected originals use `no-store`, so browser disk caching is not promised.
+
+When a non-video preview waits, it can show **Checking file**, **Waiting for
+Telegram capacity**, or **Receiving file**. Any wait estimate is approximate;
+the underlying queue counts Telegram operations, not people. Image and audio
+previews automatically retry a full Telegram queue at most twice, respecting the
+server's retry delay. Keep the preview open for those retries; after they are
+exhausted, use **Try Preview Again**. Other failures still need manual retry.
+Video uses its own playback/buffer status. Downloads use the browser's download
+controls, require a connected browser, and have no saved queue position after a
+server restart. See [shared-download limits](performance.md#shared-download-load-and-queues).
+
+| File | Preview |
+| --- | --- |
+| Images, including SVG | Image viewer |
+| PDFs up to 256 MiB | Continuous scrolling, zoom, Fit width and Fit page |
+| Video | Enhanced player with its own audio/subtitle controls |
+| Audio | Browser audio player |
+| Supported text and code | Read-only text; first 256 KiB |
+| EPUB | Chapter reader, text size and saved reading position |
+| CBZ and CBR | Comic pages, page fit and right-to-left navigation |
+| Other unsupported formats | Original download |
+
+PDFs, EPUB and comics request needed sections without automatically preloading
+the whole file. See
+[book/comic controls and practical limits](reading.md).
+
+<details>
+<summary>Video, PDF and keyboard controls</summary>
+
+| Control | Action |
+| --- | --- |
+| Video **K/Space**, **M**, arrows | Play/pause, mute, seek when focused |
+| Double-tap picture left/right | Seek 10 seconds; further taps add 10 seconds |
+| Single touch | Show/hide controls; outside an open menu, dismiss it |
+| Settings **Up/Down**, **Home/End**, **Enter/Space** | Navigate and select |
+| Settings **Escape** | Return from subpage, then close menu before preview |
+| **Chapters** | Movi's native chapter strip and seek-bar segments; also available in fullscreen |
+| **Settings → Quality** | Telegram alternatives, when available; preserves position/play state |
+| **Try again** after a long wait | Retry video preserving position/play state |
+| PDF **Fit width / Fit page** | Reading width / whole page; manual zoom leaves fit mode |
+
+Phones put chapters/picture in picture in Settings when available. Audio/subtitle
+choices depend on the file. **Ambient mode** uses the picture's colors;
+**Stable volume** softens volume changes; **Aspect** controls picture fit.
+Controls hide when idle but remain visible for keyboard focus.
+
+Use the native subtitle menu's **Add subtitle…** action for a local subtitle file;
+it stays in the browser. Chapters use embedded titles/times without extracting
+thumbnail frames from every chapter. The native player supplies track selection,
+speed, loop, HDR and picture controls when the file/browser supports them.
+
+The video timeline estimates the device's loaded ranges, separate from server
+cache coverage. Longer waits show **Waiting for video… / Loading this part…**.
+The animated status shows actual received bytes and current speed when available;
+these include seek/repeat reads, not a file-completion percentage. A compact status
+strip stays above the controls; longer waits add an inline retry action. Playback
+can start before the whole file is loaded.
+
+Video previews use Movi's browser-side player. **Software decoding on this
+device** means playback can be
+limited by the device even when download speed is fast; use **Download Original**
+to open a difficult file in a video app.
+Browsers may require a tap for sound; codec/fullscreen support varies by device.
+Image alternatives use **Preview quality**. Web uploads preserve original bytes;
+Telegram may not create lower-quality versions.
+
+</details>
+
+## Preload a file for smoother playback and downloads
+
+**Preload file** caches the **whole original on the server** before a movie,
+large download or busy share. It uses server storage/bandwidth; your device
+receives bytes when you play or download.
+
+1. Choose **My Files → file ⋯ → Preload file** and start.
+2. Follow **Monitor → Preloads**. **Ready** with full coverage means the whole
+   file is cached; blue segments mean partial coverage.
+3. Play, download or share normally. Recheck coverage before relying on it.
+
+Preloading continues with the tab closed while TGDrive runs; foreground playback/
+downloads take priority. **Cancel** keeps cached bytes; clearing cache keeps
+Telegram originals. Cached bytes can expire or be evicted after completion.
+Preloading is not a backup and does not keep a sleeping server online.
+
+<details>
+<summary>Automatic read-ahead, download managers and cache limits</summary>
+
+### What happens when I just open or stream a file?
+
+Preloading is optional. Requested sections are cached with bounded adaptive
+read-ahead. **Preload during playback** (default On) also warms upcoming original
+audio/video after sustained delivery, adjusting for bitrate and seeks.
+A first viewer does not trigger a whole-file preload; separate viewers may
+justify one within cache policy. One player's overlapping requests do not count
+as extra viewers. PDFs/books/comics stay sparse; lower-quality previews do not
+automatically preload the original. Manual preloading always targets the original.
+
+### Parallel and resumed downloads
+
+Use file **⋯ → Copy Download Link**, then paste into your download manager.
+This is a [read-only share link](#share-and-revoke), separate from your owner login.
+Managers can request ranges in parallel or resume; the manager must retain its
+own received-byte state. Downloads read ahead only within requested ranges,
+without warming unrelated gaps/the whole file. Shared cold blocks reuse origin
+fetches; Telegram alignment can fetch extra origin bytes while the response
+contains only the requested bytes. See [delivery policy](performance.md).
+
+### Storage, progress and limits
+
+The whole file must fit either the available memory cache or the disk cache,
+including overhead and other preparation jobs' reserved space. The two cache
+limits are not added together.
+If rejected, free space, raise **Configuration → Cache settings** or wait for
+other jobs. Larger files can still stream in chunks.
+Preloads sorts by newest downloaded data, not cache reads or page refreshes.
+Cache access needs a valid session/share. Cold seeks, Telegram/network delays and
+decoding can still buffer. See [cache limits](performance.md).
+
+</details>
+
+## Share and revoke
+
+1. Use the item's share action; optionally add a label.
+2. Choose one day, seven days, 30 days, no expiry or a custom date/time.
+3. Copy the link, or copy it later from **Shared Links**.
+
+> [!IMPORTANT]
+> Anyone with the link can read its contents, including a folder's accessible
+> descendants. Labels organize links; they do not restrict them to named people.
+
+Each item supports up to **100 independent links** with separate labels/expiries.
+Create additional links through the item's share action in **My Files**.
+**Shared Links** keeps one row per link, showing its purpose when labelled,
+location, creation time and expiry so links for the same item stay distinguishable.
+
+| Action | What it does |
+| --- | --- |
+| **Active / Expired / All** | Filter links by whether they still grant access. |
+| Copy icon | Copy this exact active link again; no replacement or extra link is created. |
+| **Edit link** | Change this link's label or expiry, including a custom date or no expiry. |
+| Click the name or **Show in folder** | Open its current directory and highlight the item. |
+| **Revoke link** | Confirm before blocking this link. Other links keep working. |
+
+Hover/focus/tap expiry for its exact time/timezone. Expired or unavailable links
+have a disabled copy icon with an explanation. If TGDrive cannot reconstruct
+a URL, such as after changing `SESSION_SECRET`, use its original copy; existing URLs
+keep working until expiry or revocation. Create any replacement through
+**My Files** and revoke the old link separately when appropriate.
+
+Explicit links survive moves/renames. Moving/restoring into a shared folder asks
+for confirmation; moving out removes inherited access but keeps explicit links.
+Trash revokes subtree links. Revocation stops future authorized stream blocks,
+not already downloaded copies. Invalid tokens fail even in an owner's browser.
+
+For download tools, use **Copy download link**, not an owner address that needs
+browser cookies. It creates or reuses a separate share labelled **Download link**;
+new links last **one day** and can be revoked in Shared Links. Keep the URL secret.
+
+## Trash and permanent deletion
+
+Each item shows **Deleted from: My Files / …** so you can identify its source
+folder before restoring or deleting it.
+
+- **Move to Trash:** hides the item while keeping its Telegram files.
+- **Restore:** brings it back, subject to name and access checks.
+- **Delete permanently:** removes the selected file/folder records, descendant
+  records and their shares from TGDrive's database after you confirm. Original
+  Telegram messages remain in the storage channel. It cannot be cancelled or
+  restored from Trash after completion.
+
+### Why permanent deletion keeps the Telegram files
+
+> [!WARNING]
+> **Original Telegram files remain after permanent deletion.** Removing an item
+> from TGDrive does not securely erase its contents from Telegram.
+
+Channel members may still read those messages; older backups may restore records.
+Recipient copies and caches also remain. Erasing Telegram originals separately
+requires an authorized account.
+
+<details>
+<summary>Deletion progress and retries</summary>
+
+Wait for the combined completion notice on **Trash**. Items remain listed while
+jobs run; failed items can be expanded/retried. Connection/list-refresh failures
+retry automatically. Backup protection checks or upload cleanup may delay removal.
+Running/failure details stay on Trash; successful notices dismiss after six
+seconds (paused on hover/focus) and do not return after navigation/reload.
+
+Retrying an older failed deletion job also removes only database records; it
+cannot restore Telegram messages that were previously erased. Independent backup
+protection still applies; see [backup and recovery](backup-recovery.md).
+
+</details>
+
+## Import from a URL
+
+Choose **New → Upload from URL** and enter a public HTTP(S) file URL.
+The dialog closes immediately and Transfers shows an animated **Checking source…**
+state while the server connects and checks the response. Source failures appear on
+that transfer with a retry action. You can keep browsing or cancel during checks;
+a percentage appears only when file bytes start arriving.
+
+TGDrive downloads to the server, then sends to Telegram. By default two imports
+receive at full speed. Others show **Queued · receiving slowly** when a slow source
+connection is available, **Waiting for a source connection** at the connection cap,
+or **Waiting for temporary storage** when temporary upload storage is full. Slow reception can help
+avoid idle timeouts, but cannot extend a link's fixed expiry. Change full-speed
+concurrency (1–8) in **Configuration → Transfer limits → URL downloads**.
+
+**Downloading from URL** measures source intake; the later Telegram upload has its
+own speed and progress. Parallel retrieval adapts automatically where supported.
+Use **Compatibility Mode** for sources that reject it. See
+[URL import performance](performance.md#url-import-intake) for bounds and fallbacks.
+
+After submission it continues with the tab closed while TGDrive runs.
+Temporary source interruptions retry automatically and show a countdown and
+attempt number. **Retry** is needed after the bounded retry budget is exhausted
+or after correcting a permanent error; intake restarts from the beginning.
+Private network URLs are blocked by default. URL jobs never need a device file;
+if the server job is gone, submit a new URL import.
+
+## Settings and connections
+
+Use **Management → Connections** for accounts/API credentials and
+[Configuration](configuration.md) for cache, transfer limits and timezone.
+
+| Action | Result |
+| --- | --- |
+| **Refresh** | Checks every enabled client's saved credentials and channel permissions; updates names |
+| **Manage** | Rename the local label, replace a credential, enable, disable or remove a client |
+| **Add storage bot** | Connect another administrator bot in the same channel |
+| **Connect Premium account** | Sign in with a phone number, Telegram code and optional two-step password |
+
+For an additional storage bot, create it in BotFather and give it administrator
+access to the same private channel with **Post Messages** and **Delete Messages**,
+then choose **Add storage bot**. Manage storage accounts here rather than adding
+tokens to your deployment configuration.
+
+Refresh runs in the background, skips disabled accounts and retries temporary
+failures with Telegram waits. Its confirmation means the checks were requested;
+watch each connection's result for verification. Keep at least one working
+storage bot.
+Revoked/lost-access connections are excluded and show a repair action;
+see [connection recovery](operations.md#revoked-tokens-removed-sessions-and-lost-channel-access).
+
+Finish/cancel pending transfers before changing accounts, enabled states or API
+credentials. Replacing credentials for the **same Telegram account** can repair
+pending work; keep other settings unchanged. Saved changes pause new uploads
+until you [restart TGDrive](operations.md#run-and-monitor).
+
+Blank replacement fields keep current secrets; secrets are never displayed back.
+The web password/storage channel are installation settings.
+
+### Storage and backup
+
+**Management → Storage & Backups → Saved to MongoDB** confirms the saved catalog,
+not completion of unfinished uploads.
+
+- **Temporary storage** is server disk reserved for unfinished uploads, not a Telegram storage limit.
+- **Back up now** makes a complete encrypted database copy in your private channel.
+  Automatic copies normally run hourly.
+- **Save recovery key** downloads the key needed to restore those copies.
+  Store it separately.
+
+Reconnect the same MongoDB after losing the local installation. For database
+loss, follow [backup and recovery](backup-recovery.md).
+
+<details>
+<summary>Upload through your Telegram bot</summary>
+
+<a name="optional-telegram-bot-interface"></a>
+
+The standard new-drive setup configures `MAIN_BOT_TOKEN` and
+`TELEGRAM_ADMIN_IDS`. Open that bot in a **private chat**; only the listed Telegram
+users can use it. Existing installations using only `BOT_TOKENS` can keep working
+without this interface, or enable it by adding a main bot token and allowed user
+IDs to their deployment configuration and restarting TGDrive.
+
+1. Open **Configuration → Transfer limits → Bot uploads** on the website.
+2. Click **Change folder**, browse to a destination, then click **Use this folder**.
+   To restore the default, click **Use default folder**.
+3. Send or forward files, photos, videos or audio to the bot. It shows **Saving…**,
+   then confirms the filename and destination. Send photos as files to preserve
+   their original quality.
+
+Default: **My Files / TGDriveBotModeFiles**, created on first use. The shared
+destination setting applies to every administrator's next file without restart.
+Existing imports keep their destination; moving/deleting it pauses new imports
+until an available folder is chosen.
+
+**/start**, **/help** explain uploads; **/current_folder** shows the destination;
+**/set_folder** links to its website setting (normal owner login, no token).
+The website address is remembered on save; optional `PUBLIC_URL` supplies it
+beforehand or when local access differs from the public domain.
+Bot imports lack the web queue's durability; see
+[known limits](roadmap.md#known-correctness-and-recovery-gaps).
+
+</details>
diff --git a/main.py b/main.py
deleted file mode 100644
index d37d89f0..00000000
--- a/main.py
+++ /dev/null
@@ -1,356 +0,0 @@
-from utils.downloader import (
-    download_file,
-    get_file_info_from_url,
-)
-import asyncio
-from pathlib import Path
-from contextlib import asynccontextmanager
-import aiofiles
-from fastapi import FastAPI, HTTPException, Request, File, UploadFile, Form, Response
-from fastapi.responses import FileResponse, JSONResponse
-from config import ADMIN_PASSWORD, MAX_FILE_SIZE, STORAGE_CHANNEL
-from utils.clients import initialize_clients
-from utils.directoryHandler import getRandomID
-from utils.extra import auto_ping_website, convert_class_to_dict, reset_cache_dir
-from utils.streamer import media_streamer
-from utils.uploader import start_file_uploader
-from utils.logger import Logger
-import urllib.parse
-
-
-# Startup Event
-@asynccontextmanager
-async def lifespan(app: FastAPI):
-    # Reset the cache directory, delete cache files
-    reset_cache_dir()
-
-    # Initialize the clients
-    await initialize_clients()
-
-    # Start the website auto ping task
-    asyncio.create_task(auto_ping_website())
-
-    yield
-
-
-app = FastAPI(docs_url=None, redoc_url=None, lifespan=lifespan)
-logger = Logger(__name__)
-
-
-@app.get("/")
-async def home_page():
-    return FileResponse("website/home.html")
-
-
-@app.get("/stream")
-async def home_page():
-    return FileResponse("website/VideoPlayer.html")
-
-
-@app.get("/static/{file_path:path}")
-async def static_files(file_path):
-    if "apiHandler.js" in file_path:
-        with open(Path("website/static/js/apiHandler.js")) as f:
-            content = f.read()
-            content = content.replace("MAX_FILE_SIZE__SDGJDG", str(MAX_FILE_SIZE))
-        return Response(content=content, media_type="application/javascript")
-    return FileResponse(f"website/static/{file_path}")
-
-
-@app.get("/file")
-async def dl_file(request: Request):
-    from utils.directoryHandler import DRIVE_DATA
-
-    path = request.query_params["path"]
-    file = DRIVE_DATA.get_file(path)
-    return await media_streamer(STORAGE_CHANNEL, file.file_id, file.name, request)
-
-
-# Api Routes
-
-
-@app.post("/api/checkPassword")
-async def check_password(request: Request):
-    data = await request.json()
-    if data["pass"] == ADMIN_PASSWORD:
-        return JSONResponse({"status": "ok"})
-    return JSONResponse({"status": "Invalid password"})
-
-
-@app.post("/api/createNewFolder")
-async def api_new_folder(request: Request):
-    from utils.directoryHandler import DRIVE_DATA
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"createNewFolder {data}")
-    folder_data = DRIVE_DATA.get_directory(data["path"]).contents
-    for id in folder_data:
-        f = folder_data[id]
-        if f.type == "folder":
-            if f.name == data["name"]:
-                return JSONResponse(
-                    {
-                        "status": "Folder with the name already exist in current directory"
-                    }
-                )
-
-    DRIVE_DATA.new_folder(data["path"], data["name"])
-    return JSONResponse({"status": "ok"})
-
-
-@app.post("/api/getDirectory")
-async def api_get_directory(request: Request):
-    from utils.directoryHandler import DRIVE_DATA
-
-    data = await request.json()
-
-    if data["password"] == ADMIN_PASSWORD:
-        is_admin = True
-    else:
-        is_admin = False
-
-    auth = data.get("auth")
-
-    logger.info(f"getFolder {data}")
-
-    if data["path"] == "/trash":
-        data = {"contents": DRIVE_DATA.get_trashed_files_folders()}
-        folder_data = convert_class_to_dict(data, isObject=False, showtrash=True)
-
-    elif "/search_" in data["path"]:
-        query = urllib.parse.unquote(data["path"].split("_", 1)[1])
-        print(query)
-        data = {"contents": DRIVE_DATA.search_file_folder(query)}
-        print(data)
-        folder_data = convert_class_to_dict(data, isObject=False, showtrash=False)
-        print(folder_data)
-
-    elif "/share_" in data["path"]:
-        path = data["path"].split("_", 1)[1]
-        folder_data, auth_home_path = DRIVE_DATA.get_directory(path, is_admin, auth)
-        auth_home_path= auth_home_path.replace("//", "/") if auth_home_path else None
-        folder_data = convert_class_to_dict(folder_data, isObject=True, showtrash=False)
-        return JSONResponse(
-            {"status": "ok", "data": folder_data, "auth_home_path": auth_home_path}
-        )
-
-    else:
-        folder_data = DRIVE_DATA.get_directory(data["path"])
-        folder_data = convert_class_to_dict(folder_data, isObject=True, showtrash=False)
-    return JSONResponse({"status": "ok", "data": folder_data, "auth_home_path": None})
-
-
-SAVE_PROGRESS = {}
-
-
-@app.post("/api/upload")
-async def upload_file(
-    file: UploadFile = File(...),
-    path: str = Form(...),
-    password: str = Form(...),
-    id: str = Form(...),
-    total_size: str = Form(...),
-):
-    global SAVE_PROGRESS
-
-    if password != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    total_size = int(total_size)
-    SAVE_PROGRESS[id] = ("running", 0, total_size)
-
-    ext = file.filename.lower().split(".")[-1]
-
-    cache_dir = Path("./cache")
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    file_location = cache_dir / f"{id}.{ext}"
-
-    file_size = 0
-
-    async with aiofiles.open(file_location, "wb") as buffer:
-        while chunk := await file.read(1024 * 1024):  # Read file in chunks of 1MB
-            SAVE_PROGRESS[id] = ("running", file_size, total_size)
-            file_size += len(chunk)
-            if file_size > MAX_FILE_SIZE:
-                await buffer.close()
-                file_location.unlink()  # Delete the partially written file
-                raise HTTPException(
-                    status_code=400,
-                    detail=f"File size exceeds {MAX_FILE_SIZE} bytes limit",
-                )
-            await buffer.write(chunk)
-
-    SAVE_PROGRESS[id] = ("completed", file_size, file_size)
-
-    asyncio.create_task(
-        start_file_uploader(file_location, id, path, file.filename, file_size)
-    )
-
-    return JSONResponse({"id": id, "status": "ok"})
-
-
-@app.post("/api/getSaveProgress")
-async def get_save_progress(request: Request):
-    global SAVE_PROGRESS
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"getUploadProgress {data}")
-    try:
-        progress = SAVE_PROGRESS[data["id"]]
-        return JSONResponse({"status": "ok", "data": progress})
-    except:
-        return JSONResponse({"status": "not found"})
-
-
-@app.post("/api/getUploadProgress")
-async def get_upload_progress(request: Request):
-    from utils.uploader import PROGRESS_CACHE
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"getUploadProgress {data}")
-
-    try:
-        progress = PROGRESS_CACHE[data["id"]]
-        return JSONResponse({"status": "ok", "data": progress})
-    except:
-        return JSONResponse({"status": "not found"})
-
-
-@app.post("/api/cancelUpload")
-async def cancel_upload(request: Request):
-    from utils.uploader import STOP_TRANSMISSION
-    from utils.downloader import STOP_DOWNLOAD
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"cancelUpload {data}")
-    STOP_TRANSMISSION.append(data["id"])
-    STOP_DOWNLOAD.append(data["id"])
-    return JSONResponse({"status": "ok"})
-
-
-@app.post("/api/renameFileFolder")
-async def rename_file_folder(request: Request):
-    from utils.directoryHandler import DRIVE_DATA
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"renameFileFolder {data}")
-    DRIVE_DATA.rename_file_folder(data["path"], data["name"])
-    return JSONResponse({"status": "ok"})
-
-
-@app.post("/api/trashFileFolder")
-async def trash_file_folder(request: Request):
-    from utils.directoryHandler import DRIVE_DATA
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"trashFileFolder {data}")
-    DRIVE_DATA.trash_file_folder(data["path"], data["trash"])
-    return JSONResponse({"status": "ok"})
-
-
-@app.post("/api/deleteFileFolder")
-async def delete_file_folder(request: Request):
-    from utils.directoryHandler import DRIVE_DATA
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"deleteFileFolder {data}")
-    DRIVE_DATA.delete_file_folder(data["path"])
-    return JSONResponse({"status": "ok"})
-
-
-@app.post("/api/getFileInfoFromUrl")
-async def getFileInfoFromUrl(request: Request):
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"getFileInfoFromUrl {data}")
-    try:
-        file_info = await get_file_info_from_url(data["url"])
-        return JSONResponse({"status": "ok", "data": file_info})
-    except Exception as e:
-        return JSONResponse({"status": str(e)})
-
-
-@app.post("/api/startFileDownloadFromUrl")
-async def startFileDownloadFromUrl(request: Request):
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"startFileDownloadFromUrl {data}")
-    try:
-        id = getRandomID()
-        asyncio.create_task(
-            download_file(data["url"], id, data["path"], data["filename"], data["singleThreaded"])
-        )
-        return JSONResponse({"status": "ok", "id": id})
-    except Exception as e:
-        return JSONResponse({"status": str(e)})
-
-
-@app.post("/api/getFileDownloadProgress")
-async def getFileDownloadProgress(request: Request):
-    from utils.downloader import DOWNLOAD_PROGRESS
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"getFileDownloadProgress {data}")
-
-    try:
-        progress = DOWNLOAD_PROGRESS[data["id"]]
-        return JSONResponse({"status": "ok", "data": progress})
-    except:
-        return JSONResponse({"status": "not found"})
-
-
-@app.post("/api/getFolderShareAuth")
-async def getFolderShareAuth(request: Request):
-    from utils.directoryHandler import DRIVE_DATA
-
-    data = await request.json()
-
-    if data["password"] != ADMIN_PASSWORD:
-        return JSONResponse({"status": "Invalid password"})
-
-    logger.info(f"getFolderShareAuth {data}")
-
-    try:
-        auth = DRIVE_DATA.get_folder_auth(data["path"])
-        return JSONResponse({"status": "ok", "auth": auth})
-    except:
-        return JSONResponse({"status": "not found"})
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100755
index 00000000..6623c269
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,73 @@
+[project]
+name = "tgdrive"
+version = "2.0.0"
+description = "A secure Telegram-backed personal file drive"
+readme = "README.md"
+requires-python = "==3.14.8"
+license = "MIT"
+dependencies = [
+    "aiofiles==25.1.0",
+    "aiohttp==3.14.5",
+    "argon2-cffi==25.1.0",
+    "cryptg==0.6.0",
+    "cryptography==50.0.2",
+    "defusedxml==0.7.1",
+    "fastapi==0.143.5",
+    "libarchive-c==5.3",
+    "pydantic-settings==2.16.0",
+    "pymongo==4.19.0",
+    "python-multipart==0.0.32",
+    "telethon==1.45.0",
+    "uvicorn[standard]==0.54.0",
+]
+
+[dependency-groups]
+dev = [
+    "bandit[toml]==1.9.4",
+    "httpx2==2.13.1",
+    "pip-audit==2.10.1",
+    "pytest==9.1.1",
+    "pytest-asyncio==1.4.0",
+    "pytest-cov==7.1.0",
+    "ruff==0.17.1",
+]
+e2e = [
+    "playwright==1.64.0",
+]
+
+[tool.uv]
+package = false
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = ["e2e: opt-in browser tests against a local synthetic backend"]
+
+[tool.coverage.run]
+branch = true
+source = ["tgdrive"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+extend-exclude = [".venv", "cache", "data"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "S", "SIM", "RUF"]
+ignore = [
+    "S101", # Assertions are appropriate in tests and internal invariants.
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S105", "S106", "S311", "ASYNC109", "ASYNC240"]
+
+[tool.bandit]
+exclude_dirs = [".venv", "tests"]
+skips = ["B101"]
diff --git a/render.yaml b/render.yaml
deleted file mode 100644
index 16eb8c48..00000000
--- a/render.yaml
+++ /dev/null
@@ -1,24 +0,0 @@
-services:
-  # A Docker web service
-  - type: web
-    name: tgdrive
-    repo: https://github.com/TechShreyash/TGDrive
-    runtime: python
-    branch: main
-    plan: free
-    autoDeploy: false
-    buildCommand: pip install -r requirements.txt
-    startCommand: uvicorn main:app --host 0.0.0.0 --port $PORT
-    envVars:
-      - key: ADMIN_PASSWORD
-        sync: false
-      - key: API_ID
-        sync: false
-      - key: API_HASH
-        sync: false
-      - key: BOT_TOKENS
-        sync: false
-      - key: STORAGE_CHANNEL
-        sync: false
-      - key: DATABASE_BACKUP_MSG_ID
-        sync: false
diff --git a/requirements.txt b/requirements.txt
deleted file mode 100644
index 517da645..00000000
--- a/requirements.txt
+++ /dev/null
@@ -1,11 +0,0 @@
-https://github.com/KurimuzonAkuma/pyrogram/archive/dev.zip
-tgcrypto
-uvicorn
-fastapi[all]
-python-dotenv
-aiofiles
-aiohttp
-curl_cffi
-techzdl>=1.2.6
-tqdm
-dill
\ No newline at end of file
diff --git a/runtime.txt b/runtime.txt
deleted file mode 100644
index 08f31189..00000000
--- a/runtime.txt
+++ /dev/null
@@ -1 +0,0 @@
-python-3.11
\ No newline at end of file
diff --git a/sample.env b/sample.env
deleted file mode 100644
index 30b52cc8..00000000
--- a/sample.env
+++ /dev/null
@@ -1,7 +0,0 @@
-# Required Vars
-
-API_ID=123456
-API_HASH=dagsjdhgjfsahgjfh
-BOT_TOKENS=21413535:gkdshajfhjfakhjf
-STORAGE_CHANNEL=-100123456789
-DATABASE_BACKUP_MSG_ID=123
\ No newline at end of file
diff --git a/scripts/brand-assets.py b/scripts/brand-assets.py
new file mode 100644
index 00000000..89817331
--- /dev/null
+++ b/scripts/brand-assets.py
@@ -0,0 +1,69 @@
+# /// script
+# requires-python = "==3.14.8"
+# dependencies = ["cairosvg>=2.8,<3", "pillow>=12,<13"]
+# ///
+"""Render TGDrive's checked-in SVG masters: uv run --script scripts/brand-assets.py.
+
+The approved Interlock logo is outlined in the SVG masters; rendering never
+depends on installed fonts or the original image-generation output.
+"""
+
+from io import BytesIO
+from pathlib import Path
+
+import cairosvg
+from PIL import Image
+
+BRAND = Path(__file__).resolve().parents[1] / "website/public/static/brand"
+RESAMPLE = Image.Resampling.LANCZOS
+
+
+def render(name: str, width: int, height: int | None = None) -> Image.Image:
+    """Supersample curved edges, including the 16px browser-tab icon."""
+    options = {"output_width": width * 4}
+    if height is not None:
+        options["output_height"] = height * 4
+    png = cairosvg.svg2png(url=str(BRAND / name), **options)
+    with Image.open(BytesIO(png)) as source:
+        target_height = height or round(source.height / 4)
+        return source.convert("RGBA").resize((width, target_height), RESAMPLE)
+
+
+def save(image: Image.Image, name: str) -> None:
+    image.save(BRAND / name, optimize=True)
+
+
+def white_matte(image: Image.Image) -> Image.Image:
+    background = Image.new("RGBA", image.size, "white")
+    background.alpha_composite(image)
+    return background.convert("RGB")
+
+
+def main() -> None:
+    icon_source = (BRAND / "tgdrive-icon.svg").read_bytes()
+    (BRAND / "favicon.svg").write_bytes(icon_source)
+
+    for name in ("tgdrive-icon", "tgdrive-logo", "tgdrive-logo-dark"):
+        width = 512 if name == "tgdrive-icon" else 2010
+        save(render(f"{name}.svg", width), f"{name}.png")
+
+    for size in (16, 32, 48):
+        save(render("favicon.svg", size, size), f"favicon-{size}.png")
+    render("favicon.svg", 256, 256).save(
+        BRAND / "favicon.ico", sizes=[(16, 16), (32, 32), (48, 48)]
+    )
+
+    for size in (192, 512):
+        icon = white_matte(render("tgdrive-icon.svg", size, size))
+        save(icon, f"app-icon-{size}.png")
+    save(white_matte(render("tgdrive-icon.svg", 180, 180)), "apple-touch-icon.png")
+
+    preview = Image.new("RGBA", (1200, 630), "white")
+    logo = render("tgdrive-logo.svg", 980)
+    preview.alpha_composite(logo, ((1200 - logo.width) // 2, (630 - logo.height) // 2))
+    save(preview.convert("RGB"), "social-preview.png")
+    print(f"Rendered TGDrive brand assets in {BRAND}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/build_release.py b/scripts/build_release.py
new file mode 100644
index 00000000..24328ad6
--- /dev/null
+++ b/scripts/build_release.py
@@ -0,0 +1,278 @@
+"""Build a reproducible public source ZIP without local credentials or state."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import tomllib
+import zipfile
+from pathlib import Path
+
+ROOT_FILES = (
+    ".dockerignore",
+    ".editorconfig",
+    ".env.example",
+    ".gitattributes",
+    ".gitignore",
+    ".python-version",
+    ".vscode/settings.json",
+    "AGENTS.md",
+    "Dockerfile",
+    "LICENSE",
+    "README.md",
+    "compose.yaml",
+    "compose.override.yaml",
+    "compose.server.yaml",
+    "pyproject.toml",
+    "uv.lock",
+    "website/package.json",
+    "website/package-lock.json",
+    "website/vendor/README.md",
+    "website/vendor/manifest.json",
+    "website/vendor/movi-player-0.4.1-tgdrive.1.tgz",
+    "website/vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz",
+    "website/public/third-party/README.txt",
+    "website/public/third-party/movi-player-LICENSE.txt",
+    "website/public/third-party/movi-player-TGDrive-patch-NOTICE.txt",
+    "website/public/third-party/movi-player-0.4.1-sources.tar.gz",
+    "website/public/third-party/FFmpeg-LGPL-2.1.txt",
+    "website/public/third-party/pdfjs-LICENSE.txt",
+    "website/public/third-party/pdfjs-TGDrive-patch-NOTICE.txt",
+    "website/public/third-party/react-LICENSE.txt",
+    "website/public/third-party/react-dom-LICENSE.txt",
+    "website/public/third-party/scheduler-LICENSE.txt",
+    "website/public/third-party/lucide-react-LICENSE.txt",
+    "website/public/third-party/octicons-MIT.txt",
+    "website/public/third-party/Inter-OFL-1.1.txt",
+    "website/public/third-party/ui-components-LICENSES.txt",
+    "website/public/static/fonts/InterVariable.woff2",
+    "tests/fixtures/multitrack.mkv",
+    "tests/fixtures/movtext-subtitles.mp4",
+    "tests/fixtures/software-mpeg4.wmv",
+    "tests/fixtures/unsupported-msmpeg4.wmv",
+)
+SOURCE_TREES = {
+    ".github": {".yaml", ".yml"},
+    "scripts": {".py"},
+    "tests": {".py", ".cjs"},
+    "tgdrive": {".py"},
+    "website": {
+        ".html",
+        ".css",
+        ".js",
+        ".cjs",
+        ".ts",
+        ".tsx",
+        ".json",
+        ".svg",
+        ".png",
+        ".ico",
+        ".woff2",
+    },
+}
+PUBLIC_DOCS = (
+    "docs/README.md",
+    "docs/new-user-guide.md",
+    "docs/showcase.md",
+    "docs/setup.md",
+    "docs/hosting.md",
+    "docs/release.md",
+    "docs/usage.md",
+    "docs/reading.md",
+    "docs/thumbnails.md",
+    "docs/architecture.md",
+    "docs/operations.md",
+    "docs/backup-recovery.md",
+    "docs/configuration.md",
+    "docs/development.md",
+    "docs/roadmap.md",
+    "docs/reference.md",
+    "docs/performance.md",
+    "docs/performance-tuning.md",
+    "docs/streaming-validation-2026-10-18.md",
+    "docs/assets/README.md",
+    "docs/assets/audio-preview.png",
+    "docs/assets/cache-settings.png",
+    "docs/assets/comic-reader.png",
+    "docs/assets/connections.png",
+    "docs/assets/drive-dark.png",
+    "docs/assets/drive-list.png",
+    "docs/assets/drive-overview.png",
+    "docs/assets/epub-reader.png",
+    "docs/assets/file-actions.png",
+    "docs/assets/image-preview.png",
+    "docs/assets/media-preview.png",
+    "docs/assets/mobile-drive.png",
+    "docs/assets/pdf-reader.png",
+    "docs/assets/performance-overview.png",
+    "docs/assets/performance-resources.png",
+    "docs/assets/preloads.png",
+    "docs/assets/regional-settings.png",
+    "docs/assets/search-and-sort.png",
+    "docs/assets/share-link.png",
+    "docs/assets/shared-folder.png",
+    "docs/assets/shared-links.png",
+    "docs/assets/starred-files.png",
+    "docs/assets/storage-backups.png",
+    "docs/assets/text-preview.png",
+    "docs/assets/tgdrive-v2-banner.png",
+    "docs/assets/thumbnail-rebuild.png",
+    "docs/assets/transfer-history.png",
+    "docs/assets/transfer-settings.png",
+    "docs/assets/trash-restore.png",
+    "docs/assets/upload-completed.png",
+    "docs/assets/upload-folder.png",
+    "docs/assets/upload-progress.png",
+    "docs/assets/url-import.png",
+    "docs/assets/video-settings.png",
+    "docs/assets/organize-files.mp4",
+    "docs/assets/readers-and-preview.mp4",
+    "docs/assets/upload-and-share.mp4",
+)
+
+ZIP_TIMESTAMP = (1980, 1, 1, 0, 0, 0)
+EXCLUDED_PARTS = {
+    "__pycache__",
+    "node_modules",
+    "dist",
+    "coverage",
+    ".vite",
+    ".impeccable",
+    ".agents",
+    ".codex",
+}
+
+
+def source_files(root: Path) -> list[Path]:
+    """Select only reviewed source locations; never traverse runtime folders."""
+    selected: list[Path] = []
+    for name in (*ROOT_FILES, *PUBLIC_DOCS):
+        path = root / name
+        if not path.is_file():
+            raise FileNotFoundError(f"Missing required release source: {name}")
+        selected.append(path)
+    for directory, suffixes in SOURCE_TREES.items():
+        base = root / directory
+        if not base.is_dir():
+            raise FileNotFoundError(f"Missing required source directory: {directory}")
+        for path in base.rglob("*"):
+            if (
+                EXCLUDED_PARTS.intersection(path.relative_to(base).parts)
+                or path.name in {"skills-lock.json", "request-tracker.md"}
+                or path.suffix not in suffixes
+            ):
+                continue
+            if path.is_file():
+                selected.append(path)
+    for path in selected:
+        if path.is_symlink() or not path.resolve().is_relative_to(root.resolve()):
+            raise ValueError(f"Release source cannot be a symlink: {path}")
+        if any(parent.is_symlink() for parent in path.parents if parent != root):
+            raise ValueError(f"Release source parent cannot be a symlink: {path}")
+    return sorted(selected, key=lambda path: path.relative_to(root).as_posix())
+
+
+def _write_entry(archive: zipfile.ZipFile, name: str, content: bytes) -> None:
+    entry = zipfile.ZipInfo(name, date_time=ZIP_TIMESTAMP)
+    entry.create_system = 3
+    entry.external_attr = 0o100644 << 16
+    archive.writestr(
+        entry, content, compress_type=zipfile.ZIP_DEFLATED, compresslevel=9
+    )
+
+
+def check_version(root: Path, tag: str | None = None) -> str:
+    """Reject release metadata drift before CI or archive creation."""
+    metadata = tomllib.loads((root / "pyproject.toml").read_text(encoding="utf-8"))
+    version = metadata["project"]["version"]
+    if not isinstance(version, str) or not re.fullmatch(
+        r"(?:0|[1-9][0-9]*)(?:\.(?:0|[1-9][0-9]*)){2}", version
+    ):
+        raise ValueError("Release version must use major.minor.patch format")
+    package = json.loads((root / "website/package.json").read_text(encoding="utf-8"))
+    lock = json.loads((root / "website/package-lock.json").read_text(encoding="utf-8"))
+    lock_root = lock.get("packages", {}).get("", {})
+    uv_lock = tomllib.loads((root / "uv.lock").read_text(encoding="utf-8"))
+    versions = {
+        "website/package.json": package.get("version"),
+        "website/package-lock.json version": lock.get("version"),
+        "website/package-lock.json root package": lock_root.get("version"),
+        "uv.lock local project": next(
+            (
+                package.get("version")
+                for package in uv_lock.get("package", [])
+                if package.get("name") == metadata["project"]["name"]
+                and package.get("source") == {"virtual": "."}
+            ),
+            None,
+        ),
+    }
+    for name, pattern in (
+        ("tgdrive/__init__.py", r'^__version__\s*=\s*"([^"]+)"\s*$'),
+        ("Dockerfile", r'org\.opencontainers\.image\.version="([^"]+)"'),
+    ):
+        match = re.search(pattern, (root / name).read_text(encoding="utf-8"), re.M)
+        versions[name] = match.group(1) if match else None
+    for name, actual in versions.items():
+        if actual != version:
+            raise ValueError(
+                f"Release version mismatch: {name} is {actual!r}, expected {version!r}"
+            )
+    if tag is not None and tag != f"v{version}":
+        raise ValueError(f"Release tag must be v{version}, got {tag!r}")
+    return version
+
+
+def build_release(
+    root: Path, output_dir: Path, tag: str | None = None
+) -> tuple[Path, Path]:
+    root = root.resolve()
+    version = check_version(root, tag)
+    prefix = f"tgdrive-{version}"
+    contents = {
+        path.relative_to(root).as_posix(): path.read_bytes()
+        for path in source_files(root)
+    }
+    manifest = {
+        "project": "TGDrive",
+        "version": version,
+        "files": {
+            name: hashlib.sha256(content).hexdigest()
+            for name, content in contents.items()
+        },
+    }
+    output_dir.mkdir(parents=True, exist_ok=True)
+    archive_path = output_dir / f"{prefix}.zip"
+    with zipfile.ZipFile(archive_path, "w") as archive:
+        for name, content in contents.items():
+            _write_entry(archive, f"{prefix}/{name}", content)
+        _write_entry(
+            archive,
+            f"{prefix}/release-manifest.json",
+            (json.dumps(manifest, indent=2, sort_keys=True) + "\n").encode(),
+        )
+    checksum_path = output_dir / f"{prefix}.zip.sha256"
+    digest = hashlib.sha256(archive_path.read_bytes()).hexdigest()
+    checksum_path.write_text(f"{digest}  {archive_path.name}\n", encoding="ascii")
+    return archive_path, checksum_path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output-dir", type=Path, default=Path("dist"))
+    parser.add_argument("--check-version", action="store_true")
+    parser.add_argument("--tag", help="Require the release tag to match v<version>")
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parents[1]
+    if args.check_version:
+        print(f"Release version: {check_version(root, args.tag)}")
+        return
+    archive, checksum = build_release(root, args.output_dir.resolve(), args.tag)
+    print(f"Source archive: {archive}")
+    print(f"SHA-256 file: {checksum}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/vendor_viewers.py b/scripts/vendor_viewers.py
new file mode 100644
index 00000000..c8531ec3
--- /dev/null
+++ b/scripts/vendor_viewers.py
@@ -0,0 +1,309 @@
+"""Regenerate TGDrive's reviewed viewer packages; never used by normal builds.
+
+Run explicitly after reviewing the upstream identities and JavaScript recipes.
+The complete upstream packages, licenses, declarations and exports are retained.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import gzip
+import hashlib
+import hmac
+import io
+import json
+import subprocess
+import tarfile
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+MAX_ARCHIVE_BYTES = 128 * 1024**2
+MAX_PACKAGE_BYTES = 512 * 1024**2
+MAX_MEMBERS = 10_000
+
+
+@dataclass(frozen=True)
+class Viewer:
+    name: str
+    version: str
+    integrity: str
+    target: str
+    recipe: str
+    patch: str
+
+    @property
+    def local_version(self) -> str:
+        return self.version + "-tgdrive.1"
+
+    @property
+    def upstream_filename(self) -> str:
+        return f"{self.name}-{self.version}.tgz"
+
+    @property
+    def upstream_url(self) -> str:
+        return f"https://registry.npmjs.org/{self.name}/-/{self.upstream_filename}"
+
+    @property
+    def filename(self) -> str:
+        return f"{self.name}-{self.local_version}.tgz"
+
+
+VIEWERS = (
+    Viewer(
+        name="movi-player",
+        version="0.4.1",
+        integrity=(
+            "sha512-oA91s8nxyt7tnd7SaZNKVkjkz8UeHVrcZNxWQSBo5Jj/"
+            "MOog7pnGtwv0edimjwocJkZVBBtBMy8Ef4HOGzBJGQ=="
+        ),
+        target="dist/element.slim.js",
+        recipe="website/scripts/patch-movi-player.js",
+        patch="patchMoviSource",
+    ),
+    Viewer(
+        name="pdfjs-dist",
+        version="6.4.299",
+        integrity=(
+            "sha512-AVl138zALtfaAPvADulE0PZThbYzCBS79nL4pOSL/"
+            "6Sm/4AH5A21BD9VHt97OlCuzJuCpmeZtAtkinisF4Vb1g=="
+        ),
+        target="build/pdf.worker.mjs",
+        recipe="website/scripts/patch-pdf-worker.js",
+        patch="patchPdfSource",
+    ),
+)
+
+
+@dataclass(frozen=True)
+class Entry:
+    content: bytes | None
+    mode: int
+
+
+def sha256(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def integrity(content: bytes) -> str:
+    return "sha512-" + base64.b64encode(hashlib.sha512(content).digest()).decode(
+        "ascii"
+    )
+
+
+def upstream_bytes(viewer: Viewer, source_dir: Path | None) -> bytes:
+    if source_dir is not None:
+        content = (source_dir / viewer.upstream_filename).read_bytes()
+    else:
+        # Fixed HTTPS npm identities above; no user-supplied URL or npm hooks.
+        with urllib.request.urlopen(viewer.upstream_url, timeout=60) as response:  # noqa: S310
+            content = response.read(MAX_ARCHIVE_BYTES + 1)
+    if len(content) > MAX_ARCHIVE_BYTES:
+        raise ValueError(f"Upstream archive is too large: {viewer.name}")
+    if not hmac.compare_digest(integrity(content), viewer.integrity):
+        raise ValueError(f"Upstream integrity mismatch: {viewer.name}")
+    return content
+
+
+def package_entries(content: bytes) -> dict[str, Entry]:
+    """Read regular npm files in memory; never extract paths or follow links."""
+    entries: dict[str, Entry] = {}
+    total = 0
+    with tarfile.open(fileobj=io.BytesIO(content), mode="r|gz") as archive:
+        for member in archive:
+            name = member.name.rstrip("/")
+            parts = name.split("/")
+            if (
+                len(entries) >= MAX_MEMBERS
+                or not parts
+                or parts[0] != "package"
+                or any(part in {"", ".", ".."} for part in parts)
+                or "\\" in name
+                or ":" in name
+                or PurePosixPath(name).is_absolute()
+                or name in entries
+            ):
+                raise ValueError(f"Unsafe or duplicate npm archive path: {member.name}")
+            if member.isdir():
+                entries[name] = Entry(None, 0o755)
+                continue
+            if not member.isfile() or member.size < 0:
+                raise ValueError(f"Unsupported npm archive member: {member.name}")
+            total += member.size
+            if total > MAX_PACKAGE_BYTES:
+                raise ValueError("Unpacked viewer package exceeds the size limit")
+            handle = archive.extractfile(member)
+            if handle is None:
+                raise ValueError(f"Unreadable npm archive member: {member.name}")
+            with handle:
+                data = handle.read(member.size + 1)
+            if len(data) != member.size:
+                raise ValueError(f"Truncated npm archive member: {member.name}")
+            entries[name] = Entry(data, 0o755 if member.mode & 0o111 else 0o644)
+    if "package/package.json" not in entries:
+        raise ValueError("Npm package metadata is missing")
+    return entries
+
+
+NODE_PATCH = r"""
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+const input = JSON.parse(readFileSync(0, "utf8"));
+const recipe = await import(pathToFileURL(input.recipe).href);
+process.stdout.write(recipe[input.patch](input.source, input.version));
+"""
+
+
+def patched_source(viewer: Viewer, content: bytes, root: Path, node: str) -> bytes:
+    request = {
+        "recipe": str(root / viewer.recipe),
+        "patch": viewer.patch,
+        "source": content.decode("utf-8"),
+        "version": viewer.version,
+    }
+    result = subprocess.run(  # noqa: S603 - explicit local maintenance recipe
+        [node, "--input-type=module", "--eval", NODE_PATCH],
+        input=json.dumps(request),
+        capture_output=True,
+        encoding="utf-8",
+        check=True,
+        timeout=60,
+    )
+    return result.stdout.encode("utf-8")
+
+
+def modification_notice(viewer: Viewer) -> bytes:
+    return (
+        f"TGDrive modifications to {viewer.name} {viewer.version}\n"
+        f"Local package version: {viewer.local_version}\n\n"
+        f"TGDrive changed {viewer.target} using the reviewed recipe\n"
+        f"{viewer.recipe}. The recipe records the original source identity\n"
+        "and the viewer corrections applied to that file. The modified file\n"
+        "also carries a TGDrive change notice.\n\n"
+        "The upstream package.json version was given the local suffix above.\n"
+        "All other upstream package files, licenses, attribution, declarations\n"
+        "and exported entrypoints are retained unchanged.\n\n"
+        f"Upstream package: {viewer.upstream_url}\n"
+        f"Upstream integrity: {viewer.integrity}\n\n"
+        "See website/vendor/manifest.json for upstream and local content hashes.\n"
+        "Movi decoder source/relink materials and full LGPL notice accompany\n"
+        "TGDrive under website/public/third-party/.\n"
+    ).encode()
+
+
+def deterministic_archive(entries: dict[str, Entry]) -> bytes:
+    """Normalize ordering, permissions, owner identity and archive timestamps."""
+    contents = dict(entries)
+    for name in tuple(contents):
+        for parent in PurePosixPath(name).parents:
+            if parent.as_posix() != ".":
+                contents.setdefault(parent.as_posix(), Entry(None, 0o755))
+    output = io.BytesIO()
+    with (
+        gzip.GzipFile(fileobj=output, mode="wb", filename="", mtime=0) as compressed,
+        tarfile.open(
+            fileobj=compressed, mode="w", format=tarfile.PAX_FORMAT
+        ) as archive,
+    ):
+        for name, entry in sorted(contents.items()):
+            header = tarfile.TarInfo(name)
+            header.mode = entry.mode
+            header.mtime = 0
+            header.uid = header.gid = 0
+            header.uname = header.gname = ""
+            header.type = tarfile.DIRTYPE if entry.content is None else tarfile.REGTYPE
+            header.size = len(entry.content) if entry.content is not None else 0
+            archive.addfile(
+                header,
+                io.BytesIO(entry.content) if entry.content is not None else None,
+            )
+    return output.getvalue()
+
+
+def generate(root: Path, output_dir: Path, node: str, source_dir: Path | None) -> dict:
+    manifest: dict = {"schema_version": 1, "packages": {}}
+    generated: dict[str, bytes] = {}
+    for viewer in VIEWERS:
+        upstream = upstream_bytes(viewer, source_dir)
+        entries = package_entries(upstream)
+        metadata_entry = entries["package/package.json"]
+        metadata = json.loads(metadata_entry.content)
+        if metadata["name"] != viewer.name or metadata["version"] != viewer.version:
+            raise ValueError(f"Unexpected upstream package metadata: {viewer.name}")
+        target = "package/" + viewer.target
+        original = entries[target].content
+        if original is None:
+            raise ValueError(f"Expected regular viewer runtime file: {target}")
+        patched = patched_source(viewer, original, root, node)
+        entries[target] = Entry(patched, entries[target].mode)
+        metadata["version"] = viewer.local_version
+        package_json = (
+            json.dumps(metadata, indent=2, ensure_ascii=False) + "\n"
+        ).encode()
+        entries["package/package.json"] = Entry(package_json, metadata_entry.mode)
+        entries["package/TGDRIVE-NOTICE.txt"] = Entry(
+            modification_notice(viewer), 0o644
+        )
+        files = {
+            name.removeprefix("package/"): sha256(entry.content)
+            for name, entry in sorted(entries.items())
+            if entry.content is not None
+        }
+        archive = deterministic_archive(entries)
+        generated[viewer.filename] = archive
+        manifest["packages"][viewer.name] = {
+            "upstream": {
+                "version": viewer.version,
+                "url": viewer.upstream_url,
+                "integrity": viewer.integrity,
+                "sha256": sha256(upstream),
+                "bytes": len(upstream),
+            },
+            "vendored": {
+                "version": viewer.local_version,
+                "archive": viewer.filename,
+                "integrity": integrity(archive),
+                "sha256": sha256(archive),
+                "bytes": len(archive),
+                "package_json_sha256": sha256(package_json),
+                "package_files_sha256": sha256(
+                    json.dumps(files, sort_keys=True).encode()
+                ),
+                "file_count": len(files),
+            },
+            "patch": {
+                "file": viewer.target,
+                "upstream_sha256": sha256(original),
+                "vendored_sha256": sha256(patched),
+                "recipe": viewer.recipe,
+                "recipe_sha256": sha256((root / viewer.recipe).read_bytes()),
+            },
+            "files_sha256": files,
+        }
+    generated["manifest.json"] = (json.dumps(manifest, indent=4) + "\n").encode()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    for name, content in generated.items():
+        (output_dir / name).write_bytes(content)
+    return manifest
+
+
+def main() -> None:
+    root = Path(__file__).resolve().parents[1]
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--node", default="node", help="Supported Node.js executable")
+    parser.add_argument("--output-dir", type=Path, default=root / "website/vendor")
+    parser.add_argument(
+        "--upstream-dir",
+        type=Path,
+        help="Read exact upstream .tgz files here instead of downloading them",
+    )
+    args = parser.parse_args()
+    manifest = generate(root, args.output_dir, args.node, args.upstream_dir)
+    for name, package in manifest["packages"].items():
+        local = package["vendored"]
+        print(f"{name}: {local['archive']} ({local['bytes']:,} bytes)")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/start_main.py b/start_main.py
deleted file mode 100644
index 899b51b6..00000000
--- a/start_main.py
+++ /dev/null
@@ -1,3 +0,0 @@
-import os
-
-os.system("uvicorn main:app --reload")
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 00000000..3f8ce340
--- /dev/null
+++ b/tests/__init__.py
@@ -0,0 +1 @@
+"""TGDrive test suite."""
diff --git a/tests/browser/__init__.py b/tests/browser/__init__.py
new file mode 100644
index 00000000..8d6c58b6
--- /dev/null
+++ b/tests/browser/__init__.py
@@ -0,0 +1 @@
+"""TGDrive browser tests."""
diff --git a/tests/browser/test_browser_books_shares.py b/tests/browser/test_browser_books_shares.py
new file mode 100644
index 00000000..d7b5ee5e
--- /dev/null
+++ b/tests/browser/test_browser_books_shares.py
@@ -0,0 +1,428 @@
+"""Reader and independent-link workflows on the real production bundle."""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import urlparse
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, CONTROL, expect, login
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.mark.parametrize(
+    "width,theme", [(1440, "light"), (390, "dark"), (320, "light")]
+)
+@pytest.mark.parametrize(
+    "name", ["The little journey.epub", "Sample comic.cbz", "Sample manga.cbr"]
+)
+def test_selective_reader_controls_and_mobile_layout(
+    server, desktop, width, theme, name
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 900 if width > 700 else 844})
+    page.add_init_script("localStorage.setItem('tgdrive.appearance', '" + theme + "')")
+    originals = []
+    external = []
+    page.on(
+        "request",
+        lambda request: (
+            originals.append(request.url)
+            if urlparse(request.url).path == "/file"
+            else external.append(request.url)
+            if "external.invalid" in request.url
+            else None
+        ),
+    )
+    login(page, server.url)
+    folder = page.request.post(server.url + "/__test__/books", headers=CONTROL).json()[
+        "path"
+    ]
+    page.goto(server.url + "/?path=" + folder)
+    page.get_by_role("button", name=name, exact=True).press("Enter")
+    expect(
+        page.get_by_role("group", name="Reader controls", exact=True)
+    ).to_be_visible()
+    if name.endswith("epub"):
+        expect(page.locator(".book-chapter h1")).to_have_text("A quiet morning")
+        page.locator('summary[aria-label="Reading options"]').click()
+        page.get_by_role("button", name="Increase text size", exact=True).click()
+        page.locator('summary[aria-label="Reading options"]').click()
+        expect(page.locator(".book-reader")).to_have_class(
+            __import__("re").compile("book-font-20")
+        )
+        page.get_by_role("button", name="Next chapter or page", exact=True).click()
+        expect(page.locator(".book-chapter h1")).to_have_text("Across the city")
+        image = page.locator(".book-chapter img")
+        expect(image).to_be_visible()
+        expect(image).to_have_js_property("naturalWidth", 480)
+    else:
+        image = page.locator(".book-content > .book-image > img")
+        expect(image).to_be_visible()
+        expect(image).to_have_js_property("naturalWidth", 480)
+        page.locator('summary[aria-label="Reading options"]').click()
+        page.get_by_label("Right to left", exact=True).check()
+        page.get_by_label("Page fit", exact=True).select_option("page")
+        page.locator('summary[aria-label="Reading options"]').click()
+        page.locator(".book-content").focus()
+        page.keyboard.press("ArrowLeft")
+        expect(page.locator(".book-position")).to_have_text(
+            "2 / " + ("2" if name.endswith("cbr") else "3")
+        )
+        expect(image).to_have_js_property("naturalWidth", 480)
+    assert page.locator(".preview-heading h2").evaluate(
+        "node => getComputedStyle(node).color === "
+        'getComputedStyle(node.closest(".preview-header")).color'
+    )
+    assert not originals and not external
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    assert page.locator(".preview-header").evaluate(
+        "node => node.scrollWidth <= node.clientWidth+1"
+    )
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(
+        path=ARTIFACTS / f"reader-{name.rsplit('.', 1)[-1]}-{theme}-{width}.png"
+    )
+    page.get_by_role("button", name="Close Preview", exact=True).click()
+    page.get_by_role("button", name=name, exact=True).press("Enter")
+    expect(page.locator(".book-position")).to_have_text(
+        "2 / " + ("2" if name.endswith(("epub", "cbr")) else "3")
+    )
+
+
+def test_independent_share_ui_and_public_reader_revocation(server, desktop, browser):
+    context, page = desktop
+    context.grant_permissions(["clipboard-read", "clipboard-write"], origin=server.url)
+    login(page, server.url)
+    folder = page.request.post(server.url + "/__test__/books", headers=CONTROL).json()[
+        "path"
+    ]
+    first = page.request.post(
+        server.url + "/api/v1/shares",
+        data={"path": folder, "label": "Alex", "expires_in_days": 1},
+    ).json()
+    second = page.request.post(
+        server.url + "/api/v1/shares",
+        data={"path": folder, "label": "Book club", "expires_in_days": 30},
+    ).json()
+    page.get_by_role("link", name="Shared Links", exact=True).click()
+    expect(page.locator(".share-row")).to_have_count(2)
+    expect(page.get_by_text("Unnamed link", exact=False)).to_have_count(0)
+    expect(page.get_by_role("button", name="New Link", exact=True)).to_have_count(0)
+    for share, label in [(first, "Alex"), (second, "Book club")]:
+        row = page.locator(".share-row").filter(has_text=label)
+        copy = row.locator(".share-copy")
+        expect(copy).to_have_text("")
+        copy.click()
+        expect(copy).to_have_attribute(
+            "aria-label", __import__("re").compile("^Link copied")
+        )
+        copied_url = page.evaluate("navigator.clipboard.readText()")
+        assert share["auth"] in copied_url and folder.strip("/") in copied_url
+    assert len(page.request.get(server.url + "/api/v1/shares").json()["shares"]) == 2
+    page.get_by_role("button", name="Edit link Alex", exact=True).click()
+    page.get_by_label("Link label", exact=True).fill("Alex review")
+    page.get_by_label("No expiry", exact=True).check()
+    page.get_by_role("button", name="Save changes", exact=True).click()
+    expect(
+        page.get_by_role("button", name="Edit link Alex review", exact=True)
+    ).to_be_visible()
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    for width, theme in [(1440, "light"), (390, "dark"), (320, "light")]:
+        page.set_viewport_size({"width": width, "height": 900 if width > 700 else 844})
+        page.evaluate(
+            """theme => {
+          localStorage.setItem('tgdrive.appearance', theme);
+          window.dispatchEvent(new CustomEvent(
+            'tgdrive:appearance-changed', {detail: theme}
+          ));
+        }""",
+            theme,
+        )
+        expect(page.locator("html")).to_have_attribute("data-theme", theme)
+        assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+        page.screenshot(path=ARTIFACTS / f"independent-links-{theme}-{width}.png")
+    page.set_viewport_size({"width": 1440, "height": 900})
+    copied = page.request.post(
+        server.url + "/api/v1/shares/link", data={"share_id": first["id"]}
+    ).json()
+    assert copied["auth"] == first["auth"]
+    public = browser.new_context(viewport={"width": 390, "height": 844})
+    try:
+        reader = public.new_page()
+        reader.goto(
+            server.url + "/?path=/share_" + folder.strip("/") + "&auth=" + first["auth"]
+        )
+        reader.get_by_role("button", name="The little journey.epub", exact=True).press(
+            "Enter"
+        )
+        expect(reader.locator(".book-chapter h1")).to_have_text("A quiet morning")
+        row = page.locator(".share-row").filter(has_text="Alex review")
+        row.get_by_role(
+            "button", name="Revoke Link for Reading samples", exact=True
+        ).click()
+        page.get_by_role("button", name="Revoke Link", exact=True).click()
+        expect(page.locator(".share-row")).to_have_count(1)
+        reader.get_by_role("button", name="Next chapter or page", exact=True).click()
+        expect(reader.get_by_text("Invalid share link", exact=True)).to_be_visible()
+        reader.goto(
+            server.url
+            + "/?path=/share_"
+            + folder.strip("/")
+            + "&auth="
+            + second["auth"]
+        )
+        reader.get_by_role("button", name="The little journey.epub", exact=True).press(
+            "Enter"
+        )
+        expect(reader.locator(".book-chapter")).to_be_visible()
+        assert (
+            page.request.post(
+                server.url + "/api/getDirectory",
+                data={"path": "/share_" + folder.strip("/"), "auth": first["auth"]},
+            ).status
+            == 403
+        )
+        assert (
+            page.request.post(
+                server.url + "/api/getDirectory",
+                data={"path": "/share_" + folder.strip("/"), "auth": second["auth"]},
+            ).status
+            == 200
+        )
+    finally:
+        public.close()
+
+
+def test_create_multiple_links_from_share_dialog(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="資料", exact=True).focus()
+    # Use the same per-item action as a person browsing their drive.
+    for label, expiry in [("Alex", "1 day"), ("Project team", "Custom")]:
+        page.locator('summary[aria-label="Actions for 資料"]').click()
+        page.get_by_role("button", name="Share Link", exact=True).click()
+        page.get_by_label("Link label (optional)", exact=True).fill(label)
+        page.get_by_role("button", name=expiry, exact=True).click()
+        if expiry == "Custom":
+            page.get_by_label("Expiry date and time", exact=True).fill(
+                "2030-01-01T12:00"
+            )
+        page.get_by_role("button", name="Create Share Link", exact=True).click()
+        expect(page.get_by_label("Share Link", exact=True)).to_be_visible()
+        page.get_by_role("button", name="Done", exact=True).click()
+    rows = page.request.get(server.url + "/api/v1/shares").json()["shares"]
+    assert {row["label"] for row in rows} == {"Alex", "Project team"}
+    assert len({row["id"] for row in rows}) == 2
+
+
+@pytest.mark.parametrize("kind", ["file", "folder"])
+def test_same_item_links_keep_their_copy_edit_and_revoke_scope(server, desktop, kind):
+    context, page = desktop
+    context.grant_permissions(["clipboard-read", "clipboard-write"], origin=server.url)
+    login(page, server.url)
+    path = server.control()["seed"][kind]
+    links = [
+        page.request.post(
+            server.url + "/api/v1/shares",
+            data={"path": path, "label": label, "expires_in_days": days},
+        ).json()
+        for label, days in [("Review", 1), ("Archive", 30)]
+    ]
+    assert links[0]["auth"] != links[1]["auth"]
+    page.goto(server.url + "/?view=shares")
+    expect(page.locator(".share-row")).to_have_count(2)
+
+    for link in links:
+        row = page.locator(f'[data-share-id="{link["id"]}"]')
+        expect(row).to_contain_text(link["label"])
+        assert row.locator(".share-expiry time").evaluate(
+            "(node, expiry) => Date.parse(node.dateTime) === Date.parse(expiry)",
+            link["expires_at"],
+        )
+        copy = row.locator(".share-copy")
+        expect(copy).to_have_text("")
+        copy.click()
+        expect(copy).to_have_attribute(
+            "aria-label", __import__("re").compile("^Link copied")
+        )
+        assert link["auth"] in page.evaluate("navigator.clipboard.readText()")
+
+    first_row = page.locator(f'[data-share-id="{links[0]["id"]}"]')
+    first_row.get_by_role("button", name="Edit link Review", exact=True).click()
+    page.get_by_label("Link label", exact=True).fill("Review updated")
+    page.get_by_role("button", name="Save changes", exact=True).click()
+    expect(first_row).to_contain_text("Review updated")
+    listed = page.request.get(server.url + "/api/v1/shares").json()["shares"]
+    assert len(listed) == 2
+    by_id = {link["id"]: link for link in listed}
+    assert by_id[links[0]["id"]]["expires_at"] == links[0]["expires_at"]
+    assert by_id[links[1]["id"]]["expires_at"] == links[1]["expires_at"]
+    assert by_id[links[1]["id"]]["label"] == "Archive"
+
+    first_row.get_by_role(
+        "button", name=__import__("re").compile("^Revoke Link for ")
+    ).click()
+    dialog = page.get_by_role("dialog", name="Revoke This Link?", exact=True)
+    expect(dialog).to_contain_text("Review updated")
+    dialog.get_by_role("button", name="Revoke Link", exact=True).click()
+    expect(page.locator(".share-row")).to_have_count(1)
+
+    for link, expected_status in [(links[0], 403), (links[1], 200)]:
+        if kind == "folder":
+            response = page.request.post(
+                server.url + "/api/getDirectory",
+                data={"path": "/share_" + path.strip("/"), "auth": link["auth"]},
+            )
+        else:
+            response = page.request.head(
+                server.url + "/file", params={"path": path, "auth": link["auth"]}
+            )
+        assert response.status == expected_status
+
+
+def test_comic_image_error_details_and_automatic_recovery(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    folder = page.request.post(server.url + "/__test__/books", headers=CONTROL).json()[
+        "path"
+    ]
+    page.goto(server.url + "/?path=" + folder)
+    calls = []
+
+    def page_resource(route):
+        if "entry=" not in route.request.url:
+            route.continue_()
+        else:
+            calls.append(route.request.url)
+            if len(calls) == 1:
+                route.fulfill(
+                    status=503,
+                    content_type="application/json",
+                    body='{"detail":"Reader busy"}',
+                    headers={"Retry-After": "1"},
+                )
+            else:
+                route.continue_()
+
+    page.route("**/api/v1/books?**", page_resource)
+    page.get_by_role("button", name="Sample comic.cbz", exact=True).press("Enter")
+    expect(
+        page.get_by_text("Connection interrupted. Retrying page…", exact=True)
+    ).to_be_visible()
+    expect(page.locator(".book-content > .book-image > img")).to_be_visible(
+        timeout=15000
+    )
+    assert len(calls) == 2
+    page.unroute("**/api/v1/books?**", page_resource)
+
+    def refused(route):
+        route.fulfill(
+            status=422,
+            content_type="application/json",
+            body='{"detail":"This resource exceeds the 64 MiB preview limit."}',
+        )
+
+    page.route("**/api/v1/books?**entry=**", refused)
+    page.get_by_role("button", name="Next chapter or page", exact=True).click()
+    expect(page.get_by_role("alert")).to_contain_text("64 MiB preview limit")
+    expect(page.get_by_role("button", name="Retry image", exact=True)).to_be_visible()
+
+
+def test_large_original_comic_page_renders_and_revalidates_without_resending(
+    server, desktop
+):
+    import hashlib
+    from urllib.parse import parse_qs
+
+    _, page = desktop
+    login(page, server.url)
+    sample = page.request.post(
+        server.url + "/__test__/books/large-page", headers=CONTROL
+    ).json()
+    responses = []
+
+    def record(response):
+        if urlparse(response.url).path == "/api/v1/books" and "entry=" in response.url:
+            responses.append(response)
+
+    page.on("response", record)
+    page.goto(server.url + "/?path=" + sample["path"])
+    page.get_by_role("button", name="Large original page.cbz", exact=True).press(
+        "Enter"
+    )
+    image = page.locator(".book-content > .book-image > img")
+    expect(image).to_be_visible(timeout=45000)
+    expect(image).to_have_js_property("naturalWidth", 480)
+    assert len(responses) == 1
+    result = responses[0]
+    assert result.status == 200
+    assert int(result.headers["content-length"]) == sample["image_size"]
+    # Native decode must succeed under the shipped CSP, using the unchanged bytes.
+    assert image.get_attribute("src").startswith("blob:")
+    assert parse_qs(urlparse(result.url).query)["entry"] == ["page.png"]
+    # Inspector caches can evict a 39 MiB response. Verify its declared wire size
+    # above and the authorized API bytes against the fixture's independent hash.
+    again = page.request.get(result.url)
+    assert len(again.body()) == sample["image_size"]
+    assert hashlib.sha256(again.body()).hexdigest() == sample["image_sha256"]
+    conditional = page.request.get(
+        result.url, headers={"If-None-Match": result.headers["etag"]}
+    )
+    assert conditional.status == 304 and not conditional.body()
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+
+
+def test_epub_offscreen_images_release_blobs_and_load_only_near_viewport(
+    server, desktop
+):
+    _, page = desktop
+    login(page, server.url)
+    folder = page.request.post(server.url + "/__test__/books", headers=CONTROL).json()[
+        "path"
+    ]
+    nodes = [
+        {
+            "tag": "img",
+            "src": "OPS/images/page.png",
+            "alt": "First image",
+            "children": [],
+        }
+    ]
+    nodes.extend(
+        {"tag": "p", "children": ["A chapter with illustrations. " * 8]}
+        for _ in range(80)
+    )
+    nodes.append(
+        {
+            "tag": "img",
+            "src": "OPS/images/page.png",
+            "alt": "Last image",
+            "children": [],
+        }
+    )
+    page.route(
+        "**/api/v1/books?**entry=OPS%2Fone.xhtml",
+        lambda route: route.fulfill(json={"kind": "chapter", "nodes": nodes}),
+    )
+    page.goto(server.url + "/?path=" + folder)
+    page.get_by_role("button", name="The little journey.epub", exact=True).press(
+        "Enter"
+    )
+    first = page.get_by_role("img", name="First image", exact=True)
+    last = page.get_by_role("img", name="Last image", exact=True)
+    expect(first).to_be_visible()
+    expect(last).to_have_count(0)
+    page.locator(".book-content").evaluate("node => node.scrollTop = node.scrollHeight")
+    expect(last).to_be_visible()
+    expect(first).to_have_count(0)
+    page.locator(".book-content").evaluate("node => node.scrollTop = 0")
+    expect(first).to_be_visible()
+    expect(last).to_have_count(0)
diff --git a/tests/browser/test_browser_bot_settings.py b/tests/browser/test_browser_bot_settings.py
new file mode 100644
index 00000000..b914dc9d
--- /dev/null
+++ b/tests/browser/test_browser_bot_settings.py
@@ -0,0 +1,96 @@
+"""Website-managed Telegram bot destination in desktop and mobile Chromium."""
+# ruff: noqa: F811 - shared pytest fixtures use imported names.
+
+import os
+
+import pytest
+
+pytestmark = pytest.mark.e2e
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium tests", allow_module_level=True)
+
+from tests.browser.test_browser_e2e import (  # noqa: E402
+    ARTIFACTS,
+    browser,  # noqa: F401
+    desktop,  # noqa: F401
+    expect,
+    login,
+    server,  # noqa: F401
+)
+
+
+@pytest.mark.parametrize("width,height", [(1440, 960), (390, 844)])
+def test_bot_folder_deep_link_select_save_reload_and_default(
+    server, desktop, width, height
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": height})
+    login(page, server.url + "/?view=settings&section=transfers#bot-mode")
+    section = page.locator("#bot-mode")
+    expect(
+        section.get_by_role("heading", name="Bot uploads", exact=True)
+    ).to_be_visible()
+    expect(section.locator(".bot-upload-destination")).to_contain_text(
+        "TGDriveBotModeFiles"
+    )
+    assert page.request.post(
+        server.url + "/api/createNewFolder", data={"path": "/", "name": "Bot inbox"}
+    ).ok
+    page.get_by_role("button", name="Change folder", exact=True).click()
+    dialog = page.get_by_role("dialog", name="Choose bot upload folder")
+    dialog.get_by_role("button", name="Bot inbox", exact=True).click()
+    expect(dialog.get_by_role("navigation")).to_contain_text("Bot inbox")
+    dialog.get_by_role("button", name="Use this folder", exact=True).click()
+    expect(dialog).not_to_be_visible()
+    expect(section.get_by_role("status")).to_contain_text("Bot upload folder saved")
+    snapshot = page.request.get(server.url + "/api/v1/settings/bot-mode").json()
+    assert snapshot["folder_label"] == "My Files / Bot inbox"
+    assert (
+        snapshot["settings_url"]
+        == server.url + "/?view=settings&section=transfers#bot-mode"
+    )
+    page.reload()
+    expect(section.locator(".bot-upload-destination")).to_contain_text(
+        "My Files / Bot inbox"
+    )
+    assert page.evaluate("document.documentElement.scrollWidth <= window.innerWidth")
+    page.screenshot(
+        path=str(ARTIFACTS / f"bot-upload-settings-{width}.png"), full_page=True
+    )
+    section.get_by_role("button", name="Use default folder", exact=True).click()
+    expect(section.locator(".bot-upload-destination")).to_contain_text(
+        "TGDriveBotModeFiles"
+    )
+    assert (
+        page.request.get(server.url + "/api/v1/settings/bot-mode").json()["folder_path"]
+        is None
+    )
+
+
+def test_folder_picker_read_failure_does_not_save_an_accidental_destination(
+    server, desktop
+):
+    _, page = desktop
+    login(page, server.url + "/?view=settings&section=transfers#bot-mode")
+    page.route(
+        "**/api/getDirectory",
+        lambda route: route.fulfill(
+            status=503, json={"detail": "Folder list unavailable"}
+        ),
+    )
+    page.get_by_role("button", name="Change folder", exact=True).click()
+    dialog = page.get_by_role("dialog", name="Choose bot upload folder")
+    expect(dialog.get_by_role("alert")).to_contain_text("Folder list unavailable")
+    expect(
+        dialog.get_by_role("button", name="Use this folder", exact=True)
+    ).to_be_disabled()
+    page.unroute("**/api/getDirectory")
+    dialog.get_by_role("button", name="Try again", exact=True).click()
+    expect(
+        dialog.get_by_role("button", name="Use this folder", exact=True)
+    ).to_be_enabled()
+    dialog.get_by_role("button", name="Cancel", exact=True).click()
+    assert (
+        page.request.get(server.url + "/api/v1/settings/bot-mode").json()["folder_path"]
+        is None
+    )
diff --git a/tests/browser/test_browser_channel_backup.py b/tests/browser/test_browser_channel_backup.py
new file mode 100644
index 00000000..832fd46b
--- /dev/null
+++ b/tests/browser/test_browser_channel_backup.py
@@ -0,0 +1,342 @@
+"""Owner backup UX uses the real routes with an offline replica service."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, CONTROL, expect, login, open_admin
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+BOT = "222222222:" + "a" * 35
+MAIN_BOT = "333333333:" + "b" * 35
+BACKUP_CHANNEL = "-1003333333333"
+NEW_MAIN_CHANNEL = "-1004444444444"
+KEY = "c" * 64
+
+
+@pytest.fixture(autouse=True)
+def keep_console_errors(desktop, request):
+    _, page = desktop
+    errors = []
+
+    def collect(message):
+        if message.type == "error":
+            text = message.text
+            for secret in (BOT, MAIN_BOT, KEY):
+                text = text.replace(secret, "<redacted>")
+            errors.append(text)
+
+    page.on("console", collect)
+    yield
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    (ARTIFACTS / (request.node.name + "-console.json")).write_text(json.dumps(errors))
+    assert errors == []
+
+
+def open_storage(page):
+    open_admin(page)
+    page.get_by_role("link", name="Storage & Backups", exact=True).click()
+    section = page.get_by_role("region", name="Independent backup channel", exact=True)
+    expect(section).to_be_visible()
+    return section
+
+
+def scenario(page, server, name):
+    response = page.request.post(
+        server.url + "/__test__/replica/" + name, headers=CONTROL
+    )
+    assert response.ok
+    page.get_by_role("button", name="Refresh channel backup status", exact=True).click()
+
+
+def capture(page, name):
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / name, animations="disabled")
+
+
+@pytest.mark.parametrize(
+    "width,theme", [(1440, "light"), (390, "dark"), (320, "light")]
+)
+def test_channel_backup_setup_progress_pause_errors_and_private_exports(
+    server, desktop, width, theme
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 900 if width > 720 else 844})
+    page.add_init_script("localStorage.setItem('tgdrive.appearance','" + theme + "')")
+    login(page, server.url)
+    section = open_storage(page)
+    database = page.get_by_role("region", name="Cloud Database", exact=True)
+    expect(database).to_be_visible()
+    expect(
+        database.get_by_role("button", name="Back Up Now", exact=True)
+    ).to_be_enabled()
+    section.get_by_role("button", name="Set up backup channel", exact=True).click()
+    section.get_by_label("Backup channel ID", exact=True).fill(BACKUP_CHANNEL)
+    section.get_by_label("Backup bot token", exact=True).fill(BOT)
+    submit = section.get_by_role("button", name="Verify and start backup", exact=True)
+    expect(submit).to_be_disabled()
+    section.get_by_role(
+        "checkbox", name="I created the backup channel", exact=False
+    ).check()
+    capture(page, f"channel-backup-setup-{theme}-{width}.png")
+    submit.click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text(
+        "Copying to the backup channel"
+    )
+    expect(
+        section.get_by_role("progressbar", name="Channel copy progress", exact=True)
+    ).to_have_attribute("value", str(1024**2))
+    expect(section.get_by_text("Project archive.zip", exact=True)).to_be_visible()
+    expect(section.get_by_label("Backup bot token", exact=True)).to_have_count(0)
+    expect(
+        section.get_by_role("heading", name="Independent backup channel", exact=True)
+    ).to_be_focused()
+    section.scroll_into_view_if_needed()
+    capture(page, f"channel-backup-progress-{theme}-{width}.png")
+    section.get_by_role("button", name="Pause", exact=True).click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Paused")
+    section.get_by_role("button", name="Resume", exact=True).click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Copying")
+    scenario(page, server, "error")
+    expect(section.get_by_role("alert")).to_contain_text("Backup bot cannot read")
+    expect(
+        section.get_by_text(
+            "Restore the bot's administrator permissions, then retry.", exact=True
+        )
+    ).to_be_visible()
+    section.get_by_role("alert").scroll_into_view_if_needed()
+    capture(page, f"channel-backup-error-{theme}-{width}.png")
+    section.get_by_role("button", name="Retry", exact=True).click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Copying")
+    scenario(page, server, "waiting")
+    expect(section.locator(".channel-backup-phase")).to_contain_text(
+        "Waiting for Telegram"
+    )
+    expect(section.get_by_text("Next retry:", exact=False)).to_contain_text("2026")
+    section.locator(".channel-backup-phase").scroll_into_view_if_needed()
+    capture(page, f"channel-backup-waiting-{theme}-{width}.png")
+    scenario(page, server, "protected")
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Backup confirmed")
+    expect(section.locator(".channel-backup-confirmation")).to_contain_text(
+        "catalog revision 9"
+    )
+    with page.expect_download() as key_download:
+        section.get_by_role("link", name="Save recovery key", exact=True).click()
+    exported = json.loads(Path(key_download.value.path()).read_text())
+    assert exported["key"] == KEY
+    scenario(page, server, "many-events")
+    section.locator("summary").filter(has_text="Activity and report").click()
+    expect(section.locator(".channel-backup-report li")).to_have_count(30)
+    with page.expect_download() as report_download:
+        section.get_by_role("link", name="Download report", exact=True).click()
+    report = Path(report_download.value.path()).read_text()
+    assert BOT not in report and KEY not in report and MAIN_BOT not in report
+    assert "bot_token" not in report and "credentials" not in report
+    section.locator("summary").filter(has_text="Backup settings").click()
+    section.get_by_role("button", name="Disable automatic backup", exact=True).click()
+    section.get_by_role("button", name="Confirm disable", exact=True).click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Not enabled")
+    section.get_by_role("button", name="Enable backup", exact=True).click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Copying")
+
+
+@pytest.mark.parametrize(
+    "catalog_only,width,theme", [(False, 320, "light"), (True, 390, "dark")]
+)
+def test_recovery_only_inspection_confirmation_resume_and_activation(
+    server, desktop, catalog_only, width, theme
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    page.add_init_script("localStorage.setItem('tgdrive.appearance','" + theme + "')")
+    response = page.request.post(
+        server.url + "/__test__/replica/recovery-only", headers=CONTROL
+    )
+    assert response.ok
+    login(page, server.url)
+    expect(
+        page.get_by_role("heading", name="Storage recovery", exact=True)
+    ).to_be_visible()
+    expect(page.locator(".file-browser")).to_have_count(0)
+    section = page.get_by_role("region", name="Recover your drive", exact=True)
+    capture(page, f"channel-recovery-initial-{theme}-{width}.png")
+    section.get_by_label("Surviving channel ID", exact=True).fill(BACKUP_CHANNEL)
+    section.get_by_label(
+        "Bot token with access to the surviving channel", exact=True
+    ).fill(BOT)
+    section.get_by_label("Saved recovery key", exact=True).fill(KEY)
+    section.get_by_role("button", name="Inspect recovery copy", exact=True).click()
+    expect(
+        section.get_by_role("heading", name="Recovery copy found", exact=True)
+    ).to_be_visible()
+    expect(
+        section.get_by_role("heading", name="Recovery copy found", exact=True)
+    ).to_be_focused()
+    expect(section.get_by_label("Saved recovery key", exact=True)).to_have_value("")
+    expect(
+        section.get_by_label(
+            "Bot token with access to the surviving channel", exact=True
+        )
+    ).to_have_value("")
+    # The candidate and credentials are server-side; a page reload resumes the review.
+    page.reload()
+    expect(
+        section.get_by_role("heading", name="Recovery copy found", exact=True)
+    ).to_be_visible()
+    target = BACKUP_CHANNEL if catalog_only else NEW_MAIN_CHANNEL
+    if catalog_only:
+        section.get_by_role(
+            "checkbox",
+            name="Restore the database only on this surviving channel",
+            exact=True,
+        ).check()
+        section.get_by_label("Main bot token for this channel", exact=True).fill(
+            MAIN_BOT
+        )
+    else:
+        section.get_by_label("New main channel ID", exact=True).fill(target)
+        section.get_by_label("New main bot token", exact=True).fill(MAIN_BOT)
+    confirmation = (
+        section.locator("label").filter(has_text="to confirm").locator("input")
+    )
+    copy = section.get_by_role(
+        "button",
+        name="Verify catalog on this channel"
+        if catalog_only
+        else "Copy to new main channel",
+        exact=True,
+    )
+    confirmation.fill("-1001111111111")
+    expect(copy).to_be_disabled()
+    confirmation.fill(target)
+    expect(copy).to_be_enabled()
+    capture(page, f"channel-recovery-review-{theme}-{width}.png")
+    copy.click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text(
+        "Preparing the recovered drive"
+    )
+    section.get_by_role("button", name="Pause recovery", exact=True).click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Paused")
+    section.get_by_role("button", name="Resume recovery", exact=True).click()
+    # Advance the synthetic transport only after the UI requested a confirmed target.
+    scenario(page, server, "recovery-ready")
+    expect(
+        section.get_by_role("heading", name="Recovered drive verified", exact=True)
+    ).to_be_visible()
+    activate = section.get_by_role(
+        "button", name="Activate recovered drive", exact=True
+    )
+    expect(activate).to_be_disabled()
+    section.get_by_label(
+        "Type " + target + " to activate this recovered drive", exact=True
+    ).fill(target)
+    activate.click()
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Restart required")
+    expect(
+        section.get_by_text("The recovered configuration is saved.", exact=False)
+    ).to_be_visible()
+    state = page.request.get(server.url + "/__test__/replica", headers=CONTROL).json()
+    recovery = next(item for item in state["events"] if item["action"] == "recover")
+    assert (
+        recovery["channel"] == int(target) and recovery["catalog_only"] is catalog_only
+    )
+    assert state["events"][-1]["action"] == "activate"
+    assert not page.evaluate(
+        "Object.values(localStorage).some(value => value.includes('"
+        + BOT
+        + "') || value.includes('"
+        + KEY
+        + "'))"
+    )
+    capture(page, f"channel-recovery-activated-{theme}-{width}.png")
+
+
+def test_enabled_backup_refreshes_idle_lag_without_manual_reload(server, desktop):
+    _, page = desktop
+    page.clock.install()
+    login(page, server.url)
+    response = page.request.post(
+        server.url + "/api/v1/replica/configure",
+        data={
+            "channel_id": int(BACKUP_CHANNEL),
+            "bot_token": BOT,
+            "independent_accounts": True,
+        },
+    )
+    assert response.ok
+    response = page.request.post(
+        server.url + "/__test__/replica/protected", headers=CONTROL
+    )
+    assert response.ok
+    section = open_storage(page)
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Backup confirmed")
+    response = page.request.post(
+        server.url + "/__test__/replica/lagging", headers=CONTROL
+    )
+    assert response.ok
+    page.clock.fast_forward(15001)
+    expect(section.locator(".channel-backup-confirmation")).to_contain_text(
+        "Catalog revision 10 is waiting to be protected"
+    )
+    expect(section.locator(".channel-backup-phase")).to_contain_text("Ready to sync")
+
+
+def test_slow_backup_poll_updates_progress_before_starting_the_next_request(
+    server, desktop
+):
+    _, page = desktop
+    page.clock.install()
+    login(page, server.url)
+    response = page.request.post(
+        server.url + "/api/v1/replica/configure",
+        data={
+            "channel_id": int(BACKUP_CHANNEL),
+            "bot_token": BOT,
+            "independent_accounts": True,
+        },
+    )
+    assert response.ok
+    section = open_storage(page)
+    progress = section.get_by_role(
+        "progressbar", name="Channel copy progress", exact=True
+    )
+    expect(progress).to_have_attribute("value", str(1024**2))
+    held = []
+    requests = []
+    payload = page.request.get(server.url + "/api/v1/replica").json()
+    payload["done_bytes"] = 2 * 1024**2
+
+    def delay_status(route):
+        requests.append(route.request)
+        if len(requests) == 1:
+            held.append(route)
+        else:
+            route.fulfill(json=payload)
+
+    page.route("**/api/v1/replica", delay_status)
+    try:
+        with page.expect_request("**/api/v1/replica"):
+            page.clock.fast_forward(5001)
+        # Deliver this response later than the five-second active polling interval.
+        # An interval timer would start a second request and discard this progress.
+        page.clock.fast_forward(6001)
+        assert len(requests) == 1
+        held.pop().fulfill(json=payload)
+        expect(progress).to_have_attribute("value", str(2 * 1024**2))
+        with page.expect_response("**/api/v1/replica"):
+            page.clock.fast_forward(5001)
+        assert len(requests) == 2
+    finally:
+        for route in held:
+            route.fulfill(json=payload)
+        page.unroute("**/api/v1/replica", delay_status)
diff --git a/tests/browser/test_browser_demo_access.py b/tests/browser/test_browser_demo_access.py
new file mode 100644
index 00000000..f4fe41d9
--- /dev/null
+++ b/tests/browser/test_browser_demo_access.py
@@ -0,0 +1,166 @@
+"""Demo visitor protection and full-access sessions in real Chromium."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+FULL_PASSWORD = "synthetic full demo password"
+SAMPLE_CONTENT = b"Welcome to the public TGDrive demo.\n"
+
+
+@pytest.fixture
+def full_demo_server(monkeypatch, request):
+    # Resolve the server only after its child process can inherit this policy.
+    monkeypatch.setenv("DEMO_MODE", "true")
+    monkeypatch.setenv("DEMO_ADMIN_PASSWORD", FULL_PASSWORD)
+    monkeypatch.delenv("DEMO_ADMIN_PASSWORD_HASH", raising=False)
+    return request.getfixturevalue("server")
+
+
+def navigate(page, label):
+    fixtures.open_admin(page)
+    page.get_by_role("link", name=label, exact=True).click()
+
+
+def new_folder(page, name):
+    page.locator("#new-button:visible, #compact-new-button:visible").click()
+    page.get_by_role("button", name="New Folder", exact=True).click()
+    dialog = page.get_by_role("dialog", name="New Folder", exact=True)
+    dialog.get_by_label("Folder Name", exact=True).fill(name)
+    dialog.get_by_role("button", name="Create Folder", exact=True).click()
+    return dialog
+
+
+def logout(page):
+    fixtures.open_admin(page)
+    page.get_by_role("button", name="Log Out", exact=True).click()
+    expect(page.locator("#login-dialog")).to_be_visible()
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_demo_passwords_switch_permissions_and_preserve_readable_samples(
+    full_demo_server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 960})
+    url = full_demo_server.url
+    login(page, url + "/?view=settings&section=regional")
+    expect(page.get_by_label("Timezone", exact=True)).to_be_disabled()
+    expect(page.locator(".demo-mode-notice")).to_be_visible()
+    config = page.request.get(url + "/api/config").json()
+    assert config["demo_mode"] and config["demo_read_only"]
+    assert not config["demo_admin"]
+
+    navigate(page, "My Files")
+    demo_row = page.locator(".file-row").filter(
+        has=page.get_by_role("button", name="Demo Files", exact=True)
+    )
+    expect(demo_row.locator(".demo-files-read-only-label")).to_have_text("Read-only")
+    expect(new_folder(page, "Visitor workspace")).not_to_be_visible()
+    expect(
+        page.get_by_role("button", name="Visitor workspace", exact=True)
+    ).to_be_visible()
+
+    page.get_by_role("button", name="Demo Files", exact=True).press("Enter")
+    expect(page.locator(".demo-files-read-only-note")).to_be_visible()
+    new_folder(page, "Blocked visitor change")
+    protection = page.get_by_role("dialog", name="Demo Files is read-only", exact=True)
+    expect(protection).to_be_visible()
+    expect(protection).to_contain_text("Open My Files")
+    expect(protection.get_by_role("button", name="Close", exact=True)).to_be_focused()
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(path=ARTIFACTS / f"demo-files-protection-{width}.png")
+    protection.get_by_role("button", name="Open My Files", exact=True).click()
+    expect(protection).not_to_be_visible()
+    expect(page.get_by_role("button", name="Demo Files", exact=True)).to_be_visible()
+
+    # Use this same page and login form for the full-access password.
+    logout(page)
+    page.get_by_label("Password", exact=True).fill(FULL_PASSWORD)
+    page.get_by_role("button", name="Log in", exact=True).click()
+    expect(page.locator("#login-dialog")).not_to_be_visible()
+    config = page.request.get(url + "/api/config").json()
+    assert config["demo_mode"] and config["demo_admin"]
+    assert not config["demo_read_only"]
+    expect(demo_row.locator(".demo-files-read-only-label")).to_have_count(0)
+
+    navigate(page, "Timezone")
+    timezone = page.get_by_label("Timezone", exact=True)
+    expect(timezone).to_be_enabled()
+    expect(page.locator(".demo-mode-notice")).to_have_count(0)
+    timezone.fill("UTC")
+    with page.expect_response(
+        lambda response: (
+            response.url.endswith("/api/v1/settings/performance")
+            and response.request.method == "PATCH"
+        )
+    ) as saved:
+        page.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    assert saved.value.ok
+    expect(timezone).to_have_value("UTC")
+
+    navigate(page, "My Files")
+    page.get_by_role("button", name="Demo Files", exact=True).press("Enter")
+    expect(new_folder(page, "Owner sample folder")).not_to_be_visible()
+    expect(
+        page.get_by_role("button", name="Owner sample folder", exact=True)
+    ).to_be_visible()
+    page.locator("#new-button:visible, #compact-new-button:visible").click()
+    with page.expect_file_chooser() as chooser:
+        page.locator("#file-upload-action").click()
+    chooser.value.set_files(
+        [
+            {
+                "name": "Demo welcome.txt",
+                "mimeType": "text/plain",
+                "buffer": SAMPLE_CONTENT,
+            }
+        ]
+    )
+    started = fixtures.finish_fixture_uploads(page, full_demo_server, 1)
+    assert started[0]["destination"] == "/tgdrive-demo-files"
+    expect(
+        page.get_by_role("button", name="Demo welcome.txt", exact=True)
+    ).to_be_visible()
+
+    # The ordinary password must lose owner capability without a page reload.
+    logout(page)
+    login(page)
+    navigate(page, "Timezone")
+    expect(page.get_by_label("Timezone", exact=True)).to_be_disabled()
+    expect(page.get_by_label("Timezone", exact=True)).to_have_value("UTC")
+    expect(page.locator(".demo-mode-notice")).to_be_visible()
+    config = page.request.get(url + "/api/config").json()
+    assert config["demo_read_only"] and not config["demo_admin"]
+
+    navigate(page, "My Files")
+    page.get_by_role("button", name="Demo Files", exact=True).press("Enter")
+    expect(page.locator(".demo-files-read-only-note")).to_be_visible()
+    expect(
+        page.get_by_role("button", name="Owner sample folder", exact=True)
+    ).to_be_visible()
+    expect(
+        page.get_by_role("button", name="Blocked visitor change", exact=True)
+    ).to_have_count(0)
+    sample = page.get_by_role("button", name="Demo welcome.txt", exact=True)
+    sample.press("Enter")
+    expect(page.locator(".text-preview")).to_contain_text(
+        SAMPLE_CONTENT.decode().strip()
+    )
+    page.get_by_role("button", name="Close Preview", exact=True).click()
+    page.get_by_label("Actions for Demo welcome.txt", exact=True).click()
+    with page.expect_download() as download:
+        page.get_by_role("link", name="Download", exact=True).click()
+    assert Path(download.value.path()).read_bytes() == SAMPLE_CONTENT
+    page.screenshot(path=ARTIFACTS / f"demo-files-visitor-samples-{width}.png")
diff --git a/tests/browser/test_browser_demo_mode.py b/tests/browser/test_browser_demo_mode.py
new file mode 100644
index 00000000..55e5d457
--- /dev/null
+++ b/tests/browser/test_browser_demo_mode.py
@@ -0,0 +1,165 @@
+"""Public demo controls remain inspectable in the production interface."""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 to run Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login
+
+browser = fixtures.browser
+desktop = fixtures.desktop
+server = fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.fixture
+def demo_server(monkeypatch, request):
+    monkeypatch.setenv("DEMO_MODE", "true")
+    return request.getfixturevalue("server")
+
+
+@pytest.mark.parametrize("config_failure", [False, True])
+def test_management_waits_for_deployment_policy(demo_server, desktop, config_failure):
+    _, page = desktop
+    config = page.request.get(demo_server.url + "/api/config").json()
+    pending = []
+
+    def deployment_config(route):
+        if config_failure:
+            route.abort("failed")
+        else:
+            pending.append(route)
+
+    page.route("**/api/config", deployment_config)
+    login(page, demo_server.url + "/?view=settings&section=cache")
+    state = page.locator(".deployment-config-state")
+    expect(state).to_be_visible()
+    expect(page.get_by_label("Memory cache (MiB)", exact=True)).to_have_count(0)
+    expect(page.locator(".demo-mode-notice")).to_have_count(0)
+
+    if config_failure:
+        expect(state).to_have_attribute("role", "alert")
+        page.unroute("**/api/config", deployment_config)
+        state.get_by_role("button", name="Try Again", exact=True).click()
+    else:
+        # Login refreshes session-specific permissions. An earlier response
+        # must never apply owner capability to the newly authenticated visitor.
+        deadline = time.monotonic() + 5
+        while len(pending) < 2 and time.monotonic() < deadline:
+            page.wait_for_timeout(10)
+        assert len(pending) >= 2, "Expected a fresh configuration after login"
+        pending[0].fulfill(json={**config, "demo_read_only": False, "demo_admin": True})
+        # Let the fetch body and React state updates settle before asserting
+        # that the stale response leaves the management gate in place.
+        page.evaluate("() => new Promise(requestAnimationFrame)")
+        expect(state).to_be_visible()
+        expect(page.get_by_label("Memory cache (MiB)", exact=True)).to_have_count(0)
+        for route in pending[1:]:
+            route.fulfill(json=config)
+
+    expect(state).to_have_count(0)
+    expect(page.get_by_label("Memory cache (MiB)", exact=True)).to_be_disabled()
+    expect(page.locator(".demo-mode-notice")).to_be_visible()
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_demo_pages_lock_changes_keep_navigation_and_file_features(
+    demo_server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 960})
+    management_writes = []
+    page.on(
+        "request",
+        lambda request: (
+            management_writes.append(request.url)
+            if request.method not in {"GET", "HEAD", "OPTIONS"}
+            and re.search(r"/api/v1/(settings|replica|backup)(/|$)", request.url)
+            else None
+        ),
+    )
+    login(page, demo_server.url + "/?view=settings&section=cache")
+    assert page.request.get(demo_server.url + "/api/config").json()["demo_mode"]
+
+    def navigate(label):
+        fixtures.open_admin(page)
+        page.get_by_role("link", name=label, exact=True).click()
+        expect(page.locator(".demo-mode-notice")).to_contain_text("read-only")
+
+    expect(page.locator(".demo-mode-notice")).to_be_visible()
+    expect(page.get_by_label("Memory cache (MiB)", exact=True)).to_be_disabled()
+    expect(page.get_by_label("Memory cache (MiB)", exact=True)).not_to_have_value("")
+    expect(
+        page.get_by_role("switch", name=re.compile(r"^Preload during playback"))
+    ).to_be_disabled()
+    expect(
+        page.get_by_role("button", name="Save Performance Settings", exact=True)
+    ).to_be_disabled()
+    expect(
+        page.get_by_role("button", name="Restore defaults", exact=True)
+    ).to_be_disabled()
+
+    navigate("Transfer limits")
+    expect(page.get_by_label("More Uploads per Bot", exact=True)).to_be_disabled()
+    expect(page.get_by_label("Maximum file size (GiB)", exact=True)).to_be_disabled()
+    expect(
+        page.get_by_role("button", name="Change folder", exact=True)
+    ).to_be_disabled()
+    page.get_by_text("Advanced Telegram limits", exact=True).click()
+    expect(page.get_by_label("Requests per account", exact=True)).to_be_visible()
+    expect(page.get_by_label("Requests per account", exact=True)).to_be_disabled()
+
+    navigate("Timezone")
+    expect(page.get_by_label("Timezone", exact=True)).to_be_disabled()
+
+    navigate("Connections")
+    expect(
+        page.get_by_role("heading", name="Storage Clients", exact=True)
+    ).to_be_visible()
+    for name in [
+        "Refresh",
+        "Add Storage Bot",
+        "Connect Premium Account",
+        "Edit API Credentials",
+    ]:
+        expect(page.get_by_role("button", name=name, exact=True)).to_be_disabled()
+    for control in page.get_by_role("button", name=re.compile(r"^Manage ")).all():
+        expect(control).to_be_disabled()
+
+    navigate("Storage & Backups")
+    expect(page.get_by_role("button", name="Back Up Now", exact=True)).to_be_disabled()
+    expect(page.get_by_role("button", name="Check Again", exact=True)).to_be_enabled()
+    expect(
+        page.get_by_role("button", name="Refresh channel backup status", exact=True)
+    ).to_be_enabled()
+    expect(
+        page.get_by_role("button", name="Set up backup channel", exact=True)
+    ).to_be_disabled()
+    page.get_by_text("Recover a channel or catalog", exact=True).click()
+    expect(page.get_by_label("Surviving channel ID", exact=True)).to_be_visible()
+    expect(page.get_by_label("Surviving channel ID", exact=True)).to_be_disabled()
+    expect(page.locator('a[href="/api/v1/replica/key"]')).to_have_count(0)
+    expect(page.locator('a[href="/api/v1/backup/recovery-key"]')).to_have_count(0)
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(path=ARTIFACTS / f"demo-management-{width}.png", full_page=True)
+    assert management_writes == []
+
+    # Regular visitor features still use real UI actions and the normal API.
+    fixtures.open_admin(page)
+    page.get_by_role("link", name="My Files", exact=True).click()
+    expect(page.locator(".demo-mode-notice")).to_have_count(0)
+    folder = page.request.post(
+        demo_server.url + "/api/createNewFolder",
+        data={"path": "/", "name": "Public demo folder"},
+    )
+    assert folder.ok
+    fixtures.upload(page, ["public-demo-upload.bin"])
+    assert demo_server.wait_started(1)[0]["name"] == "public-demo-upload.bin"
diff --git a/tests/browser/test_browser_e2e.py b/tests/browser/test_browser_e2e.py
new file mode 100644
index 00000000..2844c74e
--- /dev/null
+++ b/tests/browser/test_browser_e2e.py
@@ -0,0 +1,4426 @@
+"""Real Chromium coverage of the production UI and HTTP application.
+
+TGDRIVE_E2E=1 uv run --group e2e pytest -m e2e tests/browser/test_browser_e2e.py
+Install Chromium first: uv run --group e2e playwright install --with-deps chromium
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+from urllib.request import Request, urlopen
+
+import pytest
+
+pytestmark = pytest.mark.e2e
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip(
+        "Set TGDRIVE_E2E=1 to run real Chromium E2E tests", allow_module_level=True
+    )
+
+playwright = pytest.importorskip("playwright.sync_api")
+expect = playwright.expect
+ROOT = Path(__file__).resolve().parents[2]
+PASSWORD = "offline browser test password"
+CONTROL = {"x-fixture-control": "tgdrive-offline-browser-fixture"}
+ARTIFACTS = Path(os.environ.get("TGDRIVE_E2E_ARTIFACTS", ROOT / "cache/browser-e2e"))
+UPLOAD_RECOVERY_RECORDS = """(() => {
+    const prefix = 'tgdrive.uploads.v2:';
+    const rows = new Map(JSON.parse(localStorage.getItem('tgdrive.uploads.v2') || '[]')
+        .map(row => [row.key, row]));
+    for (const key of Object.keys(localStorage)) {
+        if (!key.startsWith(prefix)) continue;
+        const row = JSON.parse(localStorage.getItem(key));
+        if (row === null) rows.delete(key.slice(prefix.length));
+        else rows.set(key.slice(prefix.length), row);
+    }
+    return [...rows.values()];
+})()"""
+
+
+class Server:
+    def __init__(self, url: str) -> None:
+        self.url = url
+
+    def control(self, path: str = "/state", *, method: str = "GET") -> dict[str, Any]:
+        request = Request(  # noqa: S310 - fixture URL is a fixed loopback server
+            self.url + "/__test__" + path, headers=CONTROL, method=method
+        )
+        with urlopen(request, timeout=5) as response:  # noqa: S310 - loopback test server
+            return json.load(response)
+
+    def wait_started(self, count: int) -> list[dict[str, Any]]:
+        deadline = time.monotonic() + 10
+        while time.monotonic() < deadline:
+            started = self.control()["started"]
+            if len(started) >= count:
+                return started
+            time.sleep(0.05)
+        pytest.fail(
+            f"Expected {count} uploads to start; fixture state: {self.control()}"
+        )
+
+    def finish(self, transfer_id: str) -> None:
+        self.control(f"/finish/{transfer_id}", method="POST")
+
+
+@pytest.fixture
+def server(tmp_path: Path) -> Iterator[Server]:
+    with socket.socket() as listener:
+        listener.bind(("127.0.0.1", 0))
+        port = listener.getsockname()[1]
+    url = f"http://127.0.0.1:{port}"
+    log_path = tmp_path / "fixture.log"
+    with log_path.open("wb") as log:
+        process = subprocess.Popen(  # noqa: S603 - fixed local test process
+            [
+                sys.executable,
+                "-m",
+                "uvicorn",
+                "tests.support.browser_transfer_app:app",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                str(port),
+                "--log-level",
+                "warning",
+            ],
+            cwd=ROOT,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+        )
+        try:
+            deadline = time.monotonic() + 15
+            ready = False
+            while time.monotonic() < deadline and process.poll() is None:
+                try:
+                    with urlopen(url + "/healthz", timeout=1) as response:  # noqa: S310
+                        ready = response.status == 200
+                except OSError:
+                    pass
+                if ready:
+                    break
+                time.sleep(0.05)
+            assert ready, log_path.read_text(errors="replace")
+            yield Server(url)
+        finally:
+            process.terminate()
+            try:
+                process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=5)
+
+
+@pytest.fixture(scope="module")
+def browser():
+    with playwright.sync_playwright() as engine:
+        chromium = engine.chromium.launch(headless=True, channel="chromium")
+        yield chromium
+        chromium.close()
+
+
+@pytest.fixture
+def desktop(browser: Any, request: pytest.FixtureRequest):
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    context = browser.new_context(viewport={"width": 1440, "height": 960})
+    context.tracing.start(screenshots=True, snapshots=True, sources=True)
+    page = context.new_page()
+    page.set_default_timeout(10000)
+    errors: list[str] = []
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    yield context, page
+    if not page.is_closed():
+        page.unroute_all(behavior="ignoreErrors")
+    context.tracing.stop(path=ARTIFACTS / f"{request.node.name}.zip")
+    context.close()
+    assert errors == [], f"Uncaught browser errors: {errors}"
+
+
+def login(page: Any, url: str | None = None) -> None:
+    if url:
+        page.goto(url)
+    expect(page.locator("#login-dialog")).to_be_visible()
+    page.get_by_label("Password", exact=True).fill(PASSWORD)
+    page.get_by_role("button", name="Log in", exact=True).click()
+    expect(page.locator("#login-dialog")).not_to_be_visible()
+
+
+def open_admin(page: Any) -> None:
+    sidebar = page.locator(".sidebar")
+    if page.viewport_size["width"] <= 720:
+        if sidebar.get_attribute("inert") is not None:
+            page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+    else:
+        expect(sidebar).not_to_have_attribute("inert", "")
+    tools = sidebar.locator(".sidebar-tools")
+    if tools.get_attribute("open") is None:
+        tools.locator("summary").click()
+
+
+def upload(page: Any, names: list[str], *, add: bool = False) -> None:
+    page.locator("#new-button:visible, #compact-new-button:visible").click()
+    button = page.locator("#file-upload-action")
+    with page.expect_file_chooser() as chooser:
+        button.click()
+    chooser.value.set_files(
+        [
+            {
+                "name": name,
+                "mimeType": "application/octet-stream",
+                "buffer": b"x" * 65536,
+            }
+            for name in names
+        ]
+    )
+
+
+def cancel_all(page: Any) -> None:
+    page.get_by_role("button", name="Cancel All", exact=True).click()
+    page.get_by_role("dialog", name="Cancel All Uploads?", exact=True).get_by_role(
+        "button", name="Cancel Uploads", exact=True
+    ).click()
+
+
+def select_folder(page: Any, directory: Path):
+    page.locator("#new-button:visible, #compact-new-button:visible").click()
+    with page.expect_file_chooser() as chooser:
+        page.locator("#folder-upload-action").click()
+    chooser.value.set_files(str(directory))
+    dialog = page.get_by_role("dialog", name="Upload Folder", exact=True)
+    expect(dialog).to_be_visible()
+    return dialog
+
+
+def select_item(page: Any, name: str) -> None:
+    checkbox = page.get_by_label("Select " + name, exact=True)
+    if not checkbox.count():
+        page.get_by_role("button", name="Select", exact=True).click()
+    checkbox.check()
+
+
+def fixture_nodes(page: Any, server: Server, parent: str) -> list[dict[str, Any]]:
+    response = page.request.get(
+        server.url + "/api/v1/nodes", params={"parent_id": parent, "limit": 500}
+    )
+    assert response.ok, response.text()
+    return response.json()["items"]
+
+
+def finish_fixture_uploads(page: Any, server: Server, count: int):
+    started = server.wait_started(count)
+    for item in started:
+        server.finish(item["id"])
+    deadline = time.monotonic() + 15
+    while time.monotonic() < deadline:
+        records = server.control()["records"]
+        if all(records[item["id"]]["status"] == "completed" for item in started):
+            return started
+        page.wait_for_timeout(100)
+    pytest.fail(f"Fixture uploads did not finish: {server.control()['records']}")
+
+
+def row(page: Any, filename: str):
+    # Ordinary files render directly; folder children mount when their task opens.
+    # Open each batch once; avoid toggling an already expanded group.
+    expect(page.locator("#transfer-list")).to_be_visible()
+    for toggle in page.locator("button.transfer-batch-toggle").all():
+        if toggle.get_attribute("aria-expanded") == "false":
+            toggle.click()
+    return page.locator(".transfer-item").filter(
+        has=page.locator(".transfer-item-name", has_text=filename)
+    )
+
+
+def assert_layout(page: Any) -> None:
+    # Expanded batches intentionally scroll. Confirm that each file action is
+    # reachable, rather than treating a row below the scrollport as covered.
+    for control in page.locator(
+        "#transfer-dialog .transfer-item-actions button:not(:disabled)"
+    ).all():
+        control.scroll_into_view_if_needed()
+        assert control.evaluate("""button => {
+          const rect=button.getBoundingClientRect();
+          const hit=document.elementFromPoint(
+            rect.left+rect.width/2,rect.top+rect.height/2);
+          return hit===button || button.contains(hit);
+        }"""), control.get_attribute("aria-label") or control.inner_text()
+    metrics = page.evaluate(
+        """() => ({
+          width: innerWidth,
+          scrollWidth: document.documentElement.scrollWidth,
+          unnamedButtons: [...document.querySelectorAll('button')].filter(button => {
+            const rect = button.getBoundingClientRect();
+            return rect.width && rect.height && !button.closest('[hidden]')
+              && !button.textContent.trim() && !button.getAttribute('aria-label')
+              && !button.getAttribute('aria-labelledby');
+          }).length,
+          coveredTransferControls: [...document.querySelectorAll(
+            '#transfer-dialog button:not(:disabled)'
+          )].filter(button => {
+            const rect = button.getBoundingClientRect();
+            if (!rect.width || !rect.height || button.hidden) return false;
+            const x=rect.left+rect.width/2,y=rect.top+rect.height/2;
+            if(x<0 || y<0 || x>=innerWidth || y>=innerHeight) return false;
+            for(let ancestor=button.parentElement;ancestor;
+                ancestor=ancestor.parentElement){
+              const style=getComputedStyle(ancestor);
+              const clip=ancestor.getBoundingClientRect();
+              if(style.overflowX!=='visible' && (x<clip.left || x>=clip.right))
+                return false;
+              if(style.overflowY!=='visible' && (y<clip.top || y>=clip.bottom))
+                return false;
+            }
+            const hit = document.elementFromPoint(
+              rect.left + rect.width / 2, rect.top + rect.height / 2
+            );
+            return hit !== button && !button.contains(hit);
+          }).map(button => {
+            const rect = button.getBoundingClientRect();
+            const hit = document.elementFromPoint(
+              rect.left + rect.width / 2, rect.top + rect.height / 2
+            );
+            return {label: button.getAttribute('aria-label') || button.textContent,
+              hit: hit?.className, top: rect.top, bottom: rect.bottom};
+          }),
+          panel: (() => {
+            const panel = document.querySelector('#transfer-dialog');
+            if (!panel) return {left: 0, right: 0, bottom: 0};
+            const rect = panel.getBoundingClientRect();
+            return {left: rect.left, right: rect.right, bottom: rect.bottom};
+          })()
+        })"""
+    )
+    assert metrics["scrollWidth"] <= metrics["width"]
+    assert metrics["unnamedButtons"] == 0
+    assert metrics["coveredTransferControls"] == []
+    assert metrics["panel"]["left"] >= 0
+    assert metrics["panel"]["right"] <= metrics["width"]
+    assert metrics["panel"]["bottom"] <= page.viewport_size["height"]
+
+
+def preview_dialog(page: Any):
+    # Non-native files begin in a compact checking shell. Wait for supported
+    # descriptors to expand before checking the full-window preview contract.
+    dialog = page.locator("dialog.file-preview:not(.file-details)")
+    expect(dialog).to_be_visible()
+    expect(dialog).to_have_attribute("aria-labelledby", "preview-title")
+    assert dialog.evaluate("element => element.matches(':modal')")
+    expect(
+        dialog.get_by_role("button", name="Close Preview", exact=True)
+    ).to_be_visible()
+    download = dialog.get_by_role("link", name="Download Original", exact=True)
+    expect(download).to_be_visible()
+    metrics = dialog.evaluate("""element => {
+      const rect=element.getBoundingClientRect();
+      return {left:rect.left,top:rect.top,width:rect.width,height:rect.height,
+        viewportWidth:innerWidth,viewportHeight:innerHeight};
+    }""")
+    assert abs(metrics["left"]) <= 1 and abs(metrics["top"]) <= 1
+    assert abs(metrics["width"] - metrics["viewportWidth"]) <= 1
+    assert abs(metrics["height"] - metrics["viewportHeight"]) <= 1
+    assert download.bounding_box()["y"] < 100, (
+        "Original download belongs in the top toolbar"
+    )
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    return dialog
+
+
+def file_details_dialog(page: Any, filename: str):
+    dialog = page.locator("dialog.file-preview.file-details")
+    expect(dialog).to_be_visible()
+    expect(dialog).to_have_attribute("aria-labelledby", "preview-title")
+    assert dialog.evaluate("element=>element.matches(':modal')")
+    expect(dialog.get_by_role("heading", name=filename, exact=True)).to_be_visible()
+    expect(dialog.locator("#file-details-reason")).to_contain_text("Download")
+    download = dialog.get_by_role("link", name="Download Original", exact=True)
+    expect(download).to_be_visible()
+    expect(download).to_have_count(1)
+    expect(download).to_have_attribute("download", filename)
+    expect(
+        dialog.get_by_role("button", name="Back to files", exact=True)
+    ).to_have_count(0)
+    expect(
+        dialog.get_by_role("button", name="Close Preview", exact=True)
+    ).to_be_visible()
+    metadata = dialog.locator("dl").evaluate("""element => Object.fromEntries(
+      [...element.querySelectorAll('dt')].map(term=>[
+        term.textContent.trim(),term.nextElementSibling?.textContent.trim()
+      ]))""")
+    assert set(metadata) == {"Type", "Size", "Added"}
+    assert all(value and value != "—" for value in metadata.values())
+    bounds = dialog.bounding_box()
+    viewport = page.viewport_size
+    assert bounds is not None
+    assert bounds["x"] >= 0 and bounds["x"] + bounds["width"] <= viewport["width"]
+    assert bounds["y"] >= 0 and bounds["y"] + bounds["height"] <= viewport["height"]
+    assert bounds["width"] <= 520
+    assert bounds["height"] < viewport["height"] - 20
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    assert dialog.locator("video,audio,canvas,iframe").count() == 0
+    return dialog, metadata
+
+
+def assert_rendered_pdf_page(page: Any, filename: str, number: int):
+    canvas = page.get_by_role("img", name=f"{filename}, page {number}", exact=True)
+    expect(canvas).to_be_visible(timeout=20000)
+    expect(canvas).to_be_in_viewport()
+    assert canvas.evaluate("""canvas => {
+      const context=canvas.getContext('2d');
+      const data=context.getImageData(0,0,canvas.width,canvas.height).data;
+      let dark=0;
+      for(let i=0;i<data.length;i+=4)
+        if(data[i+3]>0 && data[i]<150 && data[i+1]<150 && data[i+2]<150) dark++;
+      return dark>100;
+    }"""), "PDF page must contain rendered glyphs, not an empty canvas"
+    return canvas
+
+
+def assert_pdf_header_layout(page: Any, dialog: Any) -> None:
+    expect(dialog.locator(".preview-header")).to_have_count(1)
+    toolbar = dialog.locator(".pdf-toolbar")
+    expect(toolbar).to_have_count(1)
+    assert toolbar.evaluate("element=>Boolean(element.closest('.preview-header'))")
+    layout = dialog.evaluate("""element => {
+      const header=element.querySelector('.preview-header').getBoundingClientRect();
+      const scroll=element.querySelector('.pdf-scroll').getBoundingClientRect();
+      return {headerHeight:header.height,headerBottom:header.bottom,
+        scrollTop:scroll.top};
+    }""")
+    # Phone readers use a second row for navigation and accessible touch targets.
+    max_height = 120 if page.viewport_size["width"] <= 720 else 72
+    assert layout["headerHeight"] <= max_height, "Preview controls must stay compact"
+    assert abs(layout["scrollTop"] - layout["headerBottom"]) <= 1, (
+        "PDF viewport must start below the one header, without a second toolbar"
+    )
+    if page.viewport_size["width"] > 720:
+        header = dialog.locator(".preview-header").bounding_box()
+        for name in ("Zoom in", "Zoom Out", "Fit Width"):
+            control = toolbar.get_by_role("button", name=name, exact=True)
+            expect(control).to_be_visible()
+            bounds = control.bounding_box()
+            assert bounds["y"] >= header["y"] - 1
+            assert bounds["y"] + bounds["height"] <= header["y"] + header["height"] + 1
+
+
+def assert_pdf_canvas_budget(dialog: Any, *, max_canvases: int | None = 5) -> None:
+    sizes = dialog.locator(".pdf-page canvas").evaluate_all(
+        "canvases=>canvases.map(canvas=>canvas.width*canvas.height)"
+    )
+    assert sizes
+    if max_canvases is not None:
+        assert len(sizes) <= max_canvases
+    assert all(size <= 2_000_000 for size in sizes)
+    assert sum(sizes) <= 10_000_000
+
+
+def test_resumable_multiple_files_navigation_and_mobile_layout(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    upload(page, ["first.txt", "second.txt"])
+    started = server.wait_started(2)
+    expect(row(page, "first.txt")).to_have_attribute("data-status", "uploading")
+    expect(row(page, "second.txt")).to_have_attribute("data-status", "uploading")
+    page.get_by_role("button", name="Hide Transfer Details", exact=True).click()
+    expect(page.locator("#transfer-list")).not_to_be_visible()
+    page.get_by_role("link", name="Trash", exact=True).click()
+    expect(page.get_by_role("heading", name="Trash", exact=True)).to_be_visible()
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    page.get_by_role("button", name="資料", exact=True).dblclick()
+    expect(page.get_by_role("button", name="résumé #1.txt", exact=True)).to_be_visible()
+    page.get_by_role("button", name="Show Transfer Details", exact=True).click()
+    expect(row(page, "first.txt").locator(".transfer-metrics")).to_contain_text("/s")
+    expect(row(page, "first.txt").locator(".transfer-metrics")).to_contain_text(
+        "remaining"
+    )
+    assert_layout(page)
+    page.screenshot(path=ARTIFACTS / "react-desktop.png", full_page=True)
+    page.set_viewport_size({"width": 390, "height": 844})
+    assert_layout(page)
+    page.screenshot(path=ARTIFACTS / "react-mobile.png", full_page=True)
+    expect(
+        page.get_by_role("button", name="Open transfer progress", exact=True)
+    ).to_be_visible()
+    expect(page.locator(".transfer-center")).to_have_count(0)
+    page.set_viewport_size({"width": 1440, "height": 900})
+    server.finish(started[0]["id"])
+    expect(row(page, "first.txt")).to_have_attribute("data-status", "completed")
+    clear = page.get_by_role("button", name="Clear Finished", exact=True)
+    expect(clear).to_be_enabled()
+    clear.click()
+    expect(row(page, "first.txt")).to_have_count(0)
+    expect(row(page, "second.txt")).to_be_visible()
+    server.finish(started[1]["id"])
+    expect(row(page, "second.txt")).to_have_attribute("data-status", "completed")
+    expect(clear).to_be_enabled()
+    clear.click()
+    expect(page.locator(".transfer-batch")).to_have_count(0)
+    page.wait_for_timeout(1800)
+    expect(page.locator(".transfer-batch")).to_have_count(0)
+
+
+def test_reload_reselect_checks_original_and_resumes_acknowledged_bytes(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    payload = {
+        "name": "resumable.bin",
+        "mimeType": "application/octet-stream",
+        "buffer": b"x" * (10 * 1024 * 1024),
+    }
+
+    def interrupt_after_first_chunk(route):
+        if (
+            route.request.method == "PATCH"
+            and route.request.headers.get("upload-offset") != "0"
+        ):
+            route.abort()
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/uploads/*", interrupt_after_first_chunk)
+    page.locator("#file-input").set_input_files(payload)
+    # Network interruptions retry after 2, 4 and 8 seconds. Let those attempts
+    # exhaust before testing reload/reselection; do not block their hashing.
+    expect(row(page, "resumable.bin")).to_have_attribute(
+        "data-status", "error", timeout=25000
+    )
+    assert server.control()["started"] == []
+    page.unroute("**/api/v1/uploads/*", interrupt_after_first_chunk)
+    page.add_init_script("""
+      const originalDigest = crypto.subtle.digest.bind(crypto.subtle);
+      crypto.subtle.digest = async (...args) => {
+        await new Promise(resolve => { window.__releaseOriginalCheck = resolve; });
+        return originalDigest(...args);
+      };
+    """)
+    page.reload()
+    expect(row(page, "resumable.bin")).to_have_attribute("data-status", "error")
+    expect(row(page, "resumable.bin").locator(".transfer-recovery")).to_be_visible()
+    with page.expect_file_chooser() as chooser:
+        row(page, "resumable.bin").get_by_role(
+            "button", name="Choose File", exact=True
+        ).click()
+    resumed_offsets = []
+    page.on(
+        "request",
+        lambda request: (
+            resumed_offsets.append(request.headers.get("upload-offset"))
+            if request.method == "PATCH" and "/api/v1/uploads/" in request.url
+            else None
+        ),
+    )
+    chooser.value.set_files(payload)
+    checking = row(page, "resumable.bin")
+    expect(checking).to_have_attribute("data-status", "verifying")
+    expect(checking.get_by_role("progressbar")).to_have_attribute("value", "0.8")
+    expect(checking.locator(".transfer-bytes")).to_have_text("8 / 10 MB")
+    expect(checking.locator(".transfer-metrics")).not_to_contain_text("/s")
+    expect(checking.locator(".transfer-verification .spinner")).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "resume-keeps-upload-progress.png", full_page=True)
+    page.evaluate("window.__releaseOriginalCheck()")
+    started = server.wait_started(1)
+    assert resumed_offsets and resumed_offsets[0] == str(8 * 1024 * 1024)
+    expect(row(page, "resumable.bin")).to_have_attribute("data-status", "uploading")
+    server.finish(started[0]["id"])
+    expect(row(page, "resumable.bin")).to_have_attribute("data-status", "completed")
+    expect(page.get_by_role("button", name="resumable.bin", exact=True)).to_be_visible()
+
+
+def test_cancellation_waits_for_server_confirmation(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    upload(page, ["cancel-me.txt"])
+    started = server.wait_started(1)
+    expect(row(page, "cancel-me.txt")).to_be_visible()
+    page.get_by_role("button", name="Cancel cancel-me.txt", exact=True).click()
+    expect(row(page, "cancel-me.txt")).to_have_attribute("data-status", "cancelled")
+    assert server.control()["records"][started[0]["id"]]["status"] == "cancelled"
+    expect(page.get_by_role("button", name="cancel-me.txt", exact=True)).to_have_count(
+        0
+    )
+
+
+def test_public_share_stays_readonly_across_move_and_revocation(
+    server: Server, desktop: tuple[Any, Any], browser: Any
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_label("Actions for 資料", exact=True).click()
+    page.get_by_role("button", name="Share Link", exact=True).click()
+    page.get_by_role("button", name="Create Share Link", exact=True).click()
+    link = page.get_by_label("Share Link", exact=True).input_value()
+    assert "share_" in link
+    page.get_by_role("button", name="Done", exact=True).click()
+    public_context = browser.new_context(viewport={"width": 390, "height": 844})
+    try:
+        public = public_context.new_page()
+        public.goto(link)
+        expect(
+            public.get_by_role("button", name="résumé #1.txt", exact=True)
+        ).to_be_visible()
+        expect(
+            public.get_by_role("button", name="Upload Files", exact=True)
+        ).to_have_count(0)
+        expect(public.locator(".item-actions")).to_have_count(0)
+        public_file = public.get_by_role("button", name="résumé #1.txt", exact=True)
+        public_file.click()
+        expect(public.locator("dialog.file-preview")).to_have_count(0)
+        public_file.dblclick()
+        public_dialog = preview_dialog(public)
+        expect(public_dialog.locator("pre")).to_contain_text("public content")
+        public_dialog.get_by_role("button", name="Close Preview", exact=True).click()
+        expect(public_file).to_be_focused()
+        page.get_by_label("Actions for 資料", exact=True).click()
+        page.get_by_role("button", name="Move", exact=True).click()
+        page.get_by_role("dialog").get_by_role(
+            "button", name="Private folder", exact=True
+        ).click()
+        page.get_by_role("button", name="Move Here", exact=True).click()
+        expect(page.get_by_role("dialog")).to_have_count(0)
+        public.reload()
+        expect(
+            public.get_by_role("button", name="résumé #1.txt", exact=True)
+        ).to_be_visible()
+        page.get_by_role("link", name="Shared Links", exact=True).click()
+        page.get_by_role("button", name="Revoke Link for 資料", exact=True).click()
+        page.get_by_role("button", name="Revoke Link", exact=True).click()
+        expect(
+            page.get_by_role("heading", name="No Active Shared Links")
+        ).to_be_visible()
+        public.reload()
+        expect(
+            public.get_by_role("heading", name="Shared Folder Unavailable")
+        ).to_be_visible()
+    finally:
+        public_context.close()
+
+
+def test_unicode_names_are_text_and_bulk_trash_can_be_restored(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.locator("#new-button:visible, #compact-new-button:visible").click()
+    page.get_by_role("button", name="New Folder", exact=True).click()
+    name = "資料 <img src=x onerror=alert(1)>"
+    page.get_by_label("Folder Name", exact=True).fill(name)
+    page.get_by_role("button", name="Create Folder", exact=True).click()
+    expect(page.get_by_role("button", name=name, exact=True)).to_be_visible()
+    assert page.locator("img[src=x]").count() == 0
+    select_item(page, name)
+    page.get_by_role("button", name="Trash", exact=True).click()
+    expect(page.get_by_role("button", name=name, exact=True)).to_have_count(0)
+    page.get_by_role("link", name="Trash", exact=True).click()
+    expect(page.get_by_role("button", name=name, exact=True)).to_be_visible()
+    select_item(page, name)
+    page.get_by_role("button", name="Restore", exact=True).click()
+    expect(page.get_by_role("button", name=name, exact=True)).to_have_count(0)
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    expect(page.get_by_role("button", name=name, exact=True)).to_be_visible()
+
+
+def test_queued_deletion_is_not_reported_complete_early(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Trash", exact=True).click()
+    page.get_by_role("link", name="Trash", exact=True).click()
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Delete Permanently", exact=True).click()
+    expect(page.get_by_role("dialog")).to_contain_text(
+        "The original files will remain in Telegram."
+    )
+    expect(page.get_by_role("dialog")).to_contain_text(
+        "You cannot restore these items from Trash after deletion."
+    )
+    page.get_by_role("dialog").get_by_role(
+        "button", name="Delete Permanently", exact=True
+    ).click()
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    expect(
+        page.get_by_role("region", name="File Deletion").get_by_role("status")
+    ).to_have_text("Deleting 1 item…")
+    expect(
+        page.get_by_role("button", name="Private folder", exact=True)
+    ).to_be_visible()
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    expect(page.get_by_role("region", name="File Deletion")).to_have_count(0)
+    page.get_by_role("link", name="Trash", exact=True).click()
+    expect(page.get_by_role("region", name="File Deletion")).to_be_visible()
+    records = server.control()["records"]
+    deletion_id = next(
+        key for key, value in records.items() if value["phase"] == "deleting"
+    )
+    failed_refreshes = []
+
+    def trash_refresh(route):
+        if not failed_refreshes:
+            failed_refreshes.append(True)
+            route.fulfill(status=503, json={"detail": "Temporary listing failure"})
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/trash*", trash_refresh)
+    server.finish(deletion_id)
+    expect(page.get_by_role("heading", name="Trash Is Empty")).to_be_visible(
+        timeout=10000
+    )
+    assert failed_refreshes
+
+
+@pytest.mark.parametrize("automatic_dismissal", [False, True])
+def test_fast_deletion_is_visible_when_an_older_job_poll_is_in_flight(
+    server: Server, desktop: tuple[Any, Any], automatic_dismissal: bool
+) -> None:
+    _, page = desktop
+    held = []
+    hold = True
+
+    def jobs(route):
+        if hold:
+            held.append(route)
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/jobs", jobs)
+    login(page, server.url)
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Trash", exact=True).click()
+    page.get_by_role("link", name="Trash", exact=True).click()
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Delete Permanently", exact=True).click()
+    page.get_by_role("dialog").get_by_role(
+        "button", name="Delete Permanently", exact=True
+    ).click()
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    notice = page.get_by_role("region", name="File Deletion", exact=True)
+    expect(notice.get_by_role("status")).to_have_text("Deleting 1 item…")
+    records = server.control()["records"]
+    deletion_id = next(
+        key for key, value in records.items() if value["phase"] == "deleting"
+    )
+    server.finish(deletion_id)
+    assert held
+    hold = False
+    for route in held:
+        route.fulfill(status=200, json={"jobs": []})
+    expect(page.get_by_text("Permanently deleted 1 item.", exact=True)).to_be_visible()
+    expect(notice).to_have_count(0)
+    expect(page.get_by_role("heading", name="Trash Is Empty")).to_be_visible()
+    if not automatic_dismissal:
+        page.get_by_role("button", name="Dismiss Notification", exact=True).click()
+    expect(page.get_by_text("Permanently deleted 1 item.", exact=True)).to_have_count(
+        0, timeout=9000
+    )
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    expect(notice).to_have_count(0)
+    page.get_by_role("link", name="Trash", exact=True).click()
+    with page.expect_response(lambda response: response.url.endswith("/api/v1/jobs")):
+        page.reload()
+    expect(notice).to_have_count(0)
+    expect(page.get_by_text("Permanently deleted 1 item.", exact=True)).to_have_count(0)
+
+
+def test_keyboard_dialog_focus_and_unicode_search(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    new = page.locator("#new-button")
+    new.focus()
+    new.press("Enter")
+    menu = page.locator("#new-menu")
+    expect(menu).to_be_visible()
+    expect(menu.get_by_role("button", name="Upload Files", exact=True)).to_be_focused()
+    page.keyboard.press("ArrowDown")
+    expect(menu.get_by_role("button", name="Upload Folder", exact=True)).to_be_focused()
+    page.keyboard.press("End")
+    expect(
+        menu.get_by_role("button", name="Upload from URL", exact=True)
+    ).to_be_focused()
+    page.keyboard.press("Home")
+    expect(menu.get_by_role("button", name="Upload Files", exact=True)).to_be_focused()
+    page.keyboard.press("Escape")
+    expect(menu).to_have_count(0)
+    expect(new).to_be_focused()
+    expect(new).to_have_attribute("aria-expanded", "false")
+    summary = page.get_by_label("Actions for 資料", exact=True)
+    summary.click()
+    page.get_by_role("button", name="Rename", exact=True).click()
+    expect(page.get_by_label("Name", exact=True)).to_be_focused()
+    page.keyboard.press("Escape")
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    expect(summary).to_be_focused()
+    search = page.get_by_role("searchbox", name="Search Files and Folders", exact=True)
+    search.fill("résumé")
+    search.press("Enter")
+    expect(
+        page.get_by_role("heading", name="Search Results", exact=True)
+    ).to_be_visible()
+    expect(page.get_by_role("button", name="résumé #1.txt", exact=True)).to_be_visible()
+    page.set_viewport_size({"width": 390, "height": 844})
+    compact_new = page.locator("#compact-new-button")
+    expect(compact_new).to_have_count(0)
+    search.press("Escape")
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    expect(compact_new).to_be_visible()
+    compact_new.focus()
+    compact_new.press("Enter")
+    expect(menu.get_by_role("button", name="Upload Files", exact=True)).to_be_focused()
+    page.keyboard.press("ArrowUp")
+    expect(
+        menu.get_by_role("button", name="Upload from URL", exact=True)
+    ).to_be_focused()
+    page.keyboard.press("Escape")
+    expect(menu).to_have_count(0)
+    expect(compact_new).to_be_focused()
+
+
+def test_move_and_restore_require_explicit_public_exposure_confirmation(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    seed = server.control()["seed"]
+    response = page.request.post(
+        server.url + "/api/v1/shares",
+        data={"path": seed["folder"], "expires_in_days": 7},
+    )
+    assert response.ok
+    page.get_by_label("Actions for Private folder", exact=True).click()
+    page.get_by_role("button", name="Move", exact=True).click()
+    page.get_by_role("dialog").get_by_role("button", name="資料", exact=True).click()
+    page.get_by_role("button", name="Move Here", exact=True).click()
+    confirmation = page.get_by_label(
+        "I understand that files moved here may become public.", exact=True
+    )
+    expect(confirmation).to_be_visible()
+    expect(page.get_by_role("button", name="Move Here", exact=True)).to_be_disabled()
+    confirmation.check()
+    page.get_by_role("button", name="Move Here", exact=True).click()
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    page.get_by_role("button", name="資料", exact=True).dblclick()
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Trash", exact=True).click()
+    page.get_by_role("link", name="Trash", exact=True).click()
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Restore", exact=True).click()
+    expect(
+        page.get_by_role("heading", name="Restore to a Shared Folder?", exact=True)
+    ).to_be_visible()
+    page.get_by_role(
+        "button", name="Restore and Allow Public Access", exact=True
+    ).click()
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    expect(page.get_by_role("heading", name="Trash Is Empty")).to_be_visible()
+
+
+def test_move_folder_navigation_clears_failed_listing_and_recovers(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    folder = server.control()["seed"]["folder"]
+    failed = []
+
+    def directory(route):
+        if route.request.post_data_json["path"] == folder and not failed:
+            failed.append(True)
+            route.fulfill(status=503, json={"detail": "Folder listing interrupted"})
+        else:
+            route.continue_()
+
+    page.route("**/api/getDirectory", directory)
+    page.get_by_label("Actions for Private folder", exact=True).click()
+    page.get_by_role("button", name="Move", exact=True).click()
+    dialog = page.get_by_role("dialog")
+    picker = dialog.locator(".folder-picker")
+    picker.get_by_role("button", name="資料", exact=True).click()
+    expect(dialog.get_by_role("alert")).to_contain_text("Folder listing interrupted")
+    expect(picker.get_by_role("button")).to_have_count(0)
+    dialog.get_by_role("navigation", name="Destination breadcrumb").get_by_role(
+        "button", name="My Files", exact=True
+    ).click()
+    expect(picker.get_by_role("button", name="資料", exact=True)).to_be_visible()
+    expect(dialog.get_by_role("alert")).to_have_count(0)
+    picker.get_by_role("button", name="資料", exact=True).click()
+    expect(picker).to_have_attribute("aria-busy", "false")
+    expect(dialog.get_by_role("alert")).to_have_count(0)
+    dialog.get_by_role("button", name="Cancel", exact=True).click()
+
+
+def test_session_expiry_preserves_server_job_recovery(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    upload(page, ["session-recovery.txt"])
+    started = server.wait_started(1)
+    response = page.request.post(
+        server.url + "/__test__/expire-session", headers=CONTROL
+    )
+    assert response.ok
+    expect(page.locator("#login-dialog")).to_be_visible()
+    saved = page.evaluate("JSON.stringify(Object.values(localStorage))")
+    assert PASSWORD not in saved
+    server.finish(started[0]["id"])
+    login(page)
+    expect(row(page, "session-recovery.txt")).to_have_attribute(
+        "data-status", "completed"
+    )
+    expect(
+        page.get_by_role("button", name="session-recovery.txt", exact=True)
+    ).to_be_visible()
+
+
+def test_svg_preview_renders_as_image_and_downloads_original(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    external_requests: list[str] = []
+    page.on(
+        "request",
+        lambda request: (
+            external_requests.append(request.url)
+            if "svg-external.invalid" in request.url
+            else None
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="sample.svg", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    image = dialog.get_by_role("img", name="sample.svg", exact=True)
+    expect(image).to_be_visible()
+    expect(
+        dialog.locator(".preview-surface").locator("pre, iframe, object, embed, svg")
+    ).to_have_count(0)
+    page.wait_for_function(
+        "() => { const img=document.querySelector('dialog img'); "
+        "return img && img.complete && img.naturalWidth === 120; }"
+    )
+    pixel = image.evaluate("""img => {
+        const canvas=document.createElement('canvas');
+        canvas.width=120; canvas.height=80;
+        const ctx=canvas.getContext('2d');
+        ctx.drawImage(img,0,0);
+        return Array.from(ctx.getImageData(40,40,1,1).data);
+    }""")
+    assert pixel == [24, 160, 88, 255], "SVG styles must render in image mode"
+    assert page.evaluate("window.svgPreviewExecuted") is None
+    assert external_requests == []
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    download = result.value
+    assert download.suggested_filename == "sample.svg"
+    original = Path(download.path()).read_bytes()
+    assert original == (
+        b'<svg xmlns="http://www.w3.org/2000/svg" width="120" height="80">'
+        b"<style>rect{fill:rgb(24,160,88)}</style>"
+        b'<rect width="120" height="80"/>'
+        b"<script>parent.svgPreviewExecuted=true</script>"
+        b'<image href="https://svg-external.invalid/track.png" '
+        b'width="1" height="1"/>'
+        b"</svg>"
+    )
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+
+
+def test_safe_document_previews_download_and_pdf_canvas(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="sample.json", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    expect(dialog.locator("pre")).to_contain_text(
+        '"message": "<img src=x onerror=alert(1)>"'
+    )
+    assert dialog.locator("img").count() == 0
+    page.get_by_label("Wrap Lines", exact=True).uncheck()
+    expect(dialog.locator("pre")).not_to_have_class("wrap-lines")
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    download = result.value
+    assert download.suggested_filename == "sample.json"
+    assert (
+        Path(download.path()).read_bytes()
+        == b'{"message":"<img src=x onerror=alert(1)>","count":3}'
+    )
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    page.get_by_role("button", name="source.html", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    expect(dialog.locator("pre")).to_contain_text("<script>")
+    assert page.evaluate("window.previewExecuted") is None
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    page.get_by_role("button", name="reports.csv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    expect(dialog.locator("pre")).to_contain_text("name,value")
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    page.get_by_role("button", name="sample.pdf", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    scroll = dialog.locator(".pdf-scroll")
+    expect(scroll).to_be_visible()
+    assert_rendered_pdf_page(page, "sample.pdf", 1)
+    assert_pdf_header_layout(page, dialog)
+    expect(
+        dialog.locator('.pdf-page[data-page-number="1"] .pdf-text-layer')
+    ).to_contain_text("TGDrive PDF preview page 1")
+    expect(
+        dialog.get_by_role("button", name="Previous PDF page", exact=True)
+    ).to_have_count(0)
+    expect(
+        dialog.get_by_role("button", name="Next PDF page", exact=True)
+    ).to_have_count(0)
+    expect(dialog.get_by_text("Page text", exact=True)).to_have_count(0)
+    assert scroll.evaluate("element=>element.scrollHeight>element.clientHeight")
+    for number in (2, 3):
+        if number == 2:
+            scroll.evaluate(
+                "element=>element.scrollTop=(element.scrollHeight-element.clientHeight)/2"
+            )
+        else:
+            scroll.evaluate("element=>element.scrollTop=element.scrollHeight")
+        assert_rendered_pdf_page(page, "sample.pdf", number)
+        expect(
+            dialog.locator(f'.pdf-page[data-page-number="{number}"] .pdf-text-layer')
+        ).to_contain_text(f"TGDrive PDF preview page {number}")
+        assert_pdf_canvas_budget(dialog)
+    zoom = dialog.get_by_label("PDF zoom", exact=True)
+    initial_zoom = zoom.inner_text()
+    dialog.get_by_role("button", name="Zoom in", exact=True).click()
+    expect(zoom).not_to_have_text(initial_zoom)
+    assert_pdf_canvas_budget(dialog)
+    dialog.get_by_role("button", name="Zoom Out", exact=True).click()
+    expect(zoom).to_have_text(initial_zoom)
+    dialog.get_by_role("button", name="Fit Width", exact=True).click()
+    expect(
+        dialog.get_by_role("button", name="Fit Width", exact=True)
+    ).to_have_attribute("aria-pressed", "true")
+    assert_pdf_canvas_budget(dialog)
+    page.screenshot(path=ARTIFACTS / "preview-desktop.png", full_page=False)
+    page.set_viewport_size({"width": 390, "height": 844})
+    preview_dialog(page)
+    assert_pdf_header_layout(page, dialog)
+    options = dialog.get_by_role("button", name="PDF View Options", exact=True)
+    expect(options).to_be_visible()
+    expect(dialog.get_by_role("button", name="Zoom in", exact=True)).not_to_be_visible()
+    options.click()
+    mobile_zoom = dialog.get_by_label("PDF zoom", exact=True)
+    previous_zoom = mobile_zoom.inner_text()
+    dialog.get_by_role("button", name="Zoom in", exact=True).click()
+    expect(mobile_zoom).not_to_have_text(previous_zoom)
+    dialog.get_by_role("button", name="Zoom Out", exact=True).click()
+    expect(mobile_zoom).to_have_text(previous_zoom)
+    dialog.get_by_role("button", name="Fit Width", exact=True).click()
+    page.keyboard.press("Escape")
+    expect(dialog).to_be_visible()
+    expect(options).to_be_focused()
+    expect(dialog.get_by_role("button", name="Zoom in", exact=True)).not_to_be_visible()
+    page.screenshot(path=ARTIFACTS / "preview-mobile.png", full_page=False)
+    page.set_viewport_size({"width": 320, "height": 740})
+    preview_dialog(page)
+    options.click()
+    toolbar = dialog.locator(".pdf-toolbar")
+    expect(toolbar).to_be_visible()
+    bounds = toolbar.bounding_box()
+    assert bounds is not None
+    assert bounds["x"] >= 0 and bounds["x"] + bounds["width"] <= 320
+    assert bounds["y"] >= 0 and bounds["y"] + bounds["height"] <= 740
+    dialog.get_by_role("button", name="Fit Width", exact=True).click()
+    expect(
+        dialog.get_by_role("button", name="Fit Width", exact=True)
+    ).to_have_attribute("aria-pressed", "true")
+    page.screenshot(path=ARTIFACTS / "preview-mobile-320.png", full_page=False)
+    page.keyboard.press("Escape")
+    expect(options).to_be_focused()
+    expect(toolbar).not_to_be_visible()
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    page.get_by_role("button", name="archive.bin", exact=True).dblclick()
+    dialog, metadata = file_details_dialog(page, "archive.bin")
+    assert metadata["Size"] == "256 B"
+
+
+def test_preview_error_has_retry_and_keeps_download(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.route(
+        "**/api/v1/preview?*",
+        lambda route: route.fulfill(
+            status=503,
+            content_type="application/json",
+            body='{"detail":"Preview temporarily unavailable. Try Again."}',
+        ),
+    )
+    page.get_by_role("button", name="reports.csv", exact=True).dblclick()
+    expect(page.get_by_role("alert")).to_contain_text("temporarily unavailable")
+    expect(page.locator("dialog.file-preview.file-details")).to_have_count(0)
+    expect(page.locator("#file-details-reason")).to_have_count(0)
+    expect(
+        page.get_by_role("link", name="Download Original", exact=True)
+    ).to_be_visible()
+    page.unroute("**/api/v1/preview?*")
+    page.get_by_role("button", name="Try Preview Again", exact=True).click()
+    expect(page.get_by_role("dialog").locator("pre")).to_contain_text("name,value")
+    page.get_by_role("button", name="Close Preview", exact=True).click()
+    page.route(
+        "**/api/v1/preview?*",
+        lambda route: route.fulfill(
+            status=401,
+            content_type="application/json",
+            body='{"detail":"Authentication required."}',
+        ),
+    )
+    page.get_by_role("button", name="reports.csv", exact=True).dblclick()
+    expect(page.locator("#login-dialog")).to_be_visible()
+    expect(page.locator("dialog.file-preview.file-details")).to_have_count(0)
+    expect(page.locator("#file-details-reason")).to_have_count(0)
+
+
+def test_enhanced_mkv_real_audio_subtitles_and_local_assets(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    requests: list[str] = []
+    page.on("request", lambda request: requests.append(request.url))
+    page.add_init_script("""window.cspViolations=[];
+      document.addEventListener('securitypolicyviolation',event=>{
+        window.cspViolations.push(event.violatedDirective+':'+event.blockedURI+':'+event.sourceFile+':'+event.lineNumber);
+      });""")
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="sample.json", exact=True).dblclick()
+    expect(page.get_by_role("dialog").locator("pre")).to_be_visible()
+    assert not any("element.slim-" in url or ".wasm" in url for url in requests)
+    page.get_by_role("button", name="Close Preview", exact=True).click()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    preview_dialog(page)
+    player = page.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(page.locator(".advanced-tracks")).to_have_count(0)
+    player.hover()
+    audio_button = player.get_by_role("button", name="Audio Track", exact=True)
+    expect(audio_button).to_be_visible(timeout=30000)
+    audio_button.click()
+    audio_items = player.locator(".movi-audio-track-item[data-track-id]")
+    expect(audio_items).to_have_count(2)
+    tracks = player.evaluate(
+        "element=>element.player.getAudioTracks().map(t=>({id:t.id,codec:t.codec}))"
+    )
+    assert all(track["codec"] == "eac3" for track in tracks)
+    second_audio = player.locator(
+        f'.movi-audio-track-item[data-track-id="{tracks[1]["id"]}"]'
+    )
+    second_audio.click()
+    expect(second_audio).to_have_class("movi-audio-track-item movi-audio-track-active")
+    assert (
+        player.evaluate("element=>element.player.trackManager.getActiveAudioTrack().id")
+        == tracks[1]["id"]
+    )
+    player.get_by_role("button", name="Subtitles/Captions", exact=True).click()
+    subtitle_items = player.locator(".movi-subtitle-track-item[data-track-id]")
+    expect(subtitle_items).to_have_count(2)
+    subtitle = player.evaluate("element=>element.player.getSubtitleTracks()[0].id")
+    subtitle_item = player.locator(
+        f'.movi-subtitle-track-item[data-track-id="{subtitle}"]'
+    )
+    subtitle_item.click()
+    expect(subtitle_item).to_have_class(
+        "movi-subtitle-track-item movi-subtitle-track-active"
+    )
+    player.locator("button.movi-play-pause").click()
+    deadline = time.monotonic() + 20
+    while time.monotonic() < deadline:
+        if player.evaluate("element=>element.currentTime") > 0.25:
+            break
+        page.wait_for_timeout(200)
+    assert player.evaluate("element=>element.currentTime") > 0.25
+    assert (
+        player.evaluate(
+            "element=>element.player.trackManager.getActiveSubtitleTrack().id"
+        )
+        == subtitle
+    )
+    expect(player.locator(".movi-subtitle-line").first).to_contain_text(
+        "TGDrive subtitle", timeout=15000
+    )
+    audio_deadline = time.monotonic() + 2
+    audio_active = False
+    while time.monotonic() < audio_deadline:
+        audio_active = player.evaluate(
+            "element=>element.player.getAudioLevels(8)?.some(value=>value>0)"
+        )
+        if audio_active:
+            break
+        page.wait_for_timeout(100)
+    assert audio_active is True
+    with page.expect_download() as result:
+        page.get_by_role("link", name="Download Original", exact=True).click()
+    assert (
+        Path(result.value.path()).read_bytes()
+        == (ROOT / "tests/fixtures/multitrack.mkv").read_bytes()
+    )
+    page.screenshot(path=ARTIFACTS / "enhanced-desktop.png", full_page=False)
+    page.set_viewport_size({"width": 390, "height": 844})
+    player.hover()
+    settings_button = player.get_by_role("button", name="Settings", exact=True)
+    expect(settings_button).to_be_visible()
+    expect(player.locator("button.movi-more-btn")).not_to_be_visible()
+    settings_button.click()
+    settings_menu = player.locator(".movi-settings-menu")
+    expect(settings_menu).to_be_visible()
+    settings_menu.locator('.movi-settings-row[data-page="audio"]').click()
+    first_audio = settings_menu.locator(
+        f'.movi-audio-track-item[data-track-id="{tracks[0]["id"]}"]'
+    )
+    first_audio.click()
+    page.wait_for_function(
+        "id=>document.querySelector('movi-player').player.trackManager"
+        ".getActiveAudioTrack()?.id===id",
+        arg=tracks[0]["id"],
+    )
+    expect(settings_menu).not_to_be_visible()
+    settings_button.click()
+    settings_menu.locator('.movi-settings-row[data-page="subtitles"]').click()
+    subtitles_off = settings_menu.locator(
+        '.movi-subtitle-track-item[data-track-id="null"]'
+    )
+    subtitles_off.click()
+    page.wait_for_function(
+        "()=>!document.querySelector('movi-player').player.trackManager"
+        ".getActiveSubtitleTrack()"
+    )
+    expect(page.locator(".advanced-tracks")).to_have_count(0)
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    assert not page.evaluate("window.cspViolations"), page.evaluate(
+        "({violations:window.cspViolations,styles:[...document.querySelectorAll('style')].map(s=>({id:s.id,text:s.textContent.slice(0,100)}))})"
+    )
+    assert not [
+        url
+        for url in requests
+        if url.startswith(("http://", "https://")) and not url.startswith(server.url)
+    ]
+    page.screenshot(path=ARTIFACTS / "enhanced-mobile.png", full_page=False)
+    page.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(player).to_have_count(0)
+
+
+def test_mp4_movtext_real_cues_seek_track_switch_off_and_original(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    requests: list[str] = []
+    csp: list[str] = []
+    page.on("request", lambda request: requests.append(request.url))
+    page.on(
+        "console",
+        lambda message: (
+            csp.append(message.text)
+            if "content security policy" in message.text.lower()
+            else None
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="movtext-subtitles.mp4", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    tracks = player.evaluate(
+        "element=>element.player.getSubtitleTracks().map(track=>({id:track.id,codec:track.codec}))"
+    )
+    assert len(tracks) == 2 and all(track["codec"] == "mov_text" for track in tracks)
+
+    def select_subtitle(identity: int | None) -> None:
+        player.hover()
+        value = "null" if identity is None else str(identity)
+        option = player.locator(f'.movi-subtitle-track-item[data-track-id="{value}"]')
+        if not option.is_visible():
+            player.get_by_role("button", name="Subtitles/Captions", exact=True).click()
+        expect(option).to_be_visible()
+        option.click()
+
+    select_subtitle(tracks[0]["id"])
+    player.locator("button.movi-play-pause").click()
+    cue = player.locator(".tgdrive-movtext-cue")
+    expect(cue).to_have_text("TGDrive MP4 first cue", timeout=15000)
+    expect(cue).to_be_visible()
+    page.wait_for_function(
+        "()=>document.querySelector('movi-player').player.getRenderHealth().framesPresented>=3",
+        timeout=15000,
+    )
+    player.evaluate("element=>element.pause()")
+    player.evaluate("async element=>{await element.player.seek(4.5);}")
+    expect(cue).to_have_text("TGDrive MP4 second cue", timeout=15000)
+    assert cue.is_visible()
+    select_subtitle(None)
+    expect(player.locator(".tgdrive-movtext-renderer")).to_have_count(0)
+
+    select_subtitle(tracks[1]["id"])
+    player.evaluate("async element=>{await element.player.seek(0.5);}")
+    cue = player.locator(".tgdrive-movtext-cue")
+    expect(cue).to_have_text("हिंदी <img src=x onerror=alert(1)>", timeout=15000)
+    expect(cue.locator("img,script,a")).to_have_count(0)
+    player.evaluate("async element=>{await element.player.seek(4.5);}")
+    expect(cue).to_have_text("TGDrive दूसरी पंक्ति", timeout=15000)
+    with page.expect_download() as original:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    assert (
+        hashlib.sha256(Path(original.value.path()).read_bytes()).digest()
+        == hashlib.sha256(
+            (ROOT / "tests/fixtures/movtext-subtitles.mp4").read_bytes()
+        ).digest()
+    )
+    assert csp == []
+    assert all(
+        request.startswith(server.url + "/") or request.startswith("blob:")
+        for request in requests
+    )
+    page.keyboard.press("Escape")
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+
+
+def test_mouse_double_click_and_mobile_tap_preserve_focus(
+    server: Server, desktop: tuple[Any, Any], browser: Any
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    directory_requests = []
+    page.on(
+        "request",
+        lambda request: (
+            directory_requests.append(request.post_data_json["path"])
+            if request.url.endswith("/api/getDirectory")
+            else None
+        ),
+    )
+    folder = page.get_by_role("button", name="Preview samples", exact=True)
+    folder.click()
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    expect(page.get_by_role("button", name="sample.json", exact=True)).to_have_count(0)
+    expect(page.get_by_role("checkbox")).to_have_count(0)
+    assert directory_requests == []
+    history_length = page.evaluate("history.length")
+    folder.dblclick()
+    primary = page.get_by_role("button", name="sample.json", exact=True)
+    expect(primary).to_be_visible()
+    assert len(set(directory_requests)) == 1
+    assert page.evaluate("history.length") == history_length + 1
+    page.evaluate("document.body.style.minHeight='220vh'")
+    prior_overflow = page.evaluate("getComputedStyle(document.body).overflow")
+    primary.click()
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    expect(page.get_by_role("checkbox")).to_have_count(0)
+    file_row = page.locator(".file-row").filter(has=primary)
+    file_row.locator(".size-cell").click()
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    expect(page.get_by_role("checkbox")).to_have_count(0)
+    history_length = page.evaluate("history.length")
+    primary.dblclick()
+    dialog = preview_dialog(page)
+    assert page.evaluate("history.length") == history_length + 1
+    background_y = page.evaluate("scrollY")
+    page.mouse.move(20, 20)
+    page.mouse.wheel(0, 600)
+    page.wait_for_timeout(100)
+    assert page.evaluate("scrollY") == background_y, (
+        "Preview must lock background scrolling"
+    )
+    assert page.evaluate("getComputedStyle(document.body).overflow") == "hidden"
+    page.keyboard.press("Escape")
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    expect(primary).to_be_focused()
+    assert page.evaluate("getComputedStyle(document.body).overflow") == prior_overflow
+
+    primary.press("Enter")
+    dialog = preview_dialog(page)
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(primary).to_be_focused()
+    actions = page.get_by_label("Actions for sample.json", exact=True)
+    actions.click()
+    page.get_by_role("button", name="Open", exact=True).click()
+    dialog = preview_dialog(page)
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(actions).to_be_focused()
+
+    page.get_by_role("button", name="Select", exact=True).click()
+    primary.click()
+    expect(page.get_by_label("Select sample.json", exact=True)).to_be_checked()
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    primary.click()
+    expect(page.get_by_label("Select sample.json", exact=True)).not_to_be_checked()
+    file_row.locator(".size-cell").click()
+    expect(page.get_by_label("Select sample.json", exact=True)).to_be_checked()
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    page.get_by_role("button", name="Done", exact=True).click()
+
+    context = browser.new_context(
+        viewport={"width": 390, "height": 844}, has_touch=True, is_mobile=True
+    )
+    try:
+        mobile = context.new_page()
+        login(mobile, server.url)
+        folder = mobile.get_by_role("button", name="Preview samples", exact=True)
+        folder.tap()
+        primary = mobile.get_by_role("button", name="sample.json", exact=True)
+        primary.tap()
+        mobile_dialog = preview_dialog(mobile)
+        expect(mobile_dialog.locator("pre")).to_contain_text('"count": 3')
+        mobile_dialog.get_by_role("button", name="Close Preview", exact=True).tap()
+        expect(mobile.locator("dialog.file-preview")).to_have_count(0)
+    finally:
+        context.close()
+
+
+def test_image_and_audio_previews_fill_window(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    for filename, selector in (
+        ("sample.png", "img"),
+        ("sample.wav", "audio"),
+    ):
+        page.get_by_role("button", name=filename, exact=True).dblclick()
+        dialog = preview_dialog(page)
+        content = dialog.locator(selector)
+        expect(content).to_be_visible()
+        if filename == "sample.png":
+            assert content.evaluate("image=>image.complete && image.naturalWidth===16")
+        else:
+            expect(content).to_have_attribute("controls", "")
+        page.keyboard.press("Escape")
+        expect(page.locator("dialog.file-preview")).to_have_count(0)
+
+
+def test_continuous_pdf_virtualizes_canvases_and_keeps_all_pages_reachable(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="long.pdf", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    scroll = dialog.locator(".pdf-scroll")
+    assert_rendered_pdf_page(page, "long.pdf", 1)
+    assert_pdf_canvas_budget(dialog)
+    scroll.evaluate(
+        "element=>element.scrollTop=(element.scrollHeight-element.clientHeight)/2"
+    )
+    middle = page.locator(
+        '.pdf-page[data-page-number="6"] canvas, .pdf-page[data-page-number="7"] canvas'
+    ).first
+    expect(middle).to_be_visible()
+    expect(middle).to_be_in_viewport()
+    assert_pdf_canvas_budget(dialog)
+    scroll.evaluate("element=>element.scrollTop=element.scrollHeight")
+    assert_rendered_pdf_page(page, "long.pdf", 12)
+    expect(
+        dialog.locator('.pdf-page[data-page-number="12"] .pdf-text-layer')
+    ).to_contain_text("TGDrive PDF preview page 12")
+    assert_pdf_canvas_budget(dialog)
+    expect(page.get_by_role("img", name="long.pdf, page 1", exact=True)).to_have_count(
+        0
+    )
+    scroll.evaluate("element=>element.scrollTop=0")
+    assert_rendered_pdf_page(page, "long.pdf", 1)
+    assert_pdf_canvas_budget(dialog)
+
+
+def test_pdf_chunk_failure_keeps_preview_controls_and_can_reload(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    blocked: list[str] = []
+    failures: list[tuple[str, str | None]] = []
+
+    def block_pdf_chunk(route: Any) -> None:
+        blocked.append(route.request.url)
+        route.abort("failed")
+
+    page.on(
+        "requestfailed",
+        lambda request: failures.append((request.url, request.failure)),
+    )
+    pattern = "**/assets/PdfPreview-*.js"
+    page.route(pattern, block_pdf_chunk)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    primary = page.get_by_role("button", name="sample.pdf", exact=True)
+    primary.dblclick()
+    dialog = preview_dialog(page)
+    expect(
+        dialog.get_by_role("button", name="Reload Viewer", exact=True)
+    ).to_be_visible()
+    assert blocked, "The actual lazy PDF JavaScript request must be blocked"
+    assert any(url in blocked and failure for url, failure in failures)
+    expect(dialog.locator(".pdf-scroll")).to_have_count(0)
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    assert result.value.suggested_filename == "sample.pdf"
+    original = Path(result.value.path()).read_bytes()
+    assert original.startswith(b"%PDF-1.4") and b"/Count 3" in original
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    expect(primary).to_be_focused()
+    expect(
+        page.get_by_role("heading", name="Preview samples", exact=True)
+    ).to_be_visible()
+
+    # React.lazy remembers a failed import. The offered reload must recover it
+    # after transport is restored, while retaining the addressed preview.
+    primary.dblclick()
+    dialog = preview_dialog(page)
+    expect(
+        dialog.get_by_role("button", name="Reload Viewer", exact=True)
+    ).to_be_visible()
+    page.unroute(pattern, block_pdf_chunk)
+    dialog.get_by_role("button", name="Reload Viewer", exact=True).click()
+    preview_dialog(page)
+    assert_rendered_pdf_page(page, "sample.pdf", 1)
+    page.keyboard.press("Escape")
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+
+
+def test_low_zoom_tall_pdf_renders_every_intersecting_page(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.set_viewport_size({"width": 1440, "height": 2160})
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="long.pdf", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    assert_rendered_pdf_page(page, "long.pdf", 1)
+    zoom = dialog.get_by_label("PDF zoom", exact=True)
+    for _ in range(20):
+        if zoom.inner_text() == "25%":
+            break
+        dialog.get_by_role("button", name="Zoom Out", exact=True).click()
+    expect(zoom).to_have_text("25%")
+    expect(dialog.get_by_role("button", name="Zoom Out", exact=True)).to_be_disabled()
+    scroll = dialog.locator(".pdf-scroll")
+    scroll.evaluate("element=>element.scrollTop=0")
+    layout = scroll.evaluate("""element => {
+      const bounds=element.getBoundingClientRect();
+      return {top:bounds.top,bottom:bounds.bottom,
+        pages:[...element.querySelectorAll('.pdf-page')].map(page=>{
+          const rect=page.getBoundingClientRect();
+          return {number:Number(page.dataset.pageNumber),
+            top:rect.top,height:rect.height};
+        }).sort((a,b)=>a.number-b.number)};
+    }""")
+    frames = layout["pages"]
+    assert len(frames) >= 2
+    # The fixture's twelve pages have identical portrait dimensions. Deriving
+    # pitch from any two mounted cards detects omitted visible pages even if a
+    # broken virtualizer only mounts a five-page slice around the viewport center.
+    first, second = frames[:2]
+    pitch = (second["top"] - first["top"]) / (second["number"] - first["number"])
+    top = first["top"] - (first["number"] - 1) * pitch
+    visible = [
+        number
+        for number in range(1, 13)
+        if top + (number - 1) * pitch < layout["bottom"]
+        and top + (number - 1) * pitch + first["height"] > layout["top"]
+    ]
+    assert len(visible) > 5, "This viewport must exercise more than five visible pages"
+    assert set(visible) <= {frame["number"] for frame in frames}
+    for number in visible:
+        canvas = page.get_by_role("img", name=f"long.pdf, page {number}", exact=True)
+        expect(canvas).to_be_visible(timeout=20000)
+        expect(canvas).to_be_in_viewport()
+        assert canvas.evaluate("element=>element.width>0 && element.height>0")
+    assert_pdf_canvas_budget(dialog, max_canvases=None)
+    expect(dialog.locator(".pdf-page")).to_have_count(len(frames))
+
+
+@pytest.mark.parametrize("play_during_open", [False, True])
+def test_enhanced_video_delayed_startup_shows_status_and_recovers(
+    server: Server, desktop: tuple[Any, Any], play_during_open: bool
+) -> None:
+    _, page = desktop
+    pending: list[Any] = []
+    holding = True
+
+    def hold_media(route: Any) -> None:
+        if holding and route.request.method == "GET":
+            pending.append(route)
+        else:
+            route.continue_()
+
+    page.route("**/file?*", hold_media)
+    try:
+        login(page, server.url)
+        page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+        page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+        dialog = preview_dialog(page)
+        status = dialog.locator(".advanced-state")
+        expect(status).to_be_visible(timeout=30000)
+        expect(status.locator('[role="status"]')).to_be_visible()
+        deadline = time.monotonic() + 20
+        while not pending and time.monotonic() < deadline:
+            page.wait_for_timeout(50)
+        assert pending, "The test must hold an actual media GET, not simulate readiness"
+        player = dialog.locator("movi-player")
+        expect(player).to_be_visible(timeout=30000)
+        player_host = dialog.locator(".advanced-player-host")
+        expect(player_host).not_to_have_attribute("inert", "")
+        expect(player_host).not_to_have_attribute("aria-hidden", "true")
+        expect(player.locator("button.movi-play-pause")).to_be_visible()
+        assert player.evaluate("element=>element.closest('[inert]')===null")
+        expect(
+            dialog.get_by_role("button", name="Start Playback", exact=True)
+        ).to_have_count(0)
+        expect(
+            dialog.get_by_role("button", name="Use Compatibility Playback", exact=True)
+        ).to_have_count(0)
+        expect(dialog.locator(".preview-surface > video")).to_have_count(0)
+        progress = status.get_by_role("progressbar", name="Loading video")
+        expect(progress).to_be_visible()
+        assert progress.evaluate("element=>!element.hasAttribute('value')"), (
+            "Unknown duration must not manufacture a loading percentage"
+        )
+        expect(
+            status.get_by_role("button", name="Try again", exact=True)
+        ).to_be_visible(timeout=12000)
+        expect(
+            dialog.get_by_role("link", name="Download Original", exact=True)
+        ).to_be_visible()
+        page.screenshot(path=ARTIFACTS / "video-startup-delayed.png", full_page=False)
+        page.set_viewport_size({"width": 390, "height": 844})
+        preview_dialog(page)
+        expect(status).to_be_visible()
+        expect(
+            status.get_by_role("button", name="Try again", exact=True)
+        ).to_be_visible()
+        page.screenshot(
+            path=ARTIFACTS / "video-startup-delayed-mobile.png", full_page=False
+        )
+        if play_during_open:
+            player.locator("button.movi-play-pause").click()
+            expect(status).to_contain_text("Loading video…")
+        holding = False
+        for route in pending:
+            route.continue_()
+        pending.clear()
+        expect(status).to_have_count(0, timeout=30000)
+        expect(player_host).not_to_have_attribute("inert", "")
+        expect(player_host).not_to_have_attribute("aria-hidden", "true")
+        assert player.evaluate("element=>element.closest('[inert]')===null")
+        if not play_during_open:
+            assert player.evaluate("element=>element.paused"), (
+                "Readiness must not force autoplay"
+            )
+            player.locator("button.movi-play-pause").click()
+        deadline = time.monotonic() + 15
+        while (
+            player.evaluate("element=>element.currentTime") <= 0.25
+            and time.monotonic() < deadline
+        ):
+            page.wait_for_timeout(100)
+        assert player.evaluate("element=>element.currentTime") > 0.25
+        page.screenshot(path=ARTIFACTS / "video-startup-ready.png", full_page=False)
+        dialog.get_by_role("button", name="Close Preview", exact=True).click()
+        expect(player).to_have_count(0)
+    finally:
+        holding = False
+        for route in pending:
+            route.continue_()
+        page.unroute("**/file?*", hold_media)
+
+
+def test_enhanced_video_quality_switch_restores_settled_paused_position(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    media_requests: list[str] = []
+    page.on(
+        "request",
+        lambda request: (
+            media_requests.append(request.url)
+            if "/file?" in request.url and request.method == "GET"
+            else None
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    assert player.evaluate("element=>element.duration") > 4
+    assert player.evaluate("element=>element.paused")
+    # Seek the real FFmpeg/WebCodecs engine while paused; no state/event stub is
+    # used. A later engine startup seek-to-zero used to overwrite this position.
+    player.evaluate(
+        "async element=>{await element.pause();await element.player.seek(3);}"
+    )
+
+    def wait_for_restored_position() -> None:
+        deadline = time.monotonic() + 15
+        state = None
+        while time.monotonic() < deadline:
+            state = player.evaluate(
+                "element=>({time:element.currentTime,paused:element.paused})"
+            )
+            if abs(state["time"] - 3) < 0.2:
+                return
+            page.wait_for_timeout(100)
+        pytest.fail(f"Real video engine did not restore the saved 3s position: {state}")
+
+    wait_for_restored_position()
+    expect(dialog.locator(".preview-quality")).to_have_count(0)
+
+    def switch_source(value: str) -> None:
+        player.hover()
+        settings = player.locator("button.movi-settings-btn")
+        if not settings.is_visible():
+            player.locator("button.movi-more-btn").click()
+        settings.click()
+        player.locator('.movi-settings-row[data-page="quality"]').click()
+        menu = player.locator(".movi-settings-menu")
+        expect(menu.locator(".movi-settings-page-title")).to_have_text("Quality")
+        labels = {
+            "original": "Original",
+            "fixture-same-bytes": "Fixture alternate source",
+        }
+        expect(menu.get_by_role("button", name="Original", exact=True)).to_be_visible()
+        player.evaluate("element=>window.previousResumePlayer=element")
+        menu.get_by_role("button", name=labels[value], exact=True).click()
+        deadline = time.monotonic() + 15
+        replaced = False
+        while time.monotonic() < deadline:
+            replaced = page.evaluate("""() => {
+              const element=document.querySelector('movi-player');
+              return Boolean(element &&
+                element!==window.previousResumePlayer && element.player);
+            }""")
+            if replaced:
+                break
+            page.wait_for_timeout(100)
+        assert replaced, "Changing quality must initialize a fresh real engine"
+        expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+
+    for value in ("fixture-same-bytes", "original"):
+        switch_source(value)
+        wait_for_restored_position()
+        assert player.evaluate("element=>element.paused"), (
+            "Switching source while paused must not start playback"
+        )
+        # Observe beyond metadata/ready so an asynchronous initializer seek-to-zero
+        # cannot pass this regression by briefly reporting the restored position.
+        deadline = time.monotonic() + 2
+        samples = []
+        while time.monotonic() < deadline:
+            samples.append(
+                player.evaluate(
+                    "element=>({time:element.currentTime,paused:element.paused})"
+                )
+            )
+            page.wait_for_timeout(100)
+        assert samples and all(
+            abs(sample["time"] - 3) < 0.2 and sample["paused"] for sample in samples
+        ), samples
+    # A genuine user play action must also survive engine replacement. Keep
+    # enough of the five-second fixture remaining to observe resumed progress.
+    player.evaluate(
+        "async element=>{await element.pause();await element.player.seek(1);}"
+    )
+    player.locator("button.movi-play-pause").click()
+    deadline = time.monotonic() + 10
+    while time.monotonic() < deadline:
+        state = player.evaluate(
+            "element=>({time:element.currentTime,paused:element.paused})"
+        )
+        if not state["paused"] and state["time"] > 1.05:
+            break
+        page.wait_for_timeout(50)
+    assert not state["paused"] and state["time"] > 1.05
+    saved_time = state["time"]
+    switch_source("fixture-same-bytes")
+    deadline = time.monotonic() + 15
+    resumed_time = None
+    while time.monotonic() < deadline:
+        state = player.evaluate(
+            "element=>({time:element.currentTime,paused:element.paused})"
+        )
+        if not state["paused"] and state["time"] >= saved_time - 0.25:
+            resumed_time = state["time"]
+            break
+        page.wait_for_timeout(50)
+    assert resumed_time is not None, state
+    deadline = time.monotonic() + 5
+    while time.monotonic() < deadline:
+        state = player.evaluate(
+            "element=>({time:element.currentTime,paused:element.paused})"
+        )
+        if not state["paused"] and state["time"] > resumed_time + 0.2:
+            break
+        page.wait_for_timeout(50)
+    assert not state["paused"] and state["time"] > resumed_time + 0.2, state
+    player.evaluate("element=>element.pause()")
+    assert any("quality=fixture-same-bytes" in url for url in media_requests)
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    assert (
+        Path(result.value.path()).read_bytes()
+        == (ROOT / "tests/fixtures/multitrack.mkv").read_bytes()
+    )
+    page.evaluate("delete window.previousResumePlayer")
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(player).to_have_count(0)
+
+
+def test_unsupported_details_are_compact_explicit_and_shared_readonly(
+    server: Server, desktop: tuple[Any, Any], browser: Any
+) -> None:
+    _, page = desktop
+    downloads: list[str] = []
+    page.on("download", lambda download: downloads.append(download.suggested_filename))
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    folder_url = page.url
+    filename = "installer-" + "very-long-file-name-" * 5 + "setup.exe"
+    primary = page.get_by_role("button", name=filename, exact=True)
+    pending: list[Any] = []
+    page.route("**/api/v1/preview?*", lambda route: pending.append(route))
+    try:
+        primary.dblclick()
+        checking = page.locator("dialog.file-preview.file-details")
+        expect(checking).to_be_visible()
+        expect(checking.get_by_role("status")).to_have_text("Checking preview…")
+        expect(
+            checking.get_by_role("link", name="Download Original", exact=True)
+        ).to_be_visible()
+        assert downloads == []
+        deadline = time.monotonic() + 5
+        while not pending and time.monotonic() < deadline:
+            page.wait_for_timeout(50)
+        assert pending, "The checking shell must be observed before metadata returns"
+    finally:
+        for route in pending:
+            route.continue_()
+        page.unroute("**/api/v1/preview?*")
+    dialog, metadata = file_details_dialog(page, filename)
+    assert "EXE" in metadata["Type"].upper()
+    assert metadata["Size"] == "18 B"
+    assert downloads == [], (
+        "Opening unsupported details must never download automatically"
+    )
+    page.screenshot(path=ARTIFACTS / "unsupported-desktop.png", full_page=False)
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    assert result.value.suggested_filename == filename
+    assert Path(result.value.path()).read_bytes() == b"Long-name fixture."
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    expect(page).to_have_url(folder_url)
+    expect(primary).to_be_focused()
+
+    empty = page.get_by_role("button", name="empty.exe", exact=True)
+    empty.dblclick()
+    _, metadata = file_details_dialog(page, "empty.exe")
+    assert metadata["Size"] == "0 B"
+    page.keyboard.press("Escape")
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    expect(page).to_have_url(folder_url)
+    expect(empty).to_be_focused()
+    primary.dblclick()
+    file_details_dialog(page, filename)
+    page.go_back()
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    expect(page).to_have_url(folder_url)
+    expect(primary).to_be_focused()
+    assert downloads == [filename]
+
+    preview_path = server.control()["seed"]["preview_folder"]
+    response = page.request.post(
+        server.url + "/api/v1/shares",
+        data={"path": preview_path, "expires_in_days": 7},
+    )
+    assert response.ok
+    share = response.json()
+    public_context = browser.new_context(viewport={"width": 1440, "height": 960})
+    mobile_context = browser.new_context(
+        viewport={"width": 390, "height": 844}, has_touch=True, is_mobile=True
+    )
+    extra_errors: list[str] = []
+    try:
+        public = public_context.new_page()
+        public.on("pageerror", lambda error: extra_errors.append(str(error)))
+        public_downloads: list[str] = []
+        public.on(
+            "download",
+            lambda download: public_downloads.append(download.suggested_filename),
+        )
+        public.goto(
+            server.url
+            + "/?path=/share_"
+            + preview_path.lstrip("/")
+            + "&auth="
+            + share["auth"]
+        )
+        public_primary = public.get_by_role("button", name="setup.exe", exact=True)
+        public_primary.dblclick()
+        public_dialog, _ = file_details_dialog(public, "setup.exe")
+        assert public_downloads == []
+        expect(public.locator(".item-actions")).to_have_count(0)
+        expect(
+            public_dialog.get_by_role("button", name="Upload Files", exact=True)
+        ).to_have_count(0)
+        with public.expect_download() as result:
+            public_dialog.get_by_role(
+                "link", name="Download Original", exact=True
+            ).click()
+        assert Path(result.value.path()).read_bytes() == (
+            b"Synthetic fixture bytes; never an executable."
+        )
+        public_dialog.get_by_role("button", name="Close Preview", exact=True).click()
+        expect(public_primary).to_be_focused()
+
+        mobile = mobile_context.new_page()
+        mobile.on("pageerror", lambda error: extra_errors.append(str(error)))
+        mobile_downloads: list[str] = []
+        mobile.on(
+            "download",
+            lambda download: mobile_downloads.append(download.suggested_filename),
+        )
+        login(mobile, server.url)
+        folder = mobile.get_by_role("button", name="Preview samples", exact=True)
+        folder.tap()
+        mobile_primary = mobile.get_by_role("button", name=filename, exact=True)
+        mobile_primary.tap()
+        mobile_dialog, _ = file_details_dialog(mobile, filename)
+        assert mobile_downloads == []
+        mobile.screenshot(path=ARTIFACTS / "unsupported-mobile.png", full_page=False)
+        mobile.set_viewport_size({"width": 320, "height": 740})
+        file_details_dialog(mobile, filename)
+        mobile_dialog.get_by_role("button", name="Close Preview", exact=True).tap()
+        expect(mobile.locator("dialog.file-preview")).to_have_count(0)
+        expect(mobile_primary).to_be_focused()
+    finally:
+        public_context.close()
+        mobile_context.close()
+    assert extra_errors == []
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_folder_upload_refresh_keeps_table_selection_page_and_scroll(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path, width: int
+) -> None:
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 960})
+    held: list[tuple[Any, Any, dict[str, Any]]] = []
+    hold = False
+
+    def listing(route: Any) -> None:
+        response = route.fetch()
+        payload = response.json()
+        if route.request.post_data_json["path"] == "/":
+            payload["data"]["contents"].update(
+                {
+                    f"stable-{i}": {
+                        "id": f"stable-{i}",
+                        "name": f"stable-{i:03}.txt",
+                        "type": "file",
+                        "path": "/",
+                        "size": 10,
+                    }
+                    for i in range(130)
+                }
+            )
+        if hold:
+            held.append((route, response, payload))
+        else:
+            route.fulfill(response=response, json=payload)
+
+    page.route("**/api/getDirectory", listing)
+    login(page, server.url)
+    directory = tmp_path / "Stable upload"
+    directory.mkdir()
+    for i in range(3):
+        (directory / f"upload-{i}.txt").write_bytes(b"folder upload contents")
+    dialog = select_folder(page, directory)
+    dialog.get_by_role("button", name="Upload", exact=True).click()
+    expect(dialog).not_to_be_visible()
+    started = server.wait_started(3)
+    expect(page.get_by_role("button", name="Stable upload", exact=True)).to_be_visible()
+    hide = page.get_by_role("button", name="Hide Transfer Details", exact=True)
+    if hide.is_visible():
+        hide.click()
+    page.get_by_role("button", name="Next Page", exact=True).click()
+    select_item(page, "stable-110.txt")
+    page.get_by_label("Select stable-110.txt", exact=True).focus()
+    page.evaluate("""() => {
+      window.stableTable = document.querySelector('.file-table');
+      window.stableRow = document.querySelector('[data-item-id="stable-110"]');
+      window.tableRemovals = 0;
+      new MutationObserver(records => {
+        for (const record of records) for (const removed of record.removedNodes)
+          if (removed === window.stableTable || removed.contains?.(window.stableTable))
+            window.tableRemovals++;
+      }).observe(document.querySelector('.workspace'), {childList:true, subtree:true});
+      window.stableScroll = document.querySelector(
+        innerWidth < 721 ? '.workspace' : '.file-list-scroll');
+      window.stableScroll.scrollTop = 250;
+    }""")
+    scroll = page.evaluate("window.stableScroll.scrollTop")
+    assert scroll > 0
+    hold = True
+    try:
+        for item in started:
+            server.finish(item["id"])
+            deadline = time.monotonic() + 10
+            while not held and time.monotonic() < deadline:
+                page.wait_for_timeout(50)
+            assert len(held) == 1
+            expect(page.locator(".loading-state")).to_have_count(0)
+            expect(
+                page.get_by_label("Select stable-110.txt", exact=True)
+            ).to_be_checked()
+            route, response, payload = held.pop()
+            route.fulfill(response=response, json=payload)
+            page.evaluate(
+                "() => new Promise(resolve => requestAnimationFrame("
+                "() => requestAnimationFrame(resolve)))"
+            )
+            expect(
+                page.get_by_label("Select stable-110.txt", exact=True)
+            ).to_be_checked()
+            expect(
+                page.get_by_label("Select stable-110.txt", exact=True)
+            ).to_be_focused()
+            expect(page.locator(".pagination")).to_contain_text("Showing 101\u2013")
+            assert page.evaluate("window.stableScroll.scrollTop") == scroll
+            assert page.evaluate(
+                "window.stableTable === document.querySelector('.file-table')"
+            )
+            assert page.evaluate(
+                "window.stableRow === "
+                "document.querySelector('[data-item-id=stable-110]')"
+            )
+            assert page.evaluate("window.tableRemovals") == 0
+        page.screenshot(path=ARTIFACTS / f"stable-folder-upload-{width}.png")
+    finally:
+        hold = False
+        for route, response, payload in held:
+            route.fulfill(response=response, json=payload)
+
+
+def test_background_listing_failure_preserves_files_and_navigation_loads_normally(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    primary = page.get_by_role("button", name="資料", exact=True)
+    expect(primary).to_be_visible()
+    select_item(page, "資料")
+    page.route(
+        "**/api/getDirectory",
+        lambda route: route.fulfill(
+            status=503, json={"detail": "Temporary test failure"}
+        ),
+    )
+    page.evaluate("window.dispatchEvent(new Event('tgdrive:files-changed'))")
+    expect(page.get_by_role("alert")).to_contain_text("Could not update your files")
+    expect(primary).to_be_visible()
+    expect(page.get_by_label("Select 資料", exact=True)).to_be_checked()
+    expect(page.get_by_role("heading", name="Could Not Load Your Files")).to_have_count(
+        0
+    )
+    page.unroute("**/api/getDirectory")
+    held: list[Any] = []
+    page.route("**/api/getDirectory", lambda route: held.append(route))
+    try:
+        page.get_by_role("button", name="Done", exact=True).click()
+        primary.press("Enter")
+        expect(page.locator(".loading-state")).to_be_visible()
+        expect(page.locator(".file-table")).to_have_count(0)
+    finally:
+        for route in held:
+            route.continue_()
+        page.unroute("**/api/getDirectory")
+    expect(page.get_by_role("button", name="résumé #1.txt", exact=True)).to_be_visible()
+
+
+def test_directory_picker_preserves_nested_paths_and_waits_for_atomic_tree(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    directory = tmp_path / "Project release"
+    payloads = {
+        "readme.txt": b"Project root readme.",
+        "alpha/notes.txt": b"Alpha notes; distinct bytes.",
+        "beta/deep/notes.txt": b"Nested beta notes; same basename.",
+    }
+    for relative, content in payloads.items():
+        path = directory / relative
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(content)
+    (directory / "empty.txt").write_bytes(b"")
+    (directory / "empty-directory").mkdir()
+    login(page, server.url)
+    response = page.request.post(
+        server.url + "/api/createNewFolder",
+        data={"path": "/", "name": directory.name},
+    )
+    assert response.ok
+    original = next(
+        item
+        for item in fixture_nodes(page, server, "/")
+        if item["name"] == directory.name
+    )
+    held: list[tuple[Any, Any, dict[str, Any]]] = []
+    upload_requests: list[str] = []
+    page.on(
+        "request",
+        lambda request: (
+            upload_requests.append(request.url)
+            if request.method == "POST" and request.url.endswith("/api/v1/uploads")
+            else None
+        ),
+    )
+
+    def hold_tree_reply(route: Any) -> None:
+        response = route.fetch()
+        assert response.ok, response.text()
+        held.append((route, response, response.json()))
+
+    page.route("**/api/v1/folders/tree", hold_tree_reply)
+    dialog = select_folder(page, directory)
+    expect(dialog.get_by_role("button", name="Upload", exact=True)).to_be_visible()
+    assert server.control()["started"] == []
+    expect(dialog.locator(".folder-upload-summary")).to_contain_text("3 files")
+    expect(dialog.locator(".folder-upload-destination")).to_have_text("To My Files")
+    expect(dialog.locator(".folder-upload-help")).to_have_count(0)
+    assert "resumable upload queue" not in dialog.inner_text()
+    assert "Keep this tab open" not in dialog.inner_text()
+    page.screenshot(path=ARTIFACTS / "folder-upload-review.png", full_page=False)
+    dialog.get_by_role("button", name="Upload", exact=True).click()
+    try:
+        expect(
+            dialog.get_by_role("button", name="Cancel Preparation", exact=True)
+        ).to_be_visible()
+        deadline = time.monotonic() + 10
+        while not held and time.monotonic() < deadline:
+            page.wait_for_timeout(50)
+        assert len(held) == 1
+        assert upload_requests == [], (
+            "No file receipt may precede folder acknowledgement"
+        )
+        assert server.control()["started"] == []
+        request_body = held[0][0].request.post_data_json
+        tree = held[0][2]
+        assert request_body["root_name"] == directory.name
+        assert request_body["destination"] == "/"
+        assert request_body["client_request_id"]
+        assert {tuple(parts) for parts in request_body["folders"]} == {
+            ("alpha",),
+            ("beta",),
+            ("beta", "deep"),
+        }
+        assert tree["root"]["id"] != original["id"]
+        assert tree["root"]["name"] != directory.name
+        assert set(tree["folders"]) == {"", "alpha", "beta", "beta/deep"}
+        held[0][0].fulfill(response=held[0][1])
+        held.clear()
+    finally:
+        page.unroute("**/api/v1/folders/tree", hold_tree_reply)
+        for route, response, _ in held:
+            route.fulfill(response=response)
+    expect(dialog).not_to_be_visible()
+    started = finish_fixture_uploads(page, server, len(payloads))
+    expected_destinations = {
+        ("readme.txt", tree["folders"][""]),
+        ("notes.txt", tree["folders"]["alpha"]),
+        ("notes.txt", tree["folders"]["beta/deep"]),
+    }
+    assert {(item["name"], item["destination"]) for item in started} == (
+        expected_destinations
+    )
+    assert len(upload_requests) == len(payloads)
+    for relative, content in payloads.items():
+        parts = relative.split("/")
+        parent = tree["folders"]["/".join(parts[:-1])]
+        items = fixture_nodes(page, server, parent)
+        item = next(item for item in items if item["name"] == parts[-1])
+        assert item["type"] == "file"
+        response = page.request.get(
+            server.url + "/file",
+            params={"path": parent + "/" + item["id"], "download": "1"},
+        )
+        assert response.ok and response.body() == content
+    root_items = fixture_nodes(page, server, tree["folders"][""])
+    assert not any(
+        item["name"] in {"empty.txt", "empty-directory"} for item in root_items
+    )
+    assert fixture_nodes(page, server, "/" + original["id"]) == []
+    saved = page.evaluate(UPLOAD_RECOVERY_RECORDS)
+    assert len(saved) == len(payloads)
+    assert {item.get("relativePath") for item in saved} == {
+        directory.name + "/" + relative for relative in payloads
+    }
+    page.screenshot(path=ARTIFACTS / "folder-upload-complete.png", full_page=False)
+
+
+def test_folder_preparation_retries_response_loss_and_cancels_without_files(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    directory = tmp_path / "Retry project"
+    directory.mkdir()
+    (directory / "retry.txt").write_bytes(b"Retry-safe directory upload.")
+    login(page, server.url)
+    attempts: list[dict[str, Any]] = []
+    prepared: list[dict[str, Any]] = []
+
+    def lose_first_reply(route: Any) -> None:
+        attempts.append(route.request.post_data_json)
+        response = route.fetch()
+        assert response.ok, response.text()
+        prepared.append(response.json())
+        if len(attempts) == 1:
+            route.abort("failed")
+        else:
+            route.fulfill(response=response)
+
+    page.route("**/api/v1/folders/tree", lose_first_reply)
+    dialog = select_folder(page, directory)
+    dialog.get_by_role("button", name="Upload", exact=True).click()
+    expect(
+        dialog.get_by_role("button", name="Retry Preparation", exact=True)
+    ).to_be_visible()
+    assert len(prepared) == 1
+    assert server.control()["started"] == []
+    dialog.get_by_role("button", name="Retry Preparation", exact=True).click()
+    expect(dialog).not_to_be_visible()
+    page.unroute("**/api/v1/folders/tree", lose_first_reply)
+    assert len(attempts) == 2
+    assert attempts[0] == attempts[1]
+    assert prepared[0]["folders"] == prepared[1]["folders"]
+    assert prepared[0]["root"]["id"] == prepared[1]["root"]["id"]
+    finish_fixture_uploads(page, server, 1)
+    matching = [
+        item
+        for item in fixture_nodes(page, server, "/")
+        if item["name"] == directory.name
+    ]
+    assert len(matching) == 1
+
+    cancelled_directory = tmp_path / "Cancelled project"
+    cancelled_directory.mkdir()
+    (cancelled_directory / "never-queued.txt").write_bytes(b"Do not enqueue.")
+    held: list[tuple[Any, dict[str, Any]]] = []
+
+    def hold_cancelled_reply(route: Any) -> None:
+        response = route.fetch()
+        assert response.ok, response.text()
+        held.append((route, response.json()))
+
+    page.route("**/api/v1/folders/tree", hold_cancelled_reply)
+    dialog = select_folder(page, cancelled_directory)
+    dialog.get_by_role("button", name="Upload", exact=True).click()
+    deadline = time.monotonic() + 10
+    while not held and time.monotonic() < deadline:
+        page.wait_for_timeout(50)
+    assert len(held) == 1
+    prepared_root = held[0][1]["folders"][""]
+    try:
+        dialog.get_by_role("button", name="Cancel Preparation", exact=True).click()
+        for route, _ in held:
+            route.abort("aborted")
+        held.clear()
+        expect(dialog.get_by_role("status")).to_contain_text(
+            "Preparation cancelled. No files were queued."
+        )
+        expect(
+            dialog.get_by_role("button", name="Retry Preparation", exact=True)
+        ).to_be_visible()
+        assert len(server.control()["started"]) == 1
+        assert fixture_nodes(page, server, prepared_root) == []
+        dialog.get_by_role("button", name="Close", exact=True).click()
+        expect(dialog).not_to_be_visible()
+        assert (
+            page.locator(".transfer-item-name", has_text="never-queued.txt").count()
+            == 0
+        )
+    finally:
+        page.unroute("**/api/v1/folders/tree", hold_cancelled_reply)
+        for route, _ in held:
+            route.abort("aborted")
+
+
+def test_large_folder_upload_stays_compact_bounded_and_filterable(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    names = [f"batch-file-{number:03}.txt" for number in range(100)]
+    directory = tmp_path / "Batch files"
+    directory.mkdir()
+    for name in names:
+        (directory / name).write_bytes(b"x" * 65536)
+    dialog = select_folder(page, directory)
+    dialog.get_by_role("button", name="Upload", exact=True).click()
+    expect(dialog).not_to_be_visible()
+    batch = page.locator(".transfer-batch")
+    expect(batch).to_have_count(1)
+    expect(batch).to_be_visible()
+    toggle = batch.locator("button.transfer-batch-toggle")
+    expect(toggle).to_have_attribute("aria-expanded", "false")
+    expect(batch.locator(".transfer-item")).to_have_count(0)
+    batch_name = batch.locator(".transfer-batch-name").inner_text()
+    progress = batch.locator(".transfer-batch-summary > progress")
+    expect(progress).to_be_visible()
+    assert progress.get_attribute("aria-label") in {
+        "Device upload progress for " + batch_name,
+        "Telegram upload progress for " + batch_name,
+    }
+    expect(batch.locator(".transfer-batch-status")).to_contain_text("100")
+    page.screenshot(path=ARTIFACTS / "upload-batch-collapsed.png", full_page=False)
+    server.wait_started(100)
+    assert len(server.control()["started"]) == 100, (
+        "Device receipts must continue independently of busy Telegram jobs"
+    )
+    expect(batch).to_have_attribute("data-stage", "telegram")
+    toggle.click()
+    expect(toggle).to_have_attribute("aria-expanded", "true")
+    expect(batch.locator(".transfer-item")).to_have_count(20)
+    expect(
+        batch.get_by_role("group", name="Files shown for " + batch_name, exact=True)
+    ).to_have_count(0)
+
+    expect(batch.locator(".transfer-item")).to_have_count(20)
+    batch.locator("button.transfer-show-more").click()
+    expect(batch.locator(".transfer-item")).to_have_count(40)
+    page.screenshot(path=ARTIFACTS / "upload-batch-expanded.png", full_page=False)
+    toggle.click()
+    expect(batch.locator(".transfer-item")).to_have_count(0)
+    page.set_viewport_size({"width": 390, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    heading = page.get_by_role("heading", name="My Files", exact=True).bounding_box()
+    assert heading is not None and heading["height"] <= 64, (
+        "Mobile toolbar actions must not squeeze the heading into vertical letters"
+    )
+    expect(batch).to_have_count(0)
+    expect(page.locator(".mobile-transfer-status")).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "upload-batch-mobile.png", full_page=False)
+    page.set_viewport_size({"width": 1440, "height": 960})
+    cancel_all(page)
+    deadline = time.monotonic() + 15
+    saved = []
+    while time.monotonic() < deadline:
+        saved = page.evaluate(UPLOAD_RECOVERY_RECORDS)
+        if len(saved) == 100 and all(item["state"] == "cancelled" for item in saved):
+            break
+        page.wait_for_timeout(100)
+    assert len(saved) == 100 and all(item["state"] == "cancelled" for item in saved)
+    assert len({item["batchId"] for item in saved}) == 1
+    expect(batch.locator(".transfer-batch-name")).to_have_text(directory.name)
+    toggle.click()
+    expect(batch.locator(".transfer-files-toolbar")).to_have_count(0)
+    expect(batch.locator(".transfer-item")).to_have_count(20)
+    assert all(
+        item.get_attribute("data-status") == "cancelled"
+        for item in batch.locator(".transfer-item").all()
+    )
+    root = saved[0]["folderUpload"]["root_path"]
+    assert not any(item["name"] in names for item in fixture_nodes(page, server, root))
+
+
+def test_settings_backup_status_never_claims_unconfirmed_protection(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    open_admin(page)
+    page.get_by_role("link", name="Storage & Backups", exact=True).click()
+    section = page.get_by_role("region", name="Cloud Database", exact=True)
+    status = section.get_by_role("status")
+    expect(page.locator(".drive-protection")).to_have_count(0)
+    expect(status).to_have_text("Saved to MongoDB", timeout=10000)
+
+    def assert_not_protected() -> None:
+        expect(status).not_to_have_text("Saved to MongoDB")
+        assert "connection-ready" not in (status.get_attribute("class") or "")
+
+    # A confirmed catalog checkpoint cannot protect bytes that are still on
+    # the owner's device. Hold an actual receipt PATCH before acknowledgement.
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    held_receipts: list[Any] = []
+
+    def hold_receipt(route: Any) -> None:
+        if route.request.method == "PATCH":
+            held_receipts.append(route)
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/uploads/*", hold_receipt)
+    try:
+        upload(page, ["unfinished-device.txt"])
+        deadline = time.monotonic() + 10
+        while not held_receipts and time.monotonic() < deadline:
+            page.wait_for_timeout(50)
+        assert len(held_receipts) == 1
+        receipt = held_receipts[0].request
+        assert receipt.headers["upload-offset"] == "0"
+        assert len(receipt.post_data_buffer) == 65536
+        offset = page.request.head(receipt.url)
+        assert offset.ok and offset.headers["upload-offset"] == "0"
+        assert server.control()["started"] == []
+        open_admin(page)
+        page.get_by_role("link", name="Storage & Backups", exact=True).click()
+        expect(status).to_have_text("Uploads Still in Progress", timeout=10000)
+        assert_not_protected()
+        with page.expect_response("**/api/v1/backup") as catalog_backup:
+            section.get_by_role("button", name="Back Up Now", exact=True).click()
+        assert catalog_backup.value.status == 200
+        protected_catalog = catalog_backup.value.json()["recovery"]
+        assert (
+            protected_catalog["protected_revision"]
+            >= (protected_catalog["metadata_revision"])
+        )
+        expect(status).to_have_text("Uploads Still in Progress", timeout=8000)
+        assert_not_protected()
+        assert server.control()["started"] == []
+        offset = page.request.head(receipt.url)
+        assert offset.ok and offset.headers["upload-offset"] == "0"
+    finally:
+        for route in held_receipts:
+            route.continue_()
+        page.unroute("**/api/v1/uploads/*", hold_receipt)
+    finish_fixture_uploads(page, server, 1)
+    server.control("/backup/protected", method="POST")
+    expect(status).to_have_text("Saved to MongoDB", timeout=8000)
+    baseline_calls = server.control("/backup")["calls"]
+    assert baseline_calls == 1
+
+    server.control("/backup/pending", method="POST")
+    expect(status).to_have_text("Backing up your latest changes", timeout=8000)
+    assert_not_protected()
+    server.control("/backup/error", method="POST")
+    expect(status).to_have_text("Database Needs Attention", timeout=8000)
+    assert_not_protected()
+    expect(section.get_by_role("alert")).to_contain_text("Synthetic Telegram")
+    # A response claiming 'protected' with an older checkpoint is inconsistent;
+    # the owner must never see green confirmation for the newer metadata.
+    stale = server.control("/backup/stale", method="POST")["recovery"]
+    assert stale["protected_revision"] < stale["metadata_revision"]
+    expect(status).to_have_text("Backup Status Unavailable", timeout=8000)
+    assert_not_protected()
+    server.control("/backup/protected", method="POST")
+    expect(status).to_have_text("Saved to MongoDB", timeout=8000)
+
+    def fail_status(route: Any) -> None:
+        route.fulfill(
+            status=503,
+            content_type="application/json",
+            body='{"detail":"Synthetic status service unavailable."}',
+        )
+
+    page.route("**/api/v1/status", fail_status)
+    expect(status).to_have_text("Backup Status Unavailable", timeout=8000)
+    assert_not_protected()
+    expect(
+        section.get_by_role("button", name="Back Up Now", exact=True)
+    ).to_be_disabled()
+    page.unroute("**/api/v1/status", fail_status)
+    expect(status).to_have_text("Saved to MongoDB", timeout=8000)
+
+    server.control("/backup/fail-next", method="POST")
+    with page.expect_response("**/api/v1/backup") as failed_backup:
+        section.get_by_role("button", name="Back Up Now", exact=True).click()
+    assert failed_backup.value.status == 503
+    expect(status).to_have_text("Database Needs Attention", timeout=8000)
+    assert_not_protected()
+    expect(section.get_by_role("alert")).to_contain_text("Backup is not confirmed")
+    assert server.control("/backup")["calls"] == baseline_calls + 1
+
+    with page.expect_response("**/api/v1/backup") as confirmed_backup:
+        section.get_by_role("button", name="Back Up Now", exact=True).click()
+    assert confirmed_backup.value.status == 200
+    recovery = confirmed_backup.value.json()["recovery"]
+    assert recovery["protected_revision"] >= recovery["metadata_revision"]
+    expect(status).to_have_text("Saved to MongoDB", timeout=8000)
+    assert server.control("/backup")["calls"] == baseline_calls + 2
+    page.get_by_text("Recover on a New Installation", exact=True).click()
+    restore_form = page.locator(".drive-recovery-help .database-restore")
+    expect(restore_form.get_by_label("Database archive (required)")).to_be_visible()
+    expect(restore_form.get_by_label("Archive recovery key (required)")).to_be_visible()
+    expect(
+        restore_form.get_by_role("button", name="Restore database archive")
+    ).to_be_disabled()
+    page.screenshot(path=ARTIFACTS / "settings-backup-desktop.png", full_page=False)
+    page.set_viewport_size({"width": 390, "height": 844})
+    expect(status).to_have_text("Saved to MongoDB")
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(path=ARTIFACTS / "settings-backup-mobile.png", full_page=False)
+
+
+def test_decoder_worker_data_frames_do_not_allow_external_connections_or_scripts(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    external_attempts = []
+    page.route(
+        "https://not-tgdrive.invalid/**",
+        lambda route: (external_attempts.append(True), route.abort()),
+    )
+    login(page, server.url)
+    result = page.evaluate("""async () => {
+      const canvas=document.createElement('canvas');
+      canvas.width=4;canvas.height=3;
+      const context=canvas.getContext('2d');
+      context.fillStyle='#ef315f';context.fillRect(0,0,4,3);
+      const frame=canvas.toDataURL('image/jpeg');
+      const code=`self.onmessage=async event=>{
+        try{
+          const response=await fetch(event.data);
+          const image=await createImageBitmap(await response.blob());
+          const result={width:image.width,height:image.height};image.close();
+          self.postMessage(result);
+        }catch(error){self.postMessage({error:String(error)});}
+      };`;
+      const url=URL.createObjectURL(new Blob([code],{type:'text/javascript'}));
+      const worker=new Worker(url);
+      try{
+        const decoded=await new Promise((resolve,reject)=>{
+          worker.onmessage=event=>resolve(event.data);
+          worker.onerror=event=>reject(Error(event.message));
+          worker.postMessage(frame);
+        });
+        let externalBlocked=false;
+        try{await fetch('https://not-tgdrive.invalid/forbidden');}
+        catch{externalBlocked=true;}
+        const script=document.createElement('script');
+        script.src='data:text/javascript,window.__unexpectedDataScript=true';
+        const scriptBlocked=await new Promise(resolve=>{
+          script.onerror=()=>resolve(true);script.onload=()=>resolve(false);
+          document.head.append(script);
+        });
+        script.remove();
+        return {decoded,externalBlocked,scriptBlocked,
+          scriptExecuted:window.__unexpectedDataScript===true};
+      }finally{worker.terminate();URL.revokeObjectURL(url);}
+    }""")
+    assert result["decoded"] == {"width": 4, "height": 3}
+    assert result["externalBlocked"] and result["scriptBlocked"]
+    assert not result["scriptExecuted"]
+    assert external_attempts == []
+
+
+def test_supported_asf_wmv_software_decode_has_real_frames_pixels_seek_and_original(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    console_csp = []
+    page.on(
+        "console",
+        lambda message: (
+            console_csp.append(message.text)
+            if "content security policy" in message.text.lower()
+            else None
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="software-mpeg4.wmv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    player.hover()
+    player.locator("button.movi-play-pause").click()
+    deadline = time.monotonic() + 15
+    state = None
+    while time.monotonic() < deadline:
+        state = player.evaluate("""element=>({
+          time:element.currentTime,paused:element.paused,
+          frames:element.player.getRenderHealth().framesPresented,
+          codec:element.player.getStats()['Video Codec'],
+          decoder:element.player.getStats()['Video Decoder']})""")
+        if state["time"] > 0.3 and state["frames"] >= 3 and not state["paused"]:
+            break
+        page.wait_for_timeout(100)
+    assert state and state["frames"] >= 3 and state["time"] > 0.3, state
+    assert state["codec"] == "mpeg4" and "Software" in state["decoder"]
+    player.evaluate("element=>element.pause()")
+    canvases = [
+        canvas for canvas in player.locator("canvas").all() if canvas.is_visible()
+    ]
+    canvas = max(canvases, key=lambda item: item.evaluate("e=>e.width*e.height"))
+    pixels = page.evaluate(
+        """async values=>{
+      const blob=new Blob([new Uint8Array(values)],{type:'image/png'});
+      const image=await createImageBitmap(blob);
+      const canvas=document.createElement('canvas');canvas.width=64;canvas.height=64;
+      const context=canvas.getContext('2d');context.drawImage(image,0,0,64,64);
+      image.close();const rgba=context.getImageData(0,0,64,64).data;
+      const colors=new Set();let brightest=0;
+      for(let i=0;i<rgba.length;i+=4){
+        colors.add(rgba[i]+','+rgba[i+1]+','+rgba[i+2]);
+        brightest=Math.max(brightest,rgba[i],rgba[i+1],rgba[i+2]);
+      }
+      return {colors:colors.size,brightest};
+    }""",
+        list(canvas.screenshot()),
+    )
+    assert pixels["colors"] > 64 and pixels["brightest"] > 150, pixels
+    player.evaluate(
+        "async element=>{await element.pause();await element.player.seek(0.7);}"
+    )
+    deadline = time.monotonic() + 10
+    while time.monotonic() < deadline:
+        position = player.evaluate(
+            "element=>({time:element.currentTime,seeking:element.seeking})"
+        )
+        if abs(position["time"] - 0.7) < 0.25 and not position["seeking"]:
+            break
+        page.wait_for_timeout(100)
+    assert abs(position["time"] - 0.7) < 0.25 and not position["seeking"]
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    assert (
+        hashlib.sha256(Path(result.value.path()).read_bytes()).digest()
+        == hashlib.sha256(
+            (ROOT / "tests/fixtures/software-mpeg4.wmv").read_bytes()
+        ).digest()
+    )
+    assert console_csp == []
+
+
+def test_actual_unavailable_wmv_codec_stays_in_custom_player_with_original_download(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="unsupported-msmpeg4.wmv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    expect(dialog.locator("movi-player")).to_be_visible(timeout=30000)
+    expect(dialog.get_by_role("alert")).to_contain_text("msmpeg4v3", timeout=30000)
+    expect(dialog.get_by_role("alert")).to_contain_text(
+        "is not supported by the player on this device"
+    )
+    expect(dialog.get_by_role("button", name="Try again", exact=True)).to_be_visible()
+    assert dialog.evaluate("element => element.matches(':modal')")
+    expect(dialog.locator(".preview-surface > video")).to_have_count(0)
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    assert (
+        hashlib.sha256(Path(result.value.path()).read_bytes()).digest()
+        == hashlib.sha256(
+            (ROOT / "tests/fixtures/unsupported-msmpeg4.wmv").read_bytes()
+        ).digest()
+    )
+
+
+def test_revoked_account_warning_links_to_connections_and_clears(server, desktop):
+    _, page = desktop
+    detail = (
+        "This storage bot can no longer sign in. Open Connections and replace "
+        "its revoked token, then restart TGDrive and retry."
+    )
+    issue = {"code": "TELEGRAM_CREDENTIALS_REVOKED", "detail": detail}
+    state = {"telegram_ready": False, "telegram_issues": [issue]}
+    page.route("**/api/v1/status", lambda route: route.fulfill(json=state))
+    login(page, server.url)
+    warning = page.get_by_role("status").filter(has_text=detail)
+    expect(warning).to_be_visible()
+    warning.get_by_role("button", name="Open Connections", exact=True).click()
+    expect(
+        page.get_by_role("heading", name="Storage Clients", exact=True)
+    ).to_be_visible()
+    state.update(telegram_ready=True, telegram_issues=[])
+    expect(page.get_by_text(detail, exact=True)).not_to_be_visible(timeout=10000)
+
+
+def assert_single_appearance(page: Any) -> None:
+    assert page.locator("html").get_attribute("data-theme") in {"light", "dark"}
+    if not page.locator('input[type="password"]').is_visible():
+        expect(
+            page.get_by_role("button", name="Change Appearance", exact=True)
+        ).to_be_visible()
+
+
+def assert_theme_contrast(page: Any) -> None:
+    values = page.evaluate("""() => {
+      const s=getComputedStyle(document.documentElement);
+      return Object.fromEntries(['--surface','--ink','--muted','--action',
+        '--on-action','--action-soft','--on-action-soft','--danger','--on-danger']
+        .map(k=>[k,s.getPropertyValue(k).trim()]));
+    }""")
+
+    def luminance(value: str) -> float:
+        value = value.lstrip("#")
+        if len(value) == 3:
+            value = "".join(channel * 2 for channel in value)
+        assert len(value) == 6
+        channels = [int(value[index : index + 2], 16) / 255 for index in (0, 2, 4)]
+        linear = [
+            channel / 12.92
+            if channel <= 0.04045
+            else ((channel + 0.055) / 1.055) ** 2.4
+            for channel in channels
+        ]
+        return sum(
+            channel * weight
+            for channel, weight in zip(linear, (0.2126, 0.7152, 0.0722), strict=True)
+        )
+
+    for foreground, background in [
+        ("--ink", "--surface"),
+        ("--muted", "--surface"),
+        ("--on-action", "--action"),
+        ("--on-action-soft", "--action-soft"),
+        ("--on-danger", "--danger"),
+    ]:
+        pair = sorted([luminance(values[foreground]), luminance(values[background])])
+        assert (pair[1] + 0.05) / (pair[0] + 0.05) >= 4.5, (
+            foreground,
+            background,
+            values,
+        )
+
+
+def test_light_dark_theme_preference_persists_and_preserves_sort_keyboard(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.add_init_script(
+        "if (!localStorage.getItem('tgdrive.appearance')) "
+        "localStorage.setItem('tgdrive.appearance', 'light')"
+    )
+    page.emulate_media(color_scheme="light")
+    page.goto(server.url)
+    assert_single_appearance(page)
+    assert_theme_contrast(page)
+    baseline = page.evaluate("""() => ({
+      font: getComputedStyle(document.body).fontFamily,
+      background: getComputedStyle(document.body).backgroundColor,
+      injected: document.querySelectorAll('style[data-mantine-styles]').length
+    })""")
+    assert "InterVariable" in baseline["font"]
+    assert baseline["background"] == "rgb(245, 247, 249)"
+    assert baseline["injected"] == 0
+    login(page)
+    page.reload()
+    assert_single_appearance(page)
+    expect(page.locator("html")).to_have_attribute("data-theme", "light")
+    page.get_by_role("button", name="Change Appearance", exact=True).click()
+    page.get_by_role("menuitemradio", name="Dark", exact=True).click()
+    expect(page.locator("html")).to_have_attribute("data-theme", "dark")
+    expect(page.locator("html")).to_have_attribute("data-mantine-color-scheme", "dark")
+    assert_theme_contrast(page)
+    page.reload()
+    expect(page.locator("html")).to_have_attribute("data-theme", "dark")
+    sort = page.get_by_role("button", name="Sort Files: Name", exact=True)
+    sort.click()
+    menu = page.get_by_role("menu", name="Sort Files", exact=True)
+    expect(menu.get_by_role("menuitemradio", name="Name", exact=True)).to_be_focused()
+    page.keyboard.press("End")
+    # Direction choices follow fields; keyboard navigation traverses both groups.
+    expect(menu.get_by_role("menuitemradio").last).to_be_focused()
+    page.keyboard.press("Home")
+    page.keyboard.press("ArrowDown")
+    page.keyboard.press("ArrowDown")
+    expect(
+        menu.get_by_role("menuitemradio", name="File Size", exact=True)
+    ).to_be_focused()
+    page.keyboard.press("Enter")
+    sort = page.get_by_role("button", name="Sort Files: File Size", exact=True)
+    expect(sort).to_be_focused()
+    sort.click()
+    expect(
+        menu.get_by_role("menuitemradio", name="File Size", exact=True)
+    ).to_have_attribute("aria-checked", "true")
+    page.keyboard.press("Escape")
+    expect(sort).to_be_focused()
+    page.screenshot(path=ARTIFACTS / "single-theme-desktop.png", full_page=False)
+    for width in [390, 320]:
+        page.set_viewport_size({"width": width, "height": 844})
+        assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+        assert_single_appearance(page)
+        assert_theme_contrast(page)
+        page.screenshot(path=ARTIFACTS / f"single-theme-{width}.png", full_page=False)
+
+
+def test_queued_uploads_have_no_elapsed_speed_or_eta(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.route(
+        "**/api/v1/uploads",
+        lambda route: route.fulfill(
+            status=507, json={"detail": "Synthetic upload staging full"}
+        ),
+    )
+    login(page, server.url)
+    upload(page, ["waiting-one.bin", "waiting-two.bin"])
+    panel = page.locator("#transfer-dialog")
+    expect(panel.locator(".transfer-batch")).to_have_count(0)
+    expect(panel.locator(".transfer-item")).to_have_count(2)
+    expect(
+        page.get_by_role("heading", name="2 uploads waiting", exact=True)
+    ).to_be_visible()
+    page.wait_for_timeout(1200)
+    assert "Elapsed" not in panel.inner_text()
+    assert "remaining" not in panel.inner_text()
+    assert "/s" not in panel.inner_text()
+    assert server.control()["started"] == []
+    saved = page.evaluate(UPLOAD_RECOVERY_RECORDS)
+    assert len(saved) == 2
+    assert all(
+        item["state"] == "queued" and not item.get("startedAt") for item in saved
+    )
+    expect(panel.get_by_role("button", name="Show Files", exact=True)).to_have_count(0)
+    assert "Elapsed" not in panel.inner_text()
+    expect(panel.locator("select")).to_have_count(0)
+    expect(panel.locator('[data-filter="active"]')).to_have_count(0)
+    expect(panel.locator('[data-filter="attention"]')).to_have_count(0)
+    page.screenshot(path=ARTIFACTS / "queued-upload-no-elapsed.png", full_page=False)
+    cancel_all(page)
+    expect(panel.locator(".transfer-item[data-status=cancelled]")).to_have_count(2)
+
+
+def test_settings_connection_changes_are_write_only_verified_and_restart_scoped(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    open_admin(page)
+    page.get_by_role("link", name="Connections", exact=True).click()
+    section = page.locator(".connection-management")
+    initial = page.request.get(server.url + "/api/v1/settings")
+    assert initial.ok and initial.json()["revision"] == 0
+    assert "api_hash" not in initial.json()
+    assert all("credential" not in client for client in initial.json()["clients"])
+    expect(section.get_by_role("heading", name="Storage Clients")).to_be_visible()
+    expect(section.locator(".managed-client-info strong").first).to_have_text(
+        "TGDrive Test Bot"
+    )
+    expect(section.locator(".managed-client-info").first).to_contain_text(
+        "@tgdrive_fixture_bot"
+    )
+    section.get_by_role("button", name="Refresh", exact=True).click()
+    expect(section.locator(".managed-client-state").first).to_contain_text(
+        "Token and channel verified"
+    )
+    expect(section.locator(".managed-client-info strong").first).to_have_text(
+        "TGDrive Test Bot"
+    )
+    expect(section.get_by_role("heading", name="Telegram API")).to_be_visible()
+    expect(section.locator("input")).to_have_count(0)
+    expect(section.get_by_role("button", name="Verify and Save")).to_have_count(0)
+
+    def open_form() -> Any:
+        section.get_by_role("button", name="Edit API Credentials", exact=True).click()
+        form = section.locator("form.connection-editor")
+        expect(form.get_by_label("Replace API Hash", exact=True)).to_have_value("")
+        return form
+
+    def fill_candidate(form: Any) -> None:
+        form.get_by_label("API ID", exact=True).fill("12346")
+        form.get_by_label("Replace API Hash", exact=True).fill("b" * 32)
+
+    form = open_form()
+    fill_candidate(form)
+    held: list[Any] = []
+    attempts = 0
+
+    def control_save(route: Any) -> None:
+        nonlocal attempts
+        if route.request.method != "PATCH":
+            route.continue_()
+            return
+        attempts += 1
+        if attempts == 1:
+            held.append(route)
+        elif attempts == 2:
+            route.fulfill(
+                status=409,
+                json={
+                    "detail": "Synthetic concurrent settings change",
+                    "code": "SETTINGS_CONFLICT",
+                },
+            )
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/settings", control_save)
+    form.get_by_role("button", name="Verify and Save", exact=True).click()
+    expect(form.get_by_role("status")).to_contain_text(
+        "Checking accounts and channel access."
+    )
+    expect(form.get_by_label("API ID", exact=True)).to_be_disabled()
+    deadline = time.monotonic() + 5
+    while not held and time.monotonic() < deadline:
+        page.wait_for_timeout(25)
+    assert len(held) == 1
+    held[0].fulfill(
+        status=503,
+        json={
+            "detail": "Synthetic channel access could not be verified",
+            "code": "SETTINGS_PREFLIGHT_FAILED",
+        },
+    )
+    expect(form.get_by_role("alert")).to_contain_text("could not be verified")
+    expect(form.get_by_label("Replace API Hash", exact=True)).to_have_value("b" * 32)
+    assert page.request.get(server.url + "/api/v1/settings").json()["revision"] == 0
+    form.get_by_role("button", name="Verify and Save", exact=True).click()
+    expect(section.locator("form.connection-editor")).to_have_count(0)
+    expect(section.get_by_role("alert")).to_contain_text("changed elsewhere")
+    form = open_form()
+    fill_candidate(form)
+    form.get_by_role("button", name="Verify and Save", exact=True).click()
+    expect(section.locator("form.connection-editor")).to_have_count(0)
+    expect(
+        section.get_by_text("Saved changes need a restart", exact=True)
+    ).to_be_visible()
+    expect(page.locator(".restart-required-banner")).to_be_visible()
+
+    # Per-client editing remains inline and retains omitted secrets.
+    section.get_by_role("button", name="Manage TGDrive Test Bot", exact=True).click()
+    form = section.locator("form.connection-editor")
+    expect(form.get_by_label("Replace Bot Token", exact=True)).to_have_value("")
+    form.get_by_role("button", name="Remove Client", exact=True).click()
+    expect(form.locator(".client-removal")).to_be_visible()
+    form.get_by_role("button", name="Undo Removal", exact=True).click()
+    expect(form.locator(".client-removal")).to_have_count(0)
+    form.get_by_label("Replace Bot Token", exact=True).fill("123456:" + "y" * 30)
+    form.get_by_role("button", name="Verify and Save", exact=True).click()
+    expect(section.locator("form.connection-editor")).to_have_count(0)
+    section.get_by_role("button", name="Add Storage Bot", exact=True).click()
+    form = section.locator("form.connection-editor")
+    form.get_by_label("Local Label", exact=True).fill("Extra storage bot")
+    form.get_by_label("Bot Token", exact=True).fill("987654:" + "z" * 30)
+    form.get_by_role("button", name="Verify and Save", exact=True).click()
+    expect(section.locator("form.connection-editor")).to_have_count(0)
+    pending = page.request.get(server.url + "/api/v1/settings")
+    assert pending.ok
+    body = pending.json()
+    assert body["revision"] == 3 and body["applied_revision"] == 0
+    assert body["restart_required"] and body["admission_paused"]
+    assert body["application_mode"] == "restart"
+    assert body["active_clients"][0]["connected"] is True
+    assert "api_hash" not in body
+    serialized = json.dumps(body)
+    for secret in ("b" * 32, "123456:" + "y" * 30, "987654:" + "z" * 30):
+        assert secret not in serialized
+        assert secret not in section.inner_text()
+    extra = section.locator(".managed-client-list > li").filter(
+        has_text="Extra storage bot"
+    )
+    expect(extra).to_contain_text("Not connected")
+    expect(extra.locator(".is-connected")).to_have_count(0)
+    section.get_by_role("button", name="Manage Extra storage bot", exact=True).click()
+    form = section.locator("form.connection-editor")
+    expect(form.get_by_label("Replace Bot Token", exact=True)).to_have_value("")
+    form.get_by_role("button", name="Done", exact=True).click()
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    expect(page.locator("#new-button")).to_be_disabled()
+    page.reload()
+    expect(page.locator(".restart-required-banner")).to_be_visible()
+    expect(page.locator("#new-button")).to_be_disabled()
+    blocked = page.request.post(
+        server.url + "/api/v1/uploads",
+        data={"name": "must-not-start.bin", "parent_id": "/", "total_size": 3},
+    )
+    assert blocked.status == 409
+    assert blocked.json()["code"] == "SETTINGS_RESTART_REQUIRED"
+    open_admin(page)
+    page.get_by_role("link", name="Connections", exact=True).click()
+    page.set_viewport_size({"width": 320, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(
+        path=ARTIFACTS / "settings-saved-pending-mobile.png", full_page=False
+    )
+
+
+def test_settings_guided_premium_login_cancel_code_and_two_step(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    open_admin(page)
+    page.get_by_role("link", name="Connections", exact=True).click()
+    section = page.locator(".connection-management")
+    section.get_by_role("button", name="Connect Premium Account", exact=True).click()
+    premium = section.get_by_role("form", name="Connect a Premium Account", exact=True)
+    premium.get_by_label("Phone Number", exact=True).fill("+441234567801")
+    premium.get_by_role("button", name="Send Login Code", exact=True).click()
+    expect(premium.get_by_label("Telegram Login Code", exact=True)).to_be_focused()
+    with page.expect_response(
+        lambda response: (
+            response.request.method == "DELETE" and "/premium-login/" in response.url
+        )
+    ) as cancelled:
+        premium.get_by_role("button", name="Cancel Connection", exact=True).click()
+    assert cancelled.value.status == 200
+    expect(section.locator(".premium-connection")).to_have_count(0)
+    section.get_by_role("button", name="Connect Premium Account", exact=True).click()
+    premium = section.get_by_role("form", name="Connect a Premium Account", exact=True)
+    premium.get_by_label("Account Name", exact=True).fill("My verified Premium")
+    premium.get_by_label("Phone Number", exact=True).fill("+441234567802")
+    premium.get_by_role("button", name="Send Login Code", exact=True).click()
+    code = premium.get_by_label("Telegram Login Code", exact=True)
+    expect(code).to_be_focused()
+    code.fill("00000")
+    premium.get_by_role("button", name="Verify Code", exact=True).click()
+    expect(premium.get_by_role("alert")).to_have_text(
+        "That code is incorrect. Try again."
+    )
+    expect(code).to_have_value("")
+    code.fill("12345")
+    premium.get_by_role("button", name="Verify Code", exact=True).click()
+    password = premium.get_by_label("Telegram Two-Step Password", exact=True)
+    expect(password).to_be_focused()
+    expect(password).to_have_attribute("type", "password")
+    password.fill("synthetic-two-step-password")
+    premium.get_by_role("button", name="Connect Account", exact=True).click()
+    expect(section.locator(".premium-connection")).to_have_count(0)
+    expect(
+        section.get_by_text("Saved changes need a restart", exact=True)
+    ).to_be_visible()
+    account = section.locator(".managed-client-list > li").filter(
+        has_text="My verified Premium"
+    )
+    expect(account).to_contain_text("Not connected")
+    expect(account).not_to_contain_text("Premium is not active")
+    assert page.locator("input[type=password]").count() == 0
+    snapshot = page.request.get(server.url + "/api/v1/settings").json()
+    assert snapshot["restart_required"] is True
+    assert "synthetic-premium-session-for-browser-tests" not in json.dumps(snapshot)
+    assert not any("credential" in client for client in snapshot["clients"])
+
+
+def test_bulk_deletion_is_one_notice_with_refresh_failure_and_retry(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    for name in ("Private folder", "資料", "Preview samples"):
+        select_item(page, name)
+    page.get_by_role("button", name="Trash", exact=True).click()
+    page.get_by_role("link", name="Trash", exact=True).click()
+    for name in ("Private folder", "資料", "Preview samples"):
+        select_item(page, name)
+    page.get_by_role("button", name="Delete Permanently", exact=True).click()
+    page.get_by_role("dialog").get_by_role(
+        "button", name="Delete Permanently", exact=True
+    ).click()
+    notice = page.get_by_role("region", name="File Deletion", exact=True)
+    expect(notice.get_by_role("status")).to_contain_text("Deleting 3 items…")
+    expect(page.locator(".transfer-batch")).to_have_count(0)
+    records = server.control()["records"]
+    ids = [key for key, record in records.items() if record.get("phase") == "deleting"]
+    assert len(ids) == 3
+    server.finish(ids[0])
+    expect(notice.get_by_role("status")).to_contain_text("Deleting 2 items…")
+    expect(notice).to_contain_text("1 completed.")
+    server.control("/fail-deletion/" + ids[1], method="POST")
+    server.finish(ids[2])
+    expect(notice.get_by_role("status")).to_have_text("1 item could not be deleted.")
+    expect(notice.locator(".deletion-errors")).not_to_have_attribute("open", "")
+    expect(page.locator(".transfer-batch")).to_have_count(0)
+    page.reload()
+    expect(notice.get_by_role("status")).to_have_text("1 item could not be deleted.")
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    expect(notice).to_have_count(0)
+    page.get_by_role("link", name="Trash", exact=True).click()
+    expect(notice.get_by_role("status")).to_have_text("1 item could not be deleted.")
+    expect(page.locator(".transfer-batch")).to_have_count(0)
+    notice.get_by_text("View Failed Items (1)", exact=True).click()
+    expect(notice).to_contain_text("Synthetic catalog deletion failed")
+    notice.get_by_role("button", name="Retry Failed deletions", exact=True).click()
+    expect(notice.get_by_role("status")).to_contain_text("Deleting 1 item…")
+    server.finish(ids[1])
+    expect(page.get_by_text("Permanently deleted 1 item.", exact=True)).to_be_visible()
+    expect(notice).to_have_count(0)
+    expect(
+        page.get_by_role("heading", name="Trash Is Empty", exact=True)
+    ).to_be_visible()
+    expect(page.locator(".transfer-batch")).to_have_count(0)
+
+
+def test_debounced_search_restores_origin_and_document_text_stays_selectable(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="資料", exact=True).dblclick()
+    origin = page.url
+    search = page.get_by_role("searchbox", name="Search Files and Folders", exact=True)
+    before = page.evaluate("history.length")
+    search.fill("private")
+    expect(
+        page.get_by_role("heading", name="Search Results", exact=True)
+    ).to_be_visible()
+    expect(page.get_by_role("button", name="private.txt", exact=True)).to_be_visible()
+    expect(
+        page.locator(".search-result-location").filter(has_text="Private folder")
+    ).to_be_visible()
+    after = page.evaluate("history.length")
+    assert after == before + 1
+    search.fill("résumé")
+    expect(page.get_by_role("button", name="résumé #1.txt", exact=True)).to_be_visible()
+    expect(page.get_by_role("button", name="private.txt", exact=True)).to_have_count(0)
+    assert page.evaluate("history.length") == after
+    page.get_by_role("button", name="Clear Search", exact=True).click()
+    expect(page).to_have_url(origin)
+    expect(search).to_have_value("")
+    search.fill("private")
+    expect(
+        page.get_by_role("heading", name="Search Results", exact=True)
+    ).to_be_visible()
+    search.press("Escape")
+    expect(page).to_have_url(origin)
+    expect(search).to_have_value("")
+    page.get_by_role("heading").first.click()
+    page.keyboard.press("Control+k")
+    expect(search).to_be_focused()
+    search.fill("input selection")
+    search.press("Control+a")
+    assert search.evaluate(
+        "input=>input.selectionStart===0 && input.selectionEnd===input.value.length"
+    )
+    search.press("Escape")
+    heading = page.get_by_role("heading").first
+    assert heading.evaluate("node=>getComputedStyle(node).userSelect") == "none"
+    page.evaluate("getSelection().removeAllRanges()")
+    bounds = heading.bounding_box()
+    assert bounds
+    page.mouse.move(bounds["x"] + 2, bounds["y"] + bounds["height"] / 2)
+    page.mouse.down()
+    page.mouse.move(
+        bounds["x"] + bounds["width"] - 2, bounds["y"] + bounds["height"] / 2, steps=10
+    )
+    page.mouse.up()
+    assert page.evaluate("getSelection().toString()") == ""
+    page.locator(".drive-nav").get_by_role("link", name="My Files", exact=True).click()
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="sample.json", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    pre = dialog.locator("pre")
+    expect(pre).to_contain_text('"count": 3')
+    assert pre.evaluate("node=>getComputedStyle(node).userSelect") == "text"
+    bounds = pre.bounding_box()
+    assert bounds
+    page.mouse.move(bounds["x"] + 28, bounds["y"] + 32)
+    page.mouse.down()
+    page.mouse.move(bounds["x"] + 250, bounds["y"] + 77, steps=10)
+    page.mouse.up()
+    assert page.evaluate("getSelection().toString().length") > 0
+    page.keyboard.press("Escape")
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+
+
+def test_ui_polish_batched_visual_states(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    target = ROOT / "cache/format-qa/ui-polish"
+    target.mkdir(parents=True, exist_ok=True)
+    directory = tmp_path / "Project release"
+    (directory / "notes").mkdir(parents=True)
+    (directory / "readme.txt").write_text("data")
+    (directory / "notes" / "summary.txt").write_text("data")
+    login(page, server.url)
+
+    def capture(name: str) -> None:
+        expect(page.locator("html")).to_have_attribute(
+            "data-theme", name.split("-", 1)[0]
+        )
+        assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+        page.screenshot(path=target / (name + ".png"), full_page=False)
+
+    for mode in ("Dark",):
+        page.set_viewport_size({"width": 1440, "height": 960})
+        page.get_by_role("button", name="Change Appearance", exact=True).click()
+        page.get_by_role("menuitemradio", name=mode, exact=True).click()
+        assert_single_appearance(page)
+        assert_theme_contrast(page)
+        page.evaluate("document.fonts.ready")
+        assert page.evaluate("document.fonts.check('14px InterVariable')")
+        search_alignment = page.locator(".search-form").evaluate("""form=>{
+          const field=form.querySelector('input').getBoundingClientRect();
+          const box=form.getBoundingClientRect();
+          return Math.abs((field.top+field.bottom)/2-(box.top+box.bottom)/2);
+        }""")
+        assert search_alignment <= 2
+        capture(mode.lower() + "-files-desktop")
+        page.set_viewport_size({"width": 390, "height": 844})
+        capture(mode.lower() + "-files-mobile")
+        page.set_viewport_size({"width": 1440, "height": 960})
+        page.locator("#new-button").click()
+        capture(mode.lower() + "-new-menu")
+        page.locator("#new-button").click()
+        dialog = select_folder(page, directory)
+        expect(dialog.locator(".folder-upload-summary")).to_contain_text(
+            "Project release"
+        )
+        expect(dialog.locator(".folder-upload-summary")).to_contain_text(
+            "2 files · 8 B"
+        )
+        expect(dialog.locator(".folder-upload-destination")).to_have_text("To My Files")
+        bounds = dialog.bounding_box()
+        assert bounds and bounds["height"] < 400
+        capture(mode.lower() + "-folder-desktop")
+        page.set_viewport_size({"width": 390, "height": 844})
+        bounds = dialog.bounding_box()
+        assert bounds and bounds["x"] >= 0 and bounds["x"] + bounds["width"] <= 390
+        capture(mode.lower() + "-folder-mobile")
+        dialog.get_by_role("button", name="Close Dialog", exact=True).click()
+
+    page.set_viewport_size({"width": 1440, "height": 960})
+    page.route(
+        "**/api/v1/uploads",
+        lambda route: route.fulfill(
+            status=507, json={"detail": "Synthetic upload staging full"}
+        ),
+    )
+    page.reload()
+    upload(page, ["waiting-one.bin", "waiting-two.bin", "waiting-three.bin"])
+    panel = page.locator("#transfer-dialog")
+    expect(panel.locator(".transfer-batch")).to_have_count(0)
+    expect(panel.locator(".transfer-item")).to_have_count(3)
+    expect(
+        page.get_by_role("heading", name="3 uploads waiting", exact=True)
+    ).to_be_visible()
+    capture("dark-transfer-queued")
+    expect(panel.get_by_role("button", name="Show Files", exact=True)).to_have_count(0)
+    capture("dark-transfer-filters")
+    page.set_viewport_size({"width": 390, "height": 844})
+    capture("dark-transfer-mobile")
+    expect(page.locator("#transfer-dialog")).to_have_count(0)
+    page.set_viewport_size({"width": 1440, "height": 960})
+    cancel_all(page)
+    expect(panel.locator(".transfer-item[data-status=cancelled]")).to_have_count(3)
+    page.unroute("**/api/v1/uploads")
+    page.get_by_role("button", name="Clear Finished", exact=True).click()
+    page.set_viewport_size({"width": 1440, "height": 960})
+    open_admin(page)
+    page.get_by_role("link", name="Connections", exact=True).click()
+    section = page.locator(".connection-management")
+    premium_button = section.get_by_role(
+        "button", name="Connect Premium Account", exact=True
+    )
+    expect(premium_button).to_be_enabled()
+    capture("dark-connections-desktop")
+    premium_button.click()
+    premium = section.get_by_role("form", name="Connect a Premium Account", exact=True)
+    expect(premium.get_by_label("Phone Number", exact=True)).to_have_value("")
+    premium.scroll_into_view_if_needed()
+    capture("dark-premium-desktop")
+    page.set_viewport_size({"width": 390, "height": 844})
+    premium.scroll_into_view_if_needed()
+    capture("dark-premium-mobile")
+    premium.get_by_role("button", name="Cancel Connection", exact=True).click()
+    page.locator(".workspace").evaluate("element=>element.scrollTop=0")
+    page.get_by_role("button", name="Change Appearance", exact=True).click()
+    page.get_by_role("menuitemradio", name="Light", exact=True).click()
+    assert_single_appearance(page)
+    capture("light-connections-mobile")
+
+    for mode in ("Dark",):
+        page.set_viewport_size({"width": 1440, "height": 960})
+        page.get_by_role("button", name="Change Appearance", exact=True).click()
+        page.get_by_role("menuitemradio", name=mode, exact=True).click()
+        assert_single_appearance(page)
+        for route, heading in (
+            ("connections", "Connections"),
+            ("storage", "Storage & Backups"),
+        ):
+            page.goto(server.url + "/?view=" + route)
+            expect(
+                page.get_by_role("heading", name=heading, exact=True)
+            ).to_be_visible()
+            if route == "connections":
+                expect(
+                    page.get_by_role("heading", name="Storage Clients")
+                ).to_be_visible()
+                expect(page.locator(".connection-management input")).to_have_count(0)
+            elif route == "storage":
+                expect(page.locator(".storage-catalog")).to_be_visible()
+                expect(
+                    page.get_by_role("progressbar", name="Reserved Upload Staging")
+                ).to_be_visible()
+            capture(mode.lower() + "-" + route + "-desktop")
+            page.set_viewport_size({"width": 390, "height": 844})
+            if route == "storage":
+                backup_title = page.get_by_role(
+                    "heading", name="Cloud Database", exact=True
+                )
+                expect(backup_title).to_be_visible()
+                expect(
+                    page.get_by_role(
+                        "region", name="Cloud Database", exact=True
+                    ).get_by_role("button", name="Back Up Now", exact=True)
+                ).to_be_enabled()
+                assert backup_title.bounding_box()["height"] <= 28
+                assert (
+                    page.locator(".drive-backup-state").bounding_box()["height"] <= 28
+                )
+            capture(mode.lower() + "-" + route + "-mobile")
+            if route == "connections":
+                page.locator(".workspace").evaluate(
+                    "element=>element.scrollTop=element.scrollHeight"
+                )
+                footer = page.locator(".connection-footer-note")
+                expect(footer).to_be_in_viewport()
+                expect(page.locator("#compact-new-button")).to_have_count(0)
+                footer_box = footer.bounding_box()
+                assert footer_box and footer_box["y"] + footer_box["height"] <= 844
+                storage_link = page.get_by_role(
+                    "link", name="Storage & Backups", exact=True
+                )
+                if page.locator(".sidebar").get_attribute("inert") is not None:
+                    page.get_by_role(
+                        "button", name="Toggle Navigation", exact=True
+                    ).click()
+                storage_link.click()
+                expect(
+                    page.get_by_role("heading", name="Storage & Backups", exact=True)
+                ).to_be_in_viewport()
+                page.go_back()
+                expect(
+                    page.get_by_role("heading", name="Connections", exact=True)
+                ).to_be_in_viewport()
+            page.set_viewport_size({"width": 320, "height": 844})
+            assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+            page.set_viewport_size({"width": 1440, "height": 960})
+
+
+def test_transfer_progress_and_safe_panel_controls(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.emulate_media(color_scheme="dark")
+    login(page, server.url)
+    expect(page.locator(".drive-protection")).to_have_count(0)
+    fraction = 0.0
+
+    def measured_progress(route: Any) -> None:
+        response = route.fetch()
+        payload = response.json()
+        for job in payload["jobs"]:
+            if job["status"] in {"queued", "running"}:
+                job["current"] = int(job["total"] * fraction)
+        route.fulfill(response=response, json=payload)
+
+    page.route("**/api/v1/jobs", measured_progress)
+    upload(page, ["single-progress.bin"])
+    server.wait_started(1)
+    single = row(page, "single-progress.bin")
+    expect(single.locator(".transfer-phase")).to_have_text("Uploading to Telegram")
+    expect(single.get_by_role("progressbar")).to_have_attribute("value", "0")
+    expect(single.locator(".transfer-bytes")).to_have_text("0 B / 64 KB")
+    expect(page.get_by_role("button", name="Show Files", exact=True)).to_have_count(0)
+    expect(
+        page.get_by_role("button", name="Add files to upload queue", exact=True)
+    ).to_have_count(0)
+    expect(page.get_by_role("button", name="Clear Finished", exact=True)).to_have_count(
+        0
+    )
+
+    fraction = 0.25
+    expect(single.get_by_role("progressbar")).to_have_attribute("value", "0.25")
+    expect(single.locator(".transfer-bytes")).to_have_text("16 / 64 KB")
+    expect(single.locator(".transfer-batch-percent")).to_have_text("25%")
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    expect(single.get_by_role("progressbar")).to_have_attribute("value", "0.25")
+    expect(page.get_by_role("button", name="Show Files", exact=True)).to_have_count(0)
+    page.screenshot(
+        path=ARTIFACTS / "single-transfer-stage-progress.png", full_page=True
+    )
+
+    page.get_by_role("link", name="My Files", exact=True).click()
+    page.get_by_role("button", name="Hide Transfer Details", exact=True).click()
+    expect(page.locator("#transfer-list")).not_to_be_visible()
+    page.get_by_role("button", name="Show Transfer Details", exact=True).click()
+    expect(single).to_be_visible()
+    page.set_viewport_size({"width": 390, "height": 844})
+    # The phone layout replaces the expanded desktop panel with its summary.
+    # Wait for that React transition before examining controls from the new layout.
+    expect(page.locator("#transfer-dialog")).to_have_count(0)
+    assert_layout(page)
+    page.screenshot(path=ARTIFACTS / "single-transfer-mobile.png", full_page=True)
+    page.set_viewport_size({"width": 1440, "height": 960})
+
+    page.get_by_role("button", name="Cancel All", exact=True).click()
+    confirmation = page.get_by_role("dialog", name="Cancel All Uploads?", exact=True)
+    expect(confirmation).to_be_visible()
+    expect(confirmation).to_contain_text("1 unfinished upload")
+    expect(
+        confirmation.get_by_role("button", name="Keep Uploading", exact=True)
+    ).to_be_focused()
+    expect(single).to_have_attribute("data-status", "uploading")
+    page.keyboard.press("Escape")
+    expect(confirmation).to_have_count(0)
+    expect(single).to_have_attribute("data-status", "uploading")
+    cancel_all(page)
+    expect(single).to_have_attribute("data-status", "cancelled")
+    page.get_by_role("button", name="Clear Finished", exact=True).click()
+    expect(single).to_have_count(0)
+
+    page.set_viewport_size({"width": 1440, "height": 960})
+    fraction = 0
+    upload(page, ["batch-first.bin", "batch-second.bin"])
+    server.wait_started(3)
+    expect(page.locator(".transfer-batch")).to_have_count(0)
+    for name in ("batch-first.bin", "batch-second.bin"):
+        expect(row(page, name).locator(".transfer-bytes")).to_have_text("0 B / 64 KB")
+    fraction = 0.25
+    for name in ("batch-first.bin", "batch-second.bin"):
+        item = row(page, name)
+        expect(item.get_by_role("progressbar")).to_have_attribute("value", "0.25")
+        expect(item.locator(".transfer-bytes")).to_have_text("16 / 64 KB")
+    expect(page.get_by_role("button", name="Show Files", exact=True)).to_have_count(0)
+    page.screenshot(
+        path=ARTIFACTS / "multi-transfer-telegram-bytes.png", full_page=True
+    )
+    cancel_all(page)
+
+
+def test_transfer_history_filters_cleared_records_and_empty_state(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.emulate_media(color_scheme="dark")
+    login(page, server.url)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    history = page.get_by_role("region", name="Transfer History", exact=True)
+    filters = history.get_by_role("group", name="Filter Finished Transfers", exact=True)
+    expect(
+        history.get_by_role("heading", name="No Finished Transfers Yet", exact=True)
+    ).to_be_visible()
+    expect(
+        history.get_by_role("button", name="Upload Files", exact=True)
+    ).to_have_count(0)
+    for name in ("All", "Successful", "Failed", "Cancelled"):
+        expect(filters.get_by_role("button", name=name, exact=True)).to_be_visible()
+    # New first opens the destination context instead of a picker on Transfers.
+    page.locator("#new-button").click()
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    expect(page.locator("#file-upload-action")).to_be_visible()
+    page.keyboard.press("Escape")
+
+    held = []
+
+    def hold_first(route: Any) -> None:
+        if route.request.method == "PATCH":
+            held.append(route)
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/uploads/*", hold_first)
+    upload(page, ["history-first.bin", "history-second.bin"])
+    deadline = time.monotonic() + 10
+    while not held and time.monotonic() < deadline:
+        page.wait_for_timeout(30)
+    # History behavior is independent of the browser's receive concurrency.
+    assert held
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    filters.get_by_role("button", name="Failed", exact=True).click()
+    expect(
+        history.get_by_role("heading", name="No Failed Transfers", exact=True)
+    ).to_be_visible()
+    filters.get_by_role("button", name="All", exact=True).click()
+    expect(history.get_by_role("button", name="Show Files", exact=True)).to_have_count(
+        0
+    )
+    expect(history.locator(".transfer-item-name")).to_have_count(2)
+    expect(row(page, "history-first.bin")).to_be_visible()
+    expect(row(page, "history-second.bin")).to_be_visible()
+    for route in held:
+        route.continue_()
+    page.unroute("**/api/v1/uploads/*", hold_first)
+    finish_fixture_uploads(page, server, 2)
+    filters.get_by_role("button", name="Successful", exact=True).click()
+    expect(history.locator(".transfer-batch")).to_have_count(0)
+    expect(history.locator(".transfer-item-name")).to_have_count(2)
+    page.get_by_role("link", name="My Files", exact=True).click()
+    expect(page.locator("#transfer-dialog")).to_have_count(0, timeout=10000)
+
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    filters.get_by_role("button", name="Successful", exact=True).click()
+    expect(history.get_by_role("button", name="Show Files", exact=True)).to_have_count(
+        0
+    )
+    expect(history.locator(".transfer-item-name")).to_have_count(2)
+    expect(history.locator("time")).to_have_count(2)
+    expect(
+        history.get_by_role("button", name="Clear Finished", exact=True)
+    ).to_have_count(0)
+    page.screenshot(path=ARTIFACTS / "transfer-history-dark.png", full_page=True)
+    # Prove server history remains after browser tracking is removed/reloaded.
+    page.evaluate("localStorage.clear()")
+    page.reload()
+    filters.get_by_role("button", name="Successful", exact=True).click()
+    expect(history.locator(".transfer-item-name")).to_have_count(2)
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.emulate_media(color_scheme="light")
+    assert_layout(page)
+    for name in ("All", "Successful", "Failed", "Cancelled"):
+        expect(filters.get_by_role("button", name=name, exact=True)).to_be_in_viewport()
+    page.screenshot(path=ARTIFACTS / "transfer-history-mobile.png", full_page=True)
+    filters.get_by_role("button", name="Cancelled", exact=True).click()
+    expect(
+        history.get_by_role("heading", name="No Cancelled Transfers", exact=True)
+    ).to_be_visible()
+    expect(
+        history.get_by_role("button", name="Upload Files", exact=True)
+    ).to_have_count(0)
+
+
+def test_transfer_task_numbered_pages_keep_folder_intact(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    now = time.time()
+    metadata = {
+        "id": "explicit-folder-task-0001",
+        "name": "Uploaded folder",
+        "root_path": "/uploaded-folder",
+        "created_at": now,
+    }
+    members = [
+        {
+            "id": "folder-member-" + str(index),
+            "name": f"member-{index:02}.txt",
+            "kind": "upload",
+            "folder_upload": metadata,
+            "destination": metadata["root_path"],
+            "status": "completed",
+            "phase": "completed",
+            "current": 100,
+            "total": 100,
+            "created_at": now,
+            "finished_at": now,
+        }
+        for index in range(72)
+    ]
+    ordinary = [
+        {
+            "id": "ordinary-task-" + str(index),
+            "name": f"separate-{index:02}.txt",
+            "kind": "upload",
+            "destination": "/",
+            "status": "completed",
+            "phase": "completed",
+            "current": 100,
+            "total": 100,
+            "created_at": now - index - 1,
+            "finished_at": now,
+        }
+        for index in range(22)
+    ]
+    offsets = []
+
+    def history(route: Any) -> None:
+        payload = route.request.post_data_json
+        offset = payload.get("offset", 0)
+        offsets.append(offset)
+        assert offset in (0, 20)
+        route.fulfill(
+            json={
+                "jobs": members + ordinary[:19] if offset == 0 else ordinary[19:],
+                "page": payload["page"],
+                "page_size": 20,
+                "total_tasks": 23,
+                "total_pages": 2,
+                "has_more": offset == 0,
+            }
+        )
+
+    page.route("**/api/v1/transfers/history/tasks", history)
+    login(page, server.url)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    center = page.get_by_role("region", name="Transfer History", exact=True)
+    finished = center.locator('.transfer-category[data-category="finished"]')
+    folder = center.locator('[data-batch-id="explicit-folder-task-0001"]')
+    navigation = center.get_by_role("navigation", name="Finished transfer pages")
+    first = navigation.get_by_role(
+        "button", name="Page 1 of finished transfers", exact=True
+    )
+    second = navigation.get_by_role(
+        "button", name="Page 2 of finished transfers", exact=True
+    )
+    expect(finished.locator(".transfer-category-title > span")).to_have_text("20")
+    expect(folder.locator(".transfer-batch-count")).to_have_text("72 files")
+    expect(center.locator(".transfer-item")).to_have_count(19)
+    expect(first).to_have_attribute("aria-current", "page")
+    second.click()
+    expect(finished.locator(".transfer-category-title > span")).to_have_text("3")
+    expect(folder).to_have_count(0)
+    expect(center.locator(".transfer-item")).to_have_count(3)
+    expect(second).to_have_attribute("aria-current", "page")
+    assert 20 in offsets
+    first.click()
+    expect(first).to_have_attribute("aria-current", "page")
+    expect(finished.locator(".transfer-category-title > span")).to_have_text("20")
+    expect(folder.locator(".transfer-batch-count")).to_have_text("72 files")
+    folder.get_by_role("button", name="Show Files", exact=True).click()
+    expect(folder.locator(".transfer-item")).to_have_count(20)
+    for count in (40, 60, 72):
+        folder.locator("button.transfer-show-more").click()
+        expect(folder.locator(".transfer-item")).to_have_count(count)
+    expect(folder.locator("button.transfer-show-more")).to_have_count(0)
+    assert offsets[-1] == 0
+
+
+def test_upload_concurrency_setting_saves_and_survives_reload(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.emulate_media(color_scheme="dark")
+    login(page, server.url)
+    open_admin(page)
+    page.get_by_role("link", name="Transfer limits", exact=True).click()
+    setting = page.get_by_role("region", name="Parallel uploads", exact=True)
+    field = setting.get_by_label("Simultaneous Uploads per Bot", exact=True)
+    expect(field).to_have_value("1")
+    setting.get_by_role("button", name="More Uploads per Bot", exact=True).click()
+    expect(field).to_have_value("2")
+    setting.get_by_role("button", name="Save Changes", exact=True).click()
+    expect(setting.get_by_role("status")).to_have_text("Upload settings saved.")
+    page.reload()
+    expect(field).to_have_value("2")
+    setting.screenshot(path=str(ARTIFACTS / "upload-settings-dark.png"))
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.emulate_media(color_scheme="light")
+    expect(field).to_be_visible()
+    setting.screenshot(path=str(ARTIFACTS / "upload-settings-mobile.png"))
+    assert page.evaluate("document.documentElement.scrollWidth <= window.innerWidth")
+    setting.get_by_role("button", name="Fewer Uploads per Bot", exact=True).click()
+    setting.get_by_role("button", name="Save Changes", exact=True).click()
+    expect(setting.get_by_role("status")).to_have_text("Upload settings saved.")
+
+
+def test_transfer_sections_locate_highlight_and_normal_preview(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    upload(page, ["completed-location.txt"])
+    first = server.wait_started(1)[0]
+    server.control("/finish/" + first["id"], method="POST")
+    expect(page.locator(".transfer-item[data-status=completed]")).to_be_visible()
+    upload(page, ["still-running.bin"], add=True)
+    server.wait_started(2)
+    held = []
+
+    def hold_device(route: Any):
+        if route.request.method == "PATCH":
+            held.append(route)
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/uploads/*", hold_device)
+    upload(page, ["device-receiving.bin", "queued-device.bin"], add=True)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    history = page.get_by_role("region", name="Transfer History", exact=True)
+    for label in ("Running", "Finished"):
+        expect(history.get_by_role("region", name=label, exact=True)).to_be_visible()
+    expect(history.get_by_role("region", name="Queued", exact=True)).to_have_count(0)
+    completed = history.locator(".transfer-item[data-status=completed]")
+    expect(completed.locator(".transfer-location")).to_have_text("My Files")
+    expect(completed).not_to_contain_text("Elapsed")
+    expect(completed.locator(".transfer-batch-percent")).to_have_count(0)
+    expect(completed.locator(".transfer-bytes")).not_to_contain_text("/")
+    page.screenshot(path=ARTIFACTS / "transfer-sections-light.png", full_page=True)
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.emulate_media(color_scheme="dark")
+    assert page.evaluate("document.documentElement.scrollWidth <= window.innerWidth")
+    page.screenshot(path=ARTIFACTS / "transfer-sections-mobile.png", full_page=True)
+    completed.locator(".transfer-item-name").dblclick()
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    selected = page.locator(".file-row.selected")
+    expect(selected).to_have_count(1)
+    expect(selected).to_contain_text("completed-location.txt")
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    selected.get_by_role("button", name="completed-location.txt", exact=True).dblclick()
+    expect(page.get_by_role("dialog")).to_be_visible()
+    for route in held:
+        route.abort()
+
+
+def test_transfer_columns_handle_long_names_paths_and_narrow_screens(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    long_name = "Very-long-file-" + "filenamewithoutspaces" * 10 + "-résumé-写真.zip"
+    long_folder = "My Files / " + "Projects-with-a-long-name / " * 16 + "Final"
+    now = time.time()
+    jobs = []
+    for index, status in enumerate(
+        ("completed", "cancelled", "queued", "running", "error")
+    ):
+        jobs.append(
+            {
+                "id": "column-fixture-" + str(index),
+                "name": long_name if status != "cancelled" else "Cancelled-upload.zip",
+                "status": status,
+                "phase": "uploading" if status == "running" else status,
+                "current": 100 if status == "completed" else 40,
+                "total": 100,
+                "kind": "upload",
+                "destination": "/",
+                "created_at": now - 100,
+                "finished_at": now if status in ("completed", "cancelled") else None,
+                "error": "Transfer cancelled"
+                if status == "cancelled"
+                else "Unbroken_error_" + "details" * 40
+                if status == "error"
+                else None,
+                "location": {
+                    "available": True,
+                    "folder_path": "/",
+                    "folder_label": long_folder,
+                    "item_id": "exact",
+                    "display_path": long_folder + " / " + long_name,
+                },
+            }
+        )
+    page.route(
+        "**/api/v1/transfers/history/tasks",
+        lambda route: route.fulfill(
+            json={
+                "jobs": jobs,
+                "page": 1,
+                "page_size": 20,
+                "total_tasks": len(jobs),
+                "total_pages": 1,
+                "has_more": False,
+            }
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    history = page.get_by_role("region", name="Transfer History", exact=True)
+    expect(history.locator(".transfer-item")).to_have_count(5)
+    completed = history.locator(".transfer-item[data-status=completed]")
+    expect(completed.locator(".transfer-item-name")).to_have_attribute(
+        "title", long_name
+    )
+    expect(completed.locator(".transfer-location")).to_have_attribute(
+        "title", long_folder + " / " + long_name
+    )
+    for inactive_location in history.locator(
+        ".transfer-item:not([data-status=completed])"
+    ).all():
+        expect(
+            inactive_location.get_by_role("button", name="Show ", exact=False)
+        ).to_have_count(0)
+        inactive_location.locator(".transfer-item-name").dblclick()
+        expect(
+            page.get_by_role("heading", name="Transfers", exact=True)
+        ).to_be_visible()
+    cancelled = history.locator(".transfer-item[data-status=cancelled]")
+    expect(cancelled.locator(".transfer-item-actions button")).to_have_count(0)
+    expect(cancelled.locator(".transfer-error")).to_have_count(0)
+
+    for width in (1920, 1440, 1100, 768, 390, 320):
+        page.set_viewport_size({"width": width, "height": 1000})
+        page.emulate_media(color_scheme="dark" if width < 720 else "light")
+        page.wait_for_timeout(50)
+        assert page.evaluate(
+            "document.documentElement.scrollWidth <= window.innerWidth"
+        )
+        layout = completed.evaluate("""row => {
+          const rect = el => {
+            const r = el.getBoundingClientRect();
+            return {x:r.x,y:r.y,right:r.right,bottom:r.bottom,
+              width:r.width,height:r.height};
+          };
+          return {row:rect(row), name:rect(row.querySelector('.transfer-item-name')),
+            folder:rect(row.querySelector('.transfer-location')),
+            size:rect(row.querySelector('.transfer-bytes')),
+            date:rect(row.querySelector('time')),
+            actions:rect(row.querySelector('.transfer-item-actions'))};
+        }""")
+        for field in ("name", "folder", "size", "date", "actions"):
+            assert layout[field]["x"] >= layout["row"]["x"] - 1, (width, field, layout)
+            assert layout[field]["right"] <= layout["row"]["right"] + 1, (
+                width,
+                field,
+                layout,
+            )
+        if width >= 1440:
+            assert abs(layout["name"]["y"] - layout["folder"]["y"]) < 3
+            assert layout["name"]["right"] <= layout["folder"]["x"]
+            assert layout["folder"]["right"] <= layout["size"]["x"]
+            assert layout["size"]["right"] <= layout["date"]["x"]
+            assert layout["row"]["height"] <= 60
+        if width in (1920, 390):
+            page.screenshot(
+                path=ARTIFACTS / ("transfer-columns-" + str(width) + ".png"),
+                full_page=True,
+            )
+
+
+def test_original_file_recovery_action_is_inline_and_not_stacked(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    name = "Long original video filename " + "archive-" * 15 + ".mkv"
+    saved = [
+        {
+            "key": "recovery-layout",
+            "initiatedHere": True,
+            "name": name,
+            "size": 4500000000,
+            "lastModified": 0,
+            "destination": "/",
+            "state": "receiving",
+            "phase": "Sending from this device",
+            "current": 3900000000,
+            "total": 4500000000,
+            "createdAt": time.time() * 1000,
+        }
+    ]
+    page.add_init_script(
+        "localStorage.setItem('tgdrive.uploads.v2', "
+        + json.dumps(json.dumps(saved))
+        + ");"
+    )
+    login(page, server.url)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    item = page.locator(".transfer-item[data-status=awaiting_file]")
+    expect(item).to_be_visible()
+    action = item.get_by_role("button", name="Choose File", exact=True)
+    expect(
+        item.locator(".transfer-recovery").get_by_role("button", name="Choose File")
+    ).to_be_visible()
+    expect(item.locator(".transfer-item-actions button")).to_have_count(1)
+    expect(
+        item.locator(".transfer-item-actions").get_by_role(
+            "button", name="Cancel " + name
+        )
+    ).to_be_visible()
+    expect(
+        item.get_by_role("button", name="Show " + name + " in folder")
+    ).to_have_count(0)
+    for width in (1440, 390):
+        page.set_viewport_size({"width": width, "height": 960})
+        page.emulate_media(color_scheme="dark" if width == 1440 else "light")
+        expect(action).to_be_visible()
+        bounds = item.evaluate("""row => {
+          const r = el => {
+            const b=el.getBoundingClientRect();
+            return {x:b.x,y:b.y,right:b.right,bottom:b.bottom,height:b.height};
+          };
+          return {row:r(row), recovery:r(row.querySelector('.transfer-recovery')),
+            message:r(row.querySelector('.transfer-recovery-message')),
+            action:r(row.querySelector('.transfer-recovery-button')),
+            cancel:r(row.querySelector('.transfer-item-actions button'))};
+        }""")
+        assert bounds["action"]["right"] <= bounds["recovery"]["right"] + 1
+        assert bounds["cancel"]["y"] < bounds["action"]["bottom"]
+        assert page.evaluate(
+            "document.documentElement.scrollWidth <= window.innerWidth"
+        )
+        if width == 1440:
+            message_center = bounds["message"]["y"] + bounds["message"]["height"] / 2
+            action_center = bounds["action"]["y"] + bounds["action"]["height"] / 2
+            assert abs(message_center - action_center) <= 1
+        page.screenshot(
+            path=ARTIFACTS / ("transfer-recovery-" + str(width) + ".png"),
+            full_page=True,
+        )
+    with page.expect_file_chooser():
+        action.click()
+
+
+def test_ordinary_files_stay_separate_and_folder_headers_stay_compact(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    now = time.time() * 1000
+    saved = []
+    jobs = []
+    for batch_id, batch_name, count, folder, state in (
+        ("six-files", "6 files", 6, False, "completed"),
+        (
+            "photos",
+            "Photos from a long memorable holiday " + "album-" * 12,
+            3,
+            True,
+            "completed",
+        ),
+        ("one-folder", "Single document folder", 1, True, "completed"),
+        ("running-files", "2 files", 2, False, "uploading"),
+        ("needs-files", "3 files", 3, False, "awaiting_file"),
+    ):
+        for index in range(count):
+            identity = batch_id + "-" + str(index)
+            name = (
+                "Long filename " + "photo-" * 20
+                if folder
+                else batch_id + "-document-" + str(index)
+            ) + ".txt"
+            relative = (
+                batch_name + ("/nested/" if folder and index else "/") + name
+                if folder
+                else None
+            )
+            destination = (
+                "/photos/nested" if folder and index else "/photos" if folder else "/"
+            )
+            folder_upload = (
+                {
+                    "id": batch_id + "-folder-selection",
+                    "name": batch_name,
+                    "root_path": "/photos",
+                    "created_at": now / 1000,
+                }
+                if folder
+                else None
+            )
+            saved.append(
+                {
+                    "key": identity,
+                    "initiatedHere": True,
+                    **({"folderUpload": folder_upload} if folder_upload else {}),
+                    "jobId": identity if state != "awaiting_file" else None,
+                    "name": name,
+                    "size": 64 * 1024 * 1024,
+                    "lastModified": 0,
+                    "destination": destination,
+                    "relativePath": relative,
+                    "batchId": folder_upload["id"] if folder_upload else batch_id,
+                    "batchName": batch_name,
+                    "batchCreatedAt": now,
+                    "state": state,
+                    "phase": "Upload completed"
+                    if state == "completed"
+                    else "Choose the original file to resume"
+                    if state == "awaiting_file"
+                    else "Uploading to Telegram",
+                    "current": 64 * 1024 * 1024
+                    if state == "completed"
+                    else 30 * 1024 * 1024,
+                    "total": 64 * 1024 * 1024,
+                    "finishedAt": now if state == "completed" else None,
+                }
+            )
+            if state == "completed":
+                jobs.append(
+                    {
+                        "id": identity,
+                        "name": name,
+                        "destination": destination,
+                        **({"folder_upload": folder_upload} if folder_upload else {}),
+                        "status": "completed",
+                        "phase": "completed",
+                        "current": 64 * 1024 * 1024,
+                        "total": 64 * 1024 * 1024,
+                        "created_at": now / 1000 - 100,
+                        "finished_at": now / 1000,
+                        "location": {
+                            "available": True,
+                            "folder_path": destination,
+                            "folder_label": (
+                                "My Files / "
+                                + batch_name
+                                + (" / nested" if index else "")
+                            )
+                            if folder
+                            else "My Files",
+                            "item_id": identity,
+                            "display_path": name,
+                        },
+                    }
+                )
+    page.add_init_script(
+        "localStorage.setItem('tgdrive.uploads.v2', "
+        + json.dumps(json.dumps(saved))
+        + ");"
+    )
+
+    def task_history(route: Any) -> None:
+        payload = route.request.post_data_json
+        rows = jobs
+        total = len(
+            {
+                ("folder", job["folder_upload"]["id"])
+                if job.get("folder_upload")
+                else ("file", job["id"])
+                for job in rows
+            }
+        )
+        route.fulfill(
+            json={
+                "jobs": rows,
+                "page": payload["page"],
+                "page_size": 20,
+                "total_tasks": total,
+                "total_pages": 1,
+                "has_more": False,
+            }
+        )
+
+    page.route("**/api/v1/transfers/history/tasks", task_history)
+    login(page, server.url)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    history = page.get_by_role("region", name="Transfer History", exact=True)
+    multi = history.locator(".transfer-item").filter(
+        has=page.locator(".transfer-item-name", has_text="six-files-document-")
+    )
+    folder = history.locator(".transfer-batch").filter(
+        has=page.locator(
+            ".transfer-batch-name", has_text="Photos from a long memorable holiday"
+        )
+    )
+    single_folder = history.locator(".transfer-batch").filter(
+        has=page.locator(".transfer-batch-name", has_text="Single document folder")
+    )
+    expect(multi).to_have_count(6)
+    expect(history.locator(".transfer-batch")).to_have_count(2)
+    expect(folder.locator(".transfer-batch-count")).to_have_text("3 files")
+    expect(single_folder.locator(".transfer-batch-count")).to_have_text("1 file")
+    expect(multi.locator(".transfer-batch-status")).to_have_count(0)
+    expect(multi.locator(".transfer-history-time")).to_have_count(6)
+    expect(
+        history.locator(".transfer-item")
+        .filter(
+            has=page.locator(".transfer-item-name", has_text="running-files-document-")
+        )
+        .locator(".transfer-item-actions .icon-button[title='Show in Folder']")
+    ).to_have_count(0)
+    expect(
+        history.locator(".transfer-item")
+        .filter(
+            has=page.locator(".transfer-item-name", has_text="needs-files-document-")
+        )
+        .get_by_role("button", name="Choose File", exact=True)
+    ).to_have_count(3)
+    for width in (1920, 1440, 390, 320):
+        page.set_viewport_size({"width": width, "height": 1000})
+        page.emulate_media(color_scheme="dark" if width >= 1440 else "light")
+        if width >= 1440:
+            assert (
+                folder.locator(".transfer-batch-summary").bounding_box()["height"] <= 64
+            )
+        assert page.evaluate(
+            "document.documentElement.scrollWidth <= window.innerWidth"
+        )
+        assert history.locator(".transfer-batch-summary").evaluate_all("""
+          rows => rows.every(row => {
+          const b=row.getBoundingClientRect();
+          const selectors = ['button', '.transfer-batch-size',
+            '.transfer-batch-time', '.transfer-batch-location'].join(',');
+          return [...row.querySelectorAll(selectors)].every(el=>{
+            const r=el.getBoundingClientRect();return r.x>=b.x-1&&r.right<=b.right+1;
+          });
+        })""")
+    page.set_viewport_size({"width": 1440, "height": 1000})
+    page.emulate_media(color_scheme="dark")
+    location_requests = []
+
+    def locate_route(route):
+        location_requests.append(route.request.url)
+        route.fulfill(json={"available": True, "folder_path": "/photos"})
+
+    page.route("**/api/v1/transfers/location", locate_route)
+    folder.locator(".transfer-batch-name").dblclick(delay=30)
+    expect(
+        folder.get_by_role("button", name="Show Files", exact=True)
+    ).to_have_attribute("aria-expanded", "false")
+    assert location_requests == []
+    folder.get_by_role("button", name="Show Files", exact=True).click()
+    folder.get_by_role("button", name="Hide Files", exact=True).click()
+    assert location_requests == []
+    expect(page.get_by_role("heading", name="Transfers", exact=True)).to_be_visible()
+    expect(multi.get_by_role("button", name="Show Files", exact=True)).to_have_count(0)
+    expect(multi).to_have_count(6)
+    folder.get_by_role("button", name="Show Files", exact=True).click()
+    expect(folder.locator(".transfer-item")).to_have_count(3)
+    expect(
+        folder.locator(".transfer-batch-files .transfer-history-time")
+    ).to_have_count(0)
+    assert all(
+        not label.startswith("My Files")
+        for label in folder.locator(
+            ".transfer-child .transfer-location"
+        ).all_text_contents()
+    )
+    single_folder.get_by_role("button", name="Show Files", exact=True).click()
+    expect(single_folder.locator(".transfer-item")).to_have_count(1)
+    assert folder.locator(".transfer-child").evaluate_all("""rows => rows.every(row => {
+      const title = row.querySelector('.transfer-item-title').getBoundingClientRect();
+      const bytes = row.querySelector('.transfer-bytes').getBoundingClientRect();
+      return title.right <= bytes.left + 1;
+    })""")
+    folder.scroll_into_view_if_needed()
+    page.screenshot(path=ARTIFACTS / "compact-batches-desktop.png", full_page=True)
+    page.set_viewport_size({"width": 390, "height": 1000})
+    page.emulate_media(color_scheme="light")
+    assert page.evaluate("document.documentElement.scrollWidth <= window.innerWidth")
+    folder.scroll_into_view_if_needed()
+    page.screenshot(path=ARTIFACTS / "compact-batches-mobile.png", full_page=True)
+
+    folder.locator(".transfer-batch-locate").click()
+    assert len(location_requests) == 1
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+
+
+def test_shared_links_compact_views_copy_location_and_indicators(server, desktop):
+    context, page = desktop
+    login(page, server.url)
+    context.grant_permissions(["clipboard-read", "clipboard-write"], origin=server.url)
+    contents = page.request.post(
+        server.url + "/api/getDirectory", data={"path": "/"}
+    ).json()["data"]["contents"]
+    folder = next(item for item in contents.values() if item["name"] == "資料")
+    folder_path = "/" + folder["id"]
+    created = page.request.post(
+        server.url + "/api/v1/shares",
+        data={"path": folder_path, "expires_in_days": None},
+    ).json()
+    page.reload()
+    expect(page.get_by_label("Shared by Link", exact=True)).to_have_count(1)
+    page.get_by_role("button", name="資料", exact=True).dblclick()
+    expect(
+        page.get_by_label("Shared Through Parent Folder", exact=True).first
+    ).to_be_visible()
+    page.get_by_role("link", name="Shared Links", exact=True).click()
+    current = page.request.get(server.url + "/api/v1/shares").json()["shares"][0]
+    long_name = "Annual-report-" * 16 + ".pdf"
+    expired = dict(
+        current,
+        id="expired-fixture",
+        node_id="expired-node",
+        name=long_name,
+        type="file",
+        size=985000,
+        created_at="2020-01-01T10:00:00Z",
+        expires_at="2020-01-02T10:00:00Z",
+        folder_label="My Files / " + "A-long-directory-name/" * 16,
+    )
+    legacy = dict(
+        current,
+        id="legacy-fixture",
+        node_id="legacy-node",
+        path="/legacy-node",
+        name="Previous link.txt",
+        type="file",
+        size=42000,
+        copyable=False,
+    )
+    page.route(
+        "**/api/v1/shares",
+        lambda route: (
+            route.fulfill(json={"shares": [current, expired, legacy]})
+            if route.request.method == "GET"
+            else route.continue_()
+        ),
+    )
+    page.get_by_role("button", name="Refresh Shared Links", exact=True).click()
+    expect(page.locator(".share-row")).to_have_count(2)
+    active_row = page.locator(
+        ".share-row", has=page.get_by_role("button", name="資料", exact=True)
+    )
+    copy_button = active_row.locator(".share-copy")
+    expect(copy_button).to_have_text("")
+    copy_button.click()
+    expect(copy_button).to_have_attribute(
+        "aria-label", __import__("re").compile("^Link copied")
+    )
+    copied = page.evaluate("navigator.clipboard.readText()")
+    assert created["auth"] in copied and folder["id"] in copied
+    expect(page.get_by_text("Unnamed link", exact=False)).to_have_count(0)
+    unavailable_row = page.locator(".share-row").filter(has_text="Previous link.txt")
+    expect(unavailable_row.locator(".share-copy")).to_have_attribute(
+        "aria-disabled", "true"
+    )
+    expect(unavailable_row.locator(".share-copy")).to_be_disabled()
+    copy_requests = []
+    page.on(
+        "request",
+        lambda request: (
+            copy_requests.append(request.url)
+            if request.url.endswith("/api/v1/shares/link")
+            else None
+        ),
+    )
+    unavailable_control = unavailable_row.locator(".share-copy-control")
+    unavailable_control.focus()
+    expect(unavailable_control.get_by_role("tooltip")).to_have_text(
+        "Original link is unavailable; existing copies still work."
+    )
+    unavailable_control.press("Escape")
+    expect(unavailable_control).not_to_be_focused()
+    unavailable_control.click()
+    expect(unavailable_control).to_be_focused()
+    unavailable_row.locator(".share-copy").evaluate("button => button.click()")
+    expect(page.locator(".toast-error")).to_have_count(0)
+    assert not copy_requests
+    expect(page.get_by_role("button", name="New Link", exact=True)).to_have_count(0)
+    assert (
+        page.request.post(
+            server.url + "/api/getDirectory",
+            data={"path": "/share_" + folder["id"], "auth": created["auth"]},
+        ).status
+        == 200
+    )
+    page.get_by_role("button", name="All 3", exact=True).click()
+    expect(page.locator(".share-row")).to_have_count(3)
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    for theme in ("light", "dark"):
+        page.evaluate(
+            "(theme) => { localStorage.setItem('tgdrive.appearance', theme);"
+            "document.documentElement.dataset.theme = theme; }",
+            theme,
+        )
+        for width in (1440, 390, 320):
+            page.set_viewport_size(
+                {"width": width, "height": 960 if width > 600 else 844}
+            )
+            assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+            assert page.locator(".share-row").evaluate_all(
+                "rows => rows.every(row => row.scrollWidth <= row.clientWidth + 1)"
+            )
+            if width in (1440, 390):
+                page.screenshot(
+                    path=str(ARTIFACTS / f"shared-links-{theme}-{width}.png")
+                )
+    page.set_viewport_size({"width": 1440, "height": 960})
+    page.get_by_role("button", name="Expired 1", exact=True).click()
+    expect(page.locator(".share-row")).to_have_count(1)
+    expect(page.locator(".share-row .share-copy")).to_have_attribute(
+        "aria-disabled", "true"
+    )
+    expect(page.locator(".share-row .share-copy")).to_be_disabled()
+    expect(page.get_by_role("button", name="New Link", exact=True)).to_have_count(0)
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    page.get_by_role("button", name="Active 2", exact=True).click()
+    page.get_by_role("button", name="Show 資料 in folder", exact=True).click()
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    expect(
+        page.locator("tr", has=page.get_by_role("button", name="資料", exact=True))
+    ).to_have_class(__import__("re").compile("selected"))
+    page.get_by_role("link", name="Shared Links", exact=True).click()
+    page.get_by_role("button", name="Revoke Link for 資料", exact=True).click()
+    page.get_by_role("dialog").get_by_role("button", name="Cancel", exact=True).click()
+    assert (
+        page.request.post(
+            server.url + "/api/getDirectory",
+            data={"path": "/share_" + folder["id"], "auth": created["auth"]},
+        ).status
+        == 200
+    )
+    page.get_by_role("button", name="Revoke Link for 資料", exact=True).click()
+    page.get_by_role("button", name="Revoke Link", exact=True).click()
+    expect(page.get_by_role("dialog")).to_have_count(0)
+    assert (
+        page.request.post(
+            server.url + "/api/getDirectory",
+            data={"path": "/share_" + folder["id"], "auth": created["auth"]},
+        ).status
+        == 403
+    )
+
+
+def test_mobile_navigation_traps_focus_closes_and_restores_trigger(server, desktop):
+    _, page = desktop
+    page.set_viewport_size({"width": 390, "height": 844})
+    login(page, server.url)
+    trigger = page.get_by_role("button", name="Toggle Navigation", exact=True)
+    trigger.click()
+    navigation = page.get_by_role("dialog", name="Drive navigation", exact=True)
+    expect(navigation).to_be_visible()
+    expect(page.locator("#main-content")).to_have_attribute("inert", "")
+    for _ in range(12):
+        page.keyboard.press("Tab")
+        assert navigation.evaluate("(node)=>node.contains(document.activeElement)")
+    page.keyboard.press("Escape")
+    expect(navigation).to_have_count(0)
+    expect(trigger).to_be_focused()
+    trigger.click()
+    page.get_by_role("button", name="Close Navigation", exact=True).first.click()
+    expect(trigger).to_be_focused()
+    trigger.click()
+    page.set_viewport_size({"width": 1440, "height": 960})
+    page.set_viewport_size({"width": 390, "height": 844})
+    expect(trigger).to_have_attribute("aria-expanded", "false")
+
+
+def test_selection_mixed_state_and_next_page_scroll_position(server, desktop):
+    _, page = desktop
+    page.set_viewport_size({"width": 390, "height": 844})
+    contents = {
+        f"entry-{index}": {
+            "id": f"entry-{index}",
+            "path": "/",
+            "type": "file",
+            "name": f"{index:03d} " + "資料-😀-very-long-filename-" * 10 + ".pdf",
+            "size": 12345678,
+            "upload_date": "2026-10-17",
+        }
+        for index in range(105)
+    }
+    page.route(
+        "**/api/getDirectory",
+        lambda route: route.fulfill(
+            json={"status": "ok", "data": {"name": "/", "contents": contents}}
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Select", exact=True).click()
+    checkbox = page.get_by_role(
+        "checkbox", name="Select All Files on This Page", exact=True
+    )
+    page.locator("tbody input[type=checkbox]").first.check()
+    assert checkbox.evaluate("(input)=>input.indeterminate")
+    target = checkbox.locator("..").bounding_box()
+    assert target["width"] >= 44 and target["height"] >= 44
+    page.get_by_role("button", name="Next Page", exact=True).click()
+    expect(page.locator("tbody .file-name").first).to_have_text(
+        contents["entry-100"]["name"]
+    )
+    page.wait_for_function("document.querySelector('.workspace').scrollTop < 5")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+
+
+def test_history_and_shares_failed_loads_have_retry_without_false_empty_state(
+    server, desktop
+):
+    _, page = desktop
+    failing = {"history": True, "shares": True}
+
+    def history(route):
+        if failing["history"]:
+            route.fulfill(
+                status=503, json={"detail": "History temporarily unavailable"}
+            )
+        else:
+            route.fulfill(
+                json={
+                    "jobs": [],
+                    "page": 1,
+                    "page_size": 20,
+                    "total_tasks": 0,
+                    "total_pages": 1,
+                    "has_more": False,
+                }
+            )
+
+    def shares(route):
+        if failing["shares"]:
+            route.fulfill(
+                status=503, json={"detail": "Shared links temporarily unavailable"}
+            )
+        else:
+            route.fulfill(json={"shares": []})
+
+    page.route("**/api/v1/transfers/history/tasks", history)
+    page.route("**/api/v1/shares", shares)
+    login(page, server.url)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    expect(page.get_by_role("button", name="Try Again", exact=True)).to_be_visible()
+    expect(
+        page.get_by_role("heading", name="No Finished Transfers Yet", exact=True)
+    ).to_have_count(0)
+    failing["history"] = False
+    page.get_by_role("button", name="Try Again", exact=True).click()
+    expect(
+        page.get_by_role("heading", name="No Finished Transfers Yet", exact=True)
+    ).to_be_visible()
+    page.get_by_role("link", name="Shared Links", exact=True).click()
+    expect(page.get_by_role("button", name="Try Again", exact=True)).to_be_visible()
+    failing["shares"] = False
+    page.get_by_role("button", name="Try Again", exact=True).click()
+    expect(
+        page.get_by_role("heading", name="No Active Shared Links", exact=True)
+    ).to_be_visible()
+
+
+def test_revoke_failure_stays_in_dialog_and_management_drops_do_not_upload(
+    server, desktop
+):
+    _, page = desktop
+
+    def share_route(route):
+        if route.request.method == "DELETE":
+            route.fulfill(
+                status=503, json={"detail": "Could not revoke this link. Try again."}
+            )
+        else:
+            route.fulfill(
+                json={
+                    "shares": [
+                        {
+                            "id": "audit-share",
+                            "node_id": "audit-item",
+                            "path": "/audit-item",
+                            "name": "A shared item",
+                            "folder_path": "/",
+                            "folder_label": "My Files",
+                            "type": "file",
+                            "size": 10,
+                            "created_at": "2026-10-17T00:00:00Z",
+                            "expires_at": None,
+                            "copyable": True,
+                        }
+                    ]
+                }
+            )
+
+    page.route("**/api/v1/shares", share_route)
+    login(page, server.url)
+    page.get_by_role("link", name="Shared Links", exact=True).click()
+    page.get_by_role("button", name="Revoke Link for A shared item", exact=True).click()
+    dialog = page.get_by_role("dialog", name="Revoke This Link?", exact=True)
+    dialog.get_by_role("button", name="Revoke Link", exact=True).click()
+    expect(dialog.get_by_role("alert")).to_have_text(
+        "Could not revoke this link. Try again."
+    )
+    dialog.get_by_role("button", name="Cancel", exact=True).click()
+    expect(dialog).to_have_count(0)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    requests = []
+    page.on(
+        "request",
+        lambda request: (
+            requests.append(request.url)
+            if request.method == "POST" and request.url.endswith("/api/v1/uploads")
+            else None
+        ),
+    )
+    page.locator("#main-content").evaluate("""element => {
+      const data = new DataTransfer();
+      data.items.add(new File(['data'], 'must-not-upload.txt'));
+      element.dispatchEvent(new DragEvent('drop', {
+        bubbles:true, cancelable:true, dataTransfer:data
+      }));
+    }""")
+    expect(page.get_by_role("alert")).to_contain_text(
+        "Open a folder in My Files before dropping files."
+    )
+    assert requests == []
diff --git a/tests/browser/test_browser_file_views.py b/tests/browser/test_browser_file_views.py
new file mode 100644
index 00000000..c8c94b35
--- /dev/null
+++ b/tests/browser/test_browser_file_views.py
@@ -0,0 +1,317 @@
+"""Sorting, grid browsing and lazy provider thumbnails on the production bundle."""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login
+
+browser = fixtures.browser
+desktop = fixtures.desktop
+server = fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+def choose_view(page, name):
+    compact = page.get_by_role("button", name="View and sort", exact=True)
+    if compact.count():
+        compact.click()
+        page.get_by_role("menuitemradio", name=name, exact=True).click()
+    else:
+        page.get_by_role("button", name=name, exact=True).click()
+
+
+@pytest.mark.parametrize("width", [1440, 390, 320])
+def test_grid_views_preserve_selection_actions_and_bounded_thumbnails(
+    server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    thumbnails = []
+    originals = []
+    page.on(
+        "request",
+        lambda request: (
+            thumbnails.append(request.url)
+            if "/api/v1/thumbnail?" in request.url
+            else originals.append(request.url)
+            if urlparse(request.url).path == "/file"
+            else None
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    expect(page.get_by_role("button", name="sample.png", exact=True)).to_be_visible()
+    expect(page.locator(".file-table thead")).to_be_visible()
+    assert thumbnails == []
+    choose_view(page, "Grid view")
+    grid = page.get_by_role("list", name="Files and folders", exact=True)
+    expect(grid).to_be_visible()
+    if width > 720:
+        expect(page.get_by_role("button", name="Grid view")).to_have_attribute(
+            "aria-pressed", "true"
+        )
+    page.locator(".file-grid .file-row").filter(
+        has_text="sample.png"
+    ).scroll_into_view_if_needed()
+    expect(
+        page.locator(".file-grid .file-row")
+        .filter(has_text="sample.png")
+        .locator(".file-tile-preview img")
+    ).to_be_visible()
+    assert thumbnails and not originals
+    page.get_by_role("button", name="Select", exact=True).click()
+    page.get_by_role("checkbox", name="Select sample.png", exact=True).check()
+    expect(page.get_by_text("1 selected", exact=True)).to_be_visible()
+    page.get_by_role(
+        "checkbox", name="Select All Files on This Page", exact=True
+    ).check()
+    expect(page.get_by_text("16 selected", exact=True)).to_be_visible()
+    page.get_by_role("button", name="Done", exact=True).click()
+    page.locator('summary[aria-label="Actions for sample.png"]').click()
+    expect(page.get_by_role("button", name="Rename", exact=True)).to_be_visible()
+    page.keyboard.press("Escape")
+    page.reload()
+    expect(page.get_by_role("list", name="Files and folders")).to_be_visible()
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(path=ARTIFACTS / f"grid-files-{width}.png")
+    choose_view(page, "List view")
+    expect(page.locator(".file-table thead")).to_be_visible()
+
+
+def test_sort_direction_and_trash_original_location_work_in_both_views(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    contents = page.request.post(
+        server.url + "/api/getDirectory", data={"path": "/"}
+    ).json()["data"]["contents"]
+    source = next(x for x in contents.values() if x["name"] == "Preview samples")
+    response = page.request.post(
+        server.url + "/api/createNewFolder",
+        data={"path": "/" + source["id"], "name": "Nested trash"},
+    )
+    assert response.ok
+    nested = page.request.post(
+        server.url + "/api/getDirectory", data={"path": "/" + source["id"]}
+    ).json()["data"]["contents"]
+    target = next(x for x in nested.values() if x["name"] == "Nested trash")
+    assert page.request.post(
+        server.url + "/api/trashFileFolder",
+        data={"path": "/" + source["id"] + "/" + target["id"], "trash": True},
+    ).ok
+    page.get_by_role("link", name="Trash", exact=True).click()
+    expect(
+        page.get_by_text("Deleted from: My Files / Preview samples", exact=True)
+    ).to_be_visible()
+    choose_view(page, "Grid view")
+    expect(
+        page.get_by_text("Deleted from: My Files / Preview samples", exact=True)
+    ).to_be_visible()
+    page.get_by_role("link", name="My Files", exact=True).click()
+    choose_view(page, "List view")
+    page.get_by_role("button", name="Sort Files: Name", exact=True).click()
+    page.get_by_role("menuitemradio", name="Descending", exact=True).click()
+    names = page.locator(".file-table .item-name-button").all_text_contents()
+    assert names == sorted(names, key=str.casefold, reverse=True)
+    page.get_by_role("button", name="Sort by Name", exact=True).click()
+    expect(page.locator(".file-table th").first).to_have_attribute(
+        "aria-sort", "ascending"
+    )
+    search = page.get_by_role("searchbox", name="Search Files and Folders", exact=True)
+    search.fill("sample")
+    expect(
+        page.get_by_role("heading", name="Search Results", exact=True)
+    ).to_be_visible()
+    page.get_by_role("button", name="Sort Files: Name", exact=True).click()
+    with page.expect_response(
+        lambda response: (
+            "/api/v1/search?" in response.url
+            and parse_qs(urlparse(response.url).query).get("order") == ["desc"]
+        )
+    ):
+        page.get_by_role("menuitemradio", name="Descending", exact=True).click()
+    choose_view(page, "Grid view")
+    expect(page.get_by_role("list", name="Files and folders")).to_be_visible()
+
+
+@pytest.mark.parametrize("view", ["overview", "telegram", "server"])
+def test_performance_content_separates_from_toolbar(server, desktop, view):
+    _, page = desktop
+    login(page, server.url + "/?view=performance")
+    label = {"overview": "Overview", "telegram": "Accounts", "server": "Resources"}[
+        view
+    ]
+    page.get_by_role("tab", name=label, exact=True).click()
+    panel = page.locator("#performance-panel-" + view)
+    expect(panel).to_be_visible()
+    gap = page.evaluate("""() => {
+      const toolbar=document.querySelector('.performance-toolbar')
+        .getBoundingClientRect();
+      const next=document.querySelector(
+        '.performance-history-availability:not([hidden])') ||
+        document.querySelector('.performance-accounts-grid:not([hidden])');
+      return next.getBoundingClientRect().top-toolbar.bottom;
+    }""")
+    assert gap >= 15
+
+
+@pytest.mark.parametrize("width", [390, 320])
+def test_mobile_header_stays_compact_and_search_and_view_controls_work(
+    server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url)
+    expect(page.get_by_role("button", name="View and sort", exact=True)).to_be_visible()
+    assert page.locator(".file-toolbar").bounding_box()["height"] <= 70
+    search = page.get_by_role("searchbox", name="Search Files and Folders", exact=True)
+    expect(search).not_to_be_visible()
+    page.get_by_role("button", name="Search Files and Folders", exact=True).click()
+    expect(search).to_be_focused()
+    search.press("Escape")
+    expect(search).not_to_be_visible()
+    expect(
+        page.get_by_role("button", name="Search Files and Folders", exact=True)
+    ).to_be_focused()
+    page.keyboard.press("Control+k")
+    expect(search).to_be_focused()
+    search.press("Escape")
+    choose_view(page, "Grid view")
+    expect(page.get_by_role("list", name="Files and folders")).to_be_visible()
+    page.get_by_role("button", name="View and sort", exact=True).click()
+    menu = page.get_by_role("menu", name="View and sort", exact=True)
+    expect(
+        menu.get_by_role("menuitemradio", name="Grid view", exact=True)
+    ).to_have_attribute("aria-checked", "true")
+    bounds = menu.bounding_box()
+    assert bounds["x"] >= 0 and bounds["x"] + bounds["width"] <= width
+    assert bounds["y"] >= 0 and bounds["y"] + bounds["height"] <= 844
+    page.keyboard.press("End")
+    expect(
+        menu.get_by_role("menuitemradio", name="Descending", exact=True)
+    ).to_be_focused()
+    page.keyboard.press("Escape")
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+
+
+def test_grid_respects_data_saver(server, desktop):
+    _, page = desktop
+    page.add_init_script(
+        "Object.defineProperty(navigator, 'connection', "
+        "{value:{saveData:true},configurable:true})"
+    )
+    requests = []
+    page.on(
+        "request",
+        lambda request: (
+            requests.append(request.url)
+            if "/api/v1/thumbnail?" in request.url
+            else None
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    choose_view(page, "Grid view")
+    expect(page.get_by_role("list", name="Files and folders")).to_be_visible()
+    expect(page.locator(".file-tile-preview img")).to_have_count(0)
+    page.get_by_role("button", name="sample.png", exact=True).focus()
+    assert not requests
+
+
+@pytest.mark.parametrize(
+    "width,theme", [(1440, "light"), (390, "dark"), (320, "light")]
+)
+def test_item_status_is_quiet_metadata_without_interrupting_names(
+    server, desktop, width, theme
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    page.emulate_media(color_scheme=theme)
+    login(page, server.url)
+    contents = page.request.post(
+        server.url + "/api/getDirectory", data={"path": "/"}
+    ).json()["data"]["contents"]
+    target = next(
+        item for item in contents.values() if item["name"] == "Preview samples"
+    )
+    path = "/" + target["id"]
+    assert page.request.patch(
+        server.url + "/api/v1/starred", data={"path": path, "starred": True}
+    ).ok
+    assert page.request.post(
+        server.url + "/api/v1/shares", data={"path": path, "expires_in_days": 7}
+    ).ok
+    page.reload()
+    row = page.locator(".file-row").filter(
+        has=page.get_by_role("button", name="Preview samples", exact=True)
+    )
+    status = row.locator(".file-item-status")
+    expect(status).to_have_text("StarredShared")
+    expect(status.locator("svg")).to_have_count(0)
+    expect(status.get_by_label("Shared by Link", exact=True)).to_have_text("Shared")
+    name = row.locator(".file-name").bounding_box()
+    state = status.bounding_box()
+    assert name and state
+    if width > 720:
+        assert state["x"] >= name["x"] + name["width"]
+    else:
+        assert state["y"] >= name["y"] + name["height"] - 1
+    height = row.bounding_box()["height"]
+    sibling = page.locator(".file-row").filter(
+        has=page.get_by_role("button", name="Private folder", exact=True)
+    )
+    assert abs(height - sibling.bounding_box()["height"]) <= 1
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(
+        path=ARTIFACTS / f"item-status-list-{theme}-{width}.png",
+        animations="disabled",
+    )
+    choose_view(page, "Grid view")
+    expect(status).to_be_visible()
+    assert status.evaluate("e => e.scrollWidth <= e.clientWidth + 1")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(
+        path=ARTIFACTS / f"item-status-grid-{theme}-{width}.png",
+        animations="disabled",
+    )
+
+
+@pytest.mark.parametrize("width,view", [(1440, "Grid view"), (390, "List view")])
+def test_escape_selection_returns_focus_to_file_control_not_workspace(
+    server, desktop, width, view
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url)
+    choose_view(page, view)
+    page.get_by_role("button", name="Select", exact=True).click()
+    checkbox = page.get_by_role("checkbox", name="Select Preview samples", exact=True)
+    checkbox.check()
+    expect(page.get_by_text("1 selected", exact=True)).to_be_visible()
+    checkbox.focus()
+    page.keyboard.press("Escape")
+    item = page.get_by_role("button", name="Preview samples", exact=True)
+    expect(item).to_be_focused()
+    expect(page.locator(".file-row.selected")).to_have_count(0)
+    expect(page.locator(".file-list-scroll")).not_to_be_focused()
+    assert not page.locator(".file-list-scroll").evaluate(
+        "e => e.matches(':focus-visible')"
+    )
+    assert item.evaluate("e => e.matches(':focus-visible')")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(
+        path=ARTIFACTS / f"selection-escape-focus-{width}.png", animations="disabled"
+    )
+    item.press("Enter")
+    expect(
+        page.get_by_role("heading", name="Preview samples", exact=True)
+    ).to_be_visible()
diff --git a/tests/browser/test_browser_history_ui.py b/tests/browser/test_browser_history_ui.py
new file mode 100644
index 00000000..cdb439f5
--- /dev/null
+++ b/tests/browser/test_browser_history_ui.py
@@ -0,0 +1,277 @@
+"""Recorded ranges and real-sample inspection in the production charts."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import time
+from datetime import UTC, datetime
+from urllib.parse import parse_qs, urlparse
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import expect, login
+
+browser = fixtures.browser
+desktop = fixtures.desktop
+server = fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+def history_result(start, end, *, empty=False):
+    start, end = int(start // 60 * 60), int(end // 60 * 60)
+    bucket = max(60, int((end - start + 359) // 360 // 60 + 1) * 60)
+    samples = [
+        {
+            "at": at,
+            "end_at": min(at + bucket, end),
+            "cpu_percent": None if empty or index == 3 else 10 + index % 40,
+            "cpu_scope": "cgroup",
+            "memory_bytes": None if empty else 1024**3,
+            "memory_limit_bytes": 8 * 1024**3,
+            "received_bytes_per_second": None if empty or index == 3 else 1024**2,
+            "sent_bytes_per_second": None if empty or index == 3 else 2 * 1024**2,
+            "network_interface": "eth0",
+            "coverage_seconds": {},
+        }
+        for index, at in enumerate(range(start, end, bucket))
+    ]
+    return {
+        "start": start,
+        "end": end,
+        "bucket_seconds": bucket,
+        "samples": samples,
+        "retention_seconds": 31 * 86400,
+        "earliest_at": None if empty else start,
+        "tracked_since": start,
+        "last_updated": end,
+        "available": True,
+        "totals": {
+            "network_received_bytes": 5 * 1024**3,
+            "network_sent_bytes": 2 * 1024**3,
+            "http_download_bytes": 1024**3,
+            "http_upload_bytes": 1024**2,
+            "http_requests": 100,
+            "http_errors": 0,
+            "telegram_download_bytes": None,
+            "telegram_upload_bytes": 3 * 1024**3,
+        },
+    }
+
+
+def install_live_snapshot(page, server):
+    login(page, server.url)
+    snapshot = page.request.get(server.url + "/api/v1/performance").json()
+    now = int(time.time())
+    snapshot["server"]["cpu"] = {"percent": 70, "scope": "cgroup", "capacity_cores": 4}
+    snapshot["server"]["history"] = [
+        {
+            **history_result(now - 300, now)["samples"][0],
+            "at": now - (2 - index) * 3,
+            "cpu_percent": 40 + index * 15,
+        }
+        for index in range(3)
+    ]
+    page.route("**/api/v1/performance", lambda route: route.fulfill(json=snapshot))
+
+
+def query_bounds(route):
+    values = parse_qs(urlparse(route.request.url).query)
+    return float(values["start"][0]), float(values["end"][0])
+
+
+def test_history_interval_hover_keyboard_poll_and_persisted_selection(server, desktop):
+    _, page = desktop
+    install_live_snapshot(page, server)
+    requests = []
+
+    def recorded(route):
+        start, end = query_bounds(route)
+        requests.append((start, end))
+        route.fulfill(json=history_result(start, end))
+
+    page.route("**/api/v1/performance/history?*", recorded)
+    page.goto(server.url + "/?view=performance")
+    interval = page.get_by_role("combobox", name="Time range", exact=True)
+    expect(interval).to_have_value("live")
+    page.get_by_role("tab", name="Resources", exact=True).click()
+    cpu = page.get_by_role("region", name="Container CPU", exact=True)
+    slider = cpu.get_by_role("slider", name="Inspect Container CPU samples")
+    expect(slider).to_have_attribute("max", "2")
+    interval.select_option("hour")
+    expect(page.locator(".performance-history-availability")).to_contain_text(
+        "Recorded interval averages"
+    )
+    expect(slider).to_have_attribute("max", "59")
+    expect(cpu.locator("polyline.performance-plot-active")).to_have_count(2)
+    for name, tab in [("Network traffic", "Overview"), ("Container RAM", "Resources")]:
+        page.get_by_role("tab", name=tab, exact=True).click()
+        expect(
+            page.get_by_role("region", name=name, exact=True).get_by_role("slider")
+        ).to_have_attribute("max", "59")
+    expect(cpu.locator(".performance-chart-heading")).to_contain_text("70.0%Now")
+    page.get_by_role("tab", name="Overview", exact=True).click()
+    expect(page.locator(".performance-chart-legend")).to_contain_text(
+        "Download to server"
+    )
+    expect(page.locator(".performance-chart-legend")).to_contain_text(
+        "Upload from server"
+    )
+    page.get_by_role("tab", name="Overview", exact=True).click()
+    expect(page.get_by_role("heading", name="All-time totals")).to_be_visible()
+    expect(page.locator(".performance-all-time")).to_contain_text("5 GB")
+    expect(page.locator(".performance-all-time")).to_contain_text("Not available")
+    page.get_by_role("tab", name="Resources", exact=True).click()
+    plot = cpu.get_by_role("img", name="Container CPU over time", exact=True)
+    cpu.scroll_into_view_if_needed()
+    bounds = plot.bounding_box()
+    page.mouse.move(bounds["x"] + bounds["width"] * 0.251, bounds["y"] + 10)
+    expect(cpu.locator(".performance-chart-tooltip")).to_be_visible()
+    # Nearest real bucket is index 15, not an interpolated 24.809 value.
+    expect(cpu.locator(".performance-chart-readout")).to_contain_text("25.0%")
+    page.screenshot(path=fixtures.ARTIFACTS / "history-hover-desktop.png")
+    page.mouse.move(0, 0)
+    expect(cpu.locator(".performance-chart-tooltip")).to_have_count(0)
+    expect(cpu.locator(".performance-chart-readout")).to_contain_text("29.0%")
+    slider.focus()
+    slider.press("Home")
+    expect(cpu.locator(".performance-chart-readout")).to_contain_text("10.0%")
+    page.mouse.move(bounds["x"] + bounds["width"] * 0.251, bounds["y"] + 10)
+    page.mouse.move(0, 0)
+    expect(cpu.locator(".performance-chart-readout")).to_contain_text("10.0%")
+    before = len(requests)
+    page.get_by_role("button", name="Refresh Performance", exact=True).click()
+    expect(interval).to_have_value("hour")
+    expect(slider).to_have_attribute("max", "59")
+    page.wait_for_function(
+        "() => !document.querySelector('.performance-history-status')"
+    )
+    assert len(requests) > before
+    page.reload()
+    page.get_by_role("tab", name="Resources", exact=True).click()
+    expect(interval).to_have_value("hour")
+    expect(slider).to_have_attribute("max", "59")
+    assert requests[-1][1] - requests[-1][0] == 3600
+    for tab, description in [
+        ("Accounts", "Live account activity and current limits."),
+    ]:
+        page.get_by_role("tab", name=tab, exact=True).click()
+        expect(interval).not_to_be_visible()
+        expect(page.get_by_text(description, exact=True)).to_be_visible()
+        expect(page.locator(".performance-history-availability")).not_to_be_visible()
+    page.get_by_role("tab", name="Resources", exact=True).click()
+    expect(interval).to_be_visible()
+    expect(interval).to_have_value("hour")
+    expect(cpu).to_be_visible()
+    page.get_by_role("tab", name="Overview", exact=True).click()
+    expect(interval).to_be_visible()
+    expect(interval).to_have_value("hour")
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.get_by_role(
+        "heading", name="Performance", exact=True
+    ).scroll_into_view_if_needed()
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    assert interval.bounding_box()["x"] + interval.bounding_box()["width"] <= 382
+    page.screenshot(path=fixtures.ARTIFACTS / "history-range-mobile.png")
+
+
+def test_custom_history_is_absolute_utc_and_stale_fetch_cannot_replace_new_range(
+    server, desktop
+):
+    _, page = desktop
+    install_live_snapshot(page, server)
+    held = []
+    requests = []
+    fail = False
+
+    def recorded(route):
+        start, end = query_bounds(route)
+        requests.append((start, end))
+        if end - start == 86400:
+            held.append(route)
+        elif fail:
+            route.fulfill(
+                status=503, json={"detail": "Recorded history is unavailable"}
+            )
+        else:
+            route.fulfill(json=history_result(start, end, empty=end - start > 86400))
+
+    page.route("**/api/v1/performance/history?*", recorded)
+    page.goto(server.url + "/?view=performance")
+    interval = page.get_by_role("combobox", name="Time range", exact=True)
+    interval.select_option("day")
+    expect(page.get_by_text("Loading selected history…", exact=False)).to_be_visible()
+    interval.select_option("week")
+    expect(page.locator(".performance-history-availability")).to_contain_text(
+        "No readings were recorded"
+    )
+    assert held
+    with contextlib.suppress(fixtures.playwright.Error):
+        held[0].fulfill(json=history_result(*requests[-2]))
+    expect(interval).to_have_value("week")
+    expect(
+        page.get_by_text("No recorded readings in this range.", exact=True)
+    ).to_have_count(3)
+    interval.select_option("custom")
+    page.set_viewport_size({"width": 320, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    assert interval.bounding_box()["x"] + interval.bounding_box()["width"] <= 312
+    start = datetime.fromtimestamp(time.time() - 7200, UTC).strftime("%Y-%m-%dT%H:%M")
+    end = datetime.fromtimestamp(time.time() - 3600, UTC).strftime("%Y-%m-%dT%H:%M")
+    page.get_by_label("Start (UTC)", exact=True).fill(start)
+    page.get_by_label("End (UTC)", exact=True).fill(end)
+    page.get_by_role("button", name="Apply Range", exact=True).click()
+    expect(page.get_by_text("Applied:", exact=False)).to_be_visible()
+    expect(page.locator(".performance-history-availability")).to_contain_text(
+        "Recorded interval averages"
+    )
+    expected = tuple(
+        datetime.fromisoformat(value).replace(tzinfo=UTC).timestamp()
+        for value in [start, end]
+    )
+    assert requests[-1] == expected
+    page.get_by_role("button", name="Refresh Performance", exact=True).click()
+    page.wait_for_function(
+        "() => !document.querySelector('.performance-history-status')"
+    )
+    assert requests[-1] == expected
+    fail = True
+    interval.select_option("hour")
+    expect(page.locator(".performance-history-error")).to_contain_text(
+        "Showing previously loaded history"
+    )
+    fail = False
+    page.get_by_role("button", name="Retry History", exact=True).click()
+    expect(page.locator(".performance-history-error")).to_have_count(0)
+    expect(interval).to_have_value("hour")
+
+
+def test_recorded_history_page_uses_real_private_history_endpoint(server, desktop):
+    _, page = desktop
+    login(page, server.url + "/?view=performance")
+    page.get_by_role("combobox", name="Time range", exact=True).select_option("hour")
+    expect(page.locator(".performance-history-availability")).to_contain_text(
+        "Recorded interval averages"
+    )
+    expect(page.locator(".performance-history-error")).to_have_count(0)
+    expect(
+        page.get_by_role("heading", name="All-time totals", exact=True)
+    ).to_be_visible()
+    expect(page.locator(".performance-all-time")).to_contain_text(
+        "independent of the time range"
+    )
+    end = int(time.time())
+    response = page.request.get(
+        server.url + f"/api/v1/performance/history?start={end - 3600}&end={end}"
+    )
+    assert response.status == 200
+    value = response.json()
+    assert value["available"] is True
+    assert 0 < len(value["samples"]) <= 360
+    assert value["bucket_seconds"] >= 60
+    assert value["retention_seconds"] == 31 * 86400
+    assert "network_received_bytes" in value["totals"]
diff --git a/tests/browser/test_browser_mobile_interactions.py b/tests/browser/test_browser_mobile_interactions.py
new file mode 100644
index 00000000..d04690a3
--- /dev/null
+++ b/tests/browser/test_browser_mobile_interactions.py
@@ -0,0 +1,391 @@
+"""Phone activation, selection geometry and reachable controls in real Chromium.
+
+Uses the isolated offline browser fixture. To check a running Vite build, set
+TGDRIVE_MOBILE_UI_URL=http://127.0.0.1:5173; API traffic still uses that fixture.
+"""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import urlsplit
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login
+
+browser, server = fixtures.browser, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+def open_fixture(page, server, suffix=""):
+    url = os.environ.get("TGDRIVE_MOBILE_UI_URL", server.url)
+    if url != server.url:
+
+        def forward(route):
+            requested = urlsplit(route.request.url)
+            headers = dict(route.request.headers)
+            if "origin" in headers:
+                headers["origin"] = server.url
+            if "referer" in headers:
+                headers["referer"] = server.url + "/"
+            response = route.fetch(
+                url=server.url
+                + requested.path
+                + ("?" + requested.query if requested.query else ""),
+                headers=headers,
+            )
+            route.fulfill(response=response)
+
+        page.route("**/api/**", forward)
+        page.route("**/file?*", forward)
+    login(page, url + suffix)
+    return url
+
+
+def assert_bounded(page, selector):
+    for element in page.locator(selector).all():
+        if not element.is_visible():
+            continue
+        bounds = element.bounding_box()
+        assert bounds["x"] >= -1, (selector, bounds)
+        assert bounds["x"] + bounds["width"] <= page.viewport_size["width"] + 1, (
+            selector,
+            bounds,
+        )
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+
+
+def geometry(page, name):
+    return page.get_by_role("button", name=name, exact=True).evaluate("""element => {
+      const rect = element.getBoundingClientRect();
+      let y = rect.top;
+      for (let parent = element.parentElement; parent; parent = parent.parentElement)
+        y += parent.scrollTop;
+      return { x: rect.left, y, height: rect.height };
+    }""")
+
+
+def assert_stable(before, after, dimensions=("x", "y", "height")):
+    for dimension in dimensions:
+        assert abs(before[dimension] - after[dimension]) <= 1, (before, after)
+
+
+def choose_view(page, label):
+    compact = page.get_by_role("button", name="View and sort", exact=True)
+    if compact.is_visible():
+        compact.tap()
+        page.get_by_role("menuitemradio", name=label, exact=True).tap()
+    else:
+        page.get_by_role("button", name=label, exact=True).tap()
+
+
+@pytest.mark.parametrize(
+    "width,height",
+    [
+        (320, 640),
+        (360, 740),
+        (390, 844),
+        (430, 932),
+        (740, 360),
+        (1440, 900),
+    ],
+)
+def test_single_tap_and_selection_keep_file_positions_stable(
+    server, browser, width, height
+):
+    context = browser.new_context(
+        viewport={"width": width, "height": height},
+        has_touch=True,
+        is_mobile=width < 800,
+    )
+    page = context.new_page()
+    errors = []
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    try:
+        open_fixture(page, server)
+        folder = page.get_by_role("button", name="Preview samples", exact=True)
+        folder_row = page.locator(".file-row").filter(has=folder)
+        expect(folder_row.locator(".folder-icon")).to_be_visible()
+        expect(folder_row.locator(".file-selection-slot")).to_have_count(0)
+        page.get_by_role("button", name="Select", exact=True).tap()
+        expect(folder_row.locator(".folder-icon")).to_be_visible()
+        folder.tap()
+        expect(page.get_by_label("Select Preview samples", exact=True)).to_be_checked()
+        page.get_by_role("button", name="Done", exact=True).tap()
+        page.get_by_role("button", name="Preview samples", exact=True).tap()
+        target = page.get_by_role("button", name="sample.json", exact=True)
+        expect(target).to_be_visible()
+        for layout in ("List view", "Grid view"):
+            choose_view(page, layout)
+            target.scroll_into_view_if_needed()
+            target.tap()
+            preview = page.locator("dialog.file-preview")
+            expect(preview).to_be_visible()
+            expect(preview.locator("pre")).to_contain_text('"count": 3')
+            assert_bounded(page, ".file-preview button, .file-preview a")
+            preview.get_by_role("button", name="Close Preview", exact=True).tap()
+            expect(preview).to_have_count(0)
+            if width == 1440:
+                target.click(modifiers=["Control"])
+                expect(preview).to_have_count(0)
+                expect(
+                    page.get_by_label("Select sample.json", exact=True)
+                ).to_have_count(0)
+                target.dblclick()
+                expect(preview).to_be_visible()
+                preview.get_by_role("button", name="Close Preview", exact=True).click()
+            # Browsing has no empty checkbox slot. Explicit selection adds its
+            # checkbox alongside the icon while preserving all row heights.
+            page.locator(".workspace").evaluate("e => e.scrollTop = 0")
+            before = geometry(page, "sample.json")
+            row = page.locator(".file-row").filter(has=target)
+            expect(row.locator(".file-icon")).to_be_visible()
+            expect(row.locator(".file-selection-slot")).to_have_count(0)
+            if layout == "List view":
+                icon = row.locator(".file-icon").bounding_box()
+                cell = row.locator(".name-cell").bounding_box()
+                assert 0 <= icon["x"] - cell["x"] <= 16
+            toolbar = page.locator(".file-toolbar").bounding_box()
+            ARTIFACTS.mkdir(parents=True, exist_ok=True)
+            if layout == "List view":
+                page.screenshot(
+                    path=ARTIFACTS / f"phone-list-idle-{width}x{height}.png"
+                )
+            page.get_by_role("button", name="Select", exact=True).tap()
+            expect(row.locator(".file-icon")).to_be_visible()
+            assert_stable(before, geometry(page, "sample.json"), ("y", "height"))
+            assert_stable(toolbar, page.locator(".file-toolbar").bounding_box())
+            selecting = geometry(page, "sample.json")
+            checkbox = page.get_by_role(
+                "checkbox", name="Select sample.json", exact=True
+            )
+            # Click the label padding as a phone user does, rather than only
+            # programmatically changing the input: this catches double toggles.
+            label = checkbox.locator("..")
+            label.tap(position={"x": 4, "y": 4})
+            expect(checkbox).to_be_checked()
+            expect(page.get_by_text("1 selected", exact=True)).to_be_visible()
+            assert_stable(selecting, geometry(page, "sample.json"))
+            if layout == "List view":
+                page.locator(".workspace").evaluate("e => e.scrollTop = 0")
+                page.screenshot(
+                    path=ARTIFACTS / f"phone-list-selected-{width}x{height}.png"
+                )
+            target.tap()
+            expect(checkbox).not_to_be_checked()
+            expect(page.get_by_text("0 selected", exact=True)).to_be_visible()
+            assert_stable(selecting, geometry(page, "sample.json"))
+            page.get_by_role("button", name="Done", exact=True).tap()
+            assert_stable(before, geometry(page, "sample.json"))
+            expect(row.locator(".file-selection-slot")).to_have_count(0)
+            assert_bounded(page, ".file-toolbar button")
+            page.get_by_label("Actions for sample.json", exact=True).tap()
+            menu = page.locator(".action-menu:popover-open")
+            expect(menu).to_be_visible()
+            assert_bounded(page, ".action-menu:popover-open")
+            menu.get_by_role("button", name="Rename", exact=True).tap()
+            dialog = page.get_by_role("dialog", name="Rename", exact=True)
+            expect(dialog).to_be_visible()
+            assert_bounded(
+                page, "dialog[open], dialog[open] input, dialog[open] button"
+            )
+            page.keyboard.press("Escape")
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=ARTIFACTS / f"phone-stable-selection-{width}x{height}.png")
+        assert errors == []
+    finally:
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=ARTIFACTS / f"phone-last-{width}x{height}.png")
+        context.close()
+
+
+@pytest.mark.parametrize("width,height", [(320, 640), (390, 844), (740, 360)])
+def test_phone_navigation_search_new_and_owner_controls_are_reachable(
+    server, browser, width, height
+):
+    context = browser.new_context(
+        viewport={"width": width, "height": height}, has_touch=True, is_mobile=True
+    )
+    page = context.new_page()
+    errors = []
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    try:
+        url = open_fixture(page, server)
+        if page.get_by_role(
+            "button", name="Toggle Navigation", exact=True
+        ).is_visible():
+            page.get_by_role(
+                "button", name="Search Files and Folders", exact=True
+            ).tap()
+            expect(
+                page.get_by_role(
+                    "searchbox", name="Search Files and Folders", exact=True
+                )
+            ).to_be_focused()
+            assert_bounded(page, ".file-toolbar input, .file-toolbar button")
+            page.keyboard.press("Escape")
+            page.get_by_role("button", name="Toggle Navigation", exact=True).tap()
+            drawer = page.get_by_role("dialog", name="Drive navigation", exact=True)
+            expect(drawer).to_be_visible()
+            drawer.get_by_role("link", name="Trash", exact=True).tap()
+            expect(drawer).to_have_count(0)
+            page.goto(url)
+        page.locator("#new-button:visible, #compact-new-button:visible").tap()
+        assert_bounded(page, "#new-menu")
+        page.get_by_role("button", name="New Folder", exact=True).tap()
+        expect(page.get_by_role("dialog")).to_be_visible()
+        assert_bounded(page, "dialog[open], dialog[open] input, dialog[open] button")
+        page.keyboard.press("Escape")
+        shares = [
+            {
+                "id": "phone-share",
+                "node_id": "phone-node",
+                "path": "/phone-node",
+                "name": "A long shared document name for a phone.pdf",
+                "type": "file",
+                "created_at": "2026-10-20T00:00:00Z",
+                "expires_at": None,
+                "copyable": True,
+            }
+        ]
+        page.route(
+            "**/api/v1/shares", lambda route: route.fulfill(json={"shares": shares})
+        )
+        for name, suffix in [
+            ("shares", "?view=shares"),
+            ("storage", "?view=storage"),
+            ("connections", "?view=connections"),
+            ("preloads", "?view=preloads"),
+            ("cache", "?view=settings&section=cache"),
+            ("uploads", "?view=settings&section=transfers"),
+            ("regional", "?view=settings&section=regional"),
+            ("transfers", "?view=activity"),
+            ("performance", "?view=performance"),
+        ]:
+            page.goto(url + "/" + suffix)
+            expect(page.locator(".workspace h1").first).to_be_visible()
+            page.wait_for_timeout(150)
+            assert_bounded(
+                page,
+                ".workspace input, .workspace select, .workspace button, "
+                ".share-row-actions a",
+            )
+            if name == "shares":
+                for label in (
+                    "Edit link for A long shared document name for a phone.pdf",
+                    "Show A long shared document name for a phone.pdf in folder",
+                    "Revoke Link for A long shared document name for a phone.pdf",
+                ):
+                    # Keep all link management actions available on phones.
+                    expect(
+                        page.get_by_role("button", name=label, exact=True)
+                    ).to_be_visible()
+            for control in page.locator(
+                ".workspace input:not([type=checkbox]):not([type=radio])"
+                ":not([type=range]):not([type=file]), "
+                ".workspace select, .workspace textarea"
+            ).all():
+                if control.is_visible():
+                    assert control.evaluate(
+                        "e => parseFloat(getComputedStyle(e).fontSize) >= 16"
+                    ), (
+                        name,
+                        control.evaluate(
+                            "e => ({html:e.outerHTML,"
+                            "font:getComputedStyle(e).fontSize})"
+                        ),
+                    )
+            ARTIFACTS.mkdir(parents=True, exist_ok=True)
+            page.screenshot(path=ARTIFACTS / f"phone-{name}-{width}x{height}.png")
+        page.route(
+            "**/api/v1/trash?*",
+            lambda route: route.fulfill(
+                json={
+                    "data": {
+                        "contents": {
+                            "phone-trash": {
+                                "id": "phone-trash",
+                                "name": "Trashed phone notes.txt",
+                                "path": "/trash",
+                                "type": "file",
+                                "size": 124,
+                                "parent_names": ["My Files"],
+                            }
+                        }
+                    }
+                }
+            ),
+        )
+        page.goto(url + "/?path=/trash")
+        trashed = page.get_by_role("button", name="Trashed phone notes.txt", exact=True)
+        trashed.tap()
+        expect(page.get_by_role("button", name="Select", exact=True)).to_be_visible()
+        expect(page.get_by_role("checkbox")).to_have_count(0)
+        expect(page.locator("dialog.file-preview")).to_have_count(0)
+        page.get_by_role("button", name="Select", exact=True).tap()
+        trashed.tap()
+        expect(
+            page.get_by_label("Select Trashed phone notes.txt", exact=True)
+        ).to_be_checked()
+        expect(page.get_by_role("button", name="Restore", exact=True)).to_be_visible()
+        assert_bounded(page, ".file-toolbar button")
+        assert errors == []
+    finally:
+        context.close()
+
+
+@pytest.mark.parametrize("width,height", [(320, 640), (740, 360)])
+def test_phone_preview_pdf_options_unsupported_and_retry_fit_viewport(
+    server, browser, width, height
+):
+    context = browser.new_context(
+        viewport={"width": width, "height": height}, has_touch=True, is_mobile=True
+    )
+    page = context.new_page()
+    try:
+        open_fixture(page, server)
+        page.get_by_role("button", name="Preview samples", exact=True).tap()
+        page.get_by_role("button", name="sample.pdf", exact=True).tap()
+        expect(page.locator(".pdf-page canvas").first).to_be_visible()
+        options = page.get_by_role("button", name="PDF View Options", exact=True)
+        expect(options).to_be_visible()
+        options.tap()
+        assert_bounded(page, ".file-preview button, .file-preview a")
+        fit = page.get_by_role("button", name="Fit Page", exact=True)
+        fit.tap()
+        expect(fit).to_have_attribute("aria-pressed", "true")
+        expect(
+            page.locator(".pdf-page").first.locator(".pdf-page-loading")
+        ).to_have_count(0)
+        page.screenshot(path=ARTIFACTS / f"phone-pdf-options-{width}x{height}.png")
+        page.get_by_role("button", name="Close Preview", exact=True).tap()
+        long_name = "installer-" + "very-long-file-name-" * 5 + "setup.exe"
+        page.get_by_role("button", name=long_name, exact=True).tap()
+        download = page.locator(".file-details-download")
+        expect(download).to_be_visible()
+        download.scroll_into_view_if_needed()
+        expect(download).to_be_in_viewport()
+        assert_bounded(page, ".file-preview button, .file-preview a")
+        page.screenshot(path=ARTIFACTS / f"phone-unsupported-{width}x{height}.png")
+        page.get_by_role("button", name="Close Preview", exact=True).tap()
+        page.route(
+            "**/api/v1/preview?*",
+            lambda route: route.fulfill(
+                status=503, json={"detail": "Temporary preview fixture failure. " * 10}
+            ),
+        )
+        page.get_by_role("button", name="sample.json", exact=True).tap()
+        retry = page.get_by_role("button", name="Try Preview Again", exact=True)
+        expect(retry).to_be_visible()
+        retry.scroll_into_view_if_needed()
+        expect(retry).to_be_in_viewport()
+        assert_bounded(page, ".file-preview button, .file-preview a")
+        page.screenshot(path=ARTIFACTS / f"phone-preview-error-{width}x{height}.png")
+        page.get_by_role("button", name="Close Preview", exact=True).tap()
+        expect(page.locator("dialog.file-preview")).to_have_count(0)
+    finally:
+        context.close()
diff --git a/tests/browser/test_browser_mobile_shell.py b/tests/browser/test_browser_mobile_shell.py
new file mode 100644
index 00000000..40fcb920
--- /dev/null
+++ b/tests/browser/test_browser_mobile_shell.py
@@ -0,0 +1,239 @@
+"""Phone-specific navigation and upload state cannot cover file content."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login, upload
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.mark.parametrize(
+    "width,height,theme", [(320, 640, "light"), (390, 844, "dark"), (600, 800, "light")]
+)
+def test_phone_browsing_drawer_and_upload_use_separate_surfaces(
+    server, desktop, width, height, theme
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": height})
+    page.add_init_script("localStorage.setItem('tgdrive.appearance','" + theme + "')")
+
+    def listing(route):
+        response = route.fetch()
+        payload = response.json()
+        if route.request.post_data_json["path"] == "/":
+            payload["data"]["contents"].update(
+                {
+                    f"phone-{i}": {
+                        "id": f"phone-{i}",
+                        "name": f"Project notes {i:03}.txt",
+                        "type": "file",
+                        "path": "/",
+                        "size": 1024,
+                    }
+                    for i in range(60)
+                }
+            )
+        route.fulfill(response=response, json=payload)
+
+    page.route("**/api/getDirectory", listing)
+    login(page, server.url)
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    expect(page.locator("#compact-new-button")).to_be_visible()
+    assert page.locator("#compact-new-button").evaluate(
+        "e => getComputedStyle(e).position !== 'fixed'"
+    )
+    page.screenshot(path=ARTIFACTS / f"phone-files-idle-{width}.png")
+    upload(page, ["Project walkthrough.mp4"])
+    server.wait_started(1)
+    status = page.get_by_role("button", name="Open transfer progress", exact=True)
+    expect(status).to_be_visible()
+    expect(page.locator("#transfer-dialog")).to_have_count(0)
+    assert (
+        page.locator(".workspace").bounding_box()["y"]
+        + page.locator(".workspace").bounding_box()["height"]
+        <= status.bounding_box()["y"] + 1
+    )
+    assert page.locator(".file-list-scroll").evaluate(
+        "e => getComputedStyle(e).overflowY === 'visible'"
+    )
+    assert page.locator(".file-toolbar").evaluate(
+        "e => e.scrollWidth <= e.clientWidth+1"
+    )
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(path=ARTIFACTS / f"phone-files-upload-{width}.png")
+    page.locator(".workspace").evaluate("e => e.scrollTop=500")
+    assert page.locator(".workspace").evaluate("e=>e.scrollTop") == 500
+    expect(
+        page.get_by_role("button", name="Toggle Navigation", exact=True)
+    ).to_be_in_viewport()
+    page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+    drawer = page.get_by_role("dialog", name="Drive navigation", exact=True)
+    expect(drawer).to_be_visible()
+    rect = drawer.bounding_box()
+    assert rect["y"] == 0 and rect["height"] == height
+    assert rect["width"] <= width - 39
+    assert drawer.evaluate("e=>e.scrollTop") == 0
+    assert page.locator("main").get_attribute("inert") is not None
+    page.screenshot(path=ARTIFACTS / f"phone-drawer-{width}.png")
+    page.keyboard.press("Escape")
+    expect(drawer).to_have_count(0)
+    expect(
+        page.get_by_role("button", name="Toggle Navigation", exact=True)
+    ).to_be_focused()
+    status.click()
+    expect(page.get_by_role("heading", name="Transfers", exact=True)).to_be_visible()
+    expect(page.locator(".transfer-page")).to_be_visible()
+    expect(status).to_have_count(0)
+    page.screenshot(path=ARTIFACTS / f"phone-transfers-{width}.png")
+
+
+@pytest.mark.parametrize(
+    "width,theme", [(1440, "light"), (390, "dark"), (320, "light")]
+)
+def test_sidebar_keeps_rare_tools_collapsed_and_exposes_project_link(
+    server, desktop, width, theme
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    page.emulate_media(color_scheme=theme)
+    login(page, server.url)
+
+    def open_drawer():
+        if page.locator(".sidebar").get_attribute("inert") is not None:
+            page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+
+    open_drawer()
+    tools = page.locator(".sidebar-tools")
+    summary = tools.locator("summary")
+    expect(tools).not_to_have_attribute("open", "")
+    expect(page.get_by_role("link", name="Performance", exact=True)).not_to_be_visible()
+    for label in ["My Files", "Starred", "Transfers", "Shared Links", "Trash"]:
+        expect(page.get_by_role("link", name=label, exact=True)).to_be_in_viewport()
+    github = page.get_by_role("link", name="TGDrive on GitHub", exact=True)
+    expect(github).to_have_attribute("href", "https://github.com/TechShreyash/TGDrive")
+    expect(github).to_have_attribute("target", "_blank")
+    expect(github).to_have_attribute("rel", "noopener noreferrer")
+    expect(github).to_be_in_viewport()
+    assert github.inner_text() == ""
+    support = page.locator(".sidebar-support")
+    assert support.locator("a").count() == 2
+    assert support.evaluate("e => getComputedStyle(e).position === 'static'")
+    assert github.bounding_box()["width"] >= 44
+    assert github.bounding_box()["height"] >= 44
+    docs = support.get_by_role("link", name="Documentation", exact=True)
+    assert abs(docs.bounding_box()["y"] - github.bounding_box()["y"]) <= 1
+    logout = page.get_by_role("button", name="Log Out", exact=True)
+    expect(logout).to_be_in_viewport()
+    assert docs.evaluate("""element => {
+      const style = getComputedStyle(element);
+      return style.paddingLeft === style.paddingRight && style.flexGrow === '0';
+    }""")
+    nav_icon = page.get_by_role("link", name="My Files", exact=True).locator("svg")
+    for icon in (docs.locator("svg"), logout.locator("svg")):
+        assert abs(icon.bounding_box()["x"] - nav_icon.bounding_box()["x"]) <= 1
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    docs.hover()
+    page.screenshot(
+        path=ARTIFACTS / f"sidebar-documentation-hover-{theme}-{width}.png",
+        animations="disabled",
+    )
+    page.screenshot(
+        path=ARTIFACTS / f"sidebar-simple-{theme}-{width}.png", animations="disabled"
+    )
+    summary.focus()
+    page.keyboard.press("Enter")
+    expect(tools).to_have_attribute("open", "")
+    children = page.get_by_role("group", name="Tools & settings", exact=True)
+    for category in ("Monitor", "Configuration", "Management"):
+        expect(children.get_by_role("group", name=category, exact=True)).to_be_visible()
+    assert children.evaluate("""e => {
+        const parent = e.closest('details').querySelector('summary');
+        return e.getBoundingClientRect().x > parent.getBoundingClientRect().x + 12
+          && getComputedStyle(e).borderInlineStartWidth === '1px'
+          && [...e.querySelectorAll('[role=group]')].every(group =>
+            group.getBoundingClientRect().x ===
+              e.firstElementChild.getBoundingClientRect().x);
+    }""")
+    page.get_by_role("link", name="Performance", exact=True).click()
+    expect(page.get_by_role("heading", name="Performance", exact=True)).to_be_visible()
+    open_drawer()
+    expect(tools).to_have_attribute("open", "")
+    expect(page.locator('.drive-nav a[aria-current="page"]')).to_have_text(
+        "Performance"
+    )
+    page.screenshot(
+        path=ARTIFACTS / f"sidebar-tools-{theme}-{width}.png", animations="disabled"
+    )
+    page.get_by_role("link", name="My Files", exact=True).click()
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    open_drawer()
+    expect(tools).not_to_have_attribute("open", "")
+    page.goto(server.url + "/?view=settings&section=regional")
+    expect(
+        page.get_by_role("heading", name="Regional settings", exact=True)
+    ).to_be_visible()
+    open_drawer()
+    expect(tools).to_have_attribute("open", "")
+    expect(page.get_by_role("link", name="Timezone", exact=True)).to_have_attribute(
+        "aria-current", "page"
+    )
+    summary.click()
+    expect(tools).not_to_have_attribute("open", "")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+
+
+@pytest.mark.parametrize(
+    "width,theme", [(1440, "light"), (1440, "dark"), (390, "dark"), (320, "light")]
+)
+def test_brand_asset_and_sidebar_footer_stay_clear_in_both_themes(
+    server, desktop, width, theme
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    page.emulate_media(color_scheme=theme)
+    page.goto(server.url)
+    expect(page.locator("#login-dialog")).to_be_visible()
+    logo = page.locator(f".login-page .brand-logo-{theme}")
+    expect(logo).to_be_visible()
+    expected_logo = "tgdrive-logo-dark.svg" if theme == "dark" else "tgdrive-logo.svg"
+    expect(logo).to_have_attribute("src", "/static/brand/" + expected_logo)
+    logo.evaluate("img => img.decode()")
+    assert logo.evaluate("img => img.complete && img.naturalWidth > 0")
+    expect(page.locator('link[rel="icon"][type="image/svg+xml"]')).to_have_attribute(
+        "href", "/static/brand/favicon.svg"
+    )
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(
+        path=ARTIFACTS / f"brand-login-{theme}-{width}.png", animations="disabled"
+    )
+    login(page)
+    for image in page.locator(".brand-logo img").all():
+        image.evaluate("img => img.decode()")
+        assert image.evaluate("img => img.complete && img.naturalWidth > 0")
+    if width <= 720:
+        page.screenshot(
+            path=ARTIFACTS / f"brand-mobile-header-{theme}-{width}.png",
+            animations="disabled",
+        )
+        page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+    sidebar = page.locator(".sidebar")
+    assert sidebar.evaluate("e => e.scrollWidth <= e.clientWidth")
+    support = sidebar.locator(".sidebar-support")
+    assert support.evaluate("e => e.scrollWidth <= e.clientWidth")
+    github = support.get_by_role("link", name="TGDrive on GitHub", exact=True)
+    support.get_by_role("link", name="Documentation", exact=True).focus()
+    page.keyboard.press("Tab")
+    expect(github).to_be_focused()
+    assert github.evaluate("e => getComputedStyle(e).outlineStyle !== 'none'")
+    page.screenshot(
+        path=ARTIFACTS / f"brand-sidebar-{theme}-{width}.png", animations="disabled"
+    )
diff --git a/tests/browser/test_browser_notifications.py b/tests/browser/test_browser_notifications.py
new file mode 100644
index 00000000..0931a55c
--- /dev/null
+++ b/tests/browser/test_browser_notifications.py
@@ -0,0 +1,142 @@
+"""Shared notification placement, lifetime and dialog usability in real Chromium."""
+
+import pytest
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    expect,
+    login,
+    select_item,
+)
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.mark.parametrize("width", [320, 390, 1440])
+@pytest.mark.parametrize("theme", ["light", "dark"])
+def test_notifications_are_single_dismissible_and_usable_in_modals(
+    server, desktop, width, theme
+):
+    context, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    page.add_init_script("localStorage.setItem('tgdrive.appearance','" + theme + "')")
+    context.grant_permissions(["clipboard-read", "clipboard-write"], origin=server.url)
+    page.clock.install()
+    login(page, server.url)
+
+    def check_notification(message):
+        toast = page.locator(".toast")
+        expect(toast).to_have_count(1)
+        expect(toast).to_have_text(message)
+        expect(toast).to_be_visible()
+        assert toast.evaluate("el => el.matches(':popover-open')")
+        box = toast.bounding_box()
+        assert box and box["x"] >= 0 and box["x"] + box["width"] <= width
+        assert box["y"] >= 0 and box["y"] + box["height"] <= 844
+        close = toast.get_by_role("button", name="Dismiss Notification")
+        close_box = close.bounding_box()
+        assert close_box and close_box["width"] >= (44 if width < 720 else 24)
+        assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+        return toast
+
+    def create_folder(name):
+        page.locator("#compact-new-button" if width < 720 else "#new-button").click()
+        page.get_by_role("button", name="New Folder", exact=True).click()
+        dialog = page.get_by_role("dialog", name="New Folder", exact=True)
+        expect(dialog.get_by_label("Folder Name")).to_be_focused()
+        dialog.get_by_label("Folder Name").fill(name)
+        dialog.get_by_role("button", name="Create Folder", exact=True).click()
+        expect(dialog).to_have_count(0)
+
+    create_folder("Popup check")
+    toast = check_notification("Folder created.")
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / f"notification-{theme}-{width}.png")
+    toast.hover()
+    page.clock.run_for(6500)
+    expect(toast).to_be_visible()
+    dismiss = toast.get_by_role("button", name="Dismiss Notification")
+    dismiss.focus()
+    page.mouse.move(0, 0)
+    page.clock.run_for(6500)
+    expect(toast).to_be_visible()
+    toast.get_by_role("button", name="Dismiss Notification").click()
+    expect(toast).to_have_count(0)
+    create_folder("Popup next")
+    check_notification("Folder created.")
+    page.clock.run_for(6500)
+    expect(toast).to_have_count(0)
+
+    page.locator('summary[aria-label="Actions for 資料"]').click()
+    page.get_by_role("button", name="Share Link", exact=True).click()
+    dialog = page.get_by_role("dialog")
+    dialog.get_by_role("button", name="Create Share Link", exact=True).click()
+    copy = dialog.get_by_role("button", name="Copy Link", exact=True)
+    copy.click()
+    check_notification("Share Link copied.")
+    expect(copy).to_be_focused()
+    expect(dialog.locator(".toast")).to_have_count(1)
+    page.screenshot(path=ARTIFACTS / f"notification-modal-{theme}-{width}.png")
+    toast.get_by_role("button", name="Dismiss Notification").click()
+    expect(copy).to_be_focused()
+    copy.click()
+    check_notification("Share Link copied.")
+    for key in ["Tab", "Shift+Tab"]:
+        for _ in range(8):
+            page.keyboard.press(key)
+            assert dialog.evaluate("el => el.contains(document.activeElement)")
+    page.keyboard.press("Escape")
+    expect(dialog).to_have_count(0)
+    expect(toast).to_have_count(0)
+
+    # A long server error must wrap, remain dismissible and stay until read.
+    detail = "Unable to update this item. Reference: " + "abcdefgh" * 240
+    page.route(
+        "**/api/v1/starred",
+        lambda route: route.fulfill(status=503, json={"detail": detail}),
+    )
+    page.locator('summary[aria-label="Actions for 資料"]').click()
+    page.get_by_role("button", name="Add to Starred", exact=True).click()
+    check_notification(detail)
+    expect(toast).to_have_attribute("role", "alert")
+    message = toast.locator("span")
+    assert message.evaluate("el => el.scrollHeight > el.clientHeight")
+    message.focus()
+    message.press("Control+End")
+    expect(message).not_to_have_js_property("scrollTop", 0)
+    page.clock.run_for(10000)
+    expect(toast).to_be_visible()
+    page.screenshot(path=ARTIFACTS / f"notification-error-{theme}-{width}.png")
+    page.locator("#compact-new-button" if width < 720 else "#new-button").click()
+    page.get_by_role("button", name="New Folder", exact=True).click()
+    expect(toast).to_have_count(0)
+    page.keyboard.press("Escape")
+
+
+def test_delete_dialog_failure_is_inline_without_duplicate_popup(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Trash", exact=True).click()
+    page.get_by_role("link", name="Trash", exact=True).click()
+    select_item(page, "Private folder")
+    page.get_by_role("button", name="Delete Permanently", exact=True).click()
+    detail = "Temporary database failure. Please try again."
+    page.route(
+        "**/api/v1/nodes/bulk",
+        lambda route: route.fulfill(
+            status=503,
+            json={"detail": detail},
+        ),
+    )
+    dialog = page.get_by_role("dialog")
+    confirm = dialog.get_by_role("button", name="Delete Permanently", exact=True)
+    confirm.click()
+    expect(dialog.get_by_role("alert")).to_have_text(detail)
+    expect(confirm).to_be_enabled()
+    expect(page.locator(".toast")).to_have_count(0)
+    expect(
+        page.get_by_role("button", name="Private folder", exact=True)
+    ).to_be_visible()
diff --git a/tests/browser/test_browser_pdf_features.py b/tests/browser/test_browser_pdf_features.py
new file mode 100644
index 00000000..c64fe2f5
--- /dev/null
+++ b/tests/browser/test_browser_pdf_features.py
@@ -0,0 +1,177 @@
+"""Synthetic password and rendering-resource cases use the shipped PDF reader."""
+
+from __future__ import annotations
+
+from urllib.parse import urlsplit
+
+import pytest
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    Server,
+    assert_pdf_canvas_budget,
+    assert_rendered_pdf_page,
+    expect,
+    login,
+    preview_dialog,
+)
+from tests.browser.test_browser_e2e import browser as browser_fixture
+from tests.browser.test_browser_e2e import desktop as desktop_fixture
+from tests.browser.test_browser_e2e import server as server_fixture
+from tests.support.book_samples import PDF_SAMPLE_PASSWORD
+
+pytestmark = pytest.mark.e2e
+browser, desktop, server = browser_fixture, desktop_fixture, server_fixture
+
+
+def open_sample(page, name):
+    page.get_by_role("button", name=name, exact=True).dblclick()
+    return preview_dialog(page)
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+@pytest.mark.parametrize("theme", ["light", "dark"])
+def test_pdf_password_retry_cancel_and_reopen_keep_the_password_in_memory(
+    server: Server, desktop, width, theme
+):
+    server.control("/pdf/features", method="POST")
+    context, page = desktop
+    context.add_init_script(f"localStorage.setItem('tgdrive.appearance', '{theme}')")
+    page.set_viewport_size({"width": width, "height": 900})
+    requests = []
+    messages = []
+    page.on(
+        "request", lambda request: requests.append((request.url, request.post_data))
+    )
+    page.on("console", lambda message: messages.append(message.text))
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+
+    name = "password-protected.pdf"
+    dialog = open_sample(page, name)
+    password = dialog.get_by_label("PDF Password", exact=True)
+    expect(password).to_be_visible()
+    expect(password).to_be_focused()
+    expect(password).to_have_attribute("type", "password")
+    expect(password).to_have_value("")
+    expect(dialog.locator(".pdf-controls select")).to_contain_text("Password Required")
+    expect(dialog.locator(".pdf-zoom")).to_have_text("—")
+    assert dialog.locator(".pdf-password").evaluate(
+        "form => form.getBoundingClientRect().width <= innerWidth - 16"
+    )
+    page.screenshot(path=str(ARTIFACTS / f"pdf-password-{theme}-{width}-required.png"))
+    for attempt in range(2):
+        password.fill("incorrect-fixture-password-" + str(attempt))
+        dialog.get_by_role("button", name="Open PDF", exact=True).click()
+        expect(dialog.get_by_role("alert")).to_contain_text("Incorrect password")
+        expect(password).to_have_value("")
+        expect(password).to_be_focused()
+        expect(password).to_have_attribute("aria-invalid", "true")
+    page.screenshot(path=str(ARTIFACTS / f"pdf-password-{theme}-{width}-incorrect.png"))
+    password.fill(PDF_SAMPLE_PASSWORD)
+    dialog.get_by_role("button", name="Open PDF", exact=True).click()
+    assert_rendered_pdf_page(page, name, 1)
+    expect(dialog.locator(".pdf-text-layer")).to_contain_text(
+        "Encrypted PDF fixture opened"
+    )
+    assert_pdf_canvas_budget(dialog)
+    page.screenshot(path=str(ARTIFACTS / f"pdf-password-{theme}-{width}-opened.png"))
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+
+    dialog = open_sample(page, name)
+    password = dialog.get_by_label("PDF Password", exact=True)
+    expect(password).to_have_value("")
+    expect(password).to_be_focused()
+    password.fill(PDF_SAMPLE_PASSWORD)
+    dialog.get_by_role("button", name="Cancel", exact=True).click()
+    expect(dialog.get_by_role("alert")).to_contain_text("PDF opening cancelled")
+    expect(dialog.locator(".preview-pdf-error")).to_be_focused()
+    expect(dialog.locator(".pdf-password")).to_have_count(0)
+    expect(
+        dialog.get_by_role("link", name="Download Original", exact=True)
+    ).to_be_visible()
+    page.screenshot(path=str(ARTIFACTS / f"pdf-password-{theme}-{width}-cancelled.png"))
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+
+    dialog = open_sample(page, name)
+    expect(dialog.get_by_label("PDF Password", exact=True)).to_have_value("")
+    expect(dialog.get_by_label("PDF Password", exact=True)).to_be_focused()
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    stored = page.evaluate(
+        "() => JSON.stringify({local: {...localStorage}, session: {...sessionStorage}})"
+    )
+    assert PDF_SAMPLE_PASSWORD not in stored
+    assert all(PDF_SAMPLE_PASSWORD not in url + (body or "") for url, body in requests)
+    assert all(PDF_SAMPLE_PASSWORD not in message for message in messages)
+    file_requests = [url for url, _ in requests if urlsplit(url).path == "/file"]
+    assert file_requests
+
+
+def test_pdf_fonts_cmaps_and_cmyk_resources_render_from_local_assets(
+    server: Server, desktop
+):
+    server.control("/pdf/features", method="POST")
+    _, page = desktop
+    resources = []
+    request_urls = []
+
+    def response_seen(response):
+        path = urlsplit(response.url).path
+        if path.startswith("/static/pdfjs/"):
+            resources.append((path, response.status))
+
+    page.on("request", lambda request: request_urls.append(request.url))
+    page.on("response", response_seen)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    name = "local-resources.pdf"
+    dialog = open_sample(page, name)
+    assert_rendered_pdf_page(page, name, 1)
+    expect(dialog.locator(".pdf-text-layer")).to_contain_text(
+        "Local PDF rendering resources"
+    )
+    expect(
+        dialog.locator(".pdf-text-layer").get_by_text("A", exact=True)
+    ).to_have_count(1)
+    canvas = dialog.locator('.pdf-page[data-page-number="1"] canvas')
+    assert canvas.evaluate("""canvas => {
+        const scale = canvas.width / 420;
+        const pixels = canvas.getContext('2d').getImageData(
+            Math.floor(22 * scale), Math.floor(126 * scale),
+            Math.ceil(35 * scale), Math.ceil(34 * scale)).data;
+        let ink = 0;
+        for (let index = 0; index < pixels.length; index += 4) {
+            if (pixels[index] < 80 && pixels[index + 1] < 80 &&
+                pixels[index + 2] < 80) ink++;
+        }
+        return ink > 50;
+    }"""), "The packed CMap glyph must paint, not merely appear in selectable text"
+    assert canvas.evaluate("""canvas => {
+        const pixels = canvas.getContext('2d')
+            .getImageData(0, 0, canvas.width, canvas.height).data;
+        let red = 0;
+        for (let index = 0; index < pixels.length; index += 4) {
+            if (pixels[index] > 100 && pixels[index + 1] < 120 &&
+                pixels[index + 2] < 120) red++;
+        }
+        return red > 1000;
+    }"""), "The CMYK patch must render; selectable text alone is insufficient"
+    assert resources
+    assert all(status == 200 for _, status in resources)
+    assert {path.split("/")[4] for path, _ in resources} == {
+        "standard_fonts",
+        "cmaps",
+        "wasm",
+        "iccs",
+    }
+    assert any(path.endswith("qcms_bg.wasm") for path, _ in resources)
+    assert any(path.endswith("CGATS001Compat-v2-micro.icc") for path, _ in resources)
+    origin = urlsplit(server.url)
+    assert all(
+        (urlsplit(url).scheme, urlsplit(url).netloc) == (origin.scheme, origin.netloc)
+        for url in request_urls
+        if urlsplit(url).scheme in {"http", "https"}
+    )
+    assert_pdf_canvas_budget(dialog)
+    page.screenshot(path=str(ARTIFACTS / "pdf-local-resources.png"))
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
diff --git a/tests/browser/test_browser_pdf_ranges.py b/tests/browser/test_browser_pdf_ranges.py
new file mode 100644
index 00000000..9fdda932
--- /dev/null
+++ b/tests/browser/test_browser_pdf_ranges.py
@@ -0,0 +1,205 @@
+"""Large real PDFs use authorized sparse HTTP bytes, never a full-file warmup."""
+
+from __future__ import annotations
+
+import json
+from urllib.parse import urlsplit
+
+import pytest
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    Server,
+    assert_pdf_canvas_budget,
+    assert_rendered_pdf_page,
+    expect,
+    login,
+    preview_dialog,
+)
+from tests.browser.test_browser_e2e import browser as browser_fixture
+from tests.browser.test_browser_e2e import desktop as desktop_fixture
+from tests.browser.test_browser_e2e import server as server_fixture
+
+pytestmark = pytest.mark.e2e
+browser, desktop, server = browser_fixture, desktop_fixture, server_fixture
+
+
+@pytest.mark.parametrize("kind", ["single", "split", "shared", "shared-filtered"])
+def test_large_pdf_first_page_and_distant_page_need_only_sparse_ranges(
+    server: Server, desktop, kind
+):
+    data = server.control(
+        "/pdf/large"
+        + (
+            "?shared=1" + ("&filtered=1" if kind == "shared-filtered" else "")
+            if kind.startswith("shared")
+            else ""
+        ),
+        method="POST",
+    )
+    assert data["size"] > 30 * 1024**2
+    context, page = desktop
+    cdp = context.new_cdp_session(page)
+    cdp.send("Network.enable")
+    cdp.send("Network.setCacheDisabled", {"cacheDisabled": True})
+    requests, finished = [], []
+
+    def is_pdf(request):
+        return urlsplit(request.url).path == "/file" and "preview=1" in request.url
+
+    def completed(request):
+        if is_pdf(request):
+            response = request.response()
+            finished.append(
+                {
+                    "range": request.headers.get("range"),
+                    "status": response.status,
+                    "bytes": int(response.headers.get("content-length", "0")),
+                }
+            )
+
+    page.on(
+        "request", lambda request: requests.append(request) if is_pdf(request) else None
+    )
+    page.on("requestfinished", completed)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    name = "split-images.pdf" if kind == "split" else "large-images.pdf"
+    page.get_by_role("button", name=name, exact=True).dblclick()
+    dialog = preview_dialog(page)
+    assert_rendered_pdf_page(page, name, 1)
+    if kind.startswith("shared"):
+        canvas = dialog.locator('.pdf-page[data-page-number="1"] canvas')
+        assert canvas.evaluate("""canvas => {
+          const ctx = canvas.getContext('2d');
+          const pixels = ctx.getImageData(
+            0, 0, canvas.width, canvas.height).data;
+          let color = 0;
+          for(let i = 0; i < pixels.length; i += 16) {
+            const channels = [pixels[i], pixels[i+1], pixels[i+2]];
+            if (Math.max(...channels) - Math.min(...channels) > 40) color++;
+          }
+          return color > 1000;
+        }"""), "Rendered text alone must not hide a missing image or soft mask"
+    page.wait_for_function(
+        "() => [...document.querySelectorAll('.pdf-page')].every("
+        "e => e.getAttribute('aria-busy') === 'false')"
+    )
+    initial = sum(row["bytes"] for row in finished)
+    assert 0 < initial < data["size"] // 3
+    before = len(requests)
+    page.wait_for_timeout(350)
+    assert len(requests) == before, "Idle viewing must not auto-fetch the remaining PDF"
+    dialog.locator(".pdf-scroll").evaluate("e => { e.scrollTop = e.scrollHeight; }")
+    assert_rendered_pdf_page(page, name, 48)
+    expect(
+        dialog.locator('.pdf-page[data-page-number="48"] .pdf-text-layer')
+    ).to_contain_text("TGDrive large PDF page 48")
+    page.wait_for_function(
+        "() => [...document.querySelectorAll('.pdf-page')].every("
+        "e => e.getAttribute('aria-busy') === 'false')"
+    )
+    assert all(
+        request.headers.get("range", "").startswith("bytes=") for request in requests
+    )
+    assert all(row["status"] == 206 for row in finished)
+    assert sum(row["bytes"] for row in finished) < data["size"] * 2 // 3
+    assert any(
+        int(request.headers["range"].split("=")[1].split("-")[0]) > data["size"] // 2
+        for request in requests
+    )
+    assert_pdf_canvas_budget(dialog)
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    (ARTIFACTS / f"pdf-ranges-{kind}.json").write_text(
+        json.dumps(
+            {
+                "source_bytes": data["size"],
+                "initial_bytes": initial,
+                "ranges": finished,
+            },
+            indent=2,
+        )
+    )
+    page.screenshot(path=str(ARTIFACTS / f"pdf-ranges-{kind}.png"))
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+
+
+def test_pdf_ignored_range_fails_without_full_download(server: Server, desktop):
+    _, page = desktop
+    calls = []
+
+    def ignore_range(route):
+        calls.append(route.request.headers.get("range"))
+        route.fulfill(
+            status=200,
+            body=b"%PDF-1.4\nwrong range response",
+            content_type="application/pdf",
+        )
+
+    page.route("**/file?**", ignore_range)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="sample.pdf", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    expect(dialog.get_by_role("alert")).to_contain_text("needs byte-range responses")
+    expect(
+        dialog.get_by_role("link", name="Download Original", exact=True)
+    ).to_be_visible()
+    assert calls and all(calls)
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+
+
+def test_pdf_close_aborts_active_range_reads(server: Server, desktop):
+    _, page = desktop
+    held = []
+    page.route("**/file?**", lambda route: held.append(route))
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    with page.expect_request(lambda request: urlsplit(request.url).path == "/file"):
+        page.get_by_role("button", name="sample.pdf", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    expect(dialog.get_by_role("status")).to_contain_text("Loading PDF")
+    assert held, "A real explicit range must be pending before cancellation"
+    with page.expect_event(
+        "requestfailed", predicate=lambda request: urlsplit(request.url).path == "/file"
+    ) as cancelled:
+        dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    assert "ABORTED" in cancelled.value.failure
+    expect(page.locator("dialog.file-preview")).to_have_count(0)
+    for route in held:
+        route.abort()
+
+
+def test_shared_pdf_rechecks_access_for_uncached_pages_after_revocation(
+    server: Server, desktop, browser
+):
+    data = server.control("/pdf/large", method="POST")
+    _, owner = desktop
+    login(owner, server.url)
+    folder = data["split"].rsplit("/", 1)[0]
+    response = owner.request.post(
+        server.url + "/api/v1/shares", data={"path": folder, "expires_in_days": 7}
+    )
+    assert response.ok
+    token = response.json()["auth"]
+    public_context = browser.new_context(viewport={"width": 390, "height": 844})
+    try:
+        public = public_context.new_page()
+        public.goto(
+            server.url + "/?path=/share_" + folder.lstrip("/") + "&auth=" + token
+        )
+        public.get_by_role("button", name="split-images.pdf", exact=True).dblclick()
+        dialog = preview_dialog(public)
+        assert_rendered_pdf_page(public, "split-images.pdf", 1)
+        assert owner.request.delete(
+            server.url + "/api/v1/shares", data={"path": folder}
+        ).ok
+        dialog.locator(".pdf-scroll").evaluate("e => { e.scrollTop = e.scrollHeight; }")
+        expect(dialog.get_by_role("alert")).to_contain_text(
+            "access has expired", timeout=15000
+        )
+        expect(
+            dialog.get_by_role("link", name="Download Original", exact=True)
+        ).to_be_visible()
+    finally:
+        public_context.close()
diff --git a/tests/browser/test_browser_performance_ui.py b/tests/browser/test_browser_performance_ui.py
new file mode 100644
index 00000000..ec002b1d
--- /dev/null
+++ b/tests/browser/test_browser_performance_ui.py
@@ -0,0 +1,558 @@
+"""Owner cache and performance controls in real Chromium."""
+# ruff: noqa: F811 - pytest fixture parameters shadow imported fixture functions.
+
+from __future__ import annotations
+
+import os
+import re
+import time
+
+import pytest
+
+pytestmark = pytest.mark.e2e
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium tests", allow_module_level=True)
+
+from tests.browser.test_browser_e2e import (  # noqa: E402
+    ARTIFACTS,
+    browser,  # noqa: F401 - shared pytest fixture
+    desktop,  # noqa: F401 - shared pytest fixture
+    expect,
+    login,
+    server,  # noqa: F401 - shared pytest fixture
+)
+
+
+def test_cache_inventory_filters_verified_coverage_and_clear_actions(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    snapshot = page.request.get(server.url + "/api/v1/preloads").json()
+    snapshot["cache"]["files"] = [
+        {
+            "id": "ready-file",
+            "name": "Prepared movie.mp4",
+            "size": 100,
+            "ready_bytes": 100,
+            "complete": True,
+            "ready_ranges": [[0, 100]],
+        },
+        {
+            "id": "partial-file",
+            "name": "Interview.mkv",
+            "size": 100,
+            "ready_bytes": 100,
+            "complete": True,
+            "ready_ranges": [[0, 10], [90, 100]],
+        },
+    ]
+    snapshot["jobs"] = [
+        {
+            "id": "active",
+            "file_id": "partial-file",
+            "name": "Interview.mkv",
+            "state": "preparing",
+            "mode": "auto",
+            "bytes_done": 20,
+            "target_bytes": 100,
+            "size": 100,
+            "start": 0,
+            "end": 100,
+        },
+        {
+            "id": "failed",
+            "file_id": "other-file",
+            "name": "Uncached video.mp4",
+            "state": "failed",
+            "mode": "manual",
+            "bytes_done": 0,
+            "target_bytes": 100,
+            "size": 100,
+            "start": 0,
+            "end": 100,
+            "error": "Telegram is temporarily unavailable",
+        },
+    ]
+    snapshot["active_jobs"] = 1
+    page.route("**/api/v1/preloads", lambda route: route.fulfill(json=snapshot))
+    cleared = []
+
+    def clear(route):
+        cleared.append(route.request.post_data_json)
+        route.fulfill(json={"status": "ok"})
+
+    page.route("**/api/v1/preloads/clear", clear)
+    page.goto(server.url + "/?view=preloads")
+    expect(page.locator(".cached-file")).to_have_count(2)
+    expect(
+        page.locator(".cached-file").filter(has_text="Interview.mkv")
+    ).to_contain_text("Preloading")
+    ready = page.locator(".cached-file").filter(has_text="Prepared movie")
+    partial = page.locator(".cached-file").filter(has_text="Interview.mkv")
+    expect(ready.locator("svg[role=img]")).to_be_visible()
+    expect(ready.locator(".cache-coverage-ready")).to_have_attribute("x", "0")
+    expect(ready.locator(".cache-coverage-ready")).to_have_attribute("width", "1000")
+    expect(ready.locator(".cache-ready-state")).to_have_text("Ready")
+    segments = partial.locator(".cache-coverage-ready")
+    expect(segments).to_have_count(2)
+    assert [segments.nth(i).get_attribute("x") for i in range(2)] == ["0", "900"]
+    assert [segments.nth(i).get_attribute("width") for i in range(2)] == ["100", "100"]
+    assert ready.locator(".cache-coverage-ready").evaluate(
+        "node => getComputedStyle(node).fill"
+    ) != segments.first.evaluate("node => getComputedStyle(node).fill")
+    expect(partial.locator(".cache-ready-state")).to_contain_text("Partial")
+    expect(page.get_by_text("Cached ranges", exact=False)).to_have_count(0)
+    expect(page.get_by_text("Cache details & recent preparations")).to_have_count(0)
+    expect(page.get_by_role("heading", name="Preload queue")).to_be_visible()
+    expect(
+        page.get_by_text("Telegram is temporarily unavailable", exact=True)
+    ).to_be_visible()
+    page.get_by_role("button", name="Ready 1", exact=True).click()
+    expect(page.locator(".cached-file")).to_have_count(1)
+    expect(page.locator(".cached-file")).to_contain_text("Prepared movie")
+    page.get_by_role("button", name="Partial 1", exact=True).click()
+    expect(page.locator(".cache-coverage")).to_contain_text("20 / 100 B cached")
+    expect(page.locator(".cache-coverage")).to_contain_text("20%")
+    page.get_by_role("searchbox", name="Search cached files", exact=True).fill(
+        "missing"
+    )
+    expect(
+        page.get_by_text("No cached files match this filter.", exact=False)
+    ).to_be_visible()
+    page.get_by_role("searchbox", name="Search cached files", exact=True).fill("")
+    page.get_by_role("button", name="All 2", exact=True).click()
+
+    # Retain tiny-range edge checks above; judge the composition with realistic
+    # synthetic file sizes and actual tier counters, independent of coverage.
+    gib = 1024**3
+    snapshot["cache"]["memory"]["bytes"] = 80 * 1024**2
+    snapshot["cache"]["files"][0].update(
+        name="Prepared movie - director's cut remastered full edition 2026.mp4",
+        size=2 * gib,
+        ready_bytes=2 * gib,
+        ready_ranges=[[0, 2 * gib]],
+    )
+    snapshot["cache"]["files"][1].update(
+        size=gib, ready_ranges=[[0, gib // 10], [gib * 9 // 10, gib]]
+    )
+    snapshot["cache"]["disk"]["bytes"] = 2 * gib + gib // 10 + (gib - gib * 9 // 10)
+    page.get_by_role("button", name="Refresh Cache Inventory").click()
+    expect(page.get_by_role("group", name="Memory cache", exact=True)).to_contain_text(
+        "31%"
+    )
+    expect(page.get_by_role("group", name="Disk cache", exact=True)).to_contain_text(
+        "22%"
+    )
+    page.screenshot(path=ARTIFACTS / "owner-preloads-desktop.png", full_page=True)
+    page.get_by_role("button", name="Evict cached bytes for Interview.mkv").click()
+    dialog = page.get_by_role("dialog", name="Clear cached file?", exact=True)
+    expect(dialog.get_by_role("button", name="Keep Cache")).to_be_focused()
+    assert cleared == []
+    dialog.get_by_role("button", name="Keep Cache").click()
+    expect(dialog).not_to_be_visible()
+    page.get_by_role("button", name="Evict cached bytes for Interview.mkv").click()
+    dialog.get_by_role("button", name="Clear Cached File", exact=True).click()
+    feedback = page.get_by_text(
+        "Cached bytes evicted. The original is unchanged.", exact=True
+    )
+    expect(feedback).to_have_count(1)
+    expect(feedback).to_be_visible()
+    assert cleared == [{"file_id": "partial-file"}]
+    page.get_by_role("button", name="Dismiss Notification").click()
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.evaluate("document.documentElement.dataset.theme = 'dark'")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    expect(
+        page.get_by_role("searchbox", name="Search cached files", exact=True)
+    ).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "owner-preloads-mobile-dark.png", full_page=True)
+
+    # The same coverage and controls stay usable in compact layouts and themes.
+    for width, theme in [
+        (1440, "light"),
+        (1440, "dark"),
+        (390, "light"),
+        (390, "dark"),
+        (320, "dark"),
+    ]:
+        page.set_viewport_size({"width": width, "height": 900})
+        page.evaluate("theme => document.documentElement.dataset.theme = theme", theme)
+        if width == 320 and theme == "dark":
+            brand = page.locator(".mobile-brand .brand-logo")
+            expect(brand.locator("img:visible")).to_have_count(1)
+            expect(brand.locator(".brand-logo-dark")).not_to_be_visible()
+            expect(brand.locator(".brand-logo-icon")).to_be_visible()
+        if width <= 640:
+            selector = page.get_by_role("combobox", name="Filter cached files")
+            selector.select_option("ready")
+            expect(page.locator(".cached-file")).to_have_count(1)
+            expect(page.locator(".cached-file")).to_contain_text("Prepared movie")
+            selector.select_option("partial")
+            expect(page.locator(".cached-file")).to_contain_text("Interview.mkv")
+            selector.select_option("all")
+        expect(page.locator(".cached-file")).to_have_count(2)
+        assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+        page.screenshot(
+            path=ARTIFACTS / f"preloads-compact-{width}-{theme}.png", full_page=True
+        )
+
+    help_panel = page.locator(".preload-help")
+    summary = help_panel.get_by_text("About preloading", exact=True)
+    summary.focus()
+    page.keyboard.press("Enter")
+    expect(help_panel).to_have_attribute("open", "")
+    expect(
+        help_panel.get_by_role("link", name="Read the preloading guide")
+    ).to_have_attribute(
+        "href",
+        "https://github.com/TechShreyash/TGDrive/blob/main/docs/usage.md"
+        "#preload-a-file-for-smoother-playback-and-downloads",
+    )
+    expect(help_panel).to_contain_text("downloads fetch their requested ranges")
+    page.keyboard.press("Enter")
+    expect(help_panel).not_to_have_attribute("open", "")
+
+    cancellations = []
+
+    def cancel(route):
+        cancellations.append(route.request.url)
+        snapshot["jobs"][0]["state"] = "cancelled"
+        snapshot["active_jobs"] = 0
+        route.fulfill(json={"status": "ok"})
+
+    page.route("**/api/v1/preloads/active/cancel", cancel)
+    page.get_by_role("button", name="Cancel preload of Interview.mkv").click()
+    expect(
+        page.get_by_role("button", name="Cancel preload of Interview.mkv")
+    ).to_have_count(0)
+    assert len(cancellations) == 1
+    expect(partial.locator(".cache-ready-state")).to_have_text("Partial")
+
+    page.get_by_role("button", name="Clear Cache", exact=True).click()
+    all_dialog = page.get_by_role("dialog", name="Clear all cached files?", exact=True)
+    expect(all_dialog.get_by_role("button", name="Keep Cache")).to_be_focused()
+    assert cleared == [{"file_id": "partial-file"}]
+    all_dialog.get_by_role("button", name="Keep Cache").click()
+    expect(all_dialog).not_to_be_visible()
+    page.get_by_role("button", name="Clear Cache", exact=True).click()
+    all_dialog.get_by_role("button", name="Clear All Cache", exact=True).click()
+    feedback = page.get_by_text(
+        "Cached bytes cleared. Originals remain in Telegram.", exact=True
+    )
+    expect(feedback).to_have_count(1)
+    expect(feedback).to_be_visible()
+    assert cleared == [{"file_id": "partial-file"}, {}]
+
+    snapshot["cache"]["files"] = []
+    snapshot["cache"]["memory"].update(max_bytes=256 * 1024**2, effective_max_bytes=0)
+    snapshot["cache"]["disk"]["available"] = False
+    page.get_by_role("button", name="Refresh Cache Inventory").click()
+    expect(page.get_by_text("No files cached yet", exact=True)).to_be_visible()
+    expect(page.get_by_role("button", name="Clear Cache", exact=True)).to_be_disabled()
+    expect(page.get_by_role("group", name="Server cache usage")).to_contain_text(
+        "Unavailable"
+    )
+    expect(page.get_by_role("group", name="Server cache usage")).not_to_contain_text(
+        "Disabled"
+    )
+    page.screenshot(path=ARTIFACTS / "preloads-empty-unavailable-320-dark.png")
+
+
+def test_performance_views_keyboard_navigation_and_settings_groups(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    snapshot = page.request.get(server.url + "/api/v1/performance").json()
+    page.goto(server.url + "/?view=performance")
+    expect(page.get_by_role("tab", name="Overview", exact=True)).to_be_visible()
+    expect(
+        page.get_by_role("img", name="Measured HTTP send and receive throughput")
+    ).not_to_be_visible()
+    page.screenshot(path=ARTIFACTS / "owner-performance-idle.png", full_page=True)
+    now = time.time()
+    snapshot["traffic"].update(
+        download_bytes_per_second=3 * 1024**2,
+        upload_bytes_per_second=1024**2,
+        history=[
+            {
+                "at": now - 6,
+                "download_bytes": 0,
+                "upload_bytes": 0,
+                "requests": 1,
+                "active": 2,
+                "errors": 0,
+            },
+            {
+                "at": now - 3,
+                "download_bytes": 6 * 1024**2,
+                "upload_bytes": 3 * 1024**2,
+                "requests": 2,
+                "active": 2,
+                "errors": 0,
+            },
+            {
+                "at": now,
+                "download_bytes": 15 * 1024**2,
+                "upload_bytes": 6 * 1024**2,
+                "requests": 3,
+                "active": 2,
+                "errors": 0,
+            },
+        ],
+    )
+    snapshot["telegram"].update(
+        active=2,
+        queued=1,
+        history=[
+            {"at": now - 3, "active": 1, "queued": 0},
+            {"at": now, "active": 2, "queued": 1},
+        ],
+        accounts=[
+            {
+                "name": "Storage bot 1",
+                "kind": "bot",
+                "uploads": 1,
+                "downloads": 1,
+                "combined_limit": 3,
+                "cooldown_seconds": 0,
+                "requests": {
+                    "active": 2,
+                    "queued": 1,
+                    "effective_limit": 8,
+                    "effective_parts_per_second": 24,
+                    "configured_parts_per_second": 24,
+                    "floods": 0,
+                },
+            }
+        ],
+        queue=[
+            {
+                "position": 1,
+                "operation": "download",
+                "priority": "demand",
+                "waiting_seconds": 3,
+                "estimated_wait_seconds": 5,
+            }
+        ],
+    )
+    page.route("**/api/v1/performance", lambda route: route.fulfill(json=snapshot))
+    page.goto(server.url + "/?view=performance")
+    overview = page.get_by_role("tab", name="Overview", exact=True)
+    expect(overview).to_have_attribute("aria-selected", "true")
+    expect(page.get_by_role("tabpanel", name="Overview")).to_be_visible()
+    expect(page.get_by_role("heading", name="Live file transfers")).to_be_visible()
+    expect(page.get_by_text("3 MB/s", exact=True)).to_be_visible()
+    expect(page.get_by_text("1 MB/s", exact=True)).to_be_visible()
+    expect(
+        page.get_by_role("region", name="Container RAM", exact=True)
+    ).not_to_be_visible()
+    expect(
+        page.get_by_role("heading", name="Storage & cache", exact=True)
+    ).not_to_be_visible()
+    overview.focus()
+    page.keyboard.press("ArrowRight")
+    expect(page.get_by_role("tab", name="Accounts", exact=True)).to_be_focused()
+    expect(page.get_by_role("heading", name="Account capacity")).to_be_visible()
+    expect(page.get_by_role("heading", name="Waiting for Telegram")).to_be_visible()
+    expect(page.get_by_role("cell", name="About 5s", exact=True)).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "owner-performance-accounts.png", full_page=True)
+    page.get_by_role("tab", name="Accounts", exact=True).focus()
+    page.keyboard.press("End")
+    page.keyboard.press("Enter")
+    expect(
+        page.get_by_role("heading", name="Storage & cache", exact=True)
+    ).to_be_visible()
+    expect(
+        page.get_by_role("progressbar", name="Cache filesystem", exact=True)
+    ).to_be_visible()
+    assert (
+        page.get_by_role("heading", name="Storage & cache")
+        .locator("xpath=ancestor::details")
+        .count()
+        == 0
+    )
+    page.screenshot(path=ARTIFACTS / "owner-performance-resources.png", full_page=True)
+    page.get_by_role("tab", name="Overview", exact=True).click()
+    page.screenshot(path=ARTIFACTS / "owner-performance-desktop.png", full_page=True)
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.evaluate("document.documentElement.dataset.theme = 'dark'")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(
+        path=ARTIFACTS / "owner-performance-mobile-dark.png", full_page=True
+    )
+    for tab in ["Accounts", "Resources"]:
+        page.get_by_role("tab", name=tab, exact=True).click()
+        assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+        page.screenshot(
+            path=ARTIFACTS / f"owner-performance-{tab.lower()}-mobile.png",
+            full_page=True,
+        )
+    page.goto(server.url + "/?view=settings&section=cache")
+    expect(page.get_by_role("group", name="Cache storage", exact=True)).to_be_visible()
+    expect(
+        page.get_by_role("group", name="Automatic preloading", exact=True)
+    ).to_be_visible()
+    expect(
+        page.get_by_role("button", name="Save Performance Settings")
+    ).to_be_disabled()
+    page.get_by_label("Memory cache (MiB)", exact=True).fill("512")
+    expect(page.get_by_text("Unsaved changes", exact=True)).to_be_visible()
+    expect(page.get_by_role("button", name="Save Performance Settings")).to_be_enabled()
+    with page.expect_response(
+        lambda response: (
+            response.request.method == "PATCH"
+            and response.url.endswith("/api/v1/settings/performance")
+        )
+    ) as saved:
+        page.get_by_role("button", name="Save Performance Settings").click()
+    assert saved.value.ok, saved.value.text()
+    assert saved.value.json()["cache_memory_bytes"] == 512 * 1024**2
+    expect(page.locator(".toast")).to_have_text("Performance settings saved.")
+    expect(page.get_by_label("Memory cache (MiB)", exact=True)).to_have_value("512")
+    expect(
+        page.get_by_role("button", name="Save Performance Settings")
+    ).to_be_disabled()
+    page.screenshot(
+        path=ARTIFACTS / "owner-performance-settings-mobile.png", full_page=True
+    )
+
+
+def test_network_includes_url_downloads_and_resources_use_container_limits(
+    server, desktop
+):
+    _, page = desktop
+    login(page, server.url)
+    snapshot = page.request.get(server.url + "/api/v1/performance").json()
+    snapshot["server"]["network"] = {
+        "available": True,
+        "interface": "eth0",
+        "started_at": time.time() - 120,
+        "received_bytes": 1024**3,
+        "sent_bytes": 2 * 1024**2,
+        "received_bytes_per_second": 12 * 1024**2,
+        "sent_bytes_per_second": 0,
+        "scope": "Default-route interface in the application's network namespace",
+    }
+    snapshot["server"]["cpu"] = {"percent": 25, "scope": "cgroup", "capacity_cores": 4}
+    snapshot["server"]["memory"] = {
+        "MemTotal": 16 * 1024**3,
+        "MemAvailable": 10 * 1024**3,
+        "cgroup_current": 2 * 1024**3,
+        "cgroup_limit": 8 * 1024**3,
+    }
+    snapshot["traffic"].update(
+        download_bytes=0,
+        upload_bytes=0,
+        download_bytes_per_second=0,
+        upload_bytes_per_second=0,
+        history=[],
+    )
+    now = time.time()
+    snapshot["server"]["history"] = [
+        {
+            "at": now - (6 - index) * 3,
+            "cpu_percent": percent,
+            "cpu_scope": "cgroup",
+            "memory_bytes": int(memory * 1024**3) if memory is not None else None,
+            "memory_limit_bytes": 8 * 1024**3,
+            "received_bytes_per_second": incoming * 1024**2
+            if incoming is not None
+            else None,
+            "sent_bytes_per_second": outgoing * 1024**2
+            if outgoing is not None
+            else None,
+            "network_interface": "eth0",
+        }
+        for index, (percent, memory, incoming, outgoing) in enumerate(
+            [
+                (10, 1, 2, 1),
+                (15, 1.3, 4, 2),
+                (20, 1.7, 5, 3),
+                (None, None, None, None),
+                (30, 1.8, 8, 1),
+                (40, 2.3, 10, 2),
+                (25, 2, 12, 0),
+            ]
+        )
+    ]
+    page.route("**/api/v1/performance", lambda route: route.fulfill(json=snapshot))
+    page.goto(server.url + "/?view=performance")
+    network = page.get_by_role("region", name="Network traffic", exact=True)
+    expect(network).to_contain_text("12 MB/s")
+    expect(network).to_contain_text(
+        "Includes Telegram, URL downloads, device uploads and viewer downloads"
+    )
+    expect(
+        page.get_by_role("img", name="Network traffic over time", exact=True)
+    ).to_be_visible()
+    expect(network.locator("polyline.performance-plot-active")).to_have_count(2)
+    plot = network.locator(".performance-chart-plot")
+    bounds = network.get_by_role("img").bounding_box()
+    positions = []
+    for fraction in (0.2, 0.65, 0.98):
+        pointer_x = bounds["x"] + bounds["width"] * fraction
+        page.mouse.move(pointer_x, bounds["y"] + bounds["height"] * 0.45)
+        tooltip = network.locator(".performance-chart-tooltip")
+        expect(tooltip).to_be_visible()
+        tip = tooltip.bounding_box()
+        frame = plot.bounding_box()
+        assert tip["x"] >= frame["x"]
+        assert tip["x"] + tip["width"] <= frame["x"] + frame["width"] + 1
+        positions.append(tip["x"])
+    assert positions[1] > positions[0] + 100
+    expect(network.locator("svg title")).to_have_count(0)
+
+    expect(
+        page.get_by_role("region", name="Container RAM", exact=True)
+    ).not_to_be_visible()
+    file_traffic = page.locator(
+        "section",
+        has=page.get_by_role("heading", name="Live file transfers", exact=True),
+    ).last
+    expect(file_traffic).to_contain_text("0 B/s")
+    page.get_by_role("tab", name="Resources", exact=True).click()
+    cpu = page.get_by_role("region", name="Container CPU", exact=True)
+    expect(cpu.locator(".performance-chart-axis")).to_contain_text("100.0%")
+    slider = cpu.get_by_role("slider", name="Inspect Container CPU samples", exact=True)
+    slider.focus()
+    slider.press("Home")
+    slider.press("ArrowRight")
+    slider.press("ArrowRight")
+    slider.press("ArrowRight")
+    expect(slider).to_have_attribute("aria-valuetext", re.compile("no reading"))
+    expect(cpu.locator(".performance-chart-readout")).to_contain_text("No reading")
+    cpu.get_by_role("button", name="Live", exact=True).click()
+    expect(cpu.locator(".performance-chart-readout")).to_contain_text("25.0%")
+    ram = page.get_by_role("region", name="Container RAM", exact=True)
+    expect(ram.locator(".performance-chart-heading")).to_contain_text("2 GB / 8 GB")
+    expect(ram.locator(".performance-chart-axis")).to_contain_text("8 GB")
+    page.set_viewport_size({"width": 1440, "height": 1100})
+    page.get_by_role(
+        "heading", name="Performance", exact=True
+    ).scroll_into_view_if_needed()
+    page.screenshot(
+        path=ARTIFACTS / "owner-performance-network-container.png", full_page=False
+    )
+    snapshot["server"]["memory"]["cgroup_limit"] = None
+    page.get_by_role("button", name="Refresh Performance", exact=True).click()
+    expect(ram).to_contain_text("No container memory limit.")
+    page.set_viewport_size({"width": 390, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.get_by_role(
+        "heading", name="Performance", exact=True
+    ).scroll_into_view_if_needed()
+    page.screenshot(
+        path=ARTIFACTS / "owner-performance-network-mobile.png", full_page=False
+    )
+    cpu.get_by_role(
+        "heading", name="Container CPU", exact=True
+    ).scroll_into_view_if_needed()
+    page.screenshot(
+        path=ARTIFACTS / "owner-performance-resource-graphs-mobile.png", full_page=False
+    )
+    snapshot["server"]["history"] = []
+    page.get_by_role("button", name="Refresh Performance", exact=True).click()
+    expect(
+        page.get_by_role("img", name="Network traffic over time", exact=True)
+    ).to_have_count(0)
+    page.get_by_role("tab", name="Overview", exact=True).click()
+    expect(network.locator(".performance-chart-heading")).to_contain_text("12 MB/s")
+    expect(network.locator(".performance-chart-collecting")).to_be_visible()
diff --git a/tests/browser/test_browser_player_controls.py b/tests/browser/test_browser_player_controls.py
new file mode 100644
index 00000000..06715998
--- /dev/null
+++ b/tests/browser/test_browser_player_controls.py
@@ -0,0 +1,533 @@
+"""Integrated chapters and truthful decoded-readiness regression coverage."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import shutil
+import struct
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from tests.browser.test_browser_e2e import ARTIFACTS, ROOT, Server, expect, login
+
+pytestmark = pytest.mark.e2e
+pytest_plugins = ("tests.browser.test_browser_e2e",)
+
+
+def _serve_media(
+    page: Any, payload: bytes, content_type: str = "video/x-matroska"
+) -> None:
+    def serve(route: Any) -> None:
+        request = route.request
+        headers = {"Accept-Ranges": "bytes", "Content-Type": content_type}
+        if request.method == "HEAD":
+            headers["Content-Length"] = str(len(payload))
+            route.fulfill(status=200, headers=headers, body=b"")
+            return
+        match = re.fullmatch(r"bytes=(\d+)-(\d*)", request.headers.get("range", ""))
+        if match:
+            start = int(match[1])
+            end = min(int(match[2]) if match[2] else len(payload) - 1, len(payload) - 1)
+            headers["Content-Range"] = f"bytes {start}-{end}/{len(payload)}"
+            route.fulfill(status=206, headers=headers, body=payload[start : end + 1])
+        else:
+            route.fulfill(status=200, headers=headers, body=payload)
+
+    page.route("**/file?*", serve)
+
+
+def test_chapters_belong_to_autohiding_player_controls(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    metadata = tmp_path / "chapters.txt"
+    metadata.write_text(
+        ";FFMETADATA1\n[CHAPTER]\nTIMEBASE=1/1000\nSTART=0\nEND=2000\n"
+        "title=Opening\n[CHAPTER]\nTIMEBASE=1/1000\nSTART=2000\nEND=5000\n"
+        "title=Second chapter\n"
+    )
+    output = tmp_path / "chapters.mkv"
+    ffmpeg = shutil.which("ffmpeg")
+    assert ffmpeg, "The media browser tests require FFmpeg"
+    subprocess.run(  # noqa: S603 - fixed self-generated local media
+        [
+            ffmpeg,
+            "-v",
+            "error",
+            "-i",
+            str(ROOT / "tests/fixtures/multitrack.mkv"),
+            "-i",
+            str(metadata),
+            "-map",
+            "0",
+            "-map_metadata",
+            "1",
+            "-c",
+            "copy",
+            str(output),
+        ],
+        check=True,
+    )
+    payload = output.read_bytes()
+
+    _serve_media(page, payload)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    chapter = player.locator(".movi-chapter-pill")
+    expect(chapter).to_be_visible(timeout=30000)
+    assert chapter.evaluate("el=>!!el.closest('.movi-controls-bar')")
+    expect(page.locator("details.advanced-chapters")).to_have_count(0)
+    expect(player.locator(".advanced-chapters")).to_have_count(0)
+    player.evaluate("""element => {
+      element.__previewFrameReads = 0;
+      const preview = element.player.getPreviewFrame.bind(element.player);
+      element.player.getPreviewFrame = (...args) => {
+        element.__previewFrameReads++;
+        return preview(...args);
+      };
+    }""")
+    chapter.click()
+    panel = player.get_by_role("region", name="Chapters", exact=True)
+    expect(panel).to_be_visible()
+    expect(panel.locator(".movi-timeline-noframe")).to_have_count(2)
+    expect(panel.locator("img")).to_have_count(0)
+    assert player.evaluate("element => element.__previewFrameReads") == 0
+    expect(
+        panel.get_by_role("button", name="Second chapter 0:02", exact=True)
+    ).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "chapters-integrated-desktop.png", full_page=False)
+    page.set_viewport_size({"width": 390, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    expect(panel).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "chapters-integrated-mobile.png", full_page=False)
+    panel.get_by_role("button", name="Second chapter 0:02", exact=True).click()
+    expect(panel).to_be_visible()
+    page.wait_for_function(
+        "()=>document.querySelector('movi-player')?.currentTime>=1.9"
+    )
+    panel.locator(".movi-timeline-close").click()
+    expect(panel).not_to_be_visible()
+    page.set_viewport_size({"width": 1440, "height": 960})
+    player.hover()
+    player.locator("button.movi-play-pause").click()
+    page.mouse.move(0, 0)
+    page.wait_for_function("""() => document.querySelector('movi-player')?.shadowRoot
+      .querySelector('.movi-controls-container')?.classList.contains('movi-controls-hidden')""")
+    assert chapter.evaluate("el=>!!el.closest('.movi-controls-hidden')")
+
+
+@pytest.mark.parametrize("output_latency", [0.0, 0.5])
+def test_seek_waits_for_delayed_decoded_audio_without_fake_buffer_percentage(
+    server: Server, desktop: tuple[Any, Any], output_latency: float
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function(
+        "()=>document.querySelector('movi-player')?.currentTime>0.25"
+    )
+    player.evaluate(
+        """(el,latency)=>{
+      // Hold real software-decoded PCM briefly: the video source is already loaded.
+      const renderer=el.player.audioRenderer, render=renderer.renderPCM.bind(renderer);
+      if(latency)renderer.expectedStartLead=()=>latency;
+      let holding=true, pending=[];
+      renderer.renderPCM=frame=>holding
+        ?pending.push({...frame,planes:frame.planes.map(plane=>plane.slice())})
+        :render(frame);
+      window.delayedAudio={samples:[],events:[]};
+      window.delayedAudio.timer=setInterval(()=>window.delayedAudio.samples.push({
+        time:el.currentTime,audio:renderer.getBufferedDuration(),
+        state:el.player.getState(),frames:el.player.videoRenderer.getQueueSize()
+      }),50);
+      el.addEventListener('seeking',()=>window.delayedAudio.events.push('seeking'));
+      setTimeout(()=>{
+        holding=false;for(const frame of pending)render(frame);pending=[];
+      },1800);
+      el.currentTime=2;
+    }""",
+        output_latency,
+    )
+    status = page.locator(".advanced-state")
+    expect(status).to_be_visible(timeout=1500)
+    expect(status).not_to_contain_text("% buffered")
+    expect(status).not_to_contain_text("s ahead")
+    indicator = status.get_by_role("progressbar", name="Loading video")
+    expect(indicator).to_be_visible()
+    assert indicator.get_attribute("value") is None
+    # Actual HTTP delivery remains distinct from the deliberately held audio.
+    expect(status).to_contain_text("received")
+    assert status.bounding_box()["height"] < 120
+    expect(status.locator("p")).to_have_count(0)
+    assert player.evaluate("el=>el.player.getSource().getNetworkStats().totalBytes>0")
+    expect(status).to_contain_text("Loading this part…")
+    # Wait feedback never intercepts the controls or offers an early reload.
+    expect(status.get_by_role("button", name="Try again")).to_have_count(0)
+    page.screenshot(path=ARTIFACTS / "seek-waiting-for-real-audio.png", full_page=False)
+    page.wait_for_function(
+        "()=>document.querySelector('movi-player')?.currentTime>2.15"
+    )
+    expect(status).to_have_count(0)
+    result = page.evaluate(
+        "clearInterval(window.delayedAudio.timer);window.delayedAudio"
+    )
+    blocked = [
+        sample
+        for sample in result["samples"]
+        if sample["audio"] == 0 and sample["frames"] > 0
+    ]
+    assert len(blocked) >= 10
+    assert all(abs(sample["time"] - 2) < 0.05 for sample in blocked)
+    assert result["events"] == ["seeking"], (
+        "Audio refill must not re-seek to the old target"
+    )
+
+
+@pytest.mark.parametrize("mode", ["video-only", "muted", "audio-off", "dropping-audio"])
+def test_seek_audio_exceptions_do_not_deadlock(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path, mode: str
+) -> None:
+    _, page = desktop
+    if mode == "video-only":
+        ffmpeg = shutil.which("ffmpeg")
+        assert ffmpeg
+        output = tmp_path / "video-only.mkv"
+        subprocess.run(  # noqa: S603 - self-generated local fixture
+            [
+                ffmpeg,
+                "-v",
+                "error",
+                "-i",
+                str(ROOT / "tests/fixtures/multitrack.mkv"),
+                "-map",
+                "0:v:0",
+                "-c",
+                "copy",
+                "-an",
+                str(output),
+            ],
+            check=True,
+        )
+        _serve_media(page, output.read_bytes())
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function(
+        "()=>document.querySelector('movi-player')?.currentTime>0.25"
+    )
+    player.evaluate(
+        """(el,mode)=>{
+      el.player.audioRenderer.expectedStartLead=()=>0.5;
+      if(mode==='muted'||mode==='dropping-audio')el.muted=true;
+      if(mode==='audio-off')el.player.disableAudio=true;
+      if(mode==='dropping-audio')el.player.audioRenderer.isDroppingAudio=()=>true;
+      window.exceptionSeeks=0;el.addEventListener('seeking',()=>window.exceptionSeeks++);
+      el.currentTime=2;
+    }""",
+        mode,
+    )
+    page.wait_for_function("()=>document.querySelector('movi-player')?.currentTime>2.2")
+    expect(page.locator(".advanced-state")).to_have_count(0)
+    assert page.evaluate("window.exceptionSeeks") == 1
+
+
+def test_frozen_picture_shows_measured_delivery_and_recovers_on_real_frames(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function("()=>document.querySelector('movi-player')?.currentTime>0.3")
+    player.evaluate("""el=>{
+      // Stop real picture presentation while the audio clock keeps moving.
+      // No manufactured waiting/state-change event should be needed for feedback.
+      el.player.videoRenderer.stopPresentationLoop();
+      window.frozenFrameCount=el.getVideoPlaybackQuality().totalVideoFrames;
+    }""")
+    status = page.locator(".advanced-state")
+    expect(status).to_be_visible(timeout=4000)
+    expect(status).to_contain_text("received")
+    assert status.bounding_box()["height"] < 120
+    expect(status.locator("p")).to_have_count(0)
+    expect(status).not_to_contain_text("%")
+    assert player.evaluate(
+        "el=>el.getVideoPlaybackQuality().totalVideoFrames===window.frozenFrameCount"
+    )
+    assert player.evaluate("el=>!el.paused")
+    expect(page.locator(".advanced-player-host")).to_have_attribute("aria-busy", "true")
+    page.screenshot(path=ARTIFACTS / "video-measured-wait.png", full_page=False)
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.screenshot(path=ARTIFACTS / "video-measured-wait-mobile.png", full_page=False)
+    player.evaluate("el=>el.player.videoRenderer.startPresentationLoop()")
+    expect(status).to_have_count(0, timeout=5000)
+    assert player.evaluate(
+        "el=>el.getVideoPlaybackQuality().totalVideoFrames>window.frozenFrameCount"
+    )
+    expect(page.locator(".advanced-player-host")).to_have_attribute(
+        "aria-busy", "false"
+    )
+
+
+@pytest.mark.parametrize("playing", [False, True])
+def test_hevc_capability_never_replaces_the_custom_player(
+    server: Server, desktop: tuple[Any, Any], playing: bool
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    if playing:
+        player.locator("button.movi-play-pause").click()
+        page.wait_for_function(
+            "()=>document.querySelector('movi-player').currentTime>0.25"
+        )
+    player.evaluate("""el=>{
+      window.originalCustomPlayer=el;
+      HTMLMediaElement.prototype.canPlayType=()=>"probably";
+      el.player.getMediaInfo=()=>({formatName:'mov,mp4',tracks:[{
+        type:'video',codecString:'hvc1.1.6.L150.b0'
+      }]});
+      el.dispatchEvent(new Event('canplay'));
+      el.dispatchEvent(new Event('progress'));
+    }""")
+    # Exercise observer ticks as well as readiness; native support cannot opt out
+    # of the custom demux/decoder/render pipeline or replace its feature state.
+    page.wait_for_timeout(1500)
+    assert player.evaluate("el=>el===window.originalCustomPlayer&&el.engine==='wasm'")
+    assert player.evaluate("el=>el.paused") is not playing
+    expect(player.locator("button.movi-play-pause")).to_have_count(1)
+
+
+def test_http_window_is_sized_before_loading_and_keeps_received_bytes(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.add_init_script("Object.defineProperty(navigator,'deviceMemory',{get:()=>8})")
+    original = (ROOT / "tests/fixtures/movtext-subtitles.mp4").read_bytes()
+    padding = 40 * 1024**2 - len(original)
+    payload = original + struct.pack(">I4s", padding, b"free") + bytes(padding - 8)
+    _serve_media(page, payload, "video/mp4")
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="movtext-subtitles.mp4", exact=True).dblclick()
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>5")
+    page.wait_for_function("""()=>{
+      const s=document.querySelector('movi-player')?.player?.getSource();
+      return s?.bufferSize===40*1024**2 && s.isFullyCached();
+    }""")
+    result = page.locator("movi-player").evaluate("""async el=>{
+      const s=el.player.getSource(),bytes=s.dataView||s.fallbackBuffer;
+      const hash=await crypto.subtle.digest('SHA-256',bytes.slice(0,s.getKnownSize()));
+      return {size:s.bufferSize,start:s.getBufferedStart(),
+        head:Array.from(bytes.slice(0,64)),
+        digest:Array.from(new Uint8Array(hash),
+          b=>b.toString(16).padStart(2,'0')).join('')
+      }
+    }""")
+    assert result["size"] == len(payload)
+    assert result["start"] == 0
+    assert result["head"] == list(payload[:64])
+    assert result["digest"] == hashlib.sha256(payload).hexdigest()
+
+
+def test_time_buffer_survives_network_loss_and_ten_second_skips(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    media = tmp_path / "long-video.mp4"
+    subprocess.run(  # noqa: S603 - fixed self-generated media fixture
+        [
+            shutil.which("ffmpeg"),
+            "-v",
+            "error",
+            "-f",
+            "lavfi",
+            "-i",
+            "testsrc2=size=640x360:rate=24",
+            "-t",
+            "180",
+            "-c:v",
+            "libx264",
+            "-preset",
+            "ultrafast",
+            "-crf",
+            "18",
+            "-g",
+            "48",
+            "-movflags",
+            "+faststart",
+            str(media),
+        ],
+        check=True,
+    )
+    payload = media.read_bytes()
+    _serve_media(page, payload, "video/mp4")
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="movtext-subtitles.mp4", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function(
+        "()=>document.querySelector('movi-player')?.duration>170", timeout=30000
+    )
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function(
+        """()=>{
+      const p=document.querySelector('movi-player')?.player,s=p?.getSource();
+      return s?.playbackPrefetchHeld && p.getBufferEndTime()>65;
+    }""",
+        timeout=30000,
+    )
+    coverage = player.evaluate("""el=>({
+      time:el.currentTime,end:el.player.getBufferEndTime(),
+      queued:el.player.videoRenderer.getQueueSize(),
+      bytes:el.player.getSource().getNetworkStats().totalBytes,
+      goal:el.player.getSource().playbackAheadBytes
+    })""")
+    assert coverage["end"] - coverage["time"] > 60
+    assert coverage["queued"] < 150  # Source buffering must not decode 90s of frames.
+    assert coverage["bytes"] < len(payload)
+    failed_requests: list[str] = []
+
+    def offline(route: Any) -> None:
+        failed_requests.append(route.request.url)
+        route.abort("internetdisconnected")
+
+    page.route("**/file?*", offline)
+    # Two forward skips use the prefetched compressed bytes during an outage.
+    player.evaluate("el=>{el.currentTime=10}")
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>10.2")
+    player.evaluate("el=>{el.currentTime=20}")
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>20.2")
+    assert failed_requests == []
+    expect(page.get_by_role("alert")).to_have_count(0)
+
+
+def test_video_only_backpressure_does_not_search_ahead_for_nonexistent_audio(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    media = tmp_path / "video-only.mkv"
+    subprocess.run(  # noqa: S603 - fixed self-generated media fixture
+        [
+            shutil.which("ffmpeg"),
+            "-v",
+            "error",
+            "-i",
+            str(ROOT / "tests/fixtures/multitrack.mkv"),
+            "-map",
+            "0:v:0",
+            "-c",
+            "copy",
+            "-an",
+            str(media),
+        ],
+        check=True,
+        timeout=30,
+    )
+    _serve_media(page, media.read_bytes())
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>0.25")
+    player.evaluate("""el=>{
+      const p=el.player,d=p.videoDecoder,r=p.videoRenderer,m=p.demuxer;
+      if(p.trackManager.getActiveAudioTrack())throw Error('Fixture must be video-only');
+      const read=m.readPacket.bind(m),size=r.getQueueSize.bind(r);
+      window.pressuredReads=0;
+      const eof=p.eofReached,stash=p._videoAheadStash,bytes=p._videoAheadStashBytes;
+      const pending=p.pendingPrebufferPackets;
+      p.eofReached=false;p._videoAheadStash=[];p._videoAheadStashBytes=0;
+      p.pendingPrebufferPackets=[];
+      m.readPacket=async()=>{window.pressuredReads++;return {
+        streamIndex:p.trackManager.getActiveVideoTrack().id,
+        timestamp:el.currentTime+5,dts:el.currentTime+5,duration:1/30,
+        data:new Uint8Array([0]),keyframe:false,isIdr:false
+      }};
+      Object.defineProperty(d,'queueSize',{configurable:true,get:()=>160});
+      r.getQueueSize=()=>100;
+      window.releasePressure=()=>{
+        delete d.queueSize;r.getQueueSize=size;m.readPacket=read;
+        p.eofReached=eof;p._videoAheadStash=stash;p._videoAheadStashBytes=bytes;
+        p.pendingPrebufferPackets=pending};
+    }""")
+    page.wait_for_timeout(500)
+    assert page.evaluate("window.pressuredReads") <= 1
+    player.evaluate("()=>window.releasePressure()")
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>0.9")
+
+
+@pytest.mark.parametrize("failure", ["reconnecting", "error"])
+def test_playback_recovers_without_a_stale_error_panel(
+    server: Server, desktop: tuple[Any, Any], failure: str
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    player.evaluate(
+        """(el,failure)=>{
+          if(failure==='reconnecting')el.dispatchEvent(new CustomEvent('errordisplay',{
+            detail:{title:'Reconnecting…',message:'Retrying automatically…'}
+          }));
+          else el.dispatchEvent(new Event('error'));
+        }""",
+        failure,
+    )
+    if failure == "error":
+        expect(page.get_by_role("alert")).to_contain_text("The video could not play")
+    else:
+        expect(page.get_by_role("alert")).to_have_count(0)
+    # Genuine playback events/frames clear a temporary failure automatically.
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function("()=>document.querySelector('movi-player')?.currentTime>0.3")
+    expect(page.get_by_role("alert")).to_have_count(0)
+    expect(page.locator(".advanced-state")).to_have_count(0)
+
+
+def test_try_again_restores_position_without_starting_a_paused_video(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    player = page.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    player.evaluate("el=>{window.originalPlayer=el;el.currentTime=1.5}")
+    page.wait_for_function(
+        "()=>Math.abs(document.querySelector('movi-player').currentTime-1.5)<0.1"
+        "&&!document.querySelector('movi-player').seeking"
+    )
+    player.evaluate("el=>el.dispatchEvent(new Event('error'))")
+    page.get_by_role("button", name="Try again", exact=True).click()
+    page.wait_for_function(
+        "()=>{const el=document.querySelector('movi-player');"
+        "return el&&el!==window.originalPlayer&&el.duration>4"
+        "&&Math.abs(el.currentTime-1.5)<0.1&&!el.seeking}"
+    )
+    assert player.evaluate("el=>el.paused") is True
+    expect(page.get_by_role("alert")).to_have_count(0)
diff --git a/tests/browser/test_browser_player_gestures.py b/tests/browser/test_browser_player_gestures.py
new file mode 100644
index 00000000..1f6afc9f
--- /dev/null
+++ b/tests/browser/test_browser_player_gestures.py
@@ -0,0 +1,258 @@
+"""Actual touchscreen gestures against a generated 65-second video and real decoder."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import expect, login, preview_dialog
+
+browser, server = fixtures.browser, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.fixture(scope="session")
+def long_video_bytes(tmp_path_factory):
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        pytest.skip("ffmpeg is needed to generate the real long-video fixture")
+    path = tmp_path_factory.mktemp("player-long-video") / "long.mp4"
+    subprocess.run(  # noqa: S603 - fixed local ffmpeg binary and generated sources
+        [
+            ffmpeg,
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-nostdin",
+            "-f",
+            "lavfi",
+            "-i",
+            "testsrc2=size=160x90:rate=12",
+            "-f",
+            "lavfi",
+            "-i",
+            "sine=frequency=440:sample_rate=22050",
+            "-t",
+            "65",
+            "-c:v",
+            "libx264",
+            "-preset",
+            "ultrafast",
+            "-pix_fmt",
+            "yuv420p",
+            "-g",
+            "12",
+            "-c:a",
+            "aac",
+            "-b:a",
+            "16k",
+            "-movflags",
+            "+faststart",
+            "-y",
+            str(path),
+        ],
+        check=True,
+        timeout=30,
+        capture_output=True,
+    )
+    return path.read_bytes()
+
+
+def route_long_media(page, content):
+    def serve(route):
+        total = len(content)
+        range_header = route.request.headers.get("range", "")
+        start, end, status = 0, total - 1, 200
+        if range_header.startswith("bytes="):
+            first, _, last = range_header[6:].partition("-")
+            start = int(first) if first else max(0, total - int(last))
+            end = min(total - 1, int(last)) if first and last else total - 1
+            status = 206
+        headers = {
+            "Content-Type": "video/mp4",
+            "Accept-Ranges": "bytes",
+            "Content-Length": str(max(0, end - start + 1)),
+        }
+        if status == 206:
+            headers["Content-Range"] = f"bytes {start}-{end}/{total}"
+        route.fulfill(
+            status=status,
+            headers=headers,
+            body=b"" if route.request.method == "HEAD" else content[start : end + 1],
+        )
+
+    page.route("**/file?*", serve)
+
+
+@pytest.fixture
+def touch_player(server, browser, long_video_bytes):
+    context = browser.new_context(
+        viewport={"width": 900, "height": 500}, has_touch=True, is_mobile=True
+    )
+    page = context.new_page()
+    page.set_default_timeout(10000)
+    errors = []
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    route_long_media(page, long_video_bytes)
+    try:
+        login(page, server.url)
+        for name in ("Preview samples", "multitrack.mkv"):
+            page.get_by_role("button", name=name, exact=True).tap()
+        dialog = preview_dialog(page)
+        player = dialog.locator("movi-player")
+        expect(player).to_be_visible(timeout=30000)
+        page.wait_for_function(
+            "() => document.querySelector('movi-player')?.duration > 60"
+        )
+        expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+        player.evaluate("element => { element.loop = false; }")
+        yield page, player, context
+        assert errors == []
+    finally:
+        context.close()
+
+
+def seek_to(page, player, position):
+    player.evaluate(
+        """async (element, time) => {
+          await element.pause(); element.currentTime = time;
+        }""",
+        position,
+    )
+    page.wait_for_function(
+        """time => {
+          const p=document.querySelector('movi-player');
+          return !p.seeking && Math.abs(p.currentTime-time)<0.3;
+        }""",
+        arg=position,
+    )
+    # Start a new tap chain independently of any preceding seek confirmation.
+    page.wait_for_timeout(1100)
+
+
+def tap_surface(page, player, side, count=1):
+    rect = player.bounding_box()
+    fraction = {"left": 0.2, "center": 0.5, "right": 0.8}[side]
+    x = rect["x"] + rect["width"] * fraction
+    # Stay clear of the central Play button and bottom playback controls.
+    y = rect["y"] + rect["height"] * 0.25
+    for _ in range(count):
+        page.touchscreen.tap(x, y)
+        page.wait_for_timeout(70)
+
+
+def wait_time(page, position, tolerance=0.5):
+    page.wait_for_function(
+        """value => {
+          const p=document.querySelector('movi-player');
+          return !p.seeking && Math.abs(p.currentTime-value.time)<value.tolerance;
+        }""",
+        arg={"time": position, "tolerance": tolerance},
+    )
+
+
+def test_touch_double_taps_seek_ten_seconds_and_repeated_taps_accumulate(touch_player):
+    page, player, _ = touch_player
+    await_pointer_events = []
+    page.expose_function(
+        "recordTouchPointer", lambda kind: await_pointer_events.append(kind)
+    )
+    player.evaluate(
+        """element => element.addEventListener('pointerdown', event => {
+          if(event.pointerType==='touch') window.recordTouchPointer(event.pointerType);
+        }, true)"""
+    )
+    seek_to(page, player, 20)
+    tap_surface(page, player, "right", 2)
+    wait_time(page, 30)
+    assert player.evaluate("element => element.paused")
+    seek_to(page, player, 20)
+    tap_surface(page, player, "right", 4)
+    wait_time(page, 50)
+    seek_to(page, player, 30)
+    tap_surface(page, player, "left", 2)
+    wait_time(page, 20)
+    assert player.evaluate("element => element.paused")
+    assert len(await_pointer_events) >= 8
+
+
+def test_touch_seek_preserves_playback_and_clamps_file_bounds(touch_player):
+    page, player, _ = touch_player
+    seek_to(page, player, 20)
+    player.locator("button.movi-play-pause").tap()
+    page.wait_for_function("() => !document.querySelector('movi-player').paused")
+    tap_surface(page, player, "right", 2)
+    page.wait_for_function(
+        "() => document.querySelector('movi-player').currentTime >= 30"
+    )
+    assert not player.evaluate("element => element.paused")
+    seek_to(page, player, 3)
+    tap_surface(page, player, "left", 2)
+    wait_time(page, 0)
+    seek_to(page, player, 62)
+    tap_surface(page, player, "right", 2)
+    wait_time(page, player.evaluate("element => element.duration"))
+    assert player.evaluate("element => element.currentTime <= element.duration")
+
+
+def test_touch_single_tap_toggles_controls_and_menu_taps_never_seek(touch_player):
+    page, player, _ = touch_player
+    seek_to(page, player, 20)
+    player.evaluate("element => element.showControls()")
+    tap_surface(page, player, "center")
+    page.wait_for_timeout(450)
+    assert not player.evaluate("element => element.areControlsVisible()")
+    tap_surface(page, player, "center")
+    page.wait_for_timeout(450)
+    assert player.evaluate("element => element.areControlsVisible()")
+    assert player.evaluate("element => element.paused")
+    settings = player.locator("button.movi-settings-btn")
+    if not settings.is_visible():
+        player.locator("button.movi-more-btn").tap()
+    settings.tap()
+    expect(player.locator(".movi-settings-menu")).to_be_visible()
+    tap_surface(page, player, "left", 2)
+    wait_time(page, 20)
+    assert player.evaluate("element => element.paused")
+    expect(player.locator(".movi-settings-menu")).not_to_be_visible()
+    assert not player.evaluate("element => element.isFullscreenActive()")
+    page.wait_for_timeout(500)
+    tap_surface(page, player, "left", 2)
+    wait_time(page, 10)
+
+
+def test_touch_drag_and_multitouch_do_not_become_double_tap_seeks(touch_player):
+    page, player, context = touch_player
+    seek_to(page, player, 20)
+    rect = player.bounding_box()
+    x, y = rect["x"] + rect["width"] * 0.2, rect["y"] + rect["height"] * 0.45
+    cdp = context.new_cdp_session(page)
+    first = {"x": x, "y": y, "id": 1}
+    second = {"x": x + 30, "y": y, "id": 2}
+    cdp.send("Input.dispatchTouchEvent", {"type": "touchStart", "touchPoints": [first]})
+    # Exceed the player's 20px tap slop without asking the browser to perform
+    # its own horizontal history-back swipe (an 80px drag can navigate away).
+    cdp.send(
+        "Input.dispatchTouchEvent",
+        {"type": "touchMove", "touchPoints": [{**first, "x": x + 24}]},
+    )
+    cdp.send("Input.dispatchTouchEvent", {"type": "touchEnd", "touchPoints": []})
+    page.wait_for_timeout(500)
+    expect(player).to_be_visible()
+    wait_time(page, 20)
+    cdp.send("Input.dispatchTouchEvent", {"type": "touchStart", "touchPoints": [first]})
+    cdp.send(
+        "Input.dispatchTouchEvent",
+        {"type": "touchStart", "touchPoints": [first, second]},
+    )
+    cdp.send("Input.dispatchTouchEvent", {"type": "touchEnd", "touchPoints": [first]})
+    cdp.send("Input.dispatchTouchEvent", {"type": "touchEnd", "touchPoints": []})
+    page.wait_for_timeout(500)
+    wait_time(page, 20)
diff --git a/tests/browser/test_browser_player_mobile.py b/tests/browser/test_browser_player_mobile.py
new file mode 100644
index 00000000..679ff5ab
--- /dev/null
+++ b/tests/browser/test_browser_player_mobile.py
@@ -0,0 +1,396 @@
+"""One compact settings menu and familiar mouse/keyboard video controls."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import pytest
+
+import tests.browser.test_browser_player_gestures as gestures
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    Server,
+    expect,
+    login,
+    preview_dialog,
+)
+
+pytestmark = pytest.mark.e2e
+pytest_plugins = ("tests.browser.test_browser_e2e",)
+long_video_bytes = gestures.long_video_bytes
+
+
+def _open_video(
+    page: Any,
+    server: Server,
+    *,
+    touch: bool = False,
+    filename: str = "multitrack.mkv",
+) -> tuple[Any, Any]:
+    login(page, server.url)
+    for name in ("Preview samples", filename):
+        button = page.get_by_role("button", name=name, exact=True)
+        button.tap() if touch else button.press("Enter")
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    return dialog, player
+
+
+def _assert_bounded(control: Any, width: int, height: int) -> None:
+    expect(control).to_be_in_viewport(ratio=1)
+    bounds = control.bounding_box()
+    assert bounds is not None
+    assert bounds["x"] >= -1 and bounds["x"] + bounds["width"] <= width + 1, bounds
+    assert bounds["y"] >= -1 and bounds["y"] + bounds["height"] <= height + 1, bounds
+
+
+@pytest.mark.parametrize("width,height", [(320, 740), (390, 844), (720, 360)])
+def test_small_touch_players_have_one_settings_menu_and_visible_fullscreen(
+    server: Server, browser: Any, width: int, height: int
+) -> None:
+    context = browser.new_context(
+        viewport={"width": width, "height": height}, has_touch=True, is_mobile=True
+    )
+    page = context.new_page()
+    page.set_default_timeout(10000)
+    errors: list[str] = []
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    try:
+        _, player = _open_video(page, server, touch=True)
+        player.tap(
+            position={
+                "x": width * 0.25,
+                "y": player.evaluate("element=>element.clientHeight") * 0.35,
+            }
+        )
+        expect(player.locator(".movi-controls-container")).to_have_class(
+            re.compile("movi-controls-visible")
+        )
+        settings = player.get_by_role("button", name="Settings", exact=True)
+        expect(settings).to_have_count(1)
+        expect(settings).to_be_visible()
+        expect(player.locator("button.movi-more-btn")).not_to_be_visible()
+        fullscreen = player.locator("button.movi-fullscreen-btn")
+        expect(fullscreen).to_be_visible()
+        _assert_bounded(settings, width, height)
+        _assert_bounded(fullscreen, width, height)
+        settings.tap()
+        menu = player.locator(".movi-settings-menu")
+        expect(menu).to_be_visible()
+        _assert_bounded(menu, width, height)
+        fit = menu.get_by_role("button", name="Aspect", exact=False)
+        fit.scroll_into_view_if_needed()
+        expect(fit).to_be_in_viewport()
+        if page.evaluate("'documentPictureInPicture' in window"):
+            pip = menu.get_by_role("button", name="Picture in picture", exact=True)
+            pip.scroll_into_view_if_needed()
+            expect(pip).to_be_in_viewport()
+        expect(menu.get_by_role("button", name="Chapters", exact=True)).to_have_count(0)
+        # Public chapter metadata exercises discoverability without frame artwork.
+        player.evaluate("""element=>{
+          element.__previewFrameReads = 0;
+          const preview = element.player.getPreviewFrame.bind(element.player);
+          element.player.getPreviewFrame = (...args) => {
+            element.__previewFrameReads++;
+            return preview(...args);
+          };
+          element.player.setChapters([
+            {title:'Opening',start:0},{title:'Next scene',start:2}
+          ]);
+          element.dispatchEvent(new Event('loadedmetadata'));
+        }""")
+        page.wait_for_function("""()=>document.querySelector('movi-player')?.shadowRoot
+          ?.querySelector('.movi-chapter-pill')""")
+        chapters = menu.get_by_role("button", name="Chapters", exact=True)
+        chapters.scroll_into_view_if_needed()
+        expect(chapters).to_be_in_viewport()
+        assert player.evaluate("element=>element.scrollLeft===0&&element.scrollTop===0")
+        chapters.tap()
+        panel = player.get_by_role("region", name="Chapters", exact=True)
+        expect(panel).to_be_visible()
+        expect(panel.locator(".movi-timeline-noframe")).to_have_count(2)
+        expect(panel.locator("img")).to_have_count(0)
+        assert player.evaluate("element => element.__previewFrameReads") == 0
+        _assert_bounded(panel, width, height)
+        panel.get_by_role("button", name="Next scene 0:02", exact=True).tap()
+        page.wait_for_function(
+            "()=>document.querySelector('movi-player').currentTime>1.8"
+        )
+        expect(panel).to_be_visible()
+        assert player.evaluate("element=>element.paused")
+        panel.locator(".movi-timeline-close").tap()
+        expect(panel).not_to_be_visible()
+        expect(settings).to_be_visible()
+        settings.tap()
+        expect(menu).to_be_visible()
+        menu.evaluate("element=>element.scrollTop=0")
+        _assert_bounded(menu, width, height)
+        expect(menu).to_have_css("opacity", "1")
+        expect(player.locator(".movi-controls-container")).to_have_css("opacity", "1")
+        assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=ARTIFACTS / f"single-settings-touch-{width}x{height}.png")
+        assert errors == []
+    finally:
+        context.close()
+
+
+def test_original_only_phone_settings_menu_is_clear_and_has_no_quality_row(
+    server: Server, browser: Any
+) -> None:
+    context = browser.new_context(
+        viewport={"width": 390, "height": 844}, has_touch=True, is_mobile=True
+    )
+    page = context.new_page()
+    try:
+        _, player = _open_video(
+            page, server, touch=True, filename="movtext-subtitles.mp4"
+        )
+        player.tap(position={"x": 100, "y": 200})
+        expect(player.locator(".movi-controls-container")).to_have_class(
+            re.compile("movi-controls-visible")
+        )
+        settings = player.get_by_role("button", name="Settings", exact=True)
+        settings.tap()
+        menu = player.locator(".movi-settings-menu")
+        expect(menu).to_have_css("opacity", "1")
+        expect(player.locator(".movi-controls-container")).to_have_css("opacity", "1")
+        _assert_bounded(menu, 390, 844)
+        expect(menu.locator('[data-page="quality"]')).to_have_count(0)
+        expect(player.locator("button.movi-more-btn")).not_to_be_visible()
+        expect(settings).to_have_count(1)
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=ARTIFACTS / "single-settings-original-touch-390x844.png")
+    finally:
+        context.close()
+
+
+def test_desktop_picture_clicks_and_standard_keyboard_shortcuts(
+    server: Server, desktop: tuple[Any, Any], long_video_bytes: bytes
+) -> None:
+    _, page = desktop
+    gestures.route_long_media(page, long_video_bytes)
+    dialog, player = _open_video(page, server)
+    page.wait_for_function("()=>document.querySelector('movi-player').duration>60")
+    picture = {"x": 500, "y": 300}
+    player.click(position=picture)
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>0.3")
+    player.click(position=picture)
+    expect(player).to_have_js_property("paused", True)
+    player.dblclick(position=picture)
+    page.wait_for_function("()=>!!document.fullscreenElement")
+    assert player.evaluate("element=>element.paused")
+    player.press("f")
+    page.wait_for_function("()=>!document.fullscreenElement")
+    player.focus()
+    player.press("Space")
+    expect(player).to_have_js_property("paused", False)
+    player.press("k")
+    expect(player).to_have_js_property("paused", True)
+    gestures.seek_to(page, player, 20)
+    player.focus()
+    player.press("ArrowRight")
+    page.wait_for_function("""()=>{
+      const player=document.querySelector('movi-player');
+      return !player.seeking&&Math.abs(player.currentTime-30)<0.4;
+    }""")
+    player.press("ArrowLeft")
+    page.wait_for_function("""()=>{
+      const player=document.querySelector('movi-player');
+      return !player.seeking&&Math.abs(player.currentTime-20)<0.4;
+    }""")
+    before = player.evaluate("element=>element.muted")
+    player.press("m")
+    assert player.evaluate("element=>element.muted") is not before
+    player.press("m")
+    assert player.evaluate("element=>element.muted") is before
+    player.press("f")
+    page.wait_for_function("()=>!!document.fullscreenElement")
+    player.press("Escape")
+    page.wait_for_function("()=>!document.fullscreenElement")
+    expect(dialog).to_be_visible()
+
+
+def test_settings_keyboard_activation_and_escape_preserve_playback_and_preview(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    dialog, player = _open_video(page, server)
+    settings = player.get_by_role("button", name="Settings", exact=True)
+    settings.focus()
+    settings.press("Space")
+    menu = player.locator(".movi-settings-menu")
+    expect(menu).to_be_visible()
+    assert player.evaluate("element=>element.paused")
+    repeat = menu.get_by_role("button", name="Loop", exact=True)
+    volume = player.evaluate("element=>element.volume")
+    time = player.evaluate("element=>element.currentTime")
+    repeat.focus()
+    repeat.press("ArrowUp")
+    expect(repeat).not_to_be_focused()
+    page.keyboard.press("ArrowDown")
+    expect(repeat).to_be_focused()
+    page.keyboard.press("Home")
+    expect(menu.locator("button:visible").first).to_be_focused()
+    page.keyboard.press("End")
+    expect(menu.locator("button:visible").last).to_be_focused()
+    assert player.evaluate("element=>element.volume") == volume
+    assert player.evaluate("element=>element.currentTime") == time
+    repeat.focus()
+    repeat.press("Space")
+    expect(repeat).to_have_attribute("aria-pressed", "true")
+    repeat.press("Enter")
+    expect(repeat).to_have_attribute("aria-pressed", "false")
+    assert player.evaluate("element=>element.paused")
+
+    def open_page(name: str) -> None:
+        if not menu.is_visible():
+            settings.focus()
+            settings.press("Space")
+        row = menu.locator(f'.movi-settings-row[data-page="{name}"]')
+        row.focus()
+        row.press("Enter")
+
+    open_page("speed")
+    speed = menu.locator('.movi-speed-item[data-speed="1.5"]')
+    speed.focus()
+    speed.press("Space")
+    expect(player).to_have_js_property("playbackRate", 1.5)
+    assert player.evaluate("element=>element.paused")
+    expect(menu).not_to_be_visible()
+    open_page("audio")
+    audio = player.evaluate("element=>element.player.getAudioTracks()[1].id")
+    audio_choice = menu.locator(f'.movi-audio-track-item[data-track-id="{audio}"]')
+    audio_choice.focus()
+    audio_choice.press("Enter")
+    page.wait_for_function(
+        "id=>document.querySelector('movi-player').player.trackManager.getActiveAudioTrack()?.id===id",
+        arg=audio,
+    )
+    assert player.evaluate("element=>element.paused")
+    expect(menu).not_to_be_visible()
+    open_page("subtitles")
+    subtitle = player.evaluate("element=>element.player.getSubtitleTracks()[0].id")
+    subtitle_choice = menu.locator(
+        f'.movi-subtitle-track-item[data-track-id="{subtitle}"]'
+    )
+    subtitle_choice.focus()
+    subtitle_choice.press("Space")
+    page.wait_for_function(
+        "id=>document.querySelector('movi-player').player.trackManager.getActiveSubtitleTrack()?.id===id",
+        arg=subtitle,
+    )
+    assert player.evaluate("element=>element.paused")
+    expect(menu).not_to_be_visible()
+    settings.focus()
+    settings.press("Space")
+    menu.get_by_role("button", name="Aspect", exact=False).click()
+    expect(menu.locator(".movi-settings-page-title")).to_have_text("Aspect")
+    page.keyboard.press("Escape")
+    expect(menu).to_be_visible()
+    expect(menu.get_by_role("button", name="Aspect", exact=False)).to_be_visible()
+    expect(dialog).to_be_visible()
+    page.keyboard.press("Escape")
+    expect(menu).not_to_be_visible()
+    expect(dialog).to_be_visible()
+    expect(settings).to_be_focused()
+    assert player.evaluate("element=>element.paused")
+    page.keyboard.press("Escape")
+    expect(dialog).to_have_count(0)
+
+
+def test_playing_controls_hide_when_idle_and_remain_visible_for_keyboard_focus(
+    server: Server, desktop: tuple[Any, Any], long_video_bytes: bytes
+) -> None:
+    _, page = desktop
+    gestures.route_long_media(page, long_video_bytes)
+    _, player = _open_video(page, server)
+    page.wait_for_function("()=>document.querySelector('movi-player').duration>60")
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>0.3")
+    page.mouse.move(20, 20)
+    controls = player.locator(".movi-controls-container")
+    expect(controls).to_have_class(re.compile("movi-controls-hidden"), timeout=6000)
+    settings = player.get_by_role("button", name="Settings", exact=True)
+    for _ in range(20):
+        page.keyboard.press("Tab")
+        if settings.evaluate("element=>element.getRootNode().activeElement===element"):
+            break
+    expect(settings).to_be_focused()
+    assert settings.evaluate("element=>element.matches(':focus-visible')")
+    page.mouse.move(20, 20)
+    start = player.evaluate("element=>element.currentTime")
+    page.wait_for_function(
+        "start=>document.querySelector('movi-player').currentTime>start+3.5", arg=start
+    )
+    expect(settings).to_be_focused()
+    expect(controls).to_have_class(re.compile("movi-controls-visible"))
+    settings.press("Space")
+    menu = player.locator(".movi-settings-menu")
+    expect(menu).to_be_visible()
+    assert not player.evaluate("element=>element.paused")
+    settings.press("Escape")
+    expect(menu).not_to_be_visible()
+    player.focus()
+    page.mouse.move(20, 20)
+    expect(controls).to_have_class(re.compile("movi-controls-hidden"), timeout=6000)
+
+
+@pytest.mark.parametrize(
+    "kind,button_name,menu_class,choice_class,key",
+    [
+        (
+            "audio",
+            "Audio Track",
+            ".movi-audio-track-menu",
+            ".movi-audio-track-item",
+            "Enter",
+        ),
+        (
+            "subtitles",
+            "Subtitles/Captions",
+            ".movi-subtitle-track-menu",
+            ".movi-subtitle-track-item",
+            "Space",
+        ),
+    ],
+)
+def test_direct_track_menu_keyboard_selection_keeps_video_paused(
+    server: Server,
+    desktop: tuple[Any, Any],
+    kind: str,
+    button_name: str,
+    menu_class: str,
+    choice_class: str,
+    key: str,
+) -> None:
+    _, page = desktop
+    _, player = _open_video(page, server)
+    button = player.get_by_role("button", name=button_name, exact=True)
+    button.focus()
+    button.press("Enter")
+    menu = player.locator(menu_class)
+    expect(menu).to_be_visible()
+    if kind == "audio":
+        track = player.evaluate("element=>element.player.getAudioTracks()[1].id")
+        selected = "getActiveAudioTrack"
+    else:
+        track = player.evaluate("element=>element.player.getSubtitleTracks()[0].id")
+        selected = "getActiveSubtitleTrack"
+    choice = menu.locator(f'{choice_class}[data-track-id="{track}"]')
+    for _ in range(menu.locator(choice_class).count() + 1):
+        page.keyboard.press("ArrowDown")
+        if choice.evaluate("element=>element.getRootNode().activeElement===element"):
+            break
+    expect(choice).to_be_focused()
+    assert player.evaluate("element=>element.paused")
+    page.keyboard.press(key)
+    page.wait_for_function(
+        """([method,id])=>document.querySelector('movi-player').player
+          .trackManager[method]()?.id===id""",
+        arg=[selected, track],
+    )
+    assert player.evaluate("element=>element.paused")
diff --git a/tests/browser/test_browser_player_native.py b/tests/browser/test_browser_player_native.py
new file mode 100644
index 00000000..bc277a01
--- /dev/null
+++ b/tests/browser/test_browser_player_native.py
@@ -0,0 +1,133 @@
+"""Native local subtitle selection renders and cleans up without remote access."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import urlsplit
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import Server, expect, preview_dialog
+from tests.browser.test_browser_player_settings import open_video
+
+browser, server, desktop = fixtures.browser, fixtures.server, fixtures.desktop
+pytestmark = pytest.mark.e2e
+
+
+def test_local_subtitle_picker_renders_and_releases_its_file_on_close(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    external_requests: list[str] = []
+    origin = urlsplit(server.url)
+
+    def record_request(request: Any) -> None:
+        url = request.url
+        if url.startswith("data:"):
+            return
+        parsed = urlsplit(url.removeprefix("blob:"))
+        if (parsed.scheme, parsed.netloc) != (origin.scheme, origin.netloc):
+            external_requests.append(url)
+
+    page.on("request", record_request)
+    page.add_init_script("""(() => {
+        window.localSubtitleFiles = { created: [], revoked: [] };
+        window.playerPolicyViolations = [];
+        const create = URL.createObjectURL.bind(URL);
+        const revoke = URL.revokeObjectURL.bind(URL);
+        URL.createObjectURL = value => {
+            const url = create(value);
+            if (value instanceof File && value.name === 'local-captions.srt')
+                window.localSubtitleFiles.created.push(url);
+            return url;
+        };
+        URL.revokeObjectURL = url => {
+            if (window.localSubtitleFiles.created.includes(url))
+                window.localSubtitleFiles.revoked.push(url);
+            return revoke(url);
+        };
+        addEventListener('securitypolicyviolation', event => {
+            window.playerPolicyViolations.push({
+                directive: event.effectiveDirective,
+                blocked: event.blockedURI,
+            });
+        });
+    })();""")
+    dialog, player = open_video(page, server)
+
+    def open_subtitles() -> Any:
+        player.hover()
+        menu = player.locator(".movi-settings-menu")
+        opened = player.locator(".movi-settings-menu.is-open")
+        if not opened.count():
+            expect(menu).to_be_hidden()
+            player.locator("button.movi-settings-btn").click()
+        expect(opened).to_be_visible()
+        if not menu.locator('.movi-settings-row[data-page="subtitles"]').is_visible():
+            menu.locator("button.movi-settings-back").click()
+        menu.locator('.movi-settings-row[data-page="subtitles"]').click()
+        return menu
+
+    menu = open_subtitles()
+    with page.expect_file_chooser() as chooser:
+        menu.get_by_role("button", name="Add subtitle…", exact=True).click()
+    chooser.value.set_files(
+        {
+            "name": "local-captions.srt",
+            "mimeType": "application/x-subrip",
+            "buffer": (b"1\n00:00:00,000 --> 00:00:05,000\nLocal subtitle fixture\n"),
+        }
+    )
+    page.wait_for_function("""() => document.querySelector('movi-player')
+        ?.getSubtitleLangs().some(track =>
+            track.label === 'local-captions' && track.active)
+    """)
+    expect(player.locator('input[type="file"]')).to_have_count(0)
+
+    # Exercise the same native choices as embedded tracks, including Off.
+    menu = open_subtitles()
+    menu.locator('.movi-subtitle-track-item[data-track-id="null"]').click()
+    page.wait_for_function("""() => document.querySelector('movi-player')
+        ?.getSubtitleLangs().every(track => !track.active)
+    """)
+    menu = open_subtitles()
+    choice = menu.locator('.movi-subtitle-track-item[data-subtitle-lang^="file-"]')
+    expect(choice).to_contain_text("local-captions")
+    choice.click()
+    page.wait_for_function("""() => document.querySelector('movi-player')
+        ?.getSubtitleLangs().some(track =>
+            track.label === 'local-captions' && track.active)
+    """)
+    player.evaluate("element => { element.currentTime = 0.5; return element.play(); }")
+    expect(player.locator(".movi-subtitle-overlay")).to_contain_text(
+        "Local subtitle fixture", timeout=10000
+    )
+    player.evaluate("element => element.pause()")
+    assert page.evaluate("window.localSubtitleFiles.created.length") == 1
+    assert external_requests == []
+    assert page.evaluate("window.playerPolicyViolations") == []
+
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(player).to_have_count(0)
+    page.wait_for_function("""() => window.localSubtitleFiles.created.every(url =>
+        window.localSubtitleFiles.revoked.includes(url))
+    """)
+
+    # A newly opened preview must not retain a revoked file or its subtitle cues.
+    page.get_by_role("button", name="multitrack.mkv", exact=True).press("Enter")
+    reopened = preview_dialog(page).locator("movi-player")
+    expect(reopened).to_be_visible(timeout=30000)
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    assert not reopened.evaluate("""element => element.getSubtitleLangs()
+        .some(track => track.label === 'local-captions')
+    """)
+    expect(reopened.locator(".movi-subtitle-overlay")).not_to_contain_text(
+        "Local subtitle fixture"
+    )
+    assert external_requests == []
+    assert page.evaluate("window.playerPolicyViolations") == []
diff --git a/tests/browser/test_browser_player_pip.py b/tests/browser/test_browser_player_pip.py
new file mode 100644
index 00000000..1916c2cf
--- /dev/null
+++ b/tests/browser/test_browser_player_pip.py
@@ -0,0 +1,221 @@
+"""Real document picture-in-picture remains styled under production CSP."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    Server,
+    expect,
+    login,
+    preview_dialog,
+)
+
+pytestmark = pytest.mark.e2e
+pytest_plugins = ("tests.browser.test_browser_e2e",)
+
+
+def _watch_csp(page: Any) -> None:
+    page.add_init_script("""window.pipCspViolations=[];
+      document.addEventListener('securitypolicyviolation',event=>{
+        window.pipCspViolations.push(event.violatedDirective+':'+event.blockedURI);
+      });
+      window.documentPictureInPicture?.addEventListener('enter',event=>{
+        event.window.document.addEventListener('securitypolicyviolation',violation=>{
+          window.pipCspViolations.push(violation.violatedDirective+':'+violation.blockedURI);
+        });
+      });""")
+
+
+def _open_pip(context: Any, player: Any) -> Any:
+    player.hover()
+    with context.expect_page() as result:
+        player.get_by_role("button", name="Picture in Picture", exact=True).click()
+    pip = result.value
+    pip.set_viewport_size({"width": 400, "height": 300})
+    expect(pip.get_by_role("slider", name="Video position", exact=True)).to_be_visible()
+    pip.locator("body").hover()
+    return pip
+
+
+def _assert_pip_layout(pip: Any) -> None:
+    metrics = pip.evaluate("""()=>({
+      margin:getComputedStyle(document.body).margin,
+      controlsPosition:getComputedStyle(document.querySelector('.pip-controls')).position,
+      inlineStyles:document.querySelectorAll('style').length,
+      sheets:document.adoptedStyleSheets.length,
+      overflow:document.documentElement.scrollWidth>innerWidth,
+      buttons:[...document.querySelectorAll('button')].map(button=>{
+        const rect=button.getBoundingClientRect();
+        const hit=document.elementFromPoint(rect.x+rect.width/2,rect.y+rect.height/2);
+        return {label:button.getAttribute('aria-label'),
+          width:rect.width,height:rect.height,
+          bounded:rect.left>=0&&rect.right<=innerWidth&&rect.top>=0&&rect.bottom<=innerHeight,
+          reachable:hit===button||button.contains(hit)};
+      })
+    })""")
+    assert metrics["margin"] == "0px"
+    assert metrics["controlsPosition"] == "absolute"
+    assert metrics["inlineStyles"] == 0
+    assert metrics["sheets"] >= 3
+    assert not metrics["overflow"]
+    assert len(metrics["buttons"]) == 5
+    assert all(
+        button["label"]
+        and button["width"] >= 44
+        and button["height"] >= 44
+        and button["bounded"]
+        and button["reachable"]
+        for button in metrics["buttons"]
+    ), metrics
+
+
+def test_document_pip_styles_controls_subtitles_and_canvas_restore(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    context, page = desktop
+    _watch_csp(page)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    player.get_by_role("button", name="Subtitles/Captions", exact=True).click()
+    track = player.evaluate("element=>element.player.getSubtitleTracks()[0].id")
+    player.locator(f'.movi-subtitle-track-item[data-track-id="{track}"]').click()
+    player.locator("button.movi-play-pause").click()
+    expect(player.locator(".movi-subtitle-line").first).to_contain_text(
+        "TGDrive subtitle", timeout=15000
+    )
+    player.locator("button.movi-play-pause").click()
+    pip = _open_pip(context, player)
+    _assert_pip_layout(pip)
+    subtitle = pip.locator(".movi-subtitle-line").first
+    expect(subtitle).to_contain_text("TGDrive subtitle")
+    assert subtitle.evaluate("element=>getComputedStyle(element).display") == "block"
+    assert subtitle.evaluate("element=>getComputedStyle(element).color") == (
+        "rgb(255, 255, 255)"
+    )
+    pip.screenshot(path=ARTIFACTS / "document-pip-styled.png")
+
+    # Pointer and keyboard controls operate the same real playback engine.
+    pip.get_by_role("button", name="Play", exact=True).click()
+    page.wait_for_function("()=>!document.querySelector('movi-player').paused")
+    pip.get_by_role("button", name="Pause", exact=True).click()
+    page.wait_for_function("()=>document.querySelector('movi-player').paused")
+    mute = pip.get_by_role("button", name="Mute", exact=True)
+    mute.focus()
+    mute.press("Space")
+    assert player.evaluate("element=>element.muted")
+    assert player.evaluate("element=>element.paused")
+    pip.get_by_role("button", name="Unmute", exact=True).press("Enter")
+    assert not player.evaluate("element=>element.muted")
+    assert player.evaluate("element=>element.paused")
+    slider = pip.get_by_role("slider", name="Video position", exact=True)
+    slider.click(position={"x": 150, "y": 8})
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>1")
+    slider.focus()
+    slider.press("Home")
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime<0.1")
+    slider.press("ArrowRight")
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>4")
+    assert player.evaluate("element=>element.paused")
+    slider.press("Home")
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime<0.1")
+    with pip.expect_event("close"):
+        pip.get_by_role("button", name="Back to video", exact=True).press("Space")
+    expect(player).to_be_focused()
+    assert player.evaluate("element=>element.paused")
+    assert player.evaluate("element=>element.canvas.getRootNode()===element.shadowRoot")
+    assert page.evaluate("window.pipCspViolations") == []
+
+    # Reopening keeps the adapter; closing the preview also closes its PiP window.
+    reopened = _open_pip(context, player)
+    _assert_pip_layout(reopened)
+    with reopened.expect_event("close"):
+        dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(dialog).to_have_count(0)
+    assert page.evaluate("window.pipCspViolations") == []
+
+
+def test_document_pip_preserves_custom_mp4_caption_styles(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    context, page = desktop
+    _watch_csp(page)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="movtext-subtitles.mp4", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    player.get_by_role("button", name="Subtitles/Captions", exact=True).click()
+    track = player.evaluate("element=>element.player.getSubtitleTracks()[0].id")
+    player.locator(f'.movi-subtitle-track-item[data-track-id="{track}"]').click()
+    player.locator("button.movi-play-pause").click()
+    expect(player.locator(".tgdrive-movtext-cue")).to_be_visible(timeout=15000)
+    player.locator("button.movi-play-pause").click()
+    pip = _open_pip(context, player)
+    cue = pip.locator(".tgdrive-movtext-cue")
+    expect(cue).to_be_visible()
+    assert cue.evaluate("element=>getComputedStyle(element).color") == (
+        "rgb(255, 255, 255)"
+    )
+    assert cue.evaluate("element=>getComputedStyle(element).backgroundColor") == (
+        "rgba(8, 10, 13, 0.84)"
+    )
+    assert (
+        pip.locator(".tgdrive-movtext-renderer").evaluate(
+            "element=>getComputedStyle(element).position"
+        )
+        == "absolute"
+    )
+    assert (
+        cue.bounding_box()["y"] + cue.bounding_box()["height"]
+        <= (pip.locator(".pip-controls").bounding_box()["y"])
+    )
+    assert page.evaluate("window.pipCspViolations") == []
+    pip.screenshot(path=ARTIFACTS / "document-pip-mp4-captions.png")
+    with pip.expect_event("close"):
+        pip.get_by_role("button", name="Back to video", exact=True).click()
+    expect(player.locator(".tgdrive-movtext-cue")).to_be_visible()
+
+
+def test_closing_preview_during_pip_request_restores_api_and_closes_child(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    context, page = desktop
+    _watch_csp(page)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    # Delay delivery of a real native child window, keeping the browser gesture.
+    page.evaluate("""()=>{
+      const api=window.documentPictureInPicture,request=api.requestWindow;
+      window.delayedPipRequest=function(options){
+        return request.call(api,options).then(child=>new Promise(resolve=>{
+          window.releasePipRequest=()=>resolve(child);
+        }));
+      };
+      api.requestWindow=window.delayedPipRequest;
+    }""")
+    player.hover()
+    with context.expect_page() as result:
+        player.get_by_role("button", name="Picture in Picture", exact=True).click()
+    child = result.value
+    page.wait_for_function("()=>!!window.releasePipRequest")
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(dialog).to_have_count(0)
+    assert page.evaluate("""()=>window.documentPictureInPicture.requestWindow===
+      window.delayedPipRequest""")
+    with child.expect_event("close"):
+        page.evaluate("window.releasePipRequest()")
+    expect(page.locator("movi-player")).to_have_count(0)
+    assert page.evaluate("window.pipCspViolations") == []
diff --git a/tests/browser/test_browser_player_settings.py b/tests/browser/test_browser_player_settings.py
new file mode 100644
index 00000000..54c36046
--- /dev/null
+++ b/tests/browser/test_browser_player_settings.py
@@ -0,0 +1,260 @@
+"""Native player settings preserve playback state and button activation."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login, preview_dialog
+
+browser, server, desktop = fixtures.browser, fixtures.server, fixtures.desktop
+pytestmark = pytest.mark.e2e
+
+
+def open_video(page, server, filename="multitrack.mkv", *, touch=False):
+    login(page, server.url)
+    for name in ("Preview samples", filename):
+        button = page.get_by_role("button", name=name, exact=True)
+        if touch:
+            button.tap()
+        else:
+            # Exercise player layout independently of mouse folder selection.
+            button.press("Enter")
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    return dialog, player
+
+
+@pytest.mark.parametrize("width,height", [(1440, 960), (390, 844), (740, 360)])
+def test_native_settings_labels_stay_within_player(server, desktop, width, height):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": height})
+    dialog, player = open_video(page, server)
+    player.hover()
+    # Compact controls can put Settings behind the extra-controls button.
+    settings = player.locator("button.movi-settings-btn")
+    if not settings.is_visible():
+        player.locator("button.movi-more-btn").click()
+    settings.click()
+    menu = player.locator(".movi-settings-menu")
+    expect(menu).to_be_visible()
+    for label in ("Ambient mode", "Stable volume", "Loop", "Crop black bars"):
+        expect(menu.get_by_role("button", name=label, exact=True)).to_be_visible()
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / f"video-settings-{width}x{height}.png")
+    menu.get_by_role("button", name="Aspect", exact=False).click()
+    expect(menu.locator(".movi-settings-page-title")).to_have_text("Aspect")
+    expect(menu.get_by_role("button", name="Fill", exact=True)).to_be_visible()
+    expect(menu.get_by_role("button", name="Stretch", exact=True)).to_be_visible()
+    bounds = menu.bounding_box()
+    assert bounds["x"] >= -1 and bounds["x"] + bounds["width"] <= width + 1, bounds
+    assert bounds["y"] >= -1 and bounds["y"] + bounds["height"] <= height + 1, bounds
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / f"video-fit-settings-{width}x{height}.png")
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+
+
+def test_space_activates_focused_settings_and_mute_without_toggling_play(
+    server, desktop
+):
+    _, page = desktop
+    _, player = open_video(page, server)
+    assert player.evaluate("element => element.paused")
+    player.hover()
+    settings = player.locator("button.movi-settings-btn")
+    settings.focus()
+    page.keyboard.press("Space")
+    expect(player.locator(".movi-settings-menu")).to_be_visible()
+    assert player.evaluate("element => element.paused"), (
+        "Space on Settings must open Settings"
+    )
+    settings.focus()
+    page.keyboard.press("Space")
+    expect(player.locator(".movi-settings-menu")).not_to_be_visible()
+    mute = player.locator("button.movi-volume-btn")
+    before = player.evaluate("element => element.muted")
+    mute.focus()
+    page.keyboard.press("Space")
+    assert player.evaluate("element => element.muted") is not before
+    assert player.evaluate("element => element.paused"), (
+        "Space on Mute must keep video paused"
+    )
+    # Player-level Space retains the familiar play/pause shortcut.
+    player.focus()
+    page.keyboard.press("Space")
+    expect(player).to_have_js_property("paused", False)
+
+
+@pytest.mark.parametrize("playing", [False, True])
+def test_native_settings_switches_preserve_playback_state(server, desktop, playing):
+    _, page = desktop
+    _, player = open_video(page, server)
+    if playing:
+        player.locator("button.movi-play-pause").click()
+        page.wait_for_function("() => !document.querySelector('movi-player').paused")
+    player.hover()
+    player.locator("button.movi-settings-btn").click()
+    menu = player.locator(".movi-settings-menu")
+    for label, property_name in [
+        ("Ambient mode", "ambientMode"),
+        ("Stable volume", "stableVolume"),
+        ("Loop", "loop"),
+    ]:
+        row = menu.get_by_role("button", name=label, exact=True)
+        before = player.evaluate(
+            "(element, property) => element[property]", property_name
+        )
+        row.focus()
+        page.keyboard.press("Space")
+        expect(row).to_have_attribute("aria-pressed", str(not before).lower())
+        assert player.evaluate("element => element.paused") is not playing
+        page.keyboard.press("Enter")
+        expect(row).to_have_attribute("aria-pressed", str(before).lower())
+        assert player.evaluate("element => element.paused") is not playing
+    # A keyboard shortcut without a menu still provides a clear confirmation.
+    player.locator("button.movi-settings-btn").click()
+    player.focus()
+    page.keyboard.press("u")
+    expect(player.locator(".movi-osd-text")).to_contain_text("Stable Volume")
+
+
+def test_glow_and_crop_keep_their_shared_frame_sampler_when_either_is_enabled(
+    server, desktop
+):
+    _, page = desktop
+    _, player = open_video(page, server)
+    player.evaluate("""element => {
+      element.ambientMode = false; element.cropbars = false;
+      element.cropbars = true; element.ambientMode = true;
+      element.ambientMode = false;
+    }""")
+    state = player.evaluate("""element => ({
+      glow:element.ambientMode,crop:element.cropbars,
+      sampler:element.player.videoRenderer.ambientEnabled,
+      detector:element.player.videoRenderer.barCropEnabled
+    })""")
+    assert state == {"glow": False, "crop": True, "sampler": True, "detector": True}, (
+        state
+    )
+    player.evaluate("element => { element.loop = true; return element.play(); }")
+    page.wait_for_function("""() => {
+      const renderer = document.querySelector('movi-player').player.videoRenderer;
+      return renderer.barCropLastCheck > 0;
+    }""")
+    player.evaluate("""element => {
+      element.ambientMode = true; element.cropbars = false;
+    }""")
+    assert player.evaluate("element => element.player.videoRenderer.ambientEnabled")
+    page.wait_for_function("""() => {
+      const color = document.querySelector('movi-player').currentAmbientColors;
+      return color.r + color.g + color.b > 0;
+    }""")
+    player.evaluate("element => { element.ambientMode = false; }")
+    assert not player.evaluate("element => element.player.videoRenderer.ambientEnabled")
+
+
+def test_software_video_does_not_offer_an_inactive_glow_switch(server, desktop):
+    _, page = desktop
+    _, player = open_video(page, server, "software-mpeg4.wmv")
+    assert player.evaluate("element => element.player.isSoftwareDecoding()")
+    player.hover()
+    player.locator("button.movi-settings-btn").click()
+    expect(player.get_by_role("button", name="Ambient mode", exact=True)).to_have_count(
+        0
+    )
+    before = player.evaluate("element => element.ambientMode")
+    player.focus()
+    page.keyboard.press("g")
+    assert player.evaluate("element => element.ambientMode") is before
+    player.locator("button.movi-settings-btn").click()
+    player.click(button="right", position={"x": 120, "y": 120})
+    context = page.locator(".movi-context-menu")
+    expect(context).to_be_visible()
+    expect(context.locator('[data-action="ambient-toggle"]')).not_to_be_visible()
+
+
+def test_touch_settings_scroll_and_switches_are_reachable(server, browser):
+    context = browser.new_context(
+        viewport={"width": 390, "height": 844}, has_touch=True, is_mobile=True
+    )
+    page = context.new_page()
+    errors = []
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    try:
+        _, player = open_video(page, server, touch=True)
+        settings = player.locator("button.movi-settings-btn")
+        if not settings.is_visible():
+            player.locator("button.movi-more-btn").tap()
+        settings.tap()
+        menu = player.locator(".movi-settings-menu")
+        expect(menu).to_be_visible()
+        repeat = menu.get_by_role("button", name="Loop", exact=True)
+        repeat.tap()
+        expect(repeat).to_have_attribute("aria-pressed", "true")
+        assert player.evaluate("element => element.paused")
+        menu.get_by_role("button", name="Aspect", exact=False).tap()
+        fill = menu.get_by_role("button", name="Fill", exact=True)
+        expect(fill).to_be_visible()
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=ARTIFACTS / "video-touch-settings-390x844.png")
+        fill.tap()
+        expect(menu).not_to_be_visible()
+        assert player.evaluate("element => element.paused")
+        assert errors == []
+    finally:
+        context.close()
+
+
+@pytest.mark.parametrize("selected", ["Original", "Fixture alternate source"])
+def test_external_quality_label_and_same_choice_keep_keyboard_playback_working(
+    server, desktop, selected
+):
+    _, page = desktop
+    _, player = open_video(page, server)
+    player.hover()
+    settings = player.locator("button.movi-settings-btn")
+    settings.click()
+    menu = player.locator(".movi-settings-menu")
+    quality = menu.locator('.movi-settings-row[data-page="quality"]')
+    if selected != "Original":
+        quality.click()
+        player.evaluate("element => { window.previousQualityPlayer = element; }")
+        menu.get_by_role("button", name=selected, exact=True).click()
+        page.wait_for_function("""() => {
+          const player = document.querySelector('movi-player');
+          return player && player !== window.previousQualityPlayer &&
+            player.duration > 4;
+        }""")
+        player.hover()
+        settings.click()
+    expect(quality.locator(".movi-settings-row-value")).to_have_text(selected)
+    menu.get_by_role("button", name="Loop", exact=True).click()
+    # Native state sync must keep the external server source label, rather than
+    # replacing it with the decoded resolution of the current file.
+    expect(quality.locator(".movi-settings-row-value")).to_have_text(selected)
+    assert player.evaluate("element => element.paused")
+    quality.click()
+    choice = menu.get_by_role("button", name=selected, exact=True)
+    expect(choice).to_have_attribute("aria-pressed", "true")
+    player.evaluate("element => { window.sameQualityPlayer = element; }")
+    choice.focus()
+    page.keyboard.press("Enter")
+    expect(menu).not_to_be_visible()
+    assert player.evaluate("element => element === window.sameQualityPlayer")
+    assert player.evaluate("""element => document.activeElement === element &&
+      !element.shadowRoot.activeElement?.closest('.movi-settings-menu')""")
+    page.keyboard.press("k")
+    expect(player).to_have_js_property("paused", False)
+    page.wait_for_function("""() => {
+      const player = document.querySelector('movi-player');
+      return player.player.getState() === 'playing' && player.currentTime > 0.1;
+    }""")
+    page.keyboard.press("Space")
+    expect(player).to_have_js_property("paused", True)
diff --git a/tests/browser/test_browser_preloads.py b/tests/browser/test_browser_preloads.py
new file mode 100644
index 00000000..cb4e649c
--- /dev/null
+++ b/tests/browser/test_browser_preloads.py
@@ -0,0 +1,146 @@
+"""Manual whole-file preload discovery, actual caching and recoverable errors."""
+
+from __future__ import annotations
+
+import os
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium tests", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login
+
+browser = fixtures.browser
+desktop = fixtures.desktop
+server = fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.mark.parametrize("filename", ["multitrack.mkv", "sample.wav"])
+def test_media_playback_identifies_preview_but_original_download_does_not(
+    server, desktop, filename
+):
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    with page.expect_response(
+        lambda response: (
+            "/file?" in response.url
+            and parse_qs(urlsplit(response.url).query).get("preview") == ["1"]
+            and response.status in {200, 206}
+        )
+    ) as playback:
+        page.get_by_role("button", name=filename, exact=True).dblclick()
+    playback_params = parse_qs(urlsplit(playback.value.url).query)
+    assert "download" not in playback_params
+    original = page.get_by_role("link", name="Download Original", exact=True)
+    download_params = parse_qs(urlsplit(original.get_attribute("href")).query)
+    assert download_params["download"] == ["1"]
+    assert "preview" not in download_params
+    assert download_params["path"] == playback_params["path"]
+    with page.expect_download() as downloaded:
+        original.click()
+    assert downloaded.value.suggested_filename == filename
+    assert downloaded.value.failure() is None
+
+
+def open_preload(page):
+    page.get_by_label("Actions for archive.bin", exact=True).click()
+    action = page.get_by_role("menuitem", name="Preload file", exact=True)
+    expect(action).to_be_visible()
+    action.click()
+    return page.get_by_role("dialog", name="Preload file", exact=True)
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_file_menu_preloads_whole_file_and_reuses_cached_bytes(server, desktop, width):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    directory_url = page.url
+    dialog = open_preload(page)
+    expect(dialog).to_contain_text("Cache the whole file on the server")
+    expect(dialog).to_contain_text("requested chunks")
+    expect(dialog).to_contain_text("bounded read-ahead")
+    expect(dialog).to_contain_text("internet connection")
+    expect(dialog.get_by_role("link", name="Preloads", exact=True)).to_have_attribute(
+        "href", "/?view=preloads"
+    )
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(path=ARTIFACTS / f"preload-file-dialog-{width}.png")
+    with page.expect_response(
+        lambda response: (
+            response.request.method == "POST"
+            and response.url.endswith("/api/v1/preloads")
+        )
+    ) as response:
+        dialog.get_by_role("button", name="Preload file", exact=True).click()
+    assert response.value.ok, response.value.text()
+    job = response.value.json()
+    assert job["mode"] == "manual"
+    assert job["target_bytes"] == job["size"] == 256
+    assert job["start"] == 0 and job["end"] == 256
+    expect(dialog).not_to_be_visible()
+    page.goto(server.url + "/?view=preloads")
+    help_panel = page.locator(".preload-help")
+    expect(help_panel).not_to_have_attribute("open", "")
+    help_panel.get_by_text("About preloading", exact=True).click()
+    expect(help_panel).to_contain_text("Preload file")
+    expect(help_panel).to_contain_text("downloads fetch their requested ranges")
+    help_panel.get_by_text("About preloading", exact=True).click()
+    cached = page.locator(".cached-file").filter(has_text="archive.bin")
+    expect(cached.locator(".cache-ready-state")).to_have_text("Ready", timeout=15000)
+    expect(cached.locator(".cache-coverage")).to_contain_text("256 / 256 B cached")
+    expect(cached.locator(".cache-coverage-ready")).to_have_attribute("width", "1000")
+    page.screenshot(path=ARTIFACTS / f"preload-file-ready-{width}.png")
+    page.goto(directory_url)
+    dialog = open_preload(page)
+    dialog.get_by_role("button", name="Preload file", exact=True).click()
+    expect(
+        page.get_by_text("Preload queued. View progress in Preloads.", exact=True)
+    ).to_be_visible()
+    expect(dialog).not_to_be_visible()
+    page.goto(server.url + "/?view=preloads")
+    expect(cached.locator(".cache-ready-state")).to_have_text("Ready")
+
+
+def test_preload_capacity_error_keeps_dialog_open_and_allows_retry(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    attempts = []
+
+    def capacity_once(route):
+        if route.request.method != "POST":
+            route.continue_()
+            return
+        attempts.append(route.request.post_data_json)
+        if len(attempts) == 1:
+            route.fulfill(
+                status=507,
+                json={
+                    "detail": (
+                        "Increase cache capacity or clear cached files, then retry."
+                    ),
+                    "code": "PRELOAD_CAPACITY",
+                },
+            )
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/preloads", capacity_once)
+    dialog = open_preload(page)
+    dialog.get_by_role("button", name="Preload file", exact=True).click()
+    expect(dialog.get_by_role("alert")).to_contain_text("Increase cache capacity")
+    expect(
+        dialog.get_by_role("button", name="Preload file", exact=True)
+    ).to_be_enabled()
+    expect(dialog.get_by_role("link", name="Preloads", exact=True)).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "preload-file-capacity-error.png")
+    dialog.get_by_role("button", name="Preload file", exact=True).click()
+    expect(dialog).not_to_be_visible()
+    assert len(attempts) == 2 and attempts[0] == attempts[1]
diff --git a/tests/browser/test_browser_preview_controls.py b/tests/browser/test_browser_preview_controls.py
new file mode 100644
index 00000000..d716cd03
--- /dev/null
+++ b/tests/browser/test_browser_preview_controls.py
@@ -0,0 +1,244 @@
+"""The real viewer fit modes and native fullscreen work beyond video."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, CONTROL, expect, login
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+def expect_collapsed_fullscreen_toolbar(page):
+    page.wait_for_function(
+        "document.fullscreenElement === "
+        "document.querySelector('.preview-fullscreen-surface')"
+    )
+    expect(page.locator(".preview-header")).to_be_hidden()
+    expect(page.get_by_role("button", name="Show Toolbar", exact=True)).to_be_visible()
+    page.wait_for_function("""() => {
+      const surface = document.querySelector('.preview-surface');
+      const bounds = surface?.getBoundingClientRect();
+      return bounds && Math.abs(bounds.top) <= 1 &&
+        Math.abs(bounds.height - innerHeight) <= 1;
+    }""")
+
+
+def expect_expanded_fullscreen_toolbar(page):
+    page.wait_for_function(
+        "document.fullscreenElement === "
+        "document.querySelector('.preview-fullscreen-surface')"
+    )
+    expect(page.locator(".preview-header")).to_be_visible()
+    expect(
+        page.get_by_role("button", name="Hide Toolbar", exact=True)
+    ).to_have_attribute("aria-expanded", "true")
+
+
+def expand_fullscreen_toolbar(page):
+    page.get_by_role("button", name="Show Toolbar", exact=True).click()
+    expect_expanded_fullscreen_toolbar(page)
+
+
+@pytest.mark.parametrize("width", [1440, 390, 320])
+def test_pdf_real_fit_width_page_and_fullscreen(server, desktop, width):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 900 if width > 720 else 844})
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    page.get_by_role("button", name="sample.pdf", exact=True).press("Enter")
+    expect(page.locator(".pdf-page canvas").first).to_be_visible()
+    if width < 721:
+        page.get_by_role("button", name="PDF View Options", exact=True).click()
+    page.get_by_role("button", name="Fit Page", exact=True).click()
+    expect(page.get_by_role("button", name="Fit Page", exact=True)).to_have_attribute(
+        "aria-pressed", "true"
+    )
+    page.wait_for_function(
+        "() => {const p=document.querySelector('.pdf-page'),"
+        "s=document.querySelector('.pdf-scroll');return p && "
+        "p.clientHeight <= s.clientHeight-30 && p.clientWidth <= s.clientWidth-30}"
+    )
+    page.get_by_role("button", name="Fit Width", exact=True).click()
+    expect(page.get_by_role("button", name="Fit Width", exact=True)).to_have_attribute(
+        "aria-pressed", "true"
+    )
+    page.wait_for_function(
+        "() => Math.abs(document.querySelector('.pdf-page').clientWidth-"
+        "(document.querySelector('.pdf-scroll').clientWidth-32)) <= 2"
+    )
+    page.get_by_role("button", name="Zoom in", exact=True).click()
+    expect(page.get_by_role("button", name="Fit Width", exact=True)).to_have_attribute(
+        "aria-pressed", "false"
+    )
+    page.get_by_role("button", name="Fit Width", exact=True).click()
+    if width < 721:
+        page.get_by_role("button", name="PDF View Options", exact=True).click()
+    page.get_by_role("button", name="Enter Fullscreen", exact=True).click()
+    expect_expanded_fullscreen_toolbar(page)
+    hide = page.get_by_role("button", name="Hide Toolbar", exact=True)
+    expect(hide).to_be_focused()
+    hide.press("Enter")
+    expect_collapsed_fullscreen_toolbar(page)
+    page.screenshot(path=ARTIFACTS / f"pdf-fullscreen-collapsed-{width}.png")
+    show = page.get_by_role("button", name="Show Toolbar", exact=True)
+    show.focus()
+    show.press("Enter")
+    expect(page.locator(".preview-header")).to_be_visible()
+    if width < 721:
+        page.get_by_role("button", name="PDF View Options", exact=True).click()
+    page.get_by_role("button", name="Zoom in", exact=True).click()
+    expect(page.get_by_role("button", name="Fit Width", exact=True)).to_have_attribute(
+        "aria-pressed", "false"
+    )
+    if width < 721:
+        page.get_by_role("button", name="PDF View Options", exact=True).click()
+    # The expanded toolbar takes its own row instead of covering the PDF.
+    assert page.locator(".preview-surface").evaluate(
+        "el => el.getBoundingClientRect().top >= "
+        "document.querySelector('.preview-header').getBoundingClientRect().bottom - 1"
+    )
+    page.screenshot(path=ARTIFACTS / f"pdf-fullscreen-expanded-{width}.png")
+    page.get_by_role("button", name="Hide Toolbar", exact=True).click()
+    expect_collapsed_fullscreen_toolbar(page)
+    expect(show).to_be_focused()
+    show.press("Enter")
+    page.get_by_role("button", name="Exit Fullscreen", exact=True).click()
+    page.wait_for_function("!document.fullscreenElement")
+    expect(page.get_by_role("dialog")).to_be_visible()
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / f"pdf-fit-controls-{width}.png")
+
+
+@pytest.mark.parametrize(
+    ("name", "width"),
+    [
+        ("sample.png", 1440),
+        ("sample.wav", 1440),
+        ("reports.csv", 1440),
+        ("The little journey.epub", 1440),
+        ("The little journey.epub", 390),
+        ("The little journey.epub", 320),
+    ],
+)
+def test_supported_previews_enter_exit_fullscreen_and_close(
+    server, desktop, name, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 900 if width > 720 else 844})
+    if name == "sample.png":
+        page.route(
+            "**/api/v1/media?*",
+            lambda route: route.fulfill(
+                json={"variants": [{"id": "small", "label": "Small"}]}
+            ),
+        )
+    login(page, server.url)
+    if name.endswith("epub"):
+        folder = page.request.post(
+            server.url + "/__test__/books", headers=CONTROL
+        ).json()["path"]
+        page.goto(server.url + "/?path=" + folder)
+    else:
+        page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    page.get_by_role("button", name=name, exact=True).press("Enter")
+    if name == "sample.png":
+        expect(page.locator(".preview-quality")).to_be_visible()
+    if name.endswith("epub"):
+        expect(
+            page.get_by_role("group", name="Reader controls", exact=True)
+        ).to_be_visible()
+    enter = page.get_by_role("button", name="Enter Fullscreen", exact=True)
+    expect(enter).to_be_visible()
+    enter.click()
+    expect_expanded_fullscreen_toolbar(page)
+    if name == "sample.png":
+        expect(page.locator(".preview-quality")).to_be_visible()
+    page.get_by_role("button", name="Hide Toolbar", exact=True).click()
+    expect_collapsed_fullscreen_toolbar(page)
+    if name == "sample.png":
+        expect(page.locator(".preview-quality")).to_be_hidden()
+    expand_fullscreen_toolbar(page)
+    if name == "sample.png":
+        expect(page.locator(".preview-quality")).to_be_visible()
+    if name.endswith("epub"):
+        assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+        page.screenshot(path=ARTIFACTS / f"book-fullscreen-expanded-{width}.png")
+        expect(
+            page.get_by_role("group", name="Reader controls", exact=True)
+        ).to_be_visible()
+        page.get_by_label("Reading options", exact=True).click()
+        page.get_by_role("button", name="Increase text size", exact=True).click()
+        expect(page.locator(".book-chapter")).to_have_css("font-size", "20px")
+        page.get_by_label("Reading options", exact=True).click()
+    page.get_by_role("button", name="Hide Toolbar", exact=True).click()
+    expect_collapsed_fullscreen_toolbar(page)
+    page.keyboard.press("Escape")
+    page.wait_for_function("!document.fullscreenElement")
+    expect(page.locator(".preview-header")).to_be_visible()
+    expect(enter).to_be_focused()
+    expect(page.get_by_role("button", name="Show Toolbar", exact=True)).to_have_count(0)
+    enter.click()
+    expect_expanded_fullscreen_toolbar(page)
+    page.get_by_role("button", name="Close Preview", exact=True).click()
+    page.wait_for_function("!document.fullscreenElement")
+    expect(page.locator(".file-preview")).to_have_count(0)
+
+
+def test_video_fullscreen_buttons_share_player_surface(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    page.get_by_role("button", name="multitrack.mkv", exact=True).press("Enter")
+    player = page.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(page.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    page.get_by_role("button", name="Enter Fullscreen", exact=True).click()
+    page.wait_for_function(
+        "document.fullscreenElement === document.querySelector('movi-player')"
+    )
+    # Both routes give the entire viewport to the player, excluding preview chrome.
+    assert player.evaluate(
+        "el => !el.contains(document.querySelector('.preview-header')) && "
+        "Math.abs(el.getBoundingClientRect().top) <= 1 && "
+        "Math.abs(el.getBoundingClientRect().height - innerHeight) <= 1"
+    )
+    page.keyboard.press("Escape")
+    page.wait_for_function("!document.fullscreenElement")
+    expect(page.get_by_role("dialog")).to_be_visible()
+    expect(
+        page.get_by_role("button", name="Enter Fullscreen", exact=True)
+    ).to_be_visible()
+    player.hover()
+    fullscreen = player.locator("button.movi-fullscreen-btn")
+    fullscreen.click()
+    page.wait_for_function(
+        "document.fullscreenElement === document.querySelector('movi-player')"
+    )
+    player.hover()
+    fullscreen.click()
+    page.wait_for_function("!document.fullscreenElement")
+    expect(page.get_by_role("dialog")).to_be_visible()
+    page.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(page.locator(".file-preview")).to_have_count(0)
+
+
+def test_settings_discard_icon_has_shared_gap(server, desktop):
+    _, page = desktop
+    login(page, server.url + "/?view=settings&section=regional")
+    button = page.get_by_role("button", name="Discard changes", exact=True)
+    expect(button).to_be_visible()
+    assert (
+        button.locator(".mantine-Button-label").evaluate(
+            "e=>parseFloat(getComputedStyle(e).gap)"
+        )
+        >= 8
+    )
+    page.screenshot(path=ARTIFACTS / "settings-button-spacing.png")
diff --git a/tests/browser/test_browser_preview_player.py b/tests/browser/test_browser_preview_player.py
new file mode 100644
index 00000000..f7493ae9
--- /dev/null
+++ b/tests/browser/test_browser_preview_player.py
@@ -0,0 +1,322 @@
+"""Video preview chrome stays consistent with the real playback state."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    ROOT,
+    Server,
+    expect,
+    login,
+    preview_dialog,
+)
+
+pytestmark = pytest.mark.e2e
+pytest_plugins = ("tests.browser.test_browser_e2e",)
+
+
+def test_video_preview_does_not_poll_or_display_a_stale_server_queue(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    diagnostics: list[str] = []
+
+    def queued(route: Any) -> None:
+        diagnostics.append(route.request.url)
+        route.fulfill(json={"queue": {"position": 7, "estimated_wait_seconds": 60}})
+
+    page.route("**/api/v1/file-status?*", queued)
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    # Other preview types still show an actual provider queue when necessary.
+    page.get_by_role("button", name="sample.png", exact=True).dblclick()
+    image = preview_dialog(page)
+    expect(image.get_by_role("status")).to_contain_text(
+        "Waiting for Telegram capacity · About 60 seconds"
+    )
+    assert diagnostics
+    image.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(image).to_have_count(0)
+    diagnostics.clear()
+
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    expect(dialog.locator(".preview-limit")).to_have_count(0)
+    player.locator("button.movi-play-pause").click()
+    # Real playback advances beyond the former diagnostic polling interval.
+    page.wait_for_function("()=>document.querySelector('movi-player')?.currentTime>3")
+    assert diagnostics == []
+    expect(dialog.get_by_text("Waiting for Telegram", exact=False)).to_have_count(0)
+
+
+@pytest.mark.parametrize("close_while_waiting", [False, True])
+def test_image_preview_retries_busy_capacity_and_cancels_on_close(
+    server: Server, desktop: tuple[Any, Any], close_while_waiting: bool
+) -> None:
+    _, page = desktop
+    media_requests: list[str] = []
+
+    def busy_file(route: Any) -> None:
+        media_requests.append(route.request.url)
+        route.fulfill(
+            status=503,
+            headers={"Retry-After": "3"},
+            json={"code": "TELEGRAM_QUEUE_FULL", "detail": "Telegram is busy"},
+        )
+
+    page.route("**/file?*", busy_file)
+    page.route(
+        "**/api/v1/file-status?*",
+        lambda route: route.fulfill(
+            json={
+                "queue": None,
+                "phase": "retry_wait",
+                "code": "TELEGRAM_QUEUE_FULL",
+                "retry_after": 3,
+            }
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.clock.install()
+    page.get_by_role("button", name="sample.png", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    expect(dialog.get_by_role("status")).to_contain_text("will retry automatically")
+    assert len(media_requests) == 1
+    expect(dialog.get_by_text("Preview Unavailable", exact=True)).to_have_count(0)
+    if close_while_waiting:
+        dialog.get_by_role("button", name="Close Preview", exact=True).click()
+        page.clock.run_for(10000)
+        assert len(media_requests) == 1
+        return
+
+    page.clock.run_for(1000)
+    assert len(media_requests) == 1
+    page.clock.run_for(2500)
+    expect(dialog.get_by_role("status")).to_contain_text("will retry automatically")
+    assert len(media_requests) == 2
+    page.clock.run_for(3500)
+    expect(
+        dialog.get_by_role("button", name="Try Preview Again", exact=True)
+    ).to_be_visible()
+    expect(dialog.get_by_role("status")).to_contain_text("waiting queue is full")
+    assert len(media_requests) == 3
+    page.clock.run_for(10000)
+    assert len(media_requests) == 3
+
+
+@pytest.mark.parametrize("width,height", [(1440, 960), (390, 844)])
+def test_video_header_fullscreen_download_and_close_stay_reachable(
+    server: Server, desktop: tuple[Any, Any], width: int, height: int
+) -> None:
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": height})
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    file_button = page.get_by_role("button", name="multitrack.mkv", exact=True)
+    file_button.dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    fullscreen = dialog.get_by_role("button", name="Enter Fullscreen", exact=True)
+    fullscreen.click()
+    page.wait_for_function(
+        "()=>document.fullscreenElement===document.querySelector('movi-player')"
+    )
+    expect(player).to_be_focused()
+    # Exiting the player returns keyboard focus to its visible toolbar action.
+    page.evaluate("document.exitFullscreen()")
+    page.wait_for_function("()=>!document.fullscreenElement")
+    expect(fullscreen).to_be_focused()
+    expect(dialog.get_by_role("heading", name="multitrack.mkv")).to_be_visible()
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(path=ARTIFACTS / f"video-preview-header-{width}.png")
+    with page.expect_download() as result:
+        dialog.get_by_role("link", name="Download Original", exact=True).click()
+    assert hashlib.sha256(Path(result.value.path()).read_bytes()).digest() == (
+        hashlib.sha256((ROOT / "tests/fixtures/multitrack.mkv").read_bytes()).digest()
+    )
+    dialog.get_by_role("button", name="Close Preview", exact=True).click()
+    expect(dialog).to_have_count(0)
+    expect(file_button).to_be_focused()
+    expect(page.locator("movi-player")).to_have_count(0)
+
+
+def _open_settings(player: Any, *, touch: bool) -> Any:
+    if not touch:
+        player.hover()
+    settings = player.locator("button.movi-settings-btn")
+    if not settings.is_visible():
+        more = player.locator("button.movi-more-btn")
+        more.tap() if touch else more.click()
+    settings.tap() if touch else settings.click()
+    menu = player.locator(".movi-settings-menu")
+    expect(menu).to_be_visible()
+    return menu
+
+
+@pytest.mark.parametrize("touch", [False, True], ids=["desktop", "touch-phone"])
+def test_video_quality_uses_bounded_player_settings_without_a_preview_bar(
+    server: Server, browser: Any, touch: bool
+) -> None:
+    width, height = (390, 844) if touch else (1440, 960)
+    context = browser.new_context(
+        viewport={"width": width, "height": height},
+        has_touch=touch,
+        is_mobile=touch,
+    )
+    page = context.new_page()
+    errors: list[str] = []
+    page.on("pageerror", lambda error: errors.append(str(error)))
+    try:
+        login(page, server.url)
+        for name in ("Preview samples", "multitrack.mkv"):
+            button = page.get_by_role("button", name=name, exact=True)
+            button.tap() if touch else button.press("Enter")
+        dialog = preview_dialog(page)
+        player = dialog.locator("movi-player")
+        page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+        expect(dialog.locator(".preview-quality")).to_have_count(0)
+        expect(
+            dialog.get_by_role("combobox", name="Preview Quality", exact=True)
+        ).to_have_count(0)
+        download = dialog.get_by_role("link", name="Download Original", exact=True)
+        original_download = download.get_attribute("href")
+        player.evaluate(
+            "async element=>{await element.pause();await element.player.seek(2)}"
+        )
+        page.wait_for_function(
+            "()=>Math.abs(document.querySelector('movi-player').currentTime-2)<0.2"
+        )
+        menu = _open_settings(player, touch=touch)
+        for name in ("Ambient mode", "Stable volume"):
+            expect(menu.get_by_role("button", name=name, exact=True)).to_be_visible()
+        quality = menu.locator('.movi-settings-row[data-page="quality"]')
+        quality.tap() if touch else quality.click()
+        expect(menu.locator(".movi-settings-page-title")).to_have_text("Quality")
+        original = menu.get_by_role("button", name="Original", exact=True)
+        expect(original).to_be_visible()
+        expect(original).to_have_attribute("aria-pressed", "true")
+        back = menu.locator(".movi-settings-back")
+        back.tap() if touch else back.click()
+        expect(quality).to_be_visible()
+        quality.tap() if touch else quality.click()
+        expect(
+            menu.get_by_role("group", name="Video quality", exact=True)
+        ).to_be_visible()
+        alternate = menu.get_by_role(
+            "button", name="Fixture alternate source", exact=True
+        )
+        expect(alternate).to_be_visible()
+        assert player.evaluate("element=>element.scrollLeft===0&&element.scrollTop===0")
+        bounds = menu.bounding_box()
+        assert bounds is not None
+        assert bounds["x"] >= -1 and bounds["x"] + bounds["width"] <= width + 1
+        assert bounds["y"] >= -1 and bounds["y"] + bounds["height"] <= height + 1
+        assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        kind = "touch-phone" if touch else "desktop"
+        page.screenshot(path=ARTIFACTS / f"video-quality-settings-{kind}.png")
+        player.evaluate("element=>window.previousQualityPlayer=element")
+        alternate.tap() if touch else alternate.click()
+        page.wait_for_function("""()=>{
+          const player=document.querySelector('movi-player');
+          return player&&player!==window.previousQualityPlayer&&player.duration>4;
+        }""")
+        page.wait_for_function(
+            "()=>Math.abs(document.querySelector('movi-player').currentTime-2)<0.2"
+        )
+        assert player.evaluate("element=>element.paused")
+        expect(download).to_have_attribute("href", original_download)
+        expect(dialog.locator(".preview-quality")).to_have_count(0)
+        menu = _open_settings(player, touch=touch)
+        quality.tap() if touch else quality.click()
+        expect(alternate).to_have_attribute("aria-pressed", "true")
+        player.evaluate("element=>window.previousQualityPlayer=element")
+        original.tap() if touch else original.click()
+        page.wait_for_function("""()=>{
+          const player=document.querySelector('movi-player');
+          return player&&player!==window.previousQualityPlayer&&player.duration>4;
+        }""")
+        page.wait_for_function(
+            "()=>Math.abs(document.querySelector('movi-player').currentTime-2)<0.2"
+        )
+        assert player.evaluate("element=>element.paused")
+        expect(download).to_have_attribute("href", original_download)
+        assert errors == []
+    finally:
+        context.close()
+
+
+def test_video_without_alternate_sources_has_no_quality_row_or_preview_bar(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    page.get_by_role("button", name="movtext-subtitles.mp4", exact=True).press("Enter")
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    expect(dialog.locator(".preview-quality")).to_have_count(0)
+    menu = _open_settings(player, touch=False)
+    expect(menu.locator('.movi-settings-row[data-page="quality"]')).to_have_count(0)
+
+
+def test_quality_switch_in_fullscreen_keeps_video_position_and_f_exits(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    media_requests: list[str] = []
+    page.on(
+        "request",
+        lambda request: (
+            media_requests.append(request.url)
+            if "/file?" in request.url and request.method == "GET"
+            else None
+        ),
+    )
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    page.get_by_role("button", name="multitrack.mkv", exact=True).press("Enter")
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    page.wait_for_function("()=>document.querySelector('movi-player')?.duration>4")
+    player.evaluate(
+        "async element=>{await element.pause();await element.player.seek(2)}"
+    )
+    page.wait_for_function(
+        "()=>Math.abs(document.querySelector('movi-player').currentTime-2)<0.2"
+    )
+    dialog.get_by_role("button", name="Enter Fullscreen", exact=True).click()
+    page.wait_for_function(
+        "()=>document.fullscreenElement===document.querySelector('movi-player')"
+    )
+    menu = _open_settings(player, touch=False)
+    menu.locator('.movi-settings-row[data-page="quality"]').click()
+    player.evaluate("element=>window.fullscreenQualityPlayer=element")
+    menu.get_by_role("button", name="Fixture alternate source", exact=True).click()
+    page.wait_for_function("""()=>{
+      const player=document.querySelector('movi-player');
+      return player&&player!==window.fullscreenQualityPlayer&&player.duration>4;
+    }""")
+    page.wait_for_function(
+        "()=>Math.abs(document.querySelector('movi-player').currentTime-2)<0.2"
+    )
+    assert player.evaluate("element=>element.paused")
+    assert player.evaluate("element=>!!document.fullscreenElement?.contains(element)")
+    assert any("quality=fixture-same-bytes" in url for url in media_requests)
+    expect(player).to_be_focused()
+    player.press("f")
+    page.wait_for_function("()=>!document.fullscreenElement")
+    expect(
+        dialog.get_by_role("button", name="Enter Fullscreen", exact=True)
+    ).to_be_focused()
diff --git a/tests/browser/test_browser_refresh_feedback.py b/tests/browser/test_browser_refresh_feedback.py
new file mode 100644
index 00000000..554f1e11
--- /dev/null
+++ b/tests/browser/test_browser_refresh_feedback.py
@@ -0,0 +1,200 @@
+"""Explicit refresh feedback waits for fresh data; automatic polling stays quiet."""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+from urllib.parse import urlsplit
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium tests", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import expect, login
+
+browser = fixtures.browser
+desktop = fixtures.desktop
+server = fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+def response_path(response, path, method="GET"):
+    return urlsplit(response.url).path == path and response.request.method == method
+
+
+def open_page(page, server, view, initial_path):
+    login(page, server.url)
+    with page.expect_response(lambda response: response_path(response, initial_path)):
+        page.goto(server.url + "/?view=" + view)
+    expect(page.locator(".toast")).to_have_count(0)
+
+
+def wait_for_request(page, held):
+    deadline = time.monotonic() + 5
+    while not held and time.monotonic() < deadline:
+        page.wait_for_timeout(20)
+    assert held, "The explicit refresh did not request fresh data"
+
+
+def assert_pending(page, button, held):
+    wait_for_request(page, held)
+    expect(button).to_be_disabled()
+    expect(button.locator(".spinner")).to_have_count(1)
+    expect(page.locator(".toast:not(.toast-error)")).to_have_count(0)
+    # Give both click events and a new render time to settle, with the actual
+    # response still held. This detects duplicate origin requests without
+    # relying on how the component stores its pending state.
+    page.wait_for_timeout(100)
+    assert len(held) == 1
+
+
+@pytest.mark.parametrize(
+    "view,initial_path,endpoint,method,button_name,button_title",
+    [
+        (
+            "preloads",
+            "/api/v1/preloads",
+            "/api/v1/preloads",
+            "GET",
+            "Refresh Cache Inventory",
+            None,
+        ),
+        (
+            "performance",
+            "/api/v1/performance",
+            "/api/v1/performance",
+            "GET",
+            "Refresh Performance",
+            None,
+        ),
+        (
+            "shares",
+            "/api/v1/shares",
+            "/api/v1/shares",
+            "GET",
+            "Refresh Shared Links",
+            None,
+        ),
+        ("storage", "/api/v1/settings", "/api/v1/settings", "GET", "Check Again", None),
+        (
+            "connections",
+            "/api/v1/settings",
+            "/api/v1/settings/refresh",
+            "POST",
+            None,
+            "Check saved credentials and storage channel access",
+        ),
+        (
+            "storage",
+            "/api/v1/replica",
+            "/api/v1/replica",
+            "GET",
+            "Refresh channel backup status",
+            None,
+        ),
+    ],
+    ids=[
+        "preloads",
+        "performance",
+        "shares",
+        "storage",
+        "connections",
+        "channel-backup",
+    ],
+)
+def test_manual_refresh_disables_and_confirms_only_after_success(
+    server, desktop, view, initial_path, endpoint, method, button_name, button_title
+):
+    _, page = desktop
+    open_page(page, server, view, initial_path)
+    button = (
+        page.get_by_title(button_title, exact=True)
+        if button_title
+        else page.get_by_role("button", name=button_name, exact=True)
+    )
+    expect(button).to_be_enabled()
+    payload_path = "/api/v1/settings" if method == "POST" else endpoint
+    payload = page.request.get(server.url + payload_path).json()
+    held = []
+
+    def hold(route):
+        if route.request.method != method:
+            route.continue_()
+        else:
+            held.append(route)
+
+    page.route("**" + endpoint, hold)
+    button.dblclick()
+    assert_pending(page, button, held)
+    held[0].fulfill(json=payload)
+    expect(button).to_be_enabled()
+    expect(page.locator(".toast:not(.toast-error)")).to_contain_text(
+        re.compile(r"refreshed|checks requested", re.I)
+    )
+
+
+def test_performance_refresh_waits_for_history_as_well_as_snapshot(server, desktop):
+    _, page = desktop
+    open_page(page, server, "performance", "/api/v1/performance/history")
+    button = page.get_by_role("button", name="Refresh Performance", exact=True)
+    expect(button).to_be_enabled()
+    held = []
+
+    def hold_history(route):
+        held.append((route, route.fetch().json()))
+
+    page.route("**/api/v1/performance/history?*", hold_history)
+    with page.expect_response(
+        lambda response: response_path(response, "/api/v1/performance")
+    ):
+        button.dblclick()
+    wait_for_request(page, held)
+    expect(button).to_be_disabled()
+    expect(page.locator(".toast:not(.toast-error)")).to_have_count(0)
+    assert len(held) == 1
+    route, payload = held[0]
+    route.fulfill(json=payload)
+    expect(button).to_be_enabled()
+    expect(page.locator(".toast:not(.toast-error)")).to_have_text(
+        re.compile(r"Performance refreshed\.")
+    )
+
+
+def test_failed_refresh_has_no_success_and_retry_then_polling_stays_quiet(
+    server, desktop
+):
+    _, page = desktop
+    open_page(page, server, "preloads", "/api/v1/preloads")
+    button = page.get_by_role("button", name="Refresh Cache Inventory", exact=True)
+    expect(button).to_be_enabled()
+    payload = page.request.get(server.url + "/api/v1/preloads").json()
+    held = []
+    page.route("**/api/v1/preloads", lambda route: held.append(route))
+    button.dblclick()
+    assert_pending(page, button, held)
+    held[0].fulfill(status=503, json={"detail": "Refresh is temporarily unavailable."})
+    expect(button).to_be_enabled()
+    expect(page.locator(".toast.toast-error")).to_contain_text(
+        "Refresh is temporarily unavailable."
+    )
+    expect(page.locator(".toast:not(.toast-error)")).to_have_count(0)
+    page.get_by_role("button", name="Dismiss Notification").click()
+    held.clear()
+    button.dblclick()
+    assert_pending(page, button, held)
+    held[0].fulfill(json=payload)
+    expect(button).to_be_enabled()
+    expect(page.locator(".toast:not(.toast-error)")).to_contain_text(
+        "Cache inventory refreshed."
+    )
+    expect(page.locator(".toast.toast-error")).to_have_count(0)
+    page.get_by_role("button", name="Dismiss Notification").click()
+    page.unroute("**/api/v1/preloads")
+    with page.expect_response(
+        lambda response: response_path(response, "/api/v1/preloads"), timeout=8000
+    ):
+        pass
+    expect(page.locator(".toast")).to_have_count(0)
diff --git a/tests/browser/test_browser_rename.py b/tests/browser/test_browser_rename.py
new file mode 100644
index 00000000..6597a1d7
--- /dev/null
+++ b/tests/browser/test_browser_rename.py
@@ -0,0 +1,127 @@
+"""File renames preserve the extension used by previews and downloads."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    expect,
+    finish_fixture_uploads,
+    fixture_nodes,
+    login,
+    preview_dialog,
+    upload,
+)
+
+browser = fixtures.browser
+desktop = fixtures.desktop
+server = fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+def rename_dialog(page, name):
+    page.get_by_label("Actions for " + name, exact=True).click()
+    page.get_by_role("button", name="Rename", exact=True).click()
+    dialog = page.get_by_role("dialog", name="Rename", exact=True)
+    expect(dialog).to_be_visible()
+    expect(dialog.get_by_label("Name", exact=True)).to_be_focused()
+    return dialog
+
+
+def save_name(page, dialog, name):
+    dialog.get_by_label("Name", exact=True).fill(name)
+    with page.expect_response("**/api/renameFileFolder") as saved:
+        dialog.get_by_role("button", name="Save Name", exact=True).click()
+    assert saved.value.ok, saved.value.text()
+    expect(dialog).not_to_be_visible()
+    return saved.value.request.post_data_json["name"]
+
+
+@pytest.mark.parametrize("width", [1440, 390, 320])
+def test_file_rename_keeps_extension_and_video_preview(server, desktop, width):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).press("Enter")
+    dialog = rename_dialog(page, "movtext-subtitles.mp4")
+    name = dialog.get_by_label("Name", exact=True)
+    expect(name).to_have_value("movtext-subtitles")
+    expect(name).to_have_attribute("aria-describedby", "item-name-hint")
+    suffix = dialog.locator(".rename-extension")
+    expect(suffix).to_be_visible()
+    expect(suffix).to_have_text(".mp4")
+    assert suffix.evaluate(
+        "element => !element.isContentEditable && "
+        "!element.matches('input,textarea,select')"
+    )
+    expect(dialog.locator("#item-name-hint")).to_contain_text("extension")
+    name.fill("earth.v2")
+    expect(suffix).to_have_text(".mp4")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    bounds = dialog.bounding_box()
+    assert bounds["x"] >= 0 and bounds["x"] + bounds["width"] <= width
+    page.screenshot(path=ARTIFACTS / f"rename-extension-{width}.png")
+
+    assert save_name(page, dialog, "earth.v2") == "earth.v2.mp4"
+    renamed = page.get_by_role("button", name="earth.v2.mp4", exact=True)
+    expect(renamed).to_be_visible()
+    renamed.press("Enter")
+    preview = preview_dialog(page)
+    player = preview.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(preview.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    player.locator("button.movi-play-pause").click()
+    page.wait_for_function(
+        "() => document.querySelector('movi-player').player"
+        ".getRenderHealth().framesPresented >= 1",
+        timeout=15000,
+    )
+    player.evaluate("element => element.pause()")
+    with page.expect_download() as download:
+        preview.get_by_role("link", name="Download Original", exact=True).click()
+    assert download.value.suggested_filename == "earth.v2.mp4"
+
+
+def test_dotted_folder_rename_edits_the_complete_name(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    created = page.request.post(
+        server.url + "/api/createNewFolder",
+        data={"path": "/", "name": "Project.v1"},
+    )
+    assert created.ok, created.text()
+    page.reload()
+    dialog = rename_dialog(page, "Project.v1")
+    expect(dialog.get_by_label("Name", exact=True)).to_have_value("Project.v1")
+    expect(dialog.locator(".rename-extension")).to_have_count(0)
+    assert save_name(page, dialog, "Project.v2") == "Project.v2"
+    expect(page.get_by_role("button", name="Project.v2", exact=True)).to_be_visible()
+    names = [node["name"] for node in fixture_nodes(page, server, "/")]
+    assert "Project.v2" in names and "Project.v2.v1" not in names
+
+
+def test_extensionless_file_can_be_renamed_and_have_its_extension_restored(
+    server, desktop
+):
+    _, page = desktop
+    login(page, server.url)
+    upload(page, ["README"])
+    finish_fixture_uploads(page, server, 1)
+    page.reload()
+    dialog = rename_dialog(page, "README")
+    expect(dialog.get_by_label("Name", exact=True)).to_have_value("README")
+    expect(dialog.locator(".rename-extension")).to_have_count(0)
+    assert save_name(page, dialog, "restored.txt") == "restored.txt"
+    expect(page.get_by_role("button", name="restored.txt", exact=True)).to_be_visible()
+
+    dialog = rename_dialog(page, "restored.txt")
+    expect(dialog.get_by_label("Name", exact=True)).to_have_value("restored")
+    expect(dialog.locator(".rename-extension")).to_have_text(".txt")
+    dialog.get_by_role("button", name="Cancel", exact=True).click()
diff --git a/tests/browser/test_browser_scoped_search.py b/tests/browser/test_browser_scoped_search.py
new file mode 100644
index 00000000..9a45452b
--- /dev/null
+++ b/tests/browser/test_browser_scoped_search.py
@@ -0,0 +1,293 @@
+"""Contextual searches stay within the page and preserve bounded history paging."""
+# ruff: noqa: F811 - pytest fixture parameters shadow imported fixture functions.
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium checks", allow_module_level=True)
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    browser,  # noqa: F401
+    desktop,  # noqa: F401
+    expect,
+    login,
+    open_admin,
+    server,  # noqa: F401
+)
+
+pytestmark = pytest.mark.e2e
+
+
+def test_context_switch_trash_shares_and_preloads_keep_search_scoped(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    contents = page.request.post(
+        server.url + "/api/getDirectory", data={"path": "/"}
+    ).json()["data"]["contents"]
+    folder = next(item for item in contents.values() if item["name"] == "資料")
+    assert page.request.post(
+        server.url + "/api/trashFileFolder",
+        data={"path": "/" + folder["id"], "trash": True},
+    ).ok
+    page.get_by_role("link", name="Trash", exact=True).click()
+    search = page.get_by_role("searchbox", name="Search Trash", exact=True)
+    expect(search).to_be_visible()
+    assert (
+        search.locator("xpath=ancestor::*[contains(@class,'file-toolbar')]").count()
+        == 1
+    )
+    search.fill("資料")
+    expect(page.get_by_role("button", name="資料", exact=True)).to_be_visible()
+    search.fill("not in the trash")
+    expect(
+        page.get_by_role("heading", name="No Matching Trashed Items")
+    ).to_be_visible()
+    assert "search_" not in page.url
+    expect(page.get_by_role("heading", name="Trash", exact=True)).to_be_visible()
+    search.press("Escape")
+    expect(search).to_have_value("")
+    expect(search).to_be_focused()
+
+    shares = [
+        {
+            "id": name,
+            "path": "/" + name,
+            "name": name,
+            "created_at": "2026-10-17T00:00:00Z",
+            "expires_at": None,
+            "type": "file",
+            "copyable": True,
+        }
+        for name in ("Movie.mp4", "Notes.pdf")
+    ]
+    page.route("**/api/v1/shares", lambda route: route.fulfill(json={"shares": shares}))
+    page.get_by_role("link", name="Shared Links", exact=True).click()
+    search = page.get_by_role("searchbox", name="Search Shared Links", exact=True)
+    expect(search).to_have_value("")
+    search.fill("movie")
+    expect(page.locator(".share-row")).to_have_count(1)
+    expect(page.locator(".share-row")).to_contain_text("Movie.mp4")
+    assert "view=shares" in page.url
+    search.fill("missing")
+    expect(page.get_by_role("heading", name="No Matching Shared Links")).to_be_visible()
+
+    cache = page.request.get(server.url + "/api/v1/preloads").json()
+    cache["cache"]["files"] = [
+        {
+            "id": name,
+            "name": name,
+            "size": 100,
+            "ready_bytes": 100,
+            "complete": True,
+            "ready_ranges": [[0, 100]],
+        }
+        for name in ("Movie.mp4", "Interview.mkv")
+    ]
+    page.route("**/api/v1/preloads", lambda route: route.fulfill(json=cache))
+    open_admin(page)
+    page.get_by_role("link", name="Preloads", exact=True).click()
+    search = page.get_by_role("searchbox", name="Search cached files", exact=True)
+    expect(search).to_have_value("")
+    expect(page.get_by_role("searchbox")).to_have_count(1)
+    search.fill("interview")
+    expect(page.locator(".cached-file")).to_have_count(1)
+    expect(page.locator(".cached-file")).to_contain_text("Interview.mkv")
+    page.keyboard.press("Control+k")
+    expect(search).to_be_focused()
+    search.press("Escape")
+    expect(page.locator(".cached-file")).to_have_count(2)
+    page.get_by_role("link", name="My Files", exact=True).click()
+    expect(
+        page.get_by_role("searchbox", name="Search Files and Folders", exact=True)
+    ).to_have_value("")
+
+
+def test_transfer_search_resets_cursor_and_filters_active_and_old_finished_names(
+    server, desktop
+):
+    _, page = desktop
+
+    def job(identity, name, at, status="completed"):
+        return dict(
+            id=identity,
+            name=name,
+            kind="upload",
+            status=status,
+            phase=status,
+            total=100,
+            current=50 if status == "running" else 100,
+            created_at=at,
+            finished_at=at + 1 if status == "completed" else None,
+        )
+
+    records = [job(f"record-{i}", f"recent-{i}.bin", 1000 - i) for i in range(55)]
+    records.append(job("old-result", "Archive video.mp4", 1))
+    active = job("active", "Live video.mp4", 2000, "running")
+    page.route("**/api/v1/jobs", lambda route: route.fulfill(json={"jobs": [active]}))
+    seen = []
+
+    def history(route):
+        params = route.request.post_data_json
+        seen.append(params)
+        query = params.get("q", "").lower()
+        offset = params["offset"]
+        selected = [row for row in records if query in row["name"].lower()]
+        rows = selected[offset : offset + 20]
+        route.fulfill(
+            json={
+                "jobs": rows,
+                "page": params["page"],
+                "page_size": 20,
+                "total_tasks": len(selected),
+                "total_pages": max(1, (len(selected) + 19) // 20),
+                "has_more": offset + 20 < len(selected),
+            }
+        )
+
+    page.route("**/api/v1/transfers/history/tasks", history)
+    login(page, server.url)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    pager = page.get_by_role("navigation", name="Finished transfer pages")
+    pager.get_by_role(
+        "button", name="Next page of finished transfers", exact=True
+    ).click()
+    expect(pager.get_by_role("status")).to_contain_text("Page 2 of 3")
+    search = page.get_by_role("searchbox", name="Search Transfers", exact=True)
+    search.fill("Archive")
+    finished = page.locator('[data-category="finished"]')
+    expect(finished).to_contain_text("Archive video.mp4")
+    expect(pager.get_by_role("status")).to_have_text("Page 1 of 1 · 1 task")
+    expect(finished.locator(".transfer-item-name")).to_have_count(1)
+    assert seen[-1]["q"] == "Archive" and seen[-1]["offset"] == 0
+    expect(page.locator('[data-category="running"]')).to_have_count(0)
+    search.fill("Live")
+    expect(page.locator('[data-category="running"]')).to_contain_text("Live video.mp4")
+    expect(
+        page.get_by_role("heading", name="No Matching Finished Transfers")
+    ).to_be_visible()
+    search.press("Escape")
+    expect(pager.get_by_role("status")).to_contain_text("Page 1 of 3")
+    expect(finished.locator(".transfer-item-name")).to_have_count(20)
+
+
+def test_touch_selection_is_explicit_and_ignores_management_actions(server, browser):
+    context = browser.new_context(
+        viewport={"width": 390, "height": 844}, has_touch=True, is_mobile=True
+    )
+    try:
+        page = context.new_page()
+        login(page, server.url)
+        first = page.get_by_role("button", name="Preview samples", exact=True)
+        second = page.get_by_role("button", name="Private folder", exact=True)
+        page.get_by_role("button", name="Select", exact=True).tap()
+        first.tap()
+        second.tap()
+        # Selection mode supports independent, additive taps on different rows.
+        expect(page.get_by_text("2 selected", exact=True)).to_be_visible()
+        expect(page.get_by_label("Select Preview samples", exact=True)).to_be_checked()
+        expect(page.get_by_label("Select Private folder", exact=True)).to_be_checked()
+        page.get_by_label("Actions for Private folder", exact=True).tap()
+        page.keyboard.press("Escape")
+        page.get_by_role("button", name="Done", exact=True).tap()
+        second.tap()
+        expect(
+            page.get_by_role("heading", name="Private folder", exact=True)
+        ).to_be_visible()
+        expect(
+            page.get_by_role("button", name="private.txt", exact=True)
+        ).to_be_visible()
+    finally:
+        context.close()
+
+
+def test_touch_file_opens_without_entering_selection(server, browser):
+    context = browser.new_context(
+        viewport={"width": 390, "height": 844}, has_touch=True, is_mobile=True
+    )
+    try:
+        page = context.new_page()
+        login(page, server.url)
+        page.get_by_role("button", name="Preview samples", exact=True).focus()
+        page.keyboard.press("Enter")
+        primary = page.get_by_role("button", name="sample.json", exact=True)
+        primary.tap()
+        expect(page.locator("dialog.file-preview")).to_be_visible()
+    finally:
+        context.close()
+
+
+@pytest.mark.parametrize("width,height", [(1440, 900), (390, 844), (320, 720)])
+def test_compact_fixed_directory_controls_leave_room_for_files(
+    server, desktop, width, height
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": height})
+    login(page, server.url)
+    folder = page.get_by_role("button", name="資料", exact=True)
+    folder.focus()
+    folder.press("Enter")
+    expect(page.get_by_role("heading", name="資料", exact=True)).to_be_visible()
+    expect(
+        page.get_by_role("navigation", name="Breadcrumb").get_by_text(
+            "資料", exact=True
+        )
+    ).to_have_count(0)
+    search = page.get_by_role("searchbox", name="Search Files and Folders", exact=True)
+    if width <= 720:
+        expect(search).not_to_be_visible()
+        expect(
+            page.get_by_role("button", name="Search Files and Folders", exact=True)
+        ).to_be_visible()
+    else:
+        expect(search).to_be_visible()
+    ratio = page.locator(".file-list-scroll").evaluate(
+        "node => node.clientHeight / node.closest('.workspace').clientHeight"
+    )
+    if width > 720:
+        assert ratio > 0.60
+    else:
+        assert (
+            page.locator(".workspace").evaluate(
+                "node => getComputedStyle(node).overflowY"
+            )
+            == "auto"
+        )
+    bounds = page.locator(".workspace").bounding_box()
+    viewport = page.viewport_size
+    assert abs(bounds["x"] + bounds["width"] - viewport["width"]) <= 1
+    assert abs(bounds["y"] + bounds["height"] - viewport["height"]) <= 1
+    assert bounds["y"] == (52 if width < 700 else 0)
+    if width < 700:
+        assert bounds["x"] == 0
+    else:
+        sidebar = page.locator(".sidebar").bounding_box()
+        assert abs(bounds["x"] - sidebar["x"] - sidebar["width"]) <= 1
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    assert page.locator(".file-toolbar").evaluate(
+        "node => node.scrollWidth <= node.clientWidth + 1"
+    )
+    page.keyboard.press("Control+k")
+    expect(search).to_be_focused()
+    if width in (1440, 390):
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=ARTIFACTS / f"directory-compact-search-{width}.png")
+    if width < 700:
+        page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+        sidebar = page.locator(".sidebar")
+        assert sidebar.evaluate("node => getComputedStyle(node).overflowY") == "auto"
+        logout = page.get_by_role("button", name="Log Out", exact=True)
+        logout.scroll_into_view_if_needed()
+        expect(logout).to_be_in_viewport()
+        documentation = page.get_by_role("link", name="Documentation", exact=True)
+        documentation.scroll_into_view_if_needed()
+        expect(documentation).to_be_in_viewport()
+        sidebar.locator(".sidebar-tools > summary").click()
+        page.get_by_role("link", name="Storage & Backups", exact=True).focus()
+        expect(
+            page.get_by_role("link", name="Storage & Backups", exact=True)
+        ).to_be_in_viewport()
diff --git a/tests/browser/test_browser_starred_thumbnails.py b/tests/browser/test_browser_starred_thumbnails.py
new file mode 100644
index 00000000..7d36a11f
--- /dev/null
+++ b/tests/browser/test_browser_starred_thumbnails.py
@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, CONTROL, expect, login
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.mark.parametrize("width", [1440, 390, 320])
+def test_starred_page_add_find_open_and_remove(server, desktop, width):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url)
+    assert page.locator(".brand-logo img").first.evaluate(
+        "img => img.complete && img.naturalWidth > 0"
+    )
+    page.locator('summary[aria-label="Actions for 資料"]').click()
+    page.get_by_role("button", name="Add to Starred", exact=True).click()
+    expect(
+        page.locator(".file-status-label").filter(has_text="Starred")
+    ).to_be_visible()
+    if width < 721:
+        page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+    page.get_by_role("link", name="Starred", exact=True).click()
+    expect(page.get_by_role("heading", name="Starred", exact=True)).to_be_visible()
+    expect(page.locator('.drive-nav a[aria-current="page"]')).to_have_text("Starred")
+    expect(page.get_by_role("button", name="資料", exact=True)).to_be_visible()
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / f"starred-{width}.png", animations="disabled")
+    page.locator('summary[aria-label="Actions for 資料"]').click()
+    page.get_by_role("button", name="Remove from Starred", exact=True).click()
+    expect(
+        page.get_by_role("heading", name="No Starred Items Yet", exact=True)
+    ).to_be_visible()
+
+
+def test_grid_uses_own_upload_derivatives_without_original_reads(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    folder = page.request.post(
+        server.url + "/__test__/thumbnails/generated", headers=CONTROL
+    ).json()["path"]
+    originals = []
+    page.on(
+        "request",
+        lambda request: (
+            originals.append(request.url) if "/file?" in request.url else None
+        ),
+    )
+    page.goto(server.url + "/?path=" + folder)
+    page.get_by_role("button", name="Grid view", exact=True).click()
+    for name in ["Illustration.png", "Walkthrough.mp4"]:
+        row = page.locator(".file-row").filter(
+            has=page.get_by_role("button", name=name, exact=True)
+        )
+        expect(row.locator(".file-tile-preview img")).to_be_visible()
+        assert (
+            row.locator(".file-tile-preview img")
+            .get_attribute("src")
+            .startswith("data:image/jpeg")
+        )
+    assert originals == []
+    page.screenshot(path=ARTIFACTS / "generated-thumbnail-grid.png")
diff --git a/tests/browser/test_browser_thumbnail_rebuild.py b/tests/browser/test_browser_thumbnail_rebuild.py
new file mode 100644
index 00000000..3d3d6ff6
--- /dev/null
+++ b/tests/browser/test_browser_thumbnail_rebuild.py
@@ -0,0 +1,112 @@
+"""Local production-bundle UI with synthetic rebuild progress and generated manga."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, CONTROL, expect, login
+
+browser, desktop, server = fixtures.browser, fixtures.desktop, fixtures.server
+pytestmark = pytest.mark.e2e
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_thumbnail_confirmation_progress_reload_and_cancellation(
+    server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 900})
+    state = {
+        "status": "idle",
+        "phase": "Ready",
+        "total": 0,
+        "processed": 0,
+        "generated": 0,
+        "failed": 0,
+        "skipped": 0,
+        "source_bytes": 0,
+    }
+    starts = []
+
+    def route(request):
+        if request.request.method == "POST":
+            starts.append(request.request.post_data_json)
+            state.update(
+                status="running",
+                phase="Regenerating thumbnail",
+                total=100,
+                current_name="movie.mov",
+            )
+        request.fulfill(
+            status=202 if request.request.method == "POST" else 200, json=state.copy()
+        )
+
+    def cancel(route):
+        state.update(status="cancelled", phase="Stopped")
+        route.fulfill(json=state.copy())
+
+    page.route("**/api/v1/settings/thumbnails/rebuild", route)
+    page.route("**/api/v1/settings/thumbnails/rebuild/cancel", cancel)
+    login(page, server.url + "/?view=settings&section=cache")
+    page.get_by_role("button", name="Regenerate all thumbnails", exact=True).click()
+    dialog = page.get_by_role("dialog", name="Regenerate all thumbnails?")
+    expect(dialog).to_contain_text("substantial bandwidth")
+    assert starts == []
+    expect(dialog.get_by_role("button", name="Cancel", exact=True)).to_be_focused()
+    dialog.get_by_role("button", name="Start background rebuild", exact=True).click()
+    expect(dialog).not_to_be_visible()
+    expect(
+        page.get_by_role("button", name="Cancel rebuild", exact=True)
+    ).to_be_visible()
+    assert starts == [{"confirmed": True}]
+    state.update(
+        processed=50, generated=45, skipped=3, failed=2, source_bytes=5 * 1024**2
+    )
+    progress = page.get_by_role("progressbar", name="Thumbnail rebuild progress")
+    expect(progress).to_have_attribute("value", "50")
+    page.reload()
+    expect(progress).to_have_attribute("value", "50")
+    expect(page.locator(".thumbnail-rebuild-status")).to_contain_text("45 regenerated")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / f"thumbnail-rebuild-{width}.png", full_page=True)
+    page.get_by_role("button", name="Cancel rebuild", exact=True).click()
+    expect(
+        page.get_by_role("button", name="Regenerate all thumbnails", exact=True)
+    ).to_be_visible()
+    expect(page.locator(".thumbnail-rebuild-status")).to_contain_text("Stopped")
+
+
+@pytest.mark.parametrize("width", [1440, 390, 320])
+def test_image_based_epub_manga_fit_and_direction(server, desktop, width):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 900})
+    login(page, server.url)
+    folder = page.request.post(server.url + "/__test__/books", headers=CONTROL).json()[
+        "path"
+    ]
+    page.goto(server.url + "/?path=" + folder)
+    page.get_by_role("button", name="Image-based manga.epub", exact=True).press("Enter")
+    image = page.locator(".book-illustrated-page img")
+    expect(image).to_be_visible()
+    expect(image).to_have_js_property("naturalWidth", 480)
+    page.locator('summary[aria-label="Reading options"]').click()
+    page.get_by_label("Page fit", exact=True).select_option("page")
+    page.get_by_label("Right to left", exact=True).check()
+    page.locator('summary[aria-label="Reading options"]').click()
+    bounds = image.bounding_box()
+    assert bounds["height"] <= 900 - 180 + 1
+    assert abs(bounds["width"] / bounds["height"] - 480 / 720) < 0.01
+    page.locator(".book-content").focus()
+    page.keyboard.press("ArrowLeft")
+    expect(page.locator(".book-position")).to_have_text("2 / 2")
+    expect(image).to_be_visible()
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    ARTIFACTS.mkdir(parents=True, exist_ok=True)
+    page.screenshot(path=ARTIFACTS / f"manga-epub-fit-page-{width}.png")
diff --git a/tests/browser/test_browser_transfer_pagination.py b/tests/browser/test_browser_transfer_pagination.py
new file mode 100644
index 00000000..3de0e90f
--- /dev/null
+++ b/tests/browser/test_browser_transfer_pagination.py
@@ -0,0 +1,164 @@
+"""Bounded terminal task pages alongside current live uploads."""
+# ruff: noqa: F811 - pytest fixture parameters shadow imported fixture functions.
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+pytestmark = pytest.mark.e2e
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 for Chromium tests", allow_module_level=True)
+
+from tests.browser.test_browser_e2e import (  # noqa: E402
+    ARTIFACTS,
+    browser,  # noqa: F401 - shared pytest fixture
+    desktop,  # noqa: F401 - shared pytest fixture
+    expect,
+    login,
+    server,  # noqa: F401 - shared pytest fixture
+)
+
+
+def test_finished_history_cursor_pages_keep_live_sections_and_reset_filters(
+    server,
+    desktop,
+):
+    _, page = desktop
+
+    def job(identity, status, at):
+        return {
+            "id": identity,
+            "name": identity + ".bin",
+            "kind": "upload",
+            "status": status,
+            "phase": "uploading" if status == "running" else status,
+            "current": 40 if status == "running" else 100,
+            "total": 100,
+            "created_at": at,
+            "finished_at": at + 1
+            if status in {"completed", "error", "cancelled"}
+            else None,
+            "error": "Provider rejected the upload" if status == "error" else None,
+        }
+
+    active = [job("live-running", "running", 1000), job("live-queued", "queued", 999)]
+    records = [
+        job("recent-success", "completed", 100),
+        job("recent-failure", "error", 99),
+        *[job(f"recent-error-{at}", "error", at) for at in range(98, 80, -1)],
+        job("older-cancelled", "cancelled", 80),
+        job("older-success", "completed", 79),
+        *[job(f"older-error-{at}", "error", at) for at in range(78, 60, -1)],
+        job("oldest-failure", "error", 60),
+    ]
+    page.route(
+        "**/api/v1/jobs",
+        lambda route: route.fulfill(json={"jobs": active + records[:2]}),
+    )
+    seen = []
+    fail_once = [True]
+
+    def history(route):
+        query = route.request.post_data_json
+        seen.append(query)
+        status = query["status"]
+        if status == "error" and fail_once:
+            fail_once.pop()
+            route.fulfill(
+                status=503, json={"detail": "History temporarily unavailable"}
+            )
+            return
+        selected = (
+            records
+            if status == "finished"
+            else []
+            if status in {"error", "cancelled"}
+            else [record for record in records if record["status"] == status]
+        )
+        offset = query["offset"]
+        batch = selected[offset : offset + 20]
+        route.fulfill(
+            json={
+                "jobs": batch,
+                "page": query["page"],
+                "page_size": 20,
+                "total_tasks": len(selected),
+                "total_pages": max(1, (len(selected) + 19) // 20),
+                "has_more": offset + 20 < len(selected),
+            }
+        )
+
+    page.route("**/api/v1/transfers/history/tasks", history)
+    login(page, server.url)
+    page.goto(server.url + "/?view=activity")
+    history_region = page.get_by_role("region", name="Transfer History", exact=True)
+    finished = history_region.locator('[data-category="finished"]')
+    pager = history_region.get_by_role("navigation", name="Finished transfer pages")
+    expect(finished).to_contain_text("recent-success.bin")
+    expect(finished).to_contain_text("recent-failure.bin")
+    expect(finished.locator(".transfer-item-name")).to_have_text(
+        [record["name"] for record in records[:20]]
+    )
+    assert history_region.locator(".transfer-category").evaluate_all(
+        "rows => rows.map(row => row.dataset.category)"
+    ) == ["running", "queued", "finished"]
+    previous = pager.get_by_role(
+        "button", name="Previous page of finished transfers", exact=True
+    )
+    next_page = pager.get_by_role(
+        "button", name="Next page of finished transfers", exact=True
+    )
+    expect(previous).to_be_disabled()
+    next_page.click()
+    expect(pager.get_by_role("status")).to_contain_text("Page 2 of 3")
+    expect(finished).to_contain_text("older-cancelled.bin")
+    expect(finished).not_to_contain_text("recent-success.bin")
+    expect(finished).not_to_contain_text("recent-failure.bin")
+    expect(history_region.locator('[data-category="running"]')).to_contain_text(
+        "live-running.bin"
+    )
+    expect(history_region.locator('[data-category="queued"]')).to_contain_text(
+        "live-queued.bin"
+    )
+    next_page.click()
+    expect(pager.get_by_role("status")).to_contain_text("Page 3 of 3")
+    expect(finished).to_contain_text("oldest-failure.bin")
+    expect(next_page).to_be_disabled()
+    previous.click()
+    expect(pager.get_by_role("status")).to_contain_text("Page 2 of 3")
+    expect(finished).to_contain_text("older-success.bin")
+    page.screenshot(path=ARTIFACTS / "transfer-pagination-desktop.png", full_page=True)
+    filters = history_region.get_by_role("group", name="Filter Finished Transfers")
+    filters.get_by_role("button", name="Successful", exact=True).click()
+    expect(finished).to_contain_text("recent-success.bin")
+    expect(finished).not_to_contain_text("recent-failure.bin")
+    expect(pager.get_by_role("status")).to_have_text("Page 1 of 1 · 2 tasks")
+    filters.get_by_role("button", name="Failed", exact=True).click()
+    expect(history_region.get_by_role("alert")).to_contain_text(
+        "History temporarily unavailable"
+    )
+    history_region.get_by_role("button", name="Try Again", exact=True).click()
+    expect(history_region.get_by_role("alert")).to_have_count(0)
+    expect(finished.get_by_role("heading", name="No Failed Transfers")).to_be_visible()
+    filters.get_by_role("button", name="Cancelled", exact=True).click()
+    expect(
+        finished.get_by_role("heading", name="No Cancelled Transfers")
+    ).to_be_visible()
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.evaluate("document.documentElement.dataset.theme = 'dark'")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    expect(pager).to_have_count(0)
+    page.screenshot(
+        path=ARTIFACTS / "transfer-pagination-empty-mobile.png", full_page=True
+    )
+    filters.get_by_role("button", name="All", exact=True).click()
+    next_page.click()
+    expect(pager.get_by_role("status")).to_contain_text("Page 2 of 3")
+    expect(finished).to_contain_text("older-cancelled.bin")
+    pager.scroll_into_view_if_needed()
+    page.screenshot(path=ARTIFACTS / "transfer-pagination-mobile.png", full_page=True)
+    assert all(query["limit"] == 20 for query in seen)
+    assert any(query["offset"] == 20 for query in seen)
+    assert any(query["offset"] == 40 for query in seen)
diff --git a/tests/browser/test_browser_upload_pipeline.py b/tests/browser/test_browser_upload_pipeline.py
new file mode 100644
index 00000000..1b25ed2c
--- /dev/null
+++ b/tests/browser/test_browser_upload_pipeline.py
@@ -0,0 +1,410 @@
+"""Device receipts flow independently of Telegram and update listings in place."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+import pytest
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    UPLOAD_RECOVERY_RECORDS,
+    Server,
+    expect,
+    fixture_nodes,
+    login,
+    select_folder,
+    select_item,
+    upload,
+)
+from tests.browser.test_browser_e2e import browser as browser_fixture
+from tests.browser.test_browser_e2e import desktop as desktop_fixture
+from tests.browser.test_browser_e2e import server as server_fixture
+
+pytestmark = pytest.mark.e2e
+browser, desktop, server = browser_fixture, desktop_fixture, server_fixture
+
+
+def _wait_started(page: Any, server: Server, count: int) -> list[dict[str, Any]]:
+    deadline = time.monotonic() + 10
+    while time.monotonic() < deadline:
+        started = server.control()["started"]
+        if len(started) >= count:
+            return started
+        # Keep servicing browser routing callbacks while receipt requests run.
+        page.wait_for_timeout(50)
+    pytest.fail(f"Expected {count} accepted uploads: {server.control()}")
+
+
+def _wait_completed(server: Server, started: list[dict[str, Any]]) -> None:
+    deadline = time.monotonic() + 10
+    while time.monotonic() < deadline:
+        records = server.control()["records"]
+        if all(records[item["id"]]["status"] == "completed" for item in started):
+            return
+        time.sleep(0.05)
+    pytest.fail(f"Server uploads did not finish: {server.control()}")
+
+
+def _device_close_blocked(page: Any) -> bool:
+    return page.evaluate("""() => {
+      const event=new Event('beforeunload', {cancelable:true});
+      window.dispatchEvent(event);
+      return event.defaultPrevented;
+    }""")
+
+
+@pytest.mark.parametrize("selection", ["files", "folder"])
+def test_device_receipts_finish_while_telegram_waits_and_survive_tab_close(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path, selection: str
+) -> None:
+    context, page = desktop
+    login(page, server.url)
+    names = [f"pipeline-{index:02}.txt" for index in range(8)]
+    held: list[Any] = []
+    first_patch = True
+
+    def hold_later_receipts(route: Any) -> None:
+        nonlocal first_patch
+        if route.request.method != "PATCH":
+            route.continue_()
+        elif first_patch:
+            first_patch = False
+            route.continue_()
+        else:
+            held.append(route)
+
+    page.route("**/api/v1/uploads/*", hold_later_receipts)
+    try:
+        if selection == "folder":
+            directory = tmp_path / "Flow folder"
+            directory.mkdir()
+            for name in names:
+                (directory / name).write_bytes(b"x" * 65536)
+            dialog = select_folder(page, directory)
+            dialog.get_by_role("button", name="Upload", exact=True).click()
+            expect(dialog).not_to_be_visible()
+        else:
+            upload(page, names)
+        first = _wait_started(page, server, 1)
+        assert len(first) == 1, "Telegram must start before the remaining receipts"
+        assert held, "Other device receipts must still be in flight"
+        assert all(
+            record["status"] != "completed"
+            for record in server.control()["records"].values()
+        )
+        assert _device_close_blocked(page), "Unsent device data must guard tab close"
+        if selection == "folder":
+            batch = page.locator('.transfer-batch[data-stage="device"]')
+            expect(batch).to_have_count(1)
+            expect(batch.locator(".transfer-batch-status")).to_contain_text(
+                "Uploading from device"
+            )
+            expect(batch).not_to_contain_text("Telegram")
+            batch.get_by_role("button", name="Show Files", exact=True).click()
+            received = batch.locator('.transfer-child[data-status="uploading"]')
+        else:
+            expect(page.locator(".transfer-batch")).to_have_count(0)
+            rows = page.locator(".transfer-item:not(.transfer-child)")
+            expect(rows).to_have_count(len(names))
+            expect(
+                page.get_by_role("button", name="Show Files", exact=True)
+            ).to_have_count(0)
+            received = page.locator(
+                '.transfer-item:not(.transfer-child)[data-status="uploading"]'
+            )
+        expect(received).to_have_count(1)
+        expect(received.locator(".transfer-phase")).to_have_text("Received")
+        expect(received.get_by_role("progressbar")).to_have_count(0)
+        expect(received.locator(".transfer-metrics")).to_have_count(0)
+        if selection == "folder":
+            batch.get_by_role("button", name="Hide Files", exact=True).click()
+    finally:
+        # Playwright releases any pending routes when this handler is removed.
+        page.unroute("**/api/v1/uploads/*", hold_later_receipts)
+
+    started = _wait_started(page, server, len(names))
+    assert {item["name"] for item in started} == set(names)
+    assert all(
+        record["status"] != "completed"
+        for record in server.control()["records"].values()
+    ), "Receiving later files must not require earlier Telegram jobs to finish"
+    safe = page.locator(".transfer-device-status, .transfer-notice").filter(
+        has_text="You can close this tab"
+    )
+    expect(safe.first).to_be_visible()
+    if selection == "folder":
+        batch = page.locator('.transfer-batch[data-stage="telegram"]')
+        expect(batch).to_have_count(1)
+        expect(batch.locator(".transfer-batch-status")).to_contain_text(
+            "Uploading to Telegram"
+        )
+        expect(batch).not_to_contain_text("Uploading from device")
+    else:
+        expect(page.locator(".transfer-batch")).to_have_count(0)
+        rows = page.locator(".transfer-item:not(.transfer-child)")
+        expect(rows).to_have_count(len(names))
+        expect(rows.locator(".transfer-phase")).to_have_text(
+            ["Uploading to Telegram"] * len(names)
+        )
+        for name in names:
+            expect(
+                rows.locator(".transfer-item-name").filter(has_text=name)
+            ).to_have_count(1)
+    assert not _device_close_blocked(page)
+    saved = page.evaluate(UPLOAD_RECOVERY_RECORDS)
+    assert len(saved) == len(names)
+    assert all(item.get("jobId") for item in saved)
+    if selection == "folder":
+        assert len({item["folderUpload"]["id"] for item in saved}) == 1
+    else:
+        assert all(not item.get("folderUpload") for item in saved)
+        assert len({item["batchId"] for item in saved}) == len(names)
+    destination = started[0]["destination"]
+    assert {item["destination"] for item in started} == {destination}
+    assert set(names).isdisjoint(
+        item["name"] for item in fixture_nodes(page, server, destination)
+    )
+    page.screenshot(path=ARTIFACTS / f"pipeline-{selection}-safe-to-close.png")
+
+    dialogs: list[str] = []
+
+    def accept_unexpected_dialog(dialog: Any) -> None:
+        dialogs.append(dialog.type)
+        dialog.accept()
+
+    page.on("dialog", accept_unexpected_dialog)
+    page.close(run_before_unload=True)
+    reopened = context.new_page()
+    assert page.is_closed()
+    assert dialogs == [], "Confirmed server receipts must remove the close warning"
+    for item in started:
+        server.finish(item["id"])
+    _wait_completed(server, started)
+
+    errors: list[str] = []
+    reopened.on("pageerror", lambda error: errors.append(str(error)))
+    reopened.goto(server.url + "/?" + urlencode({"path": destination}))
+    for name in names:
+        expect(
+            reopened.locator(".item-name-button").filter(has_text=name)
+        ).to_have_count(1)
+    assert set(names).issubset(
+        item["name"] for item in fixture_nodes(reopened, server, destination)
+    )
+    assert errors == []
+    reopened.screenshot(path=ARTIFACTS / f"pipeline-{selection}-server-finished.png")
+
+
+def test_slow_listing_refresh_coalesces_upload_bursts_without_unmounting_rows(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    held: list[tuple[Any, Any, dict[str, Any]]] = []
+    refresh_requests: list[Any] = []
+    failed_requests: list[str] = []
+    recording = False
+    hold = False
+
+    def listing(route: Any) -> None:
+        response = route.fetch()
+        payload = response.json()
+        root = route.request.post_data_json["path"] == "/"
+        if root:
+            payload["data"]["contents"].update(
+                {
+                    f"stable-{index}": {
+                        "id": f"stable-{index}",
+                        "name": f"stable-{index:03}.txt",
+                        "type": "file",
+                        "path": "/",
+                        "size": 10,
+                    }
+                    for index in range(130)
+                }
+            )
+            if recording:
+                refresh_requests.append(route.request)
+        if root and hold:
+            held.append((route, response, payload))
+        else:
+            route.fulfill(response=response, json=payload)
+
+    def failed(request: Any) -> None:
+        if recording and request.url.endswith("/api/getDirectory"):
+            failed_requests.append(request.failure or "Listing failed")
+
+    page.route("**/api/getDirectory", listing)
+    page.on("requestfailed", failed)
+    login(page, server.url)
+    names = [f"zz-upload-{index}.txt" for index in range(6)]
+    upload(page, names)
+    started = _wait_started(page, server, len(names))
+    expect(
+        page.locator(".transfer-device-status, .transfer-notice")
+        .filter(has_text="You can close this tab")
+        .first
+    ).to_be_visible()
+    hide = page.get_by_role("button", name="Hide Transfer Details", exact=True)
+    if hide.is_visible():
+        hide.click()
+    next_page = page.get_by_role("button", name="Next Page", exact=True)
+    next_page.focus()
+    next_page.press("Enter")
+    select_item(page, "stable-110.txt")
+    checkbox = page.get_by_label("Select stable-110.txt", exact=True)
+    checkbox.focus()
+    page.evaluate("""() => {
+      window.stableTable=document.querySelector('.file-table');
+      window.stableRow=document.querySelector('[data-item-id="stable-110"]');
+      window.tableRemovals=0;
+      new MutationObserver(records => {
+        for(const record of records) for(const removed of record.removedNodes)
+          if(removed===window.stableTable || removed.contains?.(window.stableTable))
+            window.tableRemovals++;
+      }).observe(document.querySelector('.workspace'), {childList:true,subtree:true});
+      window.stableScroll=document.querySelector('.file-list-scroll');
+      window.stableScroll.scrollTop=250;
+    }""")
+    scroll = page.evaluate("window.stableScroll.scrollTop")
+    assert scroll > 0
+    recording = True
+    hold = True
+    try:
+        page.evaluate("window.dispatchEvent(new Event('tgdrive:files-changed'))")
+        deadline = time.monotonic() + 10
+        while not held and time.monotonic() < deadline:
+            page.wait_for_timeout(50)
+        assert len(held) == 1
+        for item in started:
+            server.finish(item["id"])
+        page.wait_for_function(
+            "() => { const items="
+            + UPLOAD_RECOVERY_RECORDS
+            + "; return items.length===6 && "
+            "items.every(item=>item.state==='completed'); }"
+        )
+        page.evaluate("""async () => {
+          for(let index=0;index<30;index++)
+            window.dispatchEvent(new Event('tgdrive:files-changed'));
+          await new Promise(resolve=>requestAnimationFrame(
+            ()=>requestAnimationFrame(resolve)));
+        }""")
+        assert len(refresh_requests) == 1, "A slow fetch must finish before its retry"
+        assert failed_requests == [], "Upload updates must not abort listing requests"
+        expect(page.locator(".loading-state")).to_have_count(0)
+        expect(checkbox).to_be_checked()
+        expect(checkbox).to_be_focused()
+        hold = False
+        route, response, payload = held.pop()
+        route.fulfill(response=response, json=payload)
+        for name in names:
+            expect(
+                page.locator(".item-name-button").filter(has_text=name)
+            ).to_have_count(1)
+        assert len(refresh_requests) == 2, "Completion bursts need one trailing fetch"
+        assert failed_requests == []
+        expect(checkbox).to_be_checked()
+        expect(checkbox).to_be_focused()
+        expect(page.locator(".pagination")).to_contain_text("Showing 101\u2013")
+        assert page.evaluate("window.stableScroll.scrollTop") == scroll
+        assert page.evaluate(
+            "window.stableTable===document.querySelector('.file-table')"
+        )
+        assert page.evaluate(
+            "window.stableRow===document.querySelector('[data-item-id=stable-110]')"
+        )
+        assert page.evaluate("window.tableRemovals") == 0
+        page.screenshot(path=ARTIFACTS / "pipeline-listing-burst-preserves-state.png")
+    finally:
+        hold = False
+        for route, response, payload in held:
+            route.fulfill(response=response, json=payload)
+
+
+def test_new_folder_gets_device_slots_while_older_folder_and_telegram_are_pending(
+    server: Server, desktop: tuple[Any, Any], tmp_path: Path
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    receipt_names: dict[str, str] = {}
+    held: list[Any] = []
+
+    def remember_receipt(route: Any) -> None:
+        if route.request.method != "POST":
+            route.continue_()
+            return
+        response = route.fetch()
+        assert response.ok, response.text()
+        receipt_names[response.json()["id"]] = route.request.post_data_json["name"]
+        route.fulfill(response=response)
+
+    def hold_old_payloads(route: Any) -> None:
+        receipt_id = route.request.url.rsplit("/", 1)[-1]
+        if route.request.method == "PATCH" and receipt_names[receipt_id].startswith(
+            "older-"
+        ):
+            held.append(route)
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/uploads", remember_receipt)
+    page.route("**/api/v1/uploads/*", hold_old_payloads)
+    try:
+        older = tmp_path / "Older folder"
+        newer = tmp_path / "New folder"
+        older.mkdir()
+        newer.mkdir()
+        for index in range(8):
+            (older / f"older-{index}.txt").write_bytes(b"x" * 65536)
+        for index in range(2):
+            (newer / f"newer-{index}.txt").write_bytes(b"y" * 65536)
+        dialog = select_folder(page, older)
+        dialog.get_by_role("button", name="Upload", exact=True).click()
+        expect(dialog).not_to_be_visible()
+        deadline = time.monotonic() + 10
+        while len(held) < 2 and time.monotonic() < deadline:
+            page.wait_for_timeout(50)
+        assert len(held) == 2
+
+        dialog = select_folder(page, newer)
+        dialog.get_by_role("button", name="Upload", exact=True).click()
+        expect(dialog).not_to_be_visible()
+        # Existing requests continue; released slots must be shared with the new batch.
+        initial = held[:]
+        held.clear()
+        for route in initial:
+            route.continue_()
+        deadline = time.monotonic() + 10
+        started = []
+        while time.monotonic() < deadline:
+            started = server.control()["started"]
+            if sum(item["name"].startswith("newer-") for item in started) == 2:
+                break
+            page.wait_for_timeout(50)
+        assert sum(item["name"].startswith("newer-") for item in started) == 2
+        assert sum(item["name"].startswith("older-") for item in started) < 8
+        assert all(
+            record["status"] != "completed"
+            for record in server.control()["records"].values()
+        ), "The new folder must not wait for older Telegram jobs"
+        new_batch = page.locator(".transfer-batch").filter(
+            has=page.locator(".transfer-batch-name", has_text="New folder")
+        )
+        expect(new_batch).to_have_attribute("data-stage", "device")
+        expect(new_batch).to_contain_text("Received")
+        expect(new_batch).not_to_contain_text("Uploading to Telegram")
+        expect(new_batch.locator(".transfer-batch-throughput")).to_have_text("")
+        expect(new_batch).to_contain_text("Keep this tab open for other uploads")
+        assert _device_close_blocked(page)
+        page.screenshot(path=ARTIFACTS / "pipeline-new-folder-fair-slots.png")
+    finally:
+        page.unroute("**/api/v1/uploads/*", hold_old_payloads)
+        page.unroute("**/api/v1/uploads", remember_receipt)
+    _wait_started(page, server, 10)
+    expect(new_batch).to_have_attribute("data-stage", "telegram")
+    expect(new_batch).to_contain_text("Uploading to Telegram")
+    assert not _device_close_blocked(page)
diff --git a/tests/browser/test_browser_upload_progress.py b/tests/browser/test_browser_upload_progress.py
new file mode 100644
index 00000000..49668d4c
--- /dev/null
+++ b/tests/browser/test_browser_upload_progress.py
@@ -0,0 +1,369 @@
+"""Native Chromium upload progress, cancellation and safe retry coverage."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from typing import Any
+
+import pytest
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    UPLOAD_RECOVERY_RECORDS,
+    Server,
+    expect,
+    login,
+)
+
+pytestmark = pytest.mark.e2e
+pytest_plugins = ("tests.browser.test_browser_e2e",)
+
+
+def _choose_upload(page: Any, name: str, size: int) -> None:
+    page.locator("#new-button:visible, #compact-new-button:visible").click()
+    with page.expect_file_chooser() as chooser:
+        page.locator("#file-upload-action").click()
+    chooser.value.set_files(
+        {"name": name, "mimeType": "application/octet-stream", "buffer": b"x" * size}
+    )
+
+
+def _observe_and_throttle(context: Any, page: Any) -> Any:
+    page.add_init_script("""
+      window.uploadObservations=[];
+      const original=XMLHttpRequest.prototype.send;
+      XMLHttpRequest.prototype.send=function(body){
+        this.upload.addEventListener('progress',event=>{
+          window.uploadObservations.push({bytes:event.loaded,total:event.total,at:performance.now()});
+        });
+        return original.call(this,body);
+      };
+    """)
+    cdp = context.new_cdp_session(page)
+    cdp.send("Network.enable")
+    cdp.send(
+        "Network.emulateNetworkConditions",
+        {
+            "offline": False,
+            "latency": 0,
+            "downloadThroughput": -1,
+            "uploadThroughput": 256 * 1024,
+        },
+    )
+    return cdp
+
+
+def test_device_upload_reports_bytes_before_first_chunk_receipt(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    context, page = desktop
+    _observe_and_throttle(context, page)
+    login(page, server.url)
+    size = 2 * 1024 * 1024
+    _choose_upload(page, "measured-device-upload.bin", size)
+    row = page.locator(".transfer-item").filter(has_text="measured-device-upload.bin")
+    page.wait_for_function(
+        """() => {
+          const row=document.querySelector('.transfer-item[data-status="receiving"]');
+          const progress=row?.querySelector('progress');
+          return progress && progress.value>0.05 && progress.value<0.8;
+        }"""
+    )
+    expect(row.locator(".transfer-phase")).to_have_text("Uploading from your device")
+    records = page.evaluate("window.uploadObservations")
+    assert len(records) >= 2, records
+    saved = page.evaluate(UPLOAD_RECOVERY_RECORDS)
+    assert saved[0]["current"] == 0, "In-flight bytes must not become a resume offset"
+    assert "sentCurrent" not in saved[0]
+    value = float(row.get_by_role("progressbar").get_attribute("value"))
+    assert 0 < value <= records[-1]["bytes"] / size
+    assert row.locator(".transfer-bytes").inner_text() != "0 B / 2 MB"
+    expect(row.locator(".transfer-speed")).to_have_text(
+        re.compile(r"^\d[\d.,]* (?:B|KB|MB|GB)/s$")
+    )
+    expect(row.locator(".transfer-eta")).to_contain_text("remaining")
+    expect(row.locator(".transfer-eta")).to_have_attribute(
+        "title",
+        "Estimated upload time for this stage. "
+        "Verification and publishing may take longer.",
+    )
+    page.screenshot(
+        path=ARTIFACTS / "device-upload-observed-progress.png", full_page=True
+    )
+    page.set_viewport_size({"width": 390, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(
+        path=ARTIFACTS / "device-upload-observed-progress-mobile.png", full_page=True
+    )
+    page.locator(".mobile-transfer-status").click()
+    server.wait_started(1)
+    expect(row).to_have_attribute("data-status", "uploading")
+    records = page.evaluate("window.uploadObservations")
+    assert len({record["bytes"] for record in records}) >= 5
+    assert all(record["bytes"] <= size for record in records)
+    (ARTIFACTS / "device-upload-progress.json").write_text(
+        json.dumps(records, indent=2)
+    )
+
+
+def test_native_upload_cancel_stops_before_telegram_job(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    context, page = desktop
+    _observe_and_throttle(context, page)
+    page.emulate_media(reduced_motion="reduce")
+    login(page, server.url)
+    _choose_upload(page, "cancel-device-upload.bin", 2 * 1024 * 1024)
+    row = page.locator(".transfer-item").filter(has_text="cancel-device-upload.bin")
+    page.wait_for_function(
+        """() => {
+          const row=document.querySelector('.transfer-item[data-status="receiving"]');
+          return row?.querySelector('progress')?.value>0.05;
+        }"""
+    )
+    expect(row.get_by_role("progressbar")).to_be_visible()
+    page.get_by_role(
+        "button", name="Cancel cancel-device-upload.bin", exact=True
+    ).click()
+    expect(row).to_have_attribute("data-status", "cancelled")
+    assert server.control()["started"] == []
+    page.wait_for_timeout(500)
+    assert server.control()["started"] == []
+
+
+def test_native_upload_retries_rejected_chunk_from_confirmed_offset(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    offsets: list[str] = []
+
+    def reject_first(route: Any) -> None:
+        if route.request.method != "PATCH":
+            route.continue_()
+            return
+        offsets.append(route.request.headers["upload-offset"])
+        if len(offsets) == 1:
+            route.fulfill(status=409, json={"detail": "Synthetic rejected receipt"})
+        else:
+            route.continue_()
+
+    page.route("**/api/v1/uploads/*", reject_first)
+    _choose_upload(page, "retry-device-upload.bin", 256 * 1024)
+    row = page.locator(".transfer-item").filter(has_text="retry-device-upload.bin")
+    expect(row).to_have_attribute("data-status", "error")
+    page.get_by_role("button", name="Retry retry-device-upload.bin", exact=True).click()
+    expect(row).to_have_attribute("data-status", "uploading")
+    server.wait_started(1)
+    assert offsets == ["0", "0"]
+
+
+@pytest.mark.parametrize("width", [1440, 390, 320])
+def test_server_transfer_speed_and_eta_are_visible_and_expire_together(
+    server: Server, desktop: tuple[Any, Any], width: int
+) -> None:
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    mode = ["fresh"]
+
+    def jobs(route: Any) -> None:
+        at = time.time()
+        state = mode[0]
+        route.fulfill(
+            json={
+                "jobs": [
+                    {
+                        "id": "timed-server-transfer",
+                        "name": "Timed transfer.mp4",
+                        "kind": "upload",
+                        "status": "running",
+                        "phase": "retry_wait" if state == "waiting" else "uploading",
+                        "current": 512 * 1024,
+                        "total": 1024 * 1024,
+                        "created_at": at - 30,
+                        "started_at": at - 10,
+                        "progress_updated_at": at - 30 if state == "stale" else at,
+                        "speed_bytes_per_second": None
+                        if state == "calculating"
+                        else 128 * 1024,
+                        "eta_seconds": None,
+                    }
+                ]
+            }
+        )
+
+    page.route("**/api/v1/jobs", jobs)
+    login(page, server.url)
+    page.goto(server.url + "/?view=activity")
+    row = page.locator(".transfer-page .transfer-item").filter(
+        has_text="Timed transfer.mp4"
+    )
+    expect(row.locator(".transfer-phase")).to_have_text("Uploading to Telegram")
+    expect(row.locator(".transfer-speed")).to_have_text("128 KB/s")
+    expect(row.locator(".transfer-eta")).to_have_text("About 4s remaining")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    geometry = row.evaluate("""row => {
+      const box = selector => {
+        const value = row.querySelector(selector).getBoundingClientRect();
+        return {top:value.top,bottom:value.bottom,left:value.left,right:value.right};
+      };
+      return {
+        speed:box('.transfer-speed'), eta:box('.transfer-eta'),
+        percent:box('.transfer-batch-percent'), bytes:box('.transfer-bytes'),
+        progress:box('progress'), phase:box('.transfer-phase'),
+        name:box('.transfer-item-title'), row:row.getBoundingClientRect().toJSON()
+      };
+    }""")
+    metrics = [geometry[key] for key in ("speed", "eta", "percent", "bytes")]
+    assert all(metric["bottom"] < geometry["progress"]["top"] for metric in metrics)
+    assert all(metric["left"] >= geometry["row"]["left"] for metric in metrics)
+    assert all(metric["right"] <= geometry["row"]["right"] for metric in metrics)
+    if width == 1440:
+        assert (
+            max(metric["bottom"] for metric in metrics)
+            - min(metric["bottom"] for metric in metrics)
+            < 2
+        )
+        assert geometry["speed"]["left"] > geometry["name"]["right"]
+    else:
+        assert geometry["speed"]["top"] >= geometry["phase"]["bottom"]
+    page.screenshot(path=ARTIFACTS / f"transfer-speed-eta-{width}.png", full_page=True)
+    for state, expected in [
+        ("calculating", None),
+        ("stale", "No recent progress"),
+        ("waiting", "Waiting for Telegram"),
+    ]:
+        mode[0] = state
+        page.reload()
+        if expected is None:
+            expect(row.locator(".transfer-metrics")).to_have_text("")
+        else:
+            expect(row.locator(".transfer-metrics")).to_contain_text(expected)
+        expect(row.locator(".transfer-metrics")).not_to_contain_text("128 KB/s")
+        expect(row.locator(".transfer-metrics")).not_to_contain_text("About 4s")
+
+
+def test_folder_eta_survives_small_file_handoffs_and_publishing(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    size = 128 * 1024
+    mode = ["flow"]
+    polls = [0]
+    folder_upload = {
+        "id": "eta-folder-selection",
+        "name": "Small files",
+        "root_path": "/small-files",
+        "created_at": time.time(),
+    }
+    saved = [
+        {
+            "key": f"eta-file-{index}",
+            "jobId": f"eta-job-{index}",
+            "name": f"small-{index}.bin",
+            "size": size,
+            "lastModified": 0,
+            "destination": folder_upload["root_path"],
+            "relativePath": f"Small files/small-{index}.bin",
+            "folderUpload": folder_upload,
+            "batchId": folder_upload["id"],
+            "batchName": "Small files",
+            "batchCreatedAt": time.time() * 1000,
+            "state": "uploading",
+            "phase": "Queued for Telegram",
+            "current": 0,
+            "total": size,
+            "initiatedHere": True,
+        }
+        for index in range(8)
+    ]
+    page.add_init_script(
+        "localStorage.setItem('tgdrive.uploads.v2', "
+        + json.dumps(json.dumps(saved))
+        + ");"
+    )
+
+    def jobs(route: Any) -> None:
+        at = time.time()
+        step = min(polls[0], 3)
+        polls[0] += 1
+        records = []
+        for index in range(8):
+            completed = index < step
+            publishing = index == step
+            sending = index == step + 1
+            status = (
+                "completed"
+                if completed
+                else "running"
+                if publishing or sending
+                else "queued"
+            )
+            phase = (
+                "completed"
+                if completed
+                else "finalizing"
+                if publishing
+                else "uploading"
+                if sending
+                else "queued"
+            )
+            if sending and mode[0] == "waiting":
+                phase = "retry_wait"
+            records.append(
+                {
+                    "id": f"eta-job-{index}",
+                    "name": f"small-{index}.bin",
+                    "folder_upload": folder_upload,
+                    "kind": "upload",
+                    "status": status,
+                    "phase": phase,
+                    "current": size
+                    if completed or publishing
+                    else size // 4
+                    if sending
+                    else 0,
+                    "total": size,
+                    "created_at": at - 30,
+                    "started_at": at - 10 if status != "queued" else None,
+                    "finished_at": at if completed else None,
+                    "progress_updated_at": at,
+                    # Small files can complete between polls without a per-file speed.
+                    "speed_bytes_per_second": None,
+                    "eta_seconds": None,
+                }
+            )
+        route.fulfill(json={"jobs": records})
+
+    page.route("**/api/v1/jobs", jobs)
+    login(page, server.url)
+    batch = page.locator('[data-batch-id="eta-folder-selection"]')
+    expect(batch).to_have_attribute("data-stage", "telegram")
+    metrics = batch.locator(".transfer-batch-throughput")
+    expect(metrics).to_contain_text(re.compile(r"About .+ remaining"))
+    assert polls[0] >= 2, "A restored snapshot alone must not invent throughput"
+    expect(batch).not_to_contain_text("Time estimate unavailable")
+    expect(batch).not_to_contain_text("Uploading from device")
+
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    expect(metrics).to_contain_text(re.compile(r"About .+ remaining"))
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(path=ARTIFACTS / "folder-rolling-eta-desktop.png", full_page=True)
+    for width in (390, 320):
+        page.set_viewport_size({"width": width, "height": 844})
+        expect(metrics).to_contain_text(re.compile(r"About .+ remaining"))
+        assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+        assert batch.locator(".transfer-device-status").evaluate("""el =>
+          el.getBoundingClientRect().height <=
+            parseFloat(getComputedStyle(el).lineHeight) * 1.1
+        """), "The short close-tab notice should stay together"
+        page.screenshot(
+            path=ARTIFACTS / f"folder-rolling-eta-mobile-{width}.png", full_page=True
+        )
+
+    mode[0] = "waiting"
+    batch.get_by_role("button", name="Show Files", exact=True).click()
+    expect(batch).to_contain_text("Waiting for Telegram; retry scheduled")
+    expect(metrics).not_to_contain_text("remaining")
diff --git a/tests/browser/test_browser_workspace.py b/tests/browser/test_browser_workspace.py
new file mode 100644
index 00000000..77d7d968
--- /dev/null
+++ b/tests/browser/test_browser_workspace.py
@@ -0,0 +1,353 @@
+"""Scroll ownership and settings navigation in the production interface."""
+
+from __future__ import annotations
+
+import os
+import re
+import time
+
+import pytest
+
+if os.environ.get("TGDRIVE_E2E") != "1":
+    pytest.skip("Set TGDRIVE_E2E=1 to run Chromium checks", allow_module_level=True)
+
+import tests.browser.test_browser_e2e as fixtures
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login
+
+browser = fixtures.browser
+desktop = fixtures.desktop
+server = fixtures.server
+
+pytestmark = pytest.mark.e2e
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_directory_controls_stay_visible_while_only_files_scroll(
+    server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+
+    def listing(route):
+        response = route.fetch()
+        payload = response.json()
+        payload["data"]["contents"].update(
+            {
+                f"scroll-{i}": {
+                    "id": f"scroll-{i}",
+                    "name": f"scroll-{i:03}.txt",
+                    "type": "file",
+                    "path": "/",
+                    "size": 10,
+                }
+                for i in range(80)
+            }
+        )
+        route.fulfill(response=response, json=payload)
+
+    page.route("**/api/getDirectory", listing)
+    login(page, server.url)
+    page.get_by_role("button", name="Select", exact=True).click()
+    page.get_by_label("Select scroll-000.txt", exact=True).check()
+    # Compact selection actions replace the visible heading in the same slot.
+    heading = page.locator(".file-toolbar h1")
+    toolbar = page.locator(".file-toolbar")
+    before = [heading.bounding_box()["y"], toolbar.bounding_box()["y"]]
+    scroll = (
+        page.locator(".workspace")
+        if width < 721
+        else page.get_by_label("File list", exact=True)
+    )
+    scroll.evaluate("element => element.scrollTop = 700")
+    assert scroll.evaluate("element => element.scrollTop") == 700
+    if width > 720:
+        expect(page.get_by_role("button", name="Move", exact=True)).to_be_in_viewport()
+        expect(page.get_by_role("button", name="Trash", exact=True)).to_be_in_viewport()
+        assert page.locator(".workspace").evaluate("element => element.scrollTop") == 0
+        assert [heading.bounding_box()["y"], toolbar.bounding_box()["y"]] == before
+        table_header = page.locator(".file-table thead th").first.bounding_box()
+        assert abs(table_header["y"] - scroll.bounding_box()["y"]) <= 1
+    else:
+        assert heading.bounding_box()["y"] < 0
+        assert (
+            page.locator(".file-list-scroll").evaluate("element => element.scrollTop")
+            == 0
+        )
+    scroll.focus()
+    page.keyboard.press("PageDown")
+    page.wait_for_function(
+        "selector => document.querySelector(selector).scrollTop > 700",
+        arg=".workspace" if width < 721 else ".file-list-scroll",
+    )
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+    page.screenshot(path=ARTIFACTS / f"directory-fixed-controls-{width}.png")
+
+
+@pytest.mark.parametrize("width", [1440, 390, 320])
+def test_admin_navigation_separates_categories_preserves_drafts_and_supports_keyboard(
+    server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url)
+
+    def open_drawer():
+        fixtures.open_admin(page)
+
+    def navigate(label):
+        open_drawer()
+        page.get_by_role("link", name=label, exact=True).click()
+
+    open_drawer()
+    expect(page.get_by_role("button", name="Admin panel", exact=True)).to_have_count(0)
+    monitor = page.get_by_role("group", name="Monitor", exact=True)
+    expect(monitor.get_by_role("link")).to_have_count(2)
+    expect(monitor.get_by_role("link", name="Performance", exact=True)).to_be_visible()
+    expect(monitor.get_by_role("link", name="Preloads", exact=True)).to_be_visible()
+    config = page.get_by_role("group", name="Configuration", exact=True)
+    expect(config.get_by_role("link")).to_have_count(3)
+    manage = page.get_by_role("group", name="Management", exact=True)
+    expect(manage.get_by_role("link")).to_have_count(2)
+    page.get_by_role("link", name="Preloads", exact=True).focus()
+    page.keyboard.press("Tab")
+    expect(page.get_by_role("link", name="Cache settings", exact=True)).to_be_focused()
+    for label in ["Storage & Backups", "Cache settings", "Transfer limits", "Timezone"]:
+        link = page.get_by_role("link", name=label, exact=True)
+        assert link.evaluate("node => node.scrollWidth <= node.clientWidth")
+        assert (
+            link.locator("span").evaluate("node => getComputedStyle(node).whiteSpace")
+            == "nowrap"
+        )
+    navigate("Cache settings")
+    expect(
+        page.get_by_role("heading", name="Cache & preloading", exact=True)
+    ).to_be_visible()
+    memory = page.get_by_label("Memory cache (MiB)", exact=True)
+    memory.fill("512")
+    expect(page.get_by_label("Timezone", exact=True)).not_to_be_visible()
+    navigate("Timezone")
+    timezone = page.get_by_label("Timezone", exact=True)
+    expect(timezone).to_be_visible()
+    timezone.fill("Europe/London")
+    expect(memory).not_to_be_visible()
+    expect(page.get_by_role("link", name="Settings", exact=True)).to_have_count(0)
+    navigate("Transfer limits")
+    expect(
+        page.get_by_label("Simultaneous Uploads per Bot", exact=True)
+    ).to_be_visible()
+    expect(timezone).not_to_be_visible()
+    page.go_back()
+    expect(timezone).to_have_value("Europe/London")
+    navigate("Cache settings")
+    expect(memory).to_have_value("512")
+    navigate("Transfer limits")
+    expect(
+        page.get_by_label("Simultaneous Uploads per Bot", exact=True)
+    ).to_be_visible()
+    expect(memory).not_to_be_visible()
+    expect(timezone).not_to_be_visible()
+    page.screenshot(path=ARTIFACTS / f"admin-transfers-category-{width}.png")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+
+
+def test_cache_settings_deep_link_opens_cache_category(server, desktop):
+    _, page = desktop
+    login(page, server.url + "/?view=settings&section=cache")
+    expect(
+        page.get_by_role("heading", name="Cache & preloading", exact=True)
+    ).to_be_visible()
+    expect(
+        page.get_by_role("link", name="Cache settings", exact=True)
+    ).to_have_attribute("aria-current", "page")
+
+
+@pytest.mark.parametrize("refresh_failure", [False, True])
+def test_save_only_current_category_preserves_unrelated_invalid_draft(
+    server, desktop, refresh_failure
+):
+    _, page = desktop
+    patches = []
+
+    def policy(route):
+        if route.request.method == "PATCH":
+            patches.append(route.request.post_data_json)
+        route.continue_()
+
+    page.route("**/api/v1/settings/performance", policy)
+    login(page, server.url + "/?view=settings&section=cache")
+    page.get_by_label("Memory cache (MiB)", exact=True).fill("")
+    page.get_by_role("link", name="Timezone", exact=True).click()
+    page.get_by_label("Timezone", exact=True).fill("UTC")
+    if refresh_failure:
+        page.route(
+            "**/api/config",
+            lambda route: route.fulfill(
+                status=503, json={"detail": "Temporary configuration outage"}
+            ),
+        )
+    page.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".toast")).to_have_text("Performance settings saved.")
+    assert patches == [{"timezone": "UTC"}]
+    if refresh_failure:
+        state = page.locator(".deployment-config-state")
+        expect(state).to_have_attribute("role", "alert")
+        expect(page.get_by_label("Timezone", exact=True)).to_be_disabled()
+        expect(page.locator(".workspace > fieldset")).to_have_attribute("inert", "")
+        page.screenshot(path=ARTIFACTS / "config-refresh-preserved-draft.png")
+        page.unroute("**/api/config")
+        state.get_by_role("button", name="Try Again", exact=True).click()
+        expect(state).to_have_count(0)
+        expect(page.get_by_label("Timezone", exact=True)).to_have_value("UTC")
+    page.get_by_role("link", name="Cache settings", exact=True).click()
+    expect(page.get_by_label("Memory cache (MiB)", exact=True)).to_have_value("")
+    page.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".performance-settings").get_by_role("alert")).to_contain_text(
+        "Memory cache (MiB) must be"
+    )
+    assert len(patches) == 1
+
+
+@pytest.mark.parametrize("query", ["?view=settings", "?view=settings&section=general"])
+def test_missing_or_unknown_settings_section_uses_cache_without_url_rewrite(
+    server, desktop, query
+):
+    _, page = desktop
+    login(page, server.url + "/" + query)
+    expect(
+        page.get_by_role("heading", name="Cache & preloading", exact=True)
+    ).to_be_visible()
+    assert page.url == server.url + "/" + query
+    expect(page.get_by_role("link", name="Settings", exact=True)).to_have_count(0)
+    expect(
+        page.get_by_role("button", name="Change Appearance", exact=True)
+    ).to_be_visible()
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_sidebar_logout_busy_error_retry_and_server_transfer_survives(
+    server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url)
+    fixtures.upload(page, ["logout-keeps-server-transfer.bin"])
+    started = server.wait_started(1)
+    if page.locator(".sidebar").get_attribute("inert") is not None:
+        page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+    logout = page.get_by_role("button", name="Log Out", exact=True)
+    logout.scroll_into_view_if_needed()
+    sidebar = page.locator(".sidebar")
+    expect(logout).to_be_in_viewport()
+    assert sidebar.evaluate("e => getComputedStyle(e).overflowY") == "auto"
+    assert page.locator(".drive-nav").evaluate("e => e.scrollTop") == 0
+    assert (
+        page.locator(".sidebar-bottom").evaluate("e => getComputedStyle(e).position")
+        == "static"
+    )
+    page.screenshot(path=ARTIFACTS / f"sidebar-logout-{width}.png")
+    held = []
+    page.route("**/api/logout", lambda route: held.append(route))
+    logout.focus()
+    page.keyboard.press("Enter")
+    busy = page.get_by_role("button", name="Logging out…", exact=True)
+    expect(busy).to_be_disabled()
+    expect(busy).to_have_attribute("aria-busy", "true")
+    deadline = time.monotonic() + 5
+    while not held and time.monotonic() < deadline:
+        page.wait_for_timeout(10)
+    assert len(held) == 1
+    held.pop().fulfill(status=503, json={"message": "Please retry logout"})
+    expect(page.locator(".sidebar").get_by_role("alert")).to_be_visible()
+    expect(logout).to_be_focused()
+    page.unroute("**/api/logout")
+    logout.click()
+    expect(page.locator("#login-dialog")).to_be_visible()
+    expect(page.get_by_label("Password", exact=True)).to_be_focused()
+    expect(page.get_by_role("button", name="Log Out", exact=True)).to_have_count(0)
+    assert server.control()["started"] == started
+    server.finish(started[0]["id"])
+    login(page)
+    if page.locator(".sidebar").get_attribute("inert") is not None:
+        page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+    page.get_by_role("link", name="Transfers", exact=True).click()
+    expect(
+        page.get_by_text("logout-keeps-server-transfer.bin", exact=True)
+    ).to_be_visible()
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_restore_defaults_is_reviewable_scoped_and_durable(server, desktop, width):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url + "/?view=settings&section=cache")
+    initial = page.request.get(server.url + "/api/v1/settings/performance").json()
+    assert page.request.patch(
+        server.url + "/api/v1/settings/performance",
+        data={"cache_memory_bytes": 512 * 1024**2, "timezone": "UTC"},
+        headers={"If-Match": initial["revision"]},
+    ).ok
+    page.reload()
+    memory = page.get_by_label("Memory cache (MiB)", exact=True)
+    expect(memory).to_have_value("512")
+    page.get_by_role("button", name="Restore defaults", exact=True).click()
+    expect(memory).to_have_value("256")
+    assert (
+        page.request.get(server.url + "/api/v1/settings/performance").json()[
+            "cache_memory_bytes"
+        ]
+        == 512 * 1024**2
+    )
+    expect(
+        page.get_by_role("link", name="Configuration guide", exact=True)
+    ).to_have_attribute("href", re.compile(r"/docs/configuration\.md$"))
+    page.get_by_role("button", name="Discard changes", exact=True).click()
+    expect(memory).to_have_value("512")
+    page.get_by_role("button", name="Restore defaults", exact=True).click()
+    page.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".toast")).to_have_text("Performance settings saved.")
+    policy = page.request.get(server.url + "/api/v1/settings/performance").json()
+    assert policy["cache_memory_bytes"] == 256 * 1024**2
+    assert policy["timezone"] == "UTC"
+    page.get_by_label("Cache free-space floor (GiB)", exact=True).fill("0")
+    page.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".performance-settings").get_by_role("alert")).to_contain_text(
+        "at least 64 MiB"
+    )
+    assert (
+        page.request.get(server.url + "/api/v1/settings/performance").json()["revision"]
+        == policy["revision"]
+    )
+    page.get_by_role("button", name="Restore defaults", exact=True).click()
+    page.screenshot(path=ARTIFACTS / f"configuration-defaults-{width}.png")
+    assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+
+
+@pytest.mark.parametrize("width", [1440, 390])
+def test_owner_upload_storage_limits_validate_save_and_refresh_sidebar(
+    server, desktop, width
+):
+    _, page = desktop
+    page.set_viewport_size({"width": width, "height": 844})
+    login(page, server.url + "/?view=settings&section=transfers")
+    maximum = page.get_by_label("Maximum file size (GiB)", exact=True)
+    budget = page.get_by_label("Temporary upload budget (GiB)", exact=True)
+    reserve = page.get_by_label("Upload free-space reserve (GiB)", exact=True)
+    maximum.fill("32")
+    page.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".performance-settings").get_by_role("alert")).to_contain_text(
+        "cannot exceed"
+    )
+    expect(maximum).to_have_value("32")
+    budget.fill("64")
+    reserve.fill("1")
+    page.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".toast")).to_have_text("Performance settings saved.")
+    assert (
+        page.request.get(server.url + "/api/config").json()["max_file_size"]
+        == 32 * 1024**3
+    )
+    page.reload()
+    expect(maximum).to_have_value("32")
+    expect(budget).to_have_value("64")
+    page.screenshot(path=ARTIFACTS / f"owner-upload-storage-{width}.png")
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
diff --git a/tests/browser/test_owner_pages_ui.py b/tests/browser/test_owner_pages_ui.py
new file mode 100644
index 00000000..545574a9
--- /dev/null
+++ b/tests/browser/test_owner_pages_ui.py
@@ -0,0 +1,196 @@
+"""Owner page interactions that must work on touch and across timezones."""
+
+from __future__ import annotations
+
+import pytest
+
+from tests.browser.test_browser_e2e import ARTIFACTS, expect, login
+from tests.browser.test_browser_e2e import browser as browser_fixture
+from tests.browser.test_browser_e2e import desktop as desktop_fixture
+from tests.browser.test_browser_e2e import server as server_fixture
+
+pytestmark = pytest.mark.e2e
+browser, desktop, server = browser_fixture, desktop_fixture, server_fixture
+
+
+def test_shared_filename_opens_location_with_one_click(server, desktop):
+    _, page = desktop
+    login(page, server.url)
+    contents = page.request.post(
+        server.url + "/api/getDirectory", data={"path": "/"}
+    ).json()["data"]["contents"]
+    folder = next(item for item in contents.values() if item["name"] == "資料")
+    assert page.request.post(
+        server.url + "/api/v1/shares",
+        data={"path": "/" + folder["id"], "expires_in_days": None},
+    ).ok
+    page.goto(server.url + "/?view=shares")
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.get_by_role("button", name="資料", exact=True).click()
+    expect(page.get_by_role("heading", name="My Files", exact=True)).to_be_visible()
+    expect(page.locator("tr.selected")).to_contain_text("資料")
+
+
+def test_owner_documentation_and_backup_recovery_links_open_safe_new_tabs(
+    server, desktop
+):
+    context, page = desktop
+    login(page, server.url + "/?view=storage")
+    context.route(
+        "https://github.com/TechShreyash/TGDrive/blob/main/docs/**",
+        lambda route: route.fulfill(
+            body="Documentation destination", content_type="text/plain"
+        ),
+    )
+    guide = page.get_by_role("link", name="Backup & recovery guide", exact=True)
+    expect(guide).to_have_attribute(
+        "href",
+        "https://github.com/TechShreyash/TGDrive/blob/main/docs/backup-recovery.md",
+    )
+    expect(guide).to_have_attribute("target", "_blank")
+    expect(guide).to_have_attribute("rel", "noopener noreferrer")
+    with page.expect_popup() as opened:
+        guide.click()
+    popup = opened.value
+    expect(popup.get_by_text("Documentation destination", exact=True)).to_be_visible()
+    popup.close()
+    page.set_viewport_size({"width": 390, "height": 844})
+    page.get_by_role("button", name="Toggle Navigation", exact=True).click()
+    docs = page.get_by_role("link", name="Documentation", exact=True)
+    expect(docs).to_have_attribute(
+        "href", "https://github.com/TechShreyash/TGDrive/blob/main/docs/README.md"
+    )
+    expect(docs).to_have_attribute("rel", "noopener noreferrer")
+    with page.expect_popup() as opened:
+        docs.click()
+    popup = opened.value
+    expect(popup.get_by_text("Documentation destination", exact=True)).to_be_visible()
+    popup.close()
+    assert page.url.endswith("?view=storage")
+
+
+def test_shared_links_concise_expiry_keeps_exact_timezone(server, browser):
+    context = browser.new_context(timezone_id="America/New_York", locale="en-US")
+    try:
+        page = context.new_page()
+        expires = "2031-01-02T23:00:00Z"
+        share = {
+            "id": "compact-share",
+            "node_id": "compact-file",
+            "path": "/compact-file",
+            "name": "Weekend trip.mp4",
+            "folder_path": "/",
+            "folder_label": "My Files",
+            "type": "file",
+            "size": 17800000,
+            "created_at": "2026-10-17T00:00:00Z",
+            "expires_at": expires,
+            "copyable": True,
+        }
+        page.route(
+            "**/api/v1/shares",
+            lambda route: route.fulfill(
+                json={
+                    "shares": [
+                        share,
+                        dict(
+                            share,
+                            id="folder-share",
+                            name="Family photos",
+                            type="folder",
+                            path="/photos",
+                            expires_at=None,
+                        ),
+                        dict(
+                            share,
+                            id="old-share",
+                            name="Project notes.pdf",
+                            path="/notes",
+                            expires_at="2020-01-02T23:00:00Z",
+                        ),
+                    ]
+                }
+            ),
+        )
+        login(page, server.url)
+        page.goto(server.url + "/?view=shares")
+        row = page.locator(
+            ".share-row",
+            has=page.get_by_role("button", name="Weekend trip.mp4", exact=True),
+        )
+        expect(row).to_have_count(1)
+        expect(row).to_contain_text("Created")
+        expect(page.get_by_text("Details", exact=True)).to_have_count(0)
+        expect(
+            page.get_by_text("Anyone with an active link", exact=False)
+        ).to_have_count(0)
+        exact = page.evaluate(
+            "value => new Intl.DateTimeFormat(undefined, {dateStyle:'medium', "
+            "timeStyle:'long', timeZone:'Asia/Kolkata'}).format(new Date(value))",
+            expires,
+        )
+        expiry = row.locator(".share-expiry time")
+        # Jan 2 in New York is Jan 3 in the configured instance timezone.
+        expect(expiry).to_contain_text("Jan 3, 2031")
+        expect(expiry).to_have_attribute("aria-label", "Expires " + exact)
+        tooltip = expiry.get_by_role("tooltip")
+        expect(tooltip).not_to_be_visible()
+        expiry.focus()
+        expect(tooltip).to_be_visible()
+        expect(tooltip).to_have_text(exact)
+        row.locator(".share-copy").focus()
+        expect(tooltip).not_to_be_visible()
+        expect(
+            row.get_by_role("button", name="Show Weekend trip.mp4 in folder")
+        ).to_be_visible()
+        expect(
+            row.get_by_role("button", name="Revoke Link for Weekend trip.mp4")
+        ).to_be_visible()
+        page.get_by_role("button", name="All 3", exact=True).click()
+        expect(page.locator(".share-row")).to_have_count(3)
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        for width in (1440, 390, 320):
+            page.set_viewport_size(
+                {"width": width, "height": 960 if width > 600 else 844}
+            )
+            assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+            assert row.evaluate(
+                "element => element.scrollWidth <= element.clientWidth + 1"
+            )
+            if width in (1440, 390):
+                page.screenshot(path=str(ARTIFACTS / f"shares-concise-{width}.png"))
+        # Tapping the date reveals the same exact expiry on touch-sized layouts.
+        expiry.click()
+        expect(tooltip).to_be_visible()
+        expect(tooltip).to_have_text(exact)
+    finally:
+        context.close()
+
+
+def test_backup_timestamp_uses_instance_timezone_in_another_browser_zone(
+    server, browser
+):
+    context = browser.new_context(timezone_id="America/New_York", locale="en-US")
+    try:
+        page = context.new_page()
+        login(page, server.url)
+        page.goto(server.url + "/?view=storage")
+        recovery = page.request.get(server.url + "/api/v1/status").json()["recovery"]
+        expected = page.evaluate(
+            "value => new Intl.DateTimeFormat(undefined, {dateStyle: 'medium', "
+            "timeStyle: 'long', timeZone: 'Asia/Kolkata'}).format(new Date(value))",
+            recovery["last_success_at"],
+        )
+        expect(page.locator(".backup-confirmation-date strong")).to_have_text(expected)
+        assert "GMT+5:30" in expected
+        ARTIFACTS.mkdir(parents=True, exist_ok=True)
+        for width in (1440, 390, 320):
+            page.set_viewport_size(
+                {"width": width, "height": 960 if width > 600 else 844}
+            )
+            assert page.evaluate("document.documentElement.scrollWidth <= innerWidth")
+            assert page.locator(".storage-page").evaluate(
+                "element => element.scrollWidth <= element.clientWidth + 1"
+            )
+    finally:
+        context.close()
diff --git a/tests/browser/test_performance_ui.py b/tests/browser/test_performance_ui.py
new file mode 100644
index 00000000..a7b4578e
--- /dev/null
+++ b/tests/browser/test_performance_ui.py
@@ -0,0 +1,401 @@
+"""Owner controls use real React pages and explicit HTTP boundary fixtures."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from tests.browser.test_browser_e2e import ARTIFACTS, Server, expect, login
+from tests.browser.test_browser_e2e import browser as browser_fixture
+from tests.browser.test_browser_e2e import desktop as desktop_fixture
+from tests.browser.test_browser_e2e import server as server_fixture
+
+pytestmark = pytest.mark.e2e
+browser, desktop, server = browser_fixture, desktop_fixture, server_fixture
+MIB, GIB = 1024**2, 1024**3
+
+
+def preferences():
+    return {
+        "revision": '"first-revision"',
+        "timezone": "Asia/Kolkata",
+        "cache_memory_bytes": 256 * MIB,
+        "cache_disk_bytes": 10 * GIB,
+        "cache_min_free_bytes": GIB,
+        "cache_ttl_seconds": 86400,
+        "auto_preload": True,
+        "preload_max_jobs": 2,
+        "telegram_upload_pipeline": 4,
+        "telegram_request_limit": 8,
+        "telegram_parts_per_second": 24,
+        "telegram_media_per_bot": 3,
+        "telegram_max_queue": 256,
+        "upload_split_mib": 2000,
+    }
+
+
+def cache_snapshot():
+    return {
+        "memory": {
+            "bytes": 20 * MIB,
+            "max_bytes": 256 * MIB,
+            "effective_max_bytes": 128 * MIB,
+            "hits": 120,
+            "misses": 25,
+        },
+        "disk": {
+            "available": True,
+            "bytes": 100 * MIB,
+            "max_bytes": 10 * GIB,
+            "free_bytes": 20 * GIB,
+            "min_free_bytes": GIB,
+        },
+        "pending_writes": 0,
+        "files": [
+            {
+                "id": "movie-cache",
+                "name": "A long shared movie filename.mkv",
+                "size": 100 * MIB,
+                "ready_bytes": 20 * MIB,
+                "complete": False,
+                "ready_ranges": [[0, 10 * MIB], [90 * MIB, 100 * MIB]],
+            },
+            {
+                "id": "complete-cache",
+                "name": "Complete movie.mkv",
+                "size": 80 * MIB,
+                "ready_bytes": 80 * MIB,
+                "complete": True,
+                "ready_ranges": [[0, 80 * MIB]],
+            },
+        ],
+    }
+
+
+def test_settings_save_converts_units_guards_revision_and_recovers_conflict(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    saved = preferences()
+    patches = []
+    reject = False
+
+    def settings(route):
+        if route.request.method == "PATCH":
+            patches.append(route.request.post_data_json)
+            assert route.request.headers["if-match"] == saved["revision"]
+            if reject:
+                route.fulfill(
+                    status=409,
+                    json={"detail": "Changed in another tab. Reload before saving."},
+                )
+                return
+            saved.update(route.request.post_data_json)
+            saved["revision"] = '"second-revision"'
+        route.fulfill(json=saved)
+
+    page.route("**/api/v1/settings/performance", settings)
+    login(page, server.url + "/?view=settings&section=cache")
+    section = page.locator(".performance-settings")
+    expect(section.get_by_label("Memory cache (MiB)", exact=True)).to_have_value("256")
+    section.get_by_label("Memory cache (MiB)", exact=True).fill("512")
+    section.get_by_label("Disk cache (GiB)", exact=True).fill("1.5")
+    expect(
+        section.locator("#perf-help-cache_memory_bytes")
+        .locator("xpath=ancestor::*[contains(@class, 'performance-field')]")
+        .locator(".mantine-Badge-root")
+    ).to_have_count(0)
+    expect(
+        section.locator("#perf-help-cache_memory_bytes").locator(
+            "xpath=ancestor::*[contains(@class, 'performance-field')]"
+        )
+    ).to_contain_text("reduces this budget when memory is tight")
+    expect(section.locator("#perf-help-cache_min_free_bytes")).to_contain_text(
+        "Keep 1 GiB or more for normal use"
+    )
+    section.get_by_label("Disk cache retention (hours)", exact=True).fill("2")
+    page.get_by_role("link", name="Timezone", exact=True).click()
+    section.get_by_label("Timezone", exact=True).fill("UTC")
+    page.get_by_role("link", name="Cache settings", exact=True).click()
+    section.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".toast")).to_have_text("Performance settings saved.")
+    assert patches == [
+        {
+            "cache_memory_bytes": 512 * MIB,
+            "cache_disk_bytes": 1.5 * GIB,
+            "cache_ttl_seconds": 7200,
+        }
+    ]
+    page.get_by_role("link", name="Timezone", exact=True).click()
+    expect(section.get_by_label("Timezone", exact=True)).to_have_value("UTC")
+    section.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(page.locator(".toast")).to_have_text("Performance settings saved.")
+    assert patches[-1] == {"timezone": "UTC"}
+    page.get_by_role("link", name="Cache settings", exact=True).click()
+    section.scroll_into_view_if_needed()
+    page.screenshot(path=ARTIFACTS / "performance-settings-desktop.png")
+    page.set_viewport_size({"width": 390, "height": 844})
+    section.get_by_label("Disk cache (GiB)", exact=True).scroll_into_view_if_needed()
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(path=ARTIFACTS / "performance-settings-mobile.png")
+    reject = True
+    section.get_by_label("Disk cache (GiB)", exact=True).fill("2")
+    section.get_by_role("button", name="Save Performance Settings", exact=True).click()
+    expect(section.get_by_role("alert")).to_contain_text("another tab")
+    expect(
+        section.get_by_role("button", name="Save Performance Settings", exact=True)
+    ).to_be_disabled()
+    section.get_by_role("button", name="Reload Latest Settings", exact=True).click()
+    expect(section.get_by_label("Disk cache (GiB)", exact=True)).to_have_value("1.5")
+    expect(
+        section.locator("#perf-help-cache_disk_bytes")
+        .locator("xpath=ancestor::*[contains(@class, 'performance-field')]")
+        .locator(".mantine-Badge-root")
+    ).to_have_count(0)
+    page.set_viewport_size({"width": 1440, "height": 960})
+    page.get_by_role("link", name="Transfer limits", exact=True).click()
+    section.locator("summary").filter(has_text="Advanced Telegram limits").click()
+    expect(section.get_by_label("Requests per second", exact=True)).to_have_value("24")
+    expect(
+        section.locator("#perf-help-telegram_parts_per_second")
+        .locator("xpath=ancestor::*[contains(@class, 'performance-field')]")
+        .locator(".mantine-Badge-root")
+    ).to_have_count(0)
+
+
+def test_preload_inventory_cancel_and_scoped_eviction(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    data = {
+        "active_jobs": 1,
+        "max_background_jobs": 2,
+        "cache": cache_snapshot(),
+        "jobs": [
+            {
+                "id": "preparing-job",
+                "file_id": "movie-cache",
+                "name": "Preparing a movie.mkv",
+                "state": "preparing",
+                "mode": "manual",
+                "bytes_done": 20 * MIB,
+                "target_bytes": 100 * MIB,
+                "size": 100 * MIB,
+                "start": 0,
+                "end": 100 * MIB,
+            }
+        ],
+    }
+    actions = []
+
+    def handler(route):
+        path = route.request.url.split("/api/v1/preloads", 1)[1]
+        if route.request.method == "POST":
+            actions.append((path, route.request.post_data_json))
+            if path.endswith("/cancel"):
+                data["jobs"][0]["state"] = "cancelled"
+                data["active_jobs"] = 0
+            else:
+                file_id = route.request.post_data_json.get("file_id")
+                data["cache"]["files"] = [
+                    item
+                    for item in data["cache"]["files"]
+                    if file_id and item["id"] != file_id
+                ]
+            route.fulfill(json={"status": "ok"})
+        else:
+            route.fulfill(json=data)
+
+    page.route("**/api/v1/preloads**", handler)
+    login(page, server.url + "/?view=preloads")
+    page.get_by_role(
+        "button",
+        name="Cancel preload of A long shared movie filename.mkv",
+        exact=True,
+    ).click()
+    expect(
+        page.get_by_role("status").filter(has_text="Preload cancelled").first
+    ).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "preloads-desktop.png")
+    page.set_viewport_size({"width": 390, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(path=ARTIFACTS / "preloads-mobile.png")
+    page.get_by_role(
+        "button",
+        name="Evict cached bytes for A long shared movie filename.mkv",
+        exact=True,
+    ).click()
+    page.get_by_role("button", name="Clear Cached File", exact=True).click()
+    expect(
+        page.get_by_text("A long shared movie filename.mkv", exact=True)
+    ).to_have_count(0)
+    page.get_by_role("button", name="Clear Cache", exact=True).click()
+    page.get_by_role("button", name="Clear All Cache", exact=True).click()
+    expect(page.get_by_text("No files cached yet", exact=True)).to_be_visible()
+    assert actions == [
+        ("/preparing-job/cancel", {}),
+        ("/clear", {"file_id": "movie-cache"}),
+        ("/clear", {}),
+    ]
+
+
+def test_performance_real_samples_nullable_eta_and_mobile_tables(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    value = {
+        "telegram": {
+            "active": 2,
+            "queued": 1,
+            "max_queue": 256,
+            "mean_activity_seconds": None,
+            "estimates": True,
+            "accounts": [
+                {
+                    "name": "Storage account with a deliberately long label",
+                    "kind": "bot",
+                    "uploads": 1,
+                    "downloads": 1,
+                    "combined_limit": 3,
+                    "cooldown_seconds": 0,
+                    "requests": None,
+                }
+            ],
+            "queue": [
+                {
+                    "position": 1,
+                    "priority": "demand",
+                    "operation": "download",
+                    "waiting_seconds": 2,
+                    "estimated_wait_seconds": None,
+                }
+            ],
+            "history": [
+                {"at": 100, "active": 1, "queued": 0},
+                {"at": 103, "active": 2, "queued": 1},
+            ],
+        },
+        "cache": cache_snapshot(),
+        "drive": {"files": 25, "folders": 3, "total_bytes": GIB},
+        "server": {
+            "at": 103,
+            "memory": {"MemAvailable": 2 * GIB, "MemTotal": 4 * GIB},
+            "process_peak_rss_bytes": 150 * MIB,
+            "load_average": [0.1, 0.2, 0.3],
+            "disk": {
+                "free_bytes": 20 * GIB,
+                "total_bytes": 40 * GIB,
+                "used_bytes": 20 * GIB,
+            },
+            "staging_budget_bytes": 16 * GIB,
+        },
+    }
+    value["traffic"] = {
+        "at": 106,
+        "requests": 5,
+        "active": 1,
+        "errors": 0,
+        "started_at": 90,
+        "download_bytes": 30 * MIB,
+        "upload_bytes": 6 * MIB,
+        "history": [
+            {
+                "at": at,
+                "requests": 5,
+                "active": 1,
+                "errors": 0,
+                "download_bytes": download * MIB,
+                "upload_bytes": upload * MIB,
+            }
+            for at, download, upload in [(100, 0, 0), (103, 15, 3), (106, 30, 6)]
+        ],
+    }
+    value["telegram"]["accounts"][0]["requests"] = {
+        "active": 2,
+        "queued": 1,
+        "configured_limit": 8,
+        "effective_limit": 4,
+        "configured_parts_per_second": 24,
+        "effective_parts_per_second": 12,
+        "floods": 1,
+        "failed": 1,
+        "completed": 30,
+        "bytes": 3 * MIB,
+        "upload_bytes": MIB,
+        "download_bytes": 2 * MIB,
+    }
+    page.route("**/api/v1/performance", lambda route: route.fulfill(json=value))
+    login(page, server.url + "/?view=performance")
+    expect(
+        page.get_by_role("heading", name="Live file transfers", exact=True)
+    ).to_be_visible()
+    page.screenshot(path=ARTIFACTS / "performance-load-desktop.png")
+    page.get_by_role("tab", name="Accounts", exact=True).click()
+    expect(
+        page.get_by_role("img", name="Recent Telegram load", exact=False)
+    ).to_be_visible()
+    page.set_viewport_size({"width": 390, "height": 844})
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.get_by_role("tab", name="Accounts", exact=True).click()
+    expect(page.get_by_text("Estimating…", exact=True)).to_be_visible()
+    page.get_by_role(
+        "heading", name="Account capacity", exact=True
+    ).scroll_into_view_if_needed()
+    page.screenshot(path=ARTIFACTS / "performance-load-mobile.png")
+    assert page.locator(".performance-table-wrap").first.evaluate(
+        "el=>el.scrollWidth>el.clientWidth"
+    )
+
+
+def test_copy_download_link_is_explicit_public_capability_and_prepare_is_scoped(
+    server: Server, desktop: tuple[Any, Any], browser: Any
+) -> None:
+    context, page = desktop
+    context.grant_permissions(["clipboard-read", "clipboard-write"])
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_label("Actions for sample.json", exact=True).click()
+    page.get_by_role("menuitem", name="Copy Download Link", exact=True).click()
+    dialog = page.get_by_role("dialog", name="Copy Download Link", exact=True)
+    expect(dialog).to_contain_text("Anyone with this link")
+    with page.expect_response("**/api/v1/download-links") as response:
+        dialog.get_by_role("button", name="Create or Copy Link", exact=True).click()
+    link = response.value.json()
+    expect(dialog.get_by_label("Download link", exact=True)).to_have_value(link["url"])
+    assert "auth=" in link["url"]
+    assert page.evaluate("navigator.clipboard.readText()") == link["url"]
+    zone = (
+        page.request.get(server.url + "/api/config")
+        .json()
+        .get("timezone", "Asia/Kolkata")
+    )
+    expiry = page.evaluate(
+        """({value, zone})=>new Intl.DateTimeFormat(undefined,{
+      dateStyle:'medium',timeStyle:'long',timeZone:zone
+    }).format(new Date(value))""",
+        {"value": link["expires_at"], "zone": zone},
+    )
+    expect(dialog).to_contain_text("Expires " + expiry)
+    public = browser.new_context()
+    try:
+        download = public.request.get(link["url"])
+        assert download.status == 200
+        assert b'"count":3' in download.body()
+    finally:
+        public.close()
+    dialog.get_by_role("button", name="Close", exact=True).click()
+    prepared = []
+
+    def prepare(route):
+        prepared.append(route.request.post_data_json)
+        route.fulfill(status=202, json={"id": "prepared", "state": "queued"})
+
+    page.route("**/api/v1/preloads", prepare)
+    page.get_by_label("Actions for sample.json", exact=True).click()
+    page.get_by_role("menuitem", name="Preload file", exact=True).click()
+    dialog = page.get_by_role("dialog", name="Preload file", exact=True)
+    expect(dialog).to_contain_text("Cached bytes may be removed when space is needed.")
+    dialog.get_by_role("button", name="Preload file", exact=True).click()
+    expect(dialog).not_to_be_visible()
+    assert prepared == [{"path": link["path"]}]
diff --git a/tests/browser/test_player_transfer_regressions.py b/tests/browser/test_player_transfer_regressions.py
new file mode 100644
index 00000000..71607d29
--- /dev/null
+++ b/tests/browser/test_player_transfer_regressions.py
@@ -0,0 +1,303 @@
+"""Real browser regressions for playback, modal notices and device receipts."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from tests.browser.test_browser_e2e import (
+    ARTIFACTS,
+    UPLOAD_RECOVERY_RECORDS,
+    Server,
+    expect,
+    login,
+    preview_dialog,
+)
+from tests.browser.test_browser_e2e import (
+    browser as browser_fixture,
+)
+from tests.browser.test_browser_e2e import (
+    desktop as desktop_fixture,
+)
+from tests.browser.test_browser_e2e import (
+    server as server_fixture,
+)
+
+pytestmark = pytest.mark.e2e
+browser = browser_fixture
+desktop = desktop_fixture
+server = server_fixture
+
+
+def test_playing_clock_clears_stale_wait_and_keyboard_works(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(player).to_be_visible(timeout=30000)
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    player.focus()
+    player.press("k")
+    page.wait_for_function(
+        "()=>document.querySelector('movi-player').currentTime>0.25", timeout=20000
+    )
+    before = player.evaluate("element=>element.currentTime")
+    player.evaluate("element=>element.dispatchEvent(new Event('waiting'))")
+    page.wait_for_function(
+        "before=>document.querySelector('movi-player').currentTime>before+0.25",
+        arg=before,
+    )
+    expect(dialog.locator(".advanced-state-buffering")).to_have_count(0)
+    player.focus()
+    player.press("k")
+    page.wait_for_function("()=>document.querySelector('movi-player').paused")
+    player.press("m")
+    assert player.evaluate("element=>element.muted") is True
+
+
+def test_chapters_are_immediate_keyboard_accessible_and_mobile_bounded(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    page.wait_for_function("()=>!!document.querySelector('movi-player')?.player")
+    # Public chapters API supplies real metadata without requesting remote artwork.
+    player.evaluate("""element=>{
+      element.__previewFrameReads = 0;
+      const preview = element.player.getPreviewFrame.bind(element.player);
+      element.player.getPreviewFrame = (...args) => {
+        element.__previewFrameReads++;
+        return preview(...args);
+      };
+      element.player.setChapters([
+        {title:'Opening',start:0},
+        {title:'A very long chapter title for a narrow phone screen',start:1}
+      ]);
+      element.dispatchEvent(new Event('loadedmetadata'));
+    }""")
+    control = player.locator(".movi-chapter-pill")
+    expect(control).to_be_visible()
+    assert control.evaluate("element=>!!element.closest('.movi-controls-bar')")
+    chapters = player.locator(".movi-timeline-panel")
+    expect(chapters).not_to_be_visible()
+    control.focus()
+    control.press("Enter")
+    opening = chapters.get_by_role("button", name="Opening 0:00", exact=True)
+    expect(opening).to_be_visible()
+    expect(opening).to_be_focused()
+    expect(chapters).to_have_attribute("role", "region")
+    expect(chapters).to_have_attribute("aria-label", "Chapters")
+    expect(chapters.locator(".movi-timeline-noframe")).to_have_count(2)
+    expect(chapters.locator("img")).to_have_count(0)
+    assert player.evaluate("element => element.__previewFrameReads") == 0
+    page.screenshot(path=ARTIFACTS / "chapters-immediate-desktop.png")
+    page.set_viewport_size({"width": 390, "height": 844})
+    expect(chapters).to_be_visible()
+    button = chapters.get_by_role(
+        "button", name="A very long chapter title", exact=False
+    )
+    expect(button).to_be_in_viewport()
+    assert chapters.evaluate("el=>el.getBoundingClientRect().right<=innerWidth")
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
+    page.screenshot(path=ARTIFACTS / "chapters-immediate-mobile.png")
+    opening.focus()
+    opening.press("ArrowRight")
+    expect(button).to_be_focused()
+    button.press("ArrowLeft")
+    expect(opening).to_be_focused()
+    opening.press("Space")
+    assert player.evaluate("element => element.paused")
+    button.focus()
+    button.press("Enter")
+    page.wait_for_function("()=>document.querySelector('movi-player').currentTime>=0.9")
+    expect(chapters).to_be_visible()
+    assert player.evaluate("element => element.paused")
+    chapters.locator(".movi-timeline-close").click()
+    expect(chapters).not_to_be_visible()
+    player.evaluate("element=>element.requestFullscreen()")
+    page.wait_for_function("()=>!!document.fullscreenElement")
+    expect(chapters).not_to_be_visible()
+    player.hover()
+    # Compact players expose the native chapter pill through Settings.
+    if control.is_visible():
+        control.focus()
+        control.press("Space")
+    else:
+        settings = player.locator("button.movi-settings-btn")
+        settings.focus()
+        settings.press("Enter")
+        player.locator(".movi-settings-menu").get_by_role(
+            "button", name="Chapters", exact=True
+        ).click()
+    expect(chapters).to_be_visible()
+    assert chapters.evaluate("element=>element.getRootNode() instanceof ShadowRoot")
+    expect(opening).to_be_visible()
+    expect(button).to_have_class(__import__("re").compile("movi-timeline-current"))
+    expect(button).to_be_focused()
+    assert player.evaluate("element=>element.paused")
+    button.press("Escape")
+    expect(chapters).not_to_be_visible()
+    expect(player).to_be_focused()
+    assert page.evaluate("!!document.fullscreenElement")
+    page.evaluate("document.exitFullscreen()")
+    page.wait_for_function("()=>!document.fullscreenElement")
+    player.focus()
+    player.press("Space")
+    page.wait_for_function(
+        """()=>{
+          const player=document.querySelector('movi-player');
+          return !player.paused && player.currentTime>1.2;
+        }"""
+    )
+
+
+def test_share_copy_notice_is_above_native_dialog_without_stealing_focus(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    context, page = desktop
+    context.grant_permissions(["clipboard-read", "clipboard-write"])
+    login(page, server.url)
+    page.get_by_label("Actions for 資料", exact=True).click()
+    page.get_by_role("button", name="Share Link", exact=True).click()
+    page.get_by_role("button", name="Create Share Link", exact=True).click()
+    copy = page.get_by_role("button", name="Copy Link", exact=True)
+    copy.click()
+    notice = page.locator(".toast")
+    expect(notice).to_be_visible()
+    assert notice.evaluate("el=>el.matches(':popover-open')")
+    assert notice.evaluate("el=>!!el.closest('dialog[open]')")
+    assert notice.evaluate("""el=>{
+      const r=el.getBoundingClientRect();
+      return el.contains(document.elementFromPoint(r.x+r.width/2,r.y+r.height/2));
+    }""")
+    expect(copy).to_be_focused()
+    page.screenshot(path=ARTIFACTS / "share-copy-notice-top-layer.png")
+
+
+def test_other_device_transfers_stay_in_history_and_do_not_open_popup(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.route(
+        "**/api/v1/jobs",
+        lambda route: route.fulfill(
+            json={
+                "jobs": [
+                    {
+                        "id": "another-device",
+                        "name": "Other device upload.bin",
+                        "kind": "upload",
+                        "status": "running",
+                        "phase": "uploading",
+                        "current": 1,
+                        "total": 4,
+                    }
+                ]
+            }
+        ),
+    )
+    login(page, server.url)
+    expect(page.locator(".transfer-center")).to_have_count(0)
+    page.get_by_role("link", name="Transfers", exact=False).click()
+    expect(
+        page.get_by_text("Other device upload.bin", exact=True).first
+    ).to_be_visible()
+
+
+def test_url_receipt_remains_a_server_job_after_refresh(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    page.add_init_script("""localStorage.setItem('tgdrive.uploads.v2',JSON.stringify([{
+      key:'url-receipt',name:'URL import.bin',size:4,total:4,current:1,
+      lastModified:0,destination:'/',batchId:'this-device-url',kind:'remote',
+      jobId:'url-server-job',state:'uploading',phase:'Sending to Telegram',
+      initiatedHere:true
+    }]));""")
+    # Older backends can call the URL job 'upload' after local staging completes.
+    page.route(
+        "**/api/v1/jobs",
+        lambda route: route.fulfill(
+            json={
+                "jobs": [
+                    {
+                        "id": "url-server-job",
+                        "name": "URL import.bin",
+                        "kind": "upload",
+                        "status": "running",
+                        "phase": "uploading",
+                        "current": 2,
+                        "total": 4,
+                    }
+                ]
+            }
+        ),
+    )
+    login(page, server.url)
+    page.reload()
+    expect(page.locator(".transfer-center")).to_be_visible()
+    toggle = page.get_by_role("button", name="Show Transfer Details", exact=True)
+    if toggle.count():
+        toggle.click()
+    expect(page.get_by_text("URL import.bin", exact=True).first).to_be_visible()
+    expect(
+        page.get_by_text("Choose the original file to resume", exact=True)
+    ).to_have_count(0)
+    saved = page.evaluate(UPLOAD_RECOVERY_RECORDS)
+    receipt = next(item for item in saved if item["jobId"] == "url-server-job")
+    assert receipt["kind"] == "remote"
+    assert receipt["state"] == "uploading"
+
+
+def test_custom_player_timeline_shows_engine_buffered_regions_after_real_seek(
+    server: Server, desktop: tuple[Any, Any]
+) -> None:
+    _, page = desktop
+    login(page, server.url)
+    page.get_by_role("button", name="Preview samples", exact=True).dblclick()
+    page.get_by_role("button", name="multitrack.mkv", exact=True).dblclick()
+    dialog = preview_dialog(page)
+    player = dialog.locator("movi-player")
+    expect(dialog.locator(".advanced-state")).to_have_count(0, timeout=30000)
+    for target in (0, 3):
+        player.evaluate(
+            """async (element,time)=>{
+              await element.pause();await element.player.seek(time);
+            }""",
+            target,
+        )
+        # Read real engine TimeRanges rather than projecting server byte cache
+        # offsets onto VBR media time. A fully fetched tiny fixture may retain all.
+        page.wait_for_function(
+            """()=>{
+          const player=document.querySelector('movi-player');
+          const buffer=player?.shadowRoot?.querySelector('[part="progress-buffer"]');
+          if(!player?.buffered.length||!buffer||!player.duration) return false;
+          const start=player.buffered.start(0);
+          const end=player.buffered.end(0),duration=player.duration;
+          const left=parseFloat(buffer.style.left),width=parseFloat(buffer.style.width);
+          return width>0 && Math.abs(left-start/duration*100)<1 &&
+            Math.abs(width-(end-start)/duration*100)<1;
+        }""",
+            timeout=15000,
+        )
+    segment = player.locator('[part="progress-buffer"]')
+    expect(segment).to_be_visible()
+    color = segment.evaluate("element=>getComputedStyle(element).backgroundColor")
+    assert color == "rgb(171, 183, 206)"
+    page.set_viewport_size({"width": 390, "height": 844})
+    player.hover()
+    expect(segment).to_be_visible()
+    expect(player.locator("button.movi-play-pause")).to_be_visible()
+    expect(dialog.locator(".preview-surface > video")).to_have_count(0)
+    assert page.evaluate("document.documentElement.scrollWidth<=innerWidth")
diff --git a/tests/core/__init__.py b/tests/core/__init__.py
new file mode 100644
index 00000000..6855a43e
--- /dev/null
+++ b/tests/core/__init__.py
@@ -0,0 +1 @@
+"""TGDrive core tests."""
diff --git a/tests/core/test_config.py b/tests/core/test_config.py
new file mode 100644
index 00000000..4812819e
--- /dev/null
+++ b/tests/core/test_config.py
@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from tgdrive.core.config import Settings
+
+
+def settings_values(**overrides: object) -> dict[str, object]:
+    values: dict[str, object] = {
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "API_ID": 12345,
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30,
+        "STORAGE_CHANNEL": -1001234567890,
+        "ADMIN_PASSWORD": "correct horse battery staple",
+        "SESSION_SECRET": "s" * 48,
+    }
+    values.update(overrides)
+    return values
+
+
+def test_settings_parse_csv_and_derive_non_premium_limit() -> None:
+    settings = Settings(_env_file=None, **settings_values())
+
+    assert settings.bot_tokens == ("123456:" + "x" * 30,)
+    assert settings.string_sessions == ()
+    assert settings.telegram_admin_ids == ()
+    assert settings.upload_limit == settings.staging_budget_bytes
+    assert settings.bot_upload_limit == 2000 * 1024**2
+    assert len(settings.session_key) == 32
+
+
+@pytest.mark.parametrize("legacy_value", [None, "", " , "])
+def test_main_bot_seeds_storage_credentials_for_a_new_deployment(
+    monkeypatch, legacy_value
+):
+    monkeypatch.delenv("BOT_TOKENS", raising=False)
+    token = "654321:" + "y" * 30
+    values = settings_values(MAIN_BOT_TOKEN=token, TELEGRAM_ADMIN_IDS="123")
+    if legacy_value is None:
+        values.pop("BOT_TOKENS")
+    else:
+        values["BOT_TOKENS"] = legacy_value
+    settings = Settings(_env_file=None, **values)
+
+    assert settings.bot_tokens == (token,)
+    assert settings.bot_tokens_csv.get_secret_value() == token
+    assert settings.model_dump(by_alias=True)["BOT_TOKENS"].get_secret_value() == token
+    assert token not in repr(settings)
+
+
+def test_main_bot_does_not_replace_a_legacy_storage_bot_list():
+    tokens = ("123456:" + "x" * 30, "654321:" + "y" * 30)
+    settings = Settings(
+        _env_file=None,
+        **settings_values(
+            BOT_TOKENS=",".join(tokens),
+            MAIN_BOT_TOKEN="777777:" + "z" * 30,
+            TELEGRAM_ADMIN_IDS="123",
+        ),
+    )
+    assert settings.bot_tokens == tokens
+
+
+def test_main_bot_does_not_hide_invalid_legacy_storage_credentials():
+    with pytest.raises(ValidationError, match="BOT_TOKENS contains an invalid"):
+        Settings(
+            _env_file=None,
+            **settings_values(
+                BOT_TOKENS="invalid",
+                MAIN_BOT_TOKEN="654321:" + "y" * 30,
+                TELEGRAM_ADMIN_IDS="123",
+            ),
+        )
+
+
+def test_main_bot_does_not_reseed_a_managed_empty_storage_list():
+    with pytest.raises(ValidationError, match="At least one storage bot"):
+        Settings(
+            _env_file=None,
+            **settings_values(
+                BOT_TOKENS="",
+                MAIN_BOT_TOKEN="654321:" + "y" * 30,
+                TELEGRAM_ADMIN_IDS="123",
+                managed_revision=1,
+            ),
+        )
+
+
+def test_new_deployment_requires_an_initial_storage_bot():
+    with pytest.raises(ValidationError, match="set MAIN_BOT_TOKEN"):
+        Settings(_env_file=None, **settings_values(BOT_TOKENS="", MAIN_BOT_TOKEN=""))
+
+
+def test_explicit_main_bot_configuration_keeps_injected_settings_isolated(monkeypatch):
+    import tgdrive.storage.mongo as mongo
+
+    values = settings_values(TELEGRAM_ADMIN_IDS="123")
+    values.pop("BOT_TOKENS")
+    monkeypatch.delenv("BOT_TOKENS", raising=False)
+    for name, value in values.items():
+        monkeypatch.setenv(name, str(value))
+
+    def unexpected_database_lookup(*_args, **_kwargs):
+        raise AssertionError("Injected credentials must not load managed connections")
+
+    monkeypatch.setattr(mongo, "configure", unexpected_database_lookup)
+    token = "654321:" + "y" * 30
+    settings = Settings(_env_file=None, MAIN_BOT_TOKEN=token)
+    assert settings.bot_tokens == (token,)
+
+
+def test_premium_sessions_do_not_raise_new_document_or_logical_limits() -> None:
+    settings = Settings(
+        _env_file=None,
+        **settings_values(
+            STRING_SESSIONS="session-one, session-two",
+            TELEGRAM_ADMIN_IDS="123, 456",
+        ),
+    )
+
+    assert settings.string_sessions == ("session-one", "session-two")
+    assert settings.telegram_admin_ids == (123, 456)
+    assert settings.upload_limit == settings.staging_budget_bytes
+    assert settings.bot_upload_limit == 2000 * 1024**2
+    assert settings.upload_split_mib == 2000
+
+
+@pytest.mark.parametrize(
+    ("field", "value"),
+    [
+        ("MONGODB_URI", ""),
+        ("MONGODB_URI", "   "),
+        ("MONGODB_URI", "https://synthetic.invalid"),
+        ("ADMIN_PASSWORD", "admin"),
+        ("ADMIN_PASSWORD", ""),
+        ("ADMIN_PASSWORD", " \t " * 12),
+        ("SESSION_SECRET", "short"),
+        ("API_HASH", "z" * 32),
+        ("BOT_TOKENS", "not-a-token"),
+        ("MAIN_BOT_TOKEN", "not-a-token"),
+        ("TELEGRAM_ADMIN_IDS", "123,nope"),
+    ],
+)
+def test_settings_reject_unsafe_values(field: str, value: str) -> None:
+    with pytest.raises(ValidationError):
+        Settings(_env_file=None, **settings_values(**{field: value}))
+
+
+def test_bot_mode_requires_admin_ids() -> None:
+    with pytest.raises(ValidationError, match="TELEGRAM_ADMIN_IDS"):
+        Settings(
+            _env_file=None,
+            **settings_values(BOT_TOKENS="", MAIN_BOT_TOKEN="654321:" + "y" * 30),
+        )
+
+
+def test_logical_limit_can_exceed_message_limit_but_is_bounded_by_staging() -> None:
+    settings = Settings(_env_file=None, **settings_values(MAX_FILE_SIZE=4 * 1024**3))
+    assert settings.upload_limit == 4 * 1024**3
+    smaller = Settings(
+        _env_file=None,
+        **settings_values(
+            MAX_FILE_SIZE=4 * 1024**3,
+            STAGING_BUDGET_BYTES=3 * 1024**3,
+        ),
+    )
+    assert smaller.upload_limit == 3 * 1024**3
+
+
+@pytest.mark.parametrize("variant", ["i", "d"])
+def test_non_argon2id_owner_hash_is_rejected(variant: str) -> None:
+    from argon2 import PasswordHasher, Type
+
+    algorithm = Type.I if variant == "i" else Type.D
+    encoded = PasswordHasher(type=algorithm).hash("synthetic owner password")
+    with pytest.raises(ValidationError, match="Argon2id"):
+        Settings(
+            _env_file=None,
+            **settings_values(ADMIN_PASSWORD_HASH=encoded),
+        )
+
+
+def test_invalid_configuration_traceback_hides_raw_secret_inputs() -> None:
+    secret = "synthetic-secret-value-that-must-not-be-rendered"
+    with pytest.raises(ValidationError) as captured:
+        Settings(
+            _env_file=None,
+            **settings_values(API_HASH=secret, SESSION_SECRET=secret),
+        )
+    assert secret not in str(captured.value)
+    assert "input_value" not in str(captured.value)
+
+
+def test_blank_plaintext_password_with_owner_hash_is_canonical_empty() -> None:
+    from argon2 import PasswordHasher
+
+    encoded = PasswordHasher().hash("synthetic owner password")
+    settings = Settings(
+        _env_file=None,
+        **settings_values(ADMIN_PASSWORD=" \t " * 12, ADMIN_PASSWORD_HASH=encoded),
+    )
+    assert settings.admin_password.get_secret_value() == ""
+
+
+@pytest.mark.parametrize(
+    "field,value",
+    [
+        ("BOT_TOKENS", ",".join(["123456:" + "x" * 30] * 2)),
+        ("STRING_SESSIONS", "synthetic-session,synthetic-session"),
+    ],
+)
+def test_duplicate_telegram_credentials_are_rejected_without_echo(field, value):
+    with pytest.raises(ValidationError, match="must not repeat") as caught:
+        Settings(_env_file=None, **settings_values(**{field: value}))
+    assert value not in str(caught.value)
+
+
+@pytest.mark.parametrize(
+    "cost", ["m=262145,t=3,p=4", "m=65536,t=11,p=4", "m=65536,t=3,p=17"]
+)
+def test_owner_hash_cannot_request_excessive_login_resources(cost):
+    from argon2 import PasswordHasher
+
+    encoded = PasswordHasher().hash("synthetic owner password")
+    encoded = encoded.replace("m=65536,t=3,p=4", cost)
+    with pytest.raises(ValidationError, match="exceeds supported login costs"):
+        Settings(_env_file=None, **settings_values(ADMIN_PASSWORD_HASH=encoded))
+
+
+def test_blank_optional_backup_key_is_absent():
+    settings = Settings(_env_file=None, **settings_values(MONGODB_BACKUP_KEY=""))
+    assert settings.mongodb_backup_key is None
+
+
+def test_mongodb_uri_is_required_even_with_complete_telegram_configuration(monkeypatch):
+    monkeypatch.delenv("MONGODB_URI", raising=False)
+    values = settings_values()
+    values.pop("MONGODB_URI")
+    with pytest.raises(ValidationError, match="MONGODB_URI"):
+        Settings(_env_file=None, **values)
diff --git a/tests/core/test_deployment.py b/tests/core/test_deployment.py
new file mode 100644
index 00000000..3d393302
--- /dev/null
+++ b/tests/core/test_deployment.py
@@ -0,0 +1,447 @@
+"""Deployment defaults must preserve credentials and keep proxy trust narrow."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import socket
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from argon2 import PasswordHasher
+
+from tgdrive.core.config import Settings
+from tgdrive.core.deployment import installation_secrets
+from tgdrive.server import main, trusted_proxy_ips
+from tgdrive.storage.mongo import DatabaseUnavailable
+
+
+def test_generated_keys_survive_restarts_and_concurrent_startup(tmp_path):
+    with ThreadPoolExecutor(max_workers=4) as workers:
+        results = list(
+            workers.map(
+                lambda _: installation_secrets(tmp_path, {}, existing_drive=False),
+                range(4),
+            )
+        )
+    assert all(result == results[0] for result in results)
+    saved = tmp_path / "deployment-secrets.json"
+    assert saved.stat().st_mode & 0o777 == 0o600
+    assert len(bytes.fromhex(results[0]["MONGODB_BACKUP_KEY"])) == 32
+    assert len(results[0]["SESSION_SECRET"]) >= 32
+    assert installation_secrets(tmp_path, {}, existing_drive=False) == results[0]
+
+
+def test_existing_drive_never_gets_replacement_keys(tmp_path):
+    with pytest.raises(ValueError, match=r"original.*SESSION_SECRET"):
+        installation_secrets(tmp_path, {}, existing_drive=True)
+    assert not (tmp_path / "deployment-secrets.json").exists()
+
+
+@pytest.mark.parametrize("damage", ["invalid-json", "permissions", "symlink"])
+def test_saved_keys_are_never_silently_replaced(tmp_path, damage):
+    original = installation_secrets(tmp_path, {}, existing_drive=False)
+    saved = tmp_path / "deployment-secrets.json"
+    if damage == "invalid-json":
+        saved.write_text("damaged private file")
+    elif damage == "permissions":
+        saved.chmod(0o644)
+    else:
+        saved.rename(tmp_path / "preserved.json")
+        saved.symlink_to(tmp_path / "preserved.json")
+    before = saved.read_bytes()
+    with pytest.raises((OSError, ValueError)):
+        installation_secrets(tmp_path, {}, existing_drive=False)
+    assert saved.read_bytes() == before
+    if damage == "symlink":
+        assert json.loads((tmp_path / "preserved.json").read_text()) == original
+
+
+def test_existing_mongodb_bootstrap_reopens_with_only_database_configuration(
+    tmp_path, monkeypatch
+):
+    """A new server must reuse the owner's hash and both original keys."""
+    from tgdrive.storage import mongo
+
+    owner_hash = PasswordHasher().hash("original synthetic owner password")
+    bootstrap = {
+        "API_ID": 12345,
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30,
+        "STORAGE_CHANNEL": -1001234567890,
+        "ADMIN_PASSWORD_HASH": owner_hash,
+        "SESSION_SECRET": "s" * 48,
+        "MONGODB_BACKUP_KEY": "b" * 64,
+    }
+    fake = SimpleNamespace(
+        db=SimpleNamespace(
+            settings=SimpleNamespace(find_one=lambda _: {"document": bootstrap})
+        )
+    )
+    monkeypatch.setenv("TGDRIVE_AUTO_SECRETS", "true")
+    monkeypatch.setenv("MONGODB_URI", "mongodb://synthetic.invalid")
+    monkeypatch.setenv("DATA_DIR", str(tmp_path))
+    monkeypatch.setenv("ADMIN_PASSWORD", "")
+    for key in ("SESSION_SECRET", "MONGODB_BACKUP_KEY", "ADMIN_PASSWORD_HASH"):
+        monkeypatch.setenv(key, "")
+    monkeypatch.setattr(mongo, "configure", lambda *_args: fake)
+    monkeypatch.setattr(
+        "tgdrive.settings.managed_settings.read_document", lambda _: None
+    )
+    settings = Settings(_env_file=None)
+    assert settings.admin_password_hash.get_secret_value() == owner_hash
+    assert settings.session_secret.get_secret_value() == bootstrap["SESSION_SECRET"]
+    assert settings.mongodb_backup_key.get_secret_value() == "b" * 64
+    assert not (tmp_path / "deployment-secrets.json").exists()
+
+
+def test_new_container_can_generate_keys_before_explicit_initialization(
+    tmp_path, monkeypatch
+):
+    from tgdrive.storage import mongo
+
+    monkeypatch.delenv("BOT_TOKENS", raising=False)
+    for key, value in {
+        "TGDRIVE_AUTO_SECRETS": "true",
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "DATA_DIR": str(tmp_path),
+        "API_ID": "12345",
+        "API_HASH": "a" * 32,
+        "MAIN_BOT_TOKEN": "123456:" + "x" * 30,
+        "TELEGRAM_ADMIN_IDS": "12345",
+        "STORAGE_CHANNEL": "-1001234567890",
+        "ADMIN_PASSWORD": "new synthetic owner password",
+        "ADMIN_PASSWORD_HASH": "",
+        "SESSION_SECRET": "",
+        "MONGODB_BACKUP_KEY": "",
+    }.items():
+        monkeypatch.setenv(key, value)
+    fake = SimpleNamespace(
+        db=SimpleNamespace(
+            settings=SimpleNamespace(find_one=lambda _: None),
+            catalog=SimpleNamespace(find_one=lambda _: None),
+        )
+    )
+    monkeypatch.setattr(mongo, "configure", lambda *_args: fake)
+    monkeypatch.setattr(
+        "tgdrive.settings.managed_settings.read_document", lambda _: None
+    )
+    first = Settings(_env_file=None)
+    second = Settings(_env_file=None)
+    assert first.session_secret == second.session_secret
+    assert first.mongodb_backup_key == second.mongodb_backup_key
+    assert first.admin_password_hash is None
+    assert first.bot_tokens == (first.main_bot_token_value,)
+    assert first.telegram_admin_ids == (12345,)
+
+
+def test_existing_drive_marker_prevents_key_generation_for_an_empty_database(
+    tmp_path, monkeypatch
+):
+    for key, value in {
+        "TGDRIVE_AUTO_SECRETS": "true",
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "DATA_DIR": str(tmp_path),
+        "API_ID": "12345",
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30,
+        "STORAGE_CHANNEL": "-1001234567890",
+        "ADMIN_PASSWORD": "synthetic owner password",
+        "ADMIN_PASSWORD_HASH": "",
+        "SESSION_SECRET": "",
+        "MONGODB_BACKUP_KEY": "",
+    }.items():
+        monkeypatch.setenv(key, value)
+    (tmp_path / "mongodb-drive.json").write_text('{"drive_id":"saved-drive"}')
+    fake = SimpleNamespace(
+        db=SimpleNamespace(
+            settings=SimpleNamespace(find_one=lambda _: None),
+            catalog=SimpleNamespace(find_one=lambda _: None),
+        )
+    )
+    monkeypatch.setattr("tgdrive.storage.mongo.configure", lambda *_args: fake)
+    with pytest.raises(ValueError, match=r"original.*SESSION_SECRET"):
+        Settings(_env_file=None)
+    assert not (tmp_path / "deployment-secrets.json").exists()
+
+
+def recovery_configuration(tmp_path, monkeypatch, **overrides):
+    values = {
+        "API_ID": 12345,
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30,
+        "STORAGE_CHANNEL": -1001234567890,
+        "ADMIN_PASSWORD_HASH": PasswordHasher().hash("original owner password"),
+        "SESSION_SECRET": "s" * 48,
+    }
+    environment = {
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "DATA_DIR": str(tmp_path),
+        "ADMIN_PASSWORD": "",
+        "ADMIN_PASSWORD_HASH": "",
+        "SESSION_SECRET": "",
+        "MONGODB_BACKUP_KEY": "",
+        **overrides,
+    }
+    for key, value in environment.items():
+        monkeypatch.setenv(key, str(value))
+    monkeypatch.setattr(
+        "tgdrive.replication.replica_bootstrap.load_bootstrap",
+        lambda _, **_kwargs: values,
+    )
+    return values
+
+
+def test_explicit_rotation_is_not_hidden_by_local_recovery_copy(tmp_path, monkeypatch):
+    bootstrap = recovery_configuration(
+        tmp_path,
+        monkeypatch,
+        ADMIN_PASSWORD="replacement owner password",
+        SESSION_SECRET="replacement-signing-secret-" * 3,
+        STORAGE_CHANNEL=-1009876543210,
+    )
+    backend = SimpleNamespace(
+        db=SimpleNamespace(
+            settings=SimpleNamespace(find_one=lambda _: {"document": bootstrap})
+        )
+    )
+    monkeypatch.setattr("tgdrive.storage.mongo.configure", lambda *_args: backend)
+    monkeypatch.setattr(
+        "tgdrive.settings.managed_settings.read_document", lambda _: None
+    )
+    settings = Settings(_env_file=None)
+    assert settings.storage_channel == -1009876543210
+    assert (
+        settings.session_secret.get_secret_value() == "replacement-signing-secret-" * 3
+    )
+    assert settings.admin_password.get_secret_value() == "replacement owner password"
+    assert settings.admin_password_hash is None
+
+
+def test_database_outage_rejects_startup_even_with_saved_recovery_keys(
+    tmp_path, monkeypatch
+):
+    bootstrap = recovery_configuration(
+        tmp_path, monkeypatch, TGDRIVE_AUTO_SECRETS="true"
+    )
+    keys = installation_secrets(tmp_path, {}, existing_drive=False)
+    bootstrap["SESSION_SECRET"] = keys["SESSION_SECRET"]
+
+    def unavailable(_query):
+        raise ConnectionError("synthetic database outage")
+
+    backend = SimpleNamespace(
+        db=SimpleNamespace(settings=SimpleNamespace(find_one=unavailable))
+    )
+    monkeypatch.setattr("tgdrive.storage.mongo.configure", lambda *_args: backend)
+    monkeypatch.setattr(
+        "tgdrive.settings.managed_settings.read_document",
+        lambda _: pytest.fail("Do not query unavailable MongoDB a second time"),
+    )
+    before = (tmp_path / "deployment-secrets.json").read_bytes()
+    with pytest.raises(DatabaseUnavailable, match="MongoDB is unavailable"):
+        Settings(_env_file=None)
+    assert (tmp_path / "deployment-secrets.json").read_bytes() == before
+
+
+def test_database_outage_does_not_generate_replacement_recovery_keys(
+    tmp_path, monkeypatch
+):
+    recovery_configuration(tmp_path, monkeypatch, TGDRIVE_AUTO_SECRETS="true")
+
+    def unavailable(_query):
+        raise ConnectionError("synthetic database outage")
+
+    monkeypatch.setattr(
+        "tgdrive.storage.mongo.configure",
+        lambda *_args: SimpleNamespace(
+            db=SimpleNamespace(settings=SimpleNamespace(find_one=unavailable))
+        ),
+    )
+    with pytest.raises(DatabaseUnavailable, match="MongoDB is unavailable"):
+        Settings(_env_file=None)
+    assert not (tmp_path / "deployment-secrets.json").exists()
+
+
+def test_proxy_discovery_trusts_only_resolved_private_addresses(monkeypatch):
+    monkeypatch.delenv("FORWARDED_ALLOW_IPS", raising=False)
+    monkeypatch.setenv("TGDRIVE_PROXY_HOSTS", "coolify-proxy")
+    monkeypatch.setattr(
+        socket,
+        "getaddrinfo",
+        lambda host, *_args, **_kwargs: [
+            (socket.AF_INET, socket.SOCK_STREAM, 6, "", (address, 0))
+            for address in ("10.0.2.2", "10.0.2.2", "8.8.8.8", "0.0.0.0")  # noqa: S104
+            if host == "coolify-proxy"
+        ],
+    )
+    assert set(trusted_proxy_ips().split(",")) == {"127.0.0.1", "::1", "10.0.2.2"}
+
+
+def test_proxy_discovery_failure_does_not_trust_the_network(monkeypatch, caplog):
+    monkeypatch.setenv("FORWARDED_ALLOW_IPS", "auto")
+    monkeypatch.setenv("TGDRIVE_PROXY_HOSTS", "coolify-proxy")
+
+    def unavailable(*_args, **_kwargs):
+        raise socket.gaierror("synthetic DNS failure")
+
+    monkeypatch.setattr(socket, "getaddrinfo", unavailable)
+    assert set(trusted_proxy_ips().split(",")) == {"127.0.0.1", "::1"}
+    assert "could not be resolved" in caplog.text
+
+
+def test_explicit_proxy_configuration_is_preserved(monkeypatch):
+    monkeypatch.setenv("FORWARDED_ALLOW_IPS", "127.0.0.1,10.0.2.0/24")
+    assert trusted_proxy_ips() == "127.0.0.1,10.0.2.0/24"
+
+
+@pytest.mark.parametrize("auto_secrets", ["false", "true"])
+def test_container_launcher_keeps_one_worker_without_waiting_for_manual_init(
+    monkeypatch, auto_secrets
+):
+    monkeypatch.setenv("TGDRIVE_AUTO_SECRETS", auto_secrets)
+    monkeypatch.setenv("FORWARDED_ALLOW_IPS", "127.0.0.1")
+    called = {}
+    monkeypatch.setattr(
+        "tgdrive.server.uvicorn.run",
+        lambda app, **kwargs: called.update(app=app, **kwargs),
+    )
+    main()
+    assert called["app"] == "tgdrive.web.app:create_app"
+    assert called["factory"] is True
+    assert called["host"] == "0.0.0.0"  # noqa: S104
+    assert called["workers"] == 1
+    assert called["proxy_headers"] is True
+    assert called["forwarded_allow_ips"] == "127.0.0.1"
+    assert called["timeout_graceful_shutdown"] == 45
+
+
+def test_hosted_and_local_compose_resolve_without_real_credentials(tmp_path):
+    docker = shutil.which("docker")
+    if not docker:
+        pytest.skip("Docker Compose is needed for deployment configuration validation")
+    root = Path(__file__).resolve().parents[2]
+    for name in (
+        "compose.yaml",
+        "compose.override.yaml",
+        "compose.server.yaml",
+    ):
+        shutil.copyfile(root / name, tmp_path / name)
+    fixture = {
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "API_ID": "12345",
+        "API_HASH": "a" * 32,
+        "MAIN_BOT_TOKEN": "123456:" + "x" * 30,
+        "TELEGRAM_ADMIN_IDS": "12345",
+        "STORAGE_CHANNEL": "-1001234567890",
+        "ADMIN_PASSWORD": "synthetic owner password",
+        "SESSION_SECRET": "s" * 48,
+        "MONGODB_BACKUP_KEY": "b" * 64,
+    }
+    (tmp_path / ".env").write_text(
+        "".join(f"{key}={value}\n" for key, value in fixture.items())
+    )
+    environment = {**os.environ, **fixture}
+    environment.pop("BOT_TOKENS", None)
+    environment.pop("COMPOSE_FILE", None)
+    environment.pop("BIND_ADDRESS", None)
+    environment.pop("PORT", None)
+    environment.pop("TGDRIVE_RESTART_POLICY", None)
+    environment.pop("COOKIE_SECURE", None)
+
+    def config(*files):
+        arguments = [docker, "compose"]
+        for name in files:
+            arguments.extend(["-f", name])
+        result = subprocess.run(  # noqa: S603 - fixed CLI and synthetic config only
+            [*arguments, "config", "--format", "json"],
+            cwd=tmp_path,
+            env=environment,
+            capture_output=True,
+            text=True,
+            timeout=20,
+        )
+        if "is not a docker command" in result.stderr:
+            pytest.skip("Docker Compose plugin is not installed")
+        assert result.returncode == 0, result.stderr
+        return json.loads(result.stdout)["services"]["app"]
+
+    hosted = config("compose.yaml")
+    assert not hosted.get("ports")
+    assert hosted["environment"]["TGDRIVE_PROXY_HOSTS"] == "coolify-proxy"
+    assert hosted["environment"]["SESSION_SECRET"] == fixture["SESSION_SECRET"]
+    assert hosted["environment"]["COOKIE_SECURE"] == "true"
+    assert hosted["restart"] == "unless-stopped"
+    local = config()
+    assert local["ports"][0]["host_ip"] == "127.0.0.1"
+    assert str(local["ports"][0]["published"]) == "8000"
+    assert local["environment"]["SESSION_SECRET"] == fixture["SESSION_SECRET"]
+    assert local["environment"]["TGDRIVE_PROXY_HOSTS"] == ""
+    assert local["environment"]["COOKIE_SECURE"] == "false"
+    assert local["restart"] == "no"
+    server = config("compose.yaml", "compose.server.yaml")
+    assert server["ports"][0]["host_ip"] == "127.0.0.1"
+    assert server["environment"]["COOKIE_SECURE"] == "true"
+    assert server["environment"]["TGDRIVE_PROXY_HOSTS"] == ""
+    assert server["restart"] == "unless-stopped"
+    for deployment in (hosted, local, server):
+        assert deployment["environment"]["MAIN_BOT_TOKEN"] == fixture["MAIN_BOT_TOKEN"]
+        assert deployment["environment"]["TELEGRAM_ADMIN_IDS"] == "12345"
+        assert "BOT_TOKENS" not in deployment["environment"]
+        assert "CACHE_MEMORY_BYTES" not in deployment["environment"]
+        assert "AUTO_PRELOAD" not in deployment["environment"]
+        assert deployment["environment"]["DATA_DIR"] == "/app/data"
+        assert deployment["environment"]["CACHE_DIR"] == "/app/cache"
+
+    # Optional .env values pass through unchanged, including zero and false.
+    overrides = {
+        "DEMO_MODE": "true",
+        "REMOTE_DOWNLOAD_CONCURRENCY": "3",
+        "CACHE_MEMORY_BYTES": "536870912",
+        "CACHE_DISK_BYTES": "0",
+        "AUTO_PRELOAD": "false",
+        "UPLOAD_SPLIT_MIB": "0",
+        "TIMEZONE": "UTC",
+    }
+    (tmp_path / ".env").write_text(
+        "".join(f"{key}={value}\n" for key, value in (fixture | overrides).items())
+    )
+    for files in (("compose.yaml",), (), ("compose.yaml", "compose.server.yaml")):
+        rendered = config(*files)["environment"]
+        assert {key: rendered[key] for key in overrides} == overrides
+
+    # Old .env files remain usable without enabling the bot interface.
+    legacy = dict(fixture)
+    legacy["BOT_TOKENS"] = legacy.pop("MAIN_BOT_TOKEN")
+    legacy.pop("TELEGRAM_ADMIN_IDS")
+    (tmp_path / ".env").write_text(
+        "".join(f"{key}={value}\n" for key, value in legacy.items())
+    )
+    environment.pop("MAIN_BOT_TOKEN", None)
+    environment.pop("TELEGRAM_ADMIN_IDS", None)
+    rendered = config("compose.yaml")["environment"]
+    assert rendered["BOT_TOKENS"] == legacy["BOT_TOKENS"]
+    assert rendered["MAIN_BOT_TOKEN"] == ""
+    assert rendered["TELEGRAM_ADMIN_IDS"] == ""
+
+
+def test_environment_template_contains_only_required_bootstrap_values():
+    root = Path(__file__).resolve().parents[2]
+    keys = {
+        line.split("=", 1)[0]
+        for line in (root / ".env.example").read_text().splitlines()
+        if line and not line.startswith("#")
+    }
+    assert keys == {
+        "MONGODB_URI",
+        "API_ID",
+        "API_HASH",
+        "MAIN_BOT_TOKEN",
+        "TELEGRAM_ADMIN_IDS",
+        "STORAGE_CHANNEL",
+        "ADMIN_PASSWORD",
+    }
diff --git a/tests/core/test_release_package.py b/tests/core/test_release_package.py
new file mode 100644
index 00000000..6b748f92
--- /dev/null
+++ b/tests/core/test_release_package.py
@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import zipfile
+from pathlib import Path
+
+import pytest
+
+from scripts.build_release import (
+    PUBLIC_DOCS,
+    ROOT_FILES,
+    SOURCE_TREES,
+    build_release,
+    check_version,
+)
+
+
+def _source_tree(root: Path) -> None:
+    for name in (*ROOT_FILES, *PUBLIC_DOCS):
+        path = root / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("public source\n", encoding="utf-8")
+    (root / "pyproject.toml").write_text(
+        '[project]\nname = "tgdrive"\nversion = "2.0.0"\n', encoding="utf-8"
+    )
+    for directory in SOURCE_TREES:
+        (root / directory).mkdir(exist_ok=True)
+    (root / "tgdrive/__init__.py").write_text('__version__ = "2.0.0"\n')
+    (root / "website/package.json").write_text('{"version": "2.0.0"}\n')
+    (root / "website/package-lock.json").write_text(
+        '{"version": "2.0.0", "packages": {"": {"version": "2.0.0"}}}\n'
+    )
+    (root / "Dockerfile").write_text('LABEL org.opencontainers.image.version="2.0.0"\n')
+    (root / "uv.lock").write_text(
+        '[[package]]\nname = "tgdrive"\nversion = "2.0.0"\nsource = {virtual = "."}\n'
+    )
+    application = root / "tgdrive" / "web" / "app.py"
+    application.parent.mkdir(parents=True, exist_ok=True)
+    application.write_text("# application\n", encoding="utf-8")
+
+
+@pytest.mark.parametrize(
+    ("name", "content"),
+    [
+        ("tgdrive/__init__.py", '__version__ = "2.0.1"\n'),
+        ("tgdrive/__init__.py", "# Missing version\n"),
+        ("website/package.json", '{"version": "2.0.1"}'),
+        (
+            "website/package-lock.json",
+            '{"version": "2.0.1", "packages": {"": {"version": "2.0.0"}}}',
+        ),
+        (
+            "website/package-lock.json",
+            '{"version": "2.0.0", "packages": {"": {"version": "2.0.1"}}}',
+        ),
+        ("Dockerfile", 'LABEL org.opencontainers.image.version="2.0.1"\n'),
+        ("Dockerfile", "FROM python\n"),
+        (
+            "uv.lock",
+            '[[package]]\nname = "tgdrive"\nversion = "2.0.1"\n'
+            'source = {virtual = "."}\n',
+        ),
+        ("uv.lock", "version = 1\n"),
+    ],
+)
+def test_source_archive_rejects_version_drift(
+    tmp_path: Path, name: str, content: str
+) -> None:
+    _source_tree(tmp_path)
+    (tmp_path / name).write_text(content, encoding="utf-8")
+    output = tmp_path / "output"
+
+    with pytest.raises(ValueError, match="Release version mismatch"):
+        build_release(tmp_path, output)
+
+    assert not output.exists()
+
+
+@pytest.mark.parametrize("version", ["2.0", "v2.0.0", "02.0.0", "2.0.0-rc.1"])
+def test_release_version_rejects_invalid_format(tmp_path: Path, version: str) -> None:
+    _source_tree(tmp_path)
+    (tmp_path / "pyproject.toml").write_text(
+        f'[project]\nname = "tgdrive"\nversion = "{version}"\n', encoding="utf-8"
+    )
+
+    with pytest.raises(ValueError, match=r"major\.minor\.patch"):
+        check_version(tmp_path)
+
+
+def test_release_tag_must_match_version(tmp_path: Path) -> None:
+    _source_tree(tmp_path)
+    assert check_version(tmp_path, "v2.0.0") == "2.0.0"
+
+    for tag in ("v2.0.1", "2.0.0"):
+        with pytest.raises(ValueError, match=r"Release tag must be v2\.0\.0"):
+            check_version(tmp_path, tag)
+
+
+def test_source_archive_excludes_local_state_and_private_documents(
+    tmp_path: Path,
+) -> None:
+    source = tmp_path / "source"
+    _source_tree(source)
+    private_names = (
+        ".env",
+        ".agents/skills/private/SKILL.md",
+        ".codex/private.json",
+        "skills-lock.json",
+        "docs/request-tracker.md",
+        "website/.agents/skills/private/config.json",
+        "website/.codex/private.json",
+        "website/skills-lock.json",
+        ".git/config",
+        "data/drive.json",
+        "cache/uploads/private.upload",
+        ".venv/credentials.py",
+        "docs/private-local-notes.md",
+        "tgdrive/__pycache__/private.py",
+        "website/private.session",
+        "website/node_modules/dependency/index.js",
+        "website/dist/assets/index.js",
+        "website/coverage/report.json",
+        "website/.vite/cache.json",
+        "website/.impeccable/design.json",
+    )
+    for name in private_names:
+        path = source / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text("PRIVATE-CONTENT", encoding="utf-8")
+
+    frontend_source = source / "website" / "src" / "app" / "App.tsx"
+    frontend_source.parent.mkdir(parents=True, exist_ok=True)
+    frontend_source.write_text("export default function App() { return null; }\n")
+    patch_script = source / "website" / "scripts" / "patch-movi-player.js"
+    patch_script.parent.mkdir(parents=True, exist_ok=True)
+    patch_script.write_text("// reviewed portable seek fix\n", encoding="utf-8")
+    brand_assets = (
+        "website/public/static/brand/tgdrive-icon.svg",
+        "website/public/static/brand/favicon-32.png",
+        "website/public/static/brand/favicon.ico",
+        "website/public/static/brand/apple-touch-icon.png",
+        "website/public/static/brand/social-preview.png",
+    )
+    for name in brand_assets:
+        asset = source / name
+        asset.parent.mkdir(parents=True, exist_ok=True)
+        asset.write_bytes(b"public brand asset")
+    archive_path, checksum_path = build_release(source, tmp_path / "output")
+    with zipfile.ZipFile(archive_path) as archive:
+        names = archive.namelist()
+        assert "tgdrive-2.0.0/tgdrive/web/app.py" in names
+        assert "tgdrive-2.0.0/.env.example" in names
+        assert "tgdrive-2.0.0/website/src/app/App.tsx" in names
+        assert "tgdrive-2.0.0/website/package-lock.json" in names
+        assert "tgdrive-2.0.0/website/scripts/patch-movi-player.js" in names
+        for name in brand_assets:
+            assert f"tgdrive-2.0.0/{name}" in names
+        for public_asset in (
+            "docs/backup-recovery.md",
+            "docs/configuration.md",
+            "docs/performance-tuning.md",
+            "docs/assets/README.md",
+            "docs/assets/drive-overview.png",
+            "docs/assets/upload-progress.png",
+            "docs/assets/media-preview.png",
+            "docs/assets/mobile-drive.png",
+            "docs/assets/upload-and-share.mp4",
+            "website/public/third-party/ui-components-LICENSES.txt",
+            "website/public/third-party/README.txt",
+            "website/public/third-party/movi-player-LICENSE.txt",
+            "website/public/third-party/movi-player-TGDrive-patch-NOTICE.txt",
+            "website/public/third-party/movi-player-0.4.1-sources.tar.gz",
+            "website/public/third-party/FFmpeg-LGPL-2.1.txt",
+            "website/public/third-party/pdfjs-LICENSE.txt",
+            "website/public/third-party/pdfjs-TGDrive-patch-NOTICE.txt",
+            "website/vendor/README.md",
+            "website/vendor/manifest.json",
+            "website/vendor/movi-player-0.4.1-tgdrive.1.tgz",
+            "website/vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz",
+            "website/public/third-party/react-LICENSE.txt",
+            "website/public/third-party/react-dom-LICENSE.txt",
+            "website/public/third-party/scheduler-LICENSE.txt",
+            "website/public/third-party/lucide-react-LICENSE.txt",
+            "website/public/third-party/octicons-MIT.txt",
+            "tests/fixtures/multitrack.mkv",
+        ):
+            assert f"tgdrive-2.0.0/{public_asset}" in names
+        for name in private_names:
+            assert f"tgdrive-2.0.0/{name}" not in names
+        assert all(b"PRIVATE-CONTENT" not in archive.read(name) for name in names)
+        manifest = json.loads(archive.read("tgdrive-2.0.0/release-manifest.json"))
+        for name, digest in manifest["files"].items():
+            assert (
+                hashlib.sha256(archive.read(f"tgdrive-2.0.0/{name}")).hexdigest()
+                == digest
+            )
+    assert (
+        checksum_path.read_text().split()[0]
+        == hashlib.sha256(archive_path.read_bytes()).hexdigest()
+    )
+
+
+def test_source_archive_is_reproducible(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    _source_tree(source)
+    first, _ = build_release(source, tmp_path / "first")
+    second, _ = build_release(source, tmp_path / "second")
+    assert first.read_bytes() == second.read_bytes()
+
+
+def test_source_archive_rejects_symlinked_sources(tmp_path: Path) -> None:
+    source = tmp_path / "source"
+    _source_tree(source)
+    outside = tmp_path / "private.py"
+    outside.write_text("private credentials", encoding="utf-8")
+    (source / "tgdrive" / "linked.py").symlink_to(outside)
+    with pytest.raises(ValueError, match="symlink"):
+        build_release(source, tmp_path / "output")
diff --git a/tests/core/test_runtime.py b/tests/core/test_runtime.py
new file mode 100644
index 00000000..d92e7917
--- /dev/null
+++ b/tests/core/test_runtime.py
@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, Mock
+
+import pytest
+
+import tgdrive.core.runtime as runtime_module
+from tgdrive.core.config import Settings
+from tgdrive.core.runtime import Runtime
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.store import DriveStore
+
+
+def settings(tmp_path: Path, **overrides: object) -> Settings:
+    values: dict[str, object] = {
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "API_ID": 12345,
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30,
+        "STORAGE_CHANNEL": -1001234567890,
+        "ADMIN_PASSWORD": "correct horse battery staple",
+        "SESSION_SECRET": "s" * 48,
+        "DATA_DIR": tmp_path / "data",
+        "CACHE_DIR": tmp_path / "cache",
+        "COOKIE_SECURE": False,
+    }
+    values.update(overrides)
+    return Settings(_env_file=None, **values)
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(monkeypatch):
+    """Exercise lifecycle orchestration against an explicit database adapter."""
+    backend = MagicMock()
+    backend.transaction.side_effect = lambda callback: callback(None)
+    backend.db.settings.find_one.return_value = None
+    for name in ("jobs", "receipts", "bot_folders"):
+        getattr(backend.db, name).find.return_value = []
+    monkeypatch.setattr("tgdrive.storage.mongo.for_settings", lambda _: backend)
+    monkeypatch.setattr("tgdrive.storage.mongo.initialize_if_empty", lambda *_: False)
+    monkeypatch.setattr("tgdrive.storage.mongo.record_drive_open", lambda *_: None)
+    monkeypatch.setattr(
+        "tgdrive.replication.replica_activation.apply_activation", lambda *_: None
+    )
+    return backend
+
+
+class FakePool:
+    def __init__(self, *, fail_start: bool = False) -> None:
+        self.fail_start = fail_start
+        self.started = False
+        self.stopped = False
+
+    async def set_uploads_per_bot(self, value: int) -> None:
+        self.uploads_per_bot = value
+
+    async def start(self) -> None:
+        if self.fail_start:
+            raise RuntimeError("bad credentials")
+        self.started = True
+
+    async def stop(self, *, drain_timeout: float | None = None):
+        assert drain_timeout in {10, 20}
+        self.stopped = True
+        return ()
+
+
+class FakeRemote:
+    def __init__(self) -> None:
+        self.closed = False
+
+    async def close(self) -> None:
+        self.closed = True
+
+
+class FakeBackup:
+    def __init__(self, store: DriveStore) -> None:
+        self.store = store
+        self.backups = 0
+        self.started = False
+        self.stopped = False
+
+    async def restore(self) -> DriveStore:
+        return self.store
+
+    async def backup(self, store: DriveStore) -> bool:
+        self.backups += 1
+        revision, _ = store.snapshot()
+        store.mark_backed_up(revision)
+        return True
+
+    def start(self, _store: DriveStore) -> None:
+        self.started = True
+
+    async def stop(self, _store: DriveStore) -> None:
+        self.stopped = True
+
+
+@pytest.mark.asyncio
+async def test_runtime_starts_once_and_stops_components(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    store = DriveStore.create(tmp_path / "drive.json")
+    pool = FakePool()
+    runtime = Runtime(settings(tmp_path), pool=pool)
+    backup = FakeBackup(store)
+    remote = FakeRemote()
+    runtime.backup = backup
+    runtime.remote = remote
+    monkeypatch.setattr(runtime_module, "build_bot_mode_client", lambda _settings: None)
+
+    await runtime.start()
+    await runtime.start()
+
+    assert runtime.ready
+    assert runtime.store is store
+    assert runtime.transfers is not None
+    assert backup.backups == 1
+    assert backup.started
+    assert pool.started
+
+    await runtime.stop()
+    assert not runtime.ready
+    assert backup.stopped
+    assert remote.closed
+    assert pool.stopped
+
+
+@pytest.mark.asyncio
+async def test_telegram_outage_keeps_local_metadata_available(tmp_path: Path) -> None:
+    pool = FakePool(fail_start=True)
+    config = settings(tmp_path)
+    (config.resolved_data_dir / "drive.sqlite3").parent.mkdir(parents=True)
+    store = DriveStore.create(config.resolved_data_dir / "drive.sqlite3")
+    runtime = Runtime(config, pool=pool)
+    runtime.backup = FakeBackup(store)
+    remote = FakeRemote()
+    runtime.remote = remote
+    await runtime.start()
+    assert runtime.ready
+    assert runtime.store is not None
+    assert runtime.store.list_directory("/") == {}
+    await runtime.stop()
+    assert pool.stopped
+    assert remote.closed
+    assert not runtime.ready
+
+
+@pytest.mark.parametrize("failure", ["ping", "acquire", "transaction"])
+async def test_mongodb_failure_rejects_startup_even_with_recovery_state(
+    tmp_path, mongo_backend, failure, caplog
+):
+    getattr(mongo_backend, failure).side_effect = DatabaseUnavailable(
+        "Synthetic MongoDB failure"
+    )
+    pool = FakePool()
+    runtime = Runtime(settings(tmp_path), pool=pool)
+    runtime._activation_unavailable = True
+    restore = AsyncMock()
+    runtime.backup = Mock(restore=restore)
+
+    with pytest.raises(DatabaseUnavailable, match="MongoDB failure"):
+        await runtime.start()
+
+    assert not runtime.ready
+    assert not hasattr(runtime, "replica")
+    restore.assert_not_awaited()
+    assert pool.stopped
+    assert not pool.started
+    assert runtime._owner_lock is None
+    assert "startup rejected" in caplog.text
+    assert "restart the deployment" in caplog.text
+
+
+def test_runtime_rejects_dangerous_cache_root(tmp_path: Path) -> None:
+    root = Path(tmp_path.anchor)
+    runtime = Runtime(settings(tmp_path, CACHE_DIR=root), pool=FakePool())
+
+    with pytest.raises(ValueError, match="CACHE_DIR"):
+        runtime._prepare_runtime_directories()
+
+
+@pytest.mark.parametrize("nested", ["data-in-cache", "cache-in-data", "equal"])
+def test_runtime_rejects_overlapping_storage_before_cleanup(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, nested: str
+) -> None:
+    cache = tmp_path / "cache"
+    data = cache / "uploads" / "metadata"
+    if nested == "cache-in-data":
+        cache, data = data, cache
+    elif nested == "equal":
+        data = cache
+    removed: list[Path] = []
+    monkeypatch.setattr(shutil, "rmtree", lambda path, **_: removed.append(path))
+    runtime = Runtime(
+        settings(tmp_path, CACHE_DIR=cache, DATA_DIR=data), pool=FakePool()
+    )
+
+    with pytest.raises(ValueError, match="overlap"):
+        runtime._prepare_runtime_directories()
+
+    assert removed == []
+    assert not cache.exists()
+    assert not data.exists()
+
+
+def test_runtime_rejects_cleanup_symlink_outside_cache(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    cache = tmp_path / "cache"
+    outside = tmp_path / "outside"
+    cache.mkdir()
+    outside.mkdir()
+    (cache / "uploads").symlink_to(outside, target_is_directory=True)
+    removed: list[Path] = []
+    monkeypatch.setattr(shutil, "rmtree", lambda path, **_: removed.append(path))
+    runtime = Runtime(settings(tmp_path, CACHE_DIR=cache), pool=FakePool())
+
+    with pytest.raises(ValueError, match="cleanup paths"):
+        runtime._prepare_runtime_directories()
+
+    assert removed == []
+    assert outside.exists()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("reconnecting", [False, True])
+async def test_bot_mode_shares_channel_send_pacing_and_flood_cooldown(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, reconnecting: bool
+) -> None:
+    store = DriveStore.create(tmp_path / "drive.json")
+
+    class PacedPool(FakePool):
+        async def pace_send(self, channel: int) -> None:
+            pass
+
+        async def defer_channel(self, deadline: float) -> None:
+            pass
+
+    class BoundClient:
+        gate = None
+        defer = None
+
+        def bind_send_gate(self, gate, defer):
+            self.gate, self.defer = gate, defer
+
+    class Bot:
+        def __init__(self, *, client, **_):
+            self.client = client
+
+        async def start(self):
+            assert self.client.gate == pool.pace_send
+            assert self.client.defer == pool.defer_channel
+
+        async def stop(self):
+            pass
+
+        def close(self):
+            pass
+
+    pool = PacedPool()
+    client = BoundClient()
+    runtime = Runtime(settings(tmp_path), pool=pool)
+    runtime.backup = FakeBackup(store)
+    runtime.remote = FakeRemote()
+    monkeypatch.setattr(runtime_module, "BotMode", Bot)
+    monkeypatch.setattr(
+        runtime_module,
+        "build_bot_mode_client",
+        lambda _: None if reconnecting else client,
+    )
+    try:
+        await runtime.start()
+        if reconnecting:
+            monkeypatch.setattr(
+                runtime_module,
+                "build_bot_mode_client",
+                lambda _: client,
+            )
+            await runtime._reconnect()
+        assert runtime.bot_mode.client is client
+        assert client.gate == pool.pace_send
+        assert client.defer == pool.defer_channel
+    finally:
+        await runtime.stop()
diff --git a/tests/fixtures/movtext-subtitles.mp4 b/tests/fixtures/movtext-subtitles.mp4
new file mode 100644
index 00000000..50de9666
Binary files /dev/null and b/tests/fixtures/movtext-subtitles.mp4 differ
diff --git a/tests/fixtures/multitrack.mkv b/tests/fixtures/multitrack.mkv
new file mode 100644
index 00000000..ca1bcde4
Binary files /dev/null and b/tests/fixtures/multitrack.mkv differ
diff --git a/tests/fixtures/software-mpeg4.wmv b/tests/fixtures/software-mpeg4.wmv
new file mode 100644
index 00000000..bd422368
Binary files /dev/null and b/tests/fixtures/software-mpeg4.wmv differ
diff --git a/tests/fixtures/unsupported-msmpeg4.wmv b/tests/fixtures/unsupported-msmpeg4.wmv
new file mode 100644
index 00000000..745a74ee
Binary files /dev/null and b/tests/fixtures/unsupported-msmpeg4.wmv differ
diff --git a/tests/media/__init__.py b/tests/media/__init__.py
new file mode 100644
index 00000000..502385a0
--- /dev/null
+++ b/tests/media/__init__.py
@@ -0,0 +1 @@
+"""TGDrive media tests."""
diff --git a/tests/media/test_adaptive_read_ahead.py b/tests/media/test_adaptive_read_ahead.py
new file mode 100644
index 00000000..03fade3e
--- /dev/null
+++ b/tests/media/test_adaptive_read_ahead.py
@@ -0,0 +1,221 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from tests.media.test_media_scheduler import wait_until
+from tests.media.test_pooled_media import account
+from tests.media.test_telegram_cache import message
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import (
+    BLOCK,
+    MediaReadCache,
+    _AdaptiveReadAhead,
+    stream_pooled_media,
+)
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+
+
+class Clock:
+    def __init__(self):
+        self.now = 0.0
+
+    def __call__(self):
+        return self.now
+
+    def advance(self, seconds):
+        self.now += seconds
+
+
+def consume(controller, clock, *, blocks_per_second, blocks):
+    for _ in range(blocks):
+        clock.advance(1 / blocks_per_second)
+        controller.consumed(BLOCK)
+
+
+def test_pipeline_grows_for_sustained_fast_delivery_and_shrinks_when_it_slows():
+    clock = Clock()
+    controller = _AdaptiveReadAhead(32, clock=clock)
+    controller.observe_fetch(0.2)
+    assert controller.window == 2
+    consume(controller, clock, blocks_per_second=2, blocks=8)
+    assert controller.window == 2
+    consume(controller, clock, blocks_per_second=128, blocks=256)
+    assert 16 <= controller.window <= 32
+    consume(controller, clock, blocks_per_second=1, blocks=1)
+    assert controller.window == 2
+
+
+def test_source_latency_changes_pipeline_needed_for_the_same_delivery_rate():
+    windows = []
+    for latency in (0.01, 0.5):
+        clock = Clock()
+        controller = _AdaptiveReadAhead(32, clock=clock)
+        controller.observe_fetch(latency)
+        consume(controller, clock, blocks_per_second=8, blocks=24)
+        windows.append(controller.window)
+    assert windows[0] < windows[1] < 32
+
+
+def test_immediate_cache_bursts_cannot_start_an_unproven_large_pipeline():
+    clock = Clock()
+    controller = _AdaptiveReadAhead(32, clock=clock)
+    controller.observe_fetch(1)
+    for _ in range(128):
+        controller.consumed(BLOCK)
+    assert controller.window == 2
+    clock.advance(0.1)
+    controller.consumed(BLOCK)
+    assert controller.window == 4  # One measured sample permits one growth step.
+
+
+def test_tail_bytes_and_new_responses_do_not_inherit_a_full_block_fast_rate():
+    clock = Clock()
+    controller = _AdaptiveReadAhead(32, clock=clock)
+    controller.observe_fetch(0.2)
+    clock.advance(0.2)
+    controller.consumed(17)
+    assert controller.window == 2
+    consume(controller, clock, blocks_per_second=128, blocks=256)
+    assert controller.window > 2
+    assert _AdaptiveReadAhead(32, clock=clock).window == 2
+    assert _AdaptiveReadAhead(1, clock=clock).window == 1
+
+
+@pytest.mark.asyncio
+async def test_small_range_has_no_remote_reads_outside_its_aligned_span(tmp_path):
+    payload = b"".join(bytes([index]) * BLOCK for index in range(8))
+    client = account("bot", payload)
+    calls = []
+
+    async def remote(_source, *, offset, limit, **_kwargs):
+        calls.append(offset)
+        assert limit == 1
+        yield payload[offset * BLOCK : (offset + 1) * BLOCK]
+
+    client.stream_media = remote
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    source = await client.get_messages(1, message_ids=77)
+    iterator = stream_pooled_media(pool, client, source, channel=1, offset=5, limit=2)
+    try:
+        assert (
+            b"".join([data async for data in iterator])
+            == payload[5 * BLOCK : 7 * BLOCK]
+        )
+        assert sorted(calls) == [5, 6]
+        assert pool._media_read_cache.scratch.used == 0
+    finally:
+        await iterator.aclose()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_paused_consumer_drops_ahead_and_disconnect_keeps_only_owned_head(
+    tmp_path, monkeypatch
+):
+    payload = b"x" * (16 * BLOCK)
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    cache = pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=0,
+            disk_max_bytes=0,
+            scratch_max_bytes=4 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+    # Exercise the timer without a one-second real wait; its action must never
+    # reclaim the already-yielded head or leave detached I/O on disconnect.
+    monkeypatch.setattr(
+        _AdaptiveReadAhead, "idle_seconds", property(lambda _self: 0.01)
+    )
+    await pool.start()
+    source = await client.get_messages(1, message_ids=77)
+    iterator = stream_pooled_media(pool, client, source, channel=1, offset=0, limit=16)
+    try:
+        assert await anext(iterator) == payload[:BLOCK]
+        assert cache.scratch.used == 2
+        await wait_until(lambda: cache.scratch.used == 1)
+        assert cache._active_streams == 1
+        assert await anext(iterator) == payload[BLOCK : 2 * BLOCK]
+        await iterator.aclose()
+        assert cache.scratch.used == cache._active_streams == 0
+        assert not cache.memory.flights
+        await asyncio.sleep(0.02)
+        assert cache.scratch.used == 0
+    finally:
+        await iterator.aclose()
+        await cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_actual_reader_ramps_then_shares_scratch_and_reduces_slow_pipeline(
+    tmp_path, monkeypatch
+):
+    clock = Clock()
+
+    class ClockedReadAhead(_AdaptiveReadAhead):
+        def __init__(self, maximum):
+            super().__init__(maximum, clock=clock)
+
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._AdaptiveReadAhead", ClockedReadAhead
+    )
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    client = account("bot", b"x")
+    payload = b"x" * BLOCK
+
+    async def remote(_source, *, offset, limit, **_kwargs):
+        assert 0 <= offset < 128 and limit == 1
+        yield payload
+
+    client.stream_media = remote
+    pool = ClientPool([client], media_cache_dir=tmp_path, media_per_bot=16)
+    cache = pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=0,
+            disk_max_bytes=0,
+            scratch_max_bytes=32 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+    await pool.start()
+    source = TelegramMessage(client, message(1, 128 * BLOCK))
+    fast = stream_pooled_media(pool, client, source, channel=1, offset=0, limit=128)
+    seek = stream_pooled_media(pool, client, source, channel=1, offset=127, limit=1)
+    try:
+        assert await anext(fast) == payload
+        assert cache.scratch.used == 2
+        for _ in range(85):
+            clock.advance(0.005)
+            assert await anext(fast) == payload
+        assert cache.scratch.used == 32
+        assert await asyncio.wait_for(anext(seek), 2) == payload
+        assert cache.scratch.used == cache.scratch.peak == 32
+        clock.advance(0.005)
+        assert await anext(fast) == payload
+        # The advanced reader trims to its fair share while another response
+        # owns a head, even though its rate still supports the maximum window.
+        # In-flight reads keep their reservations until cancellation cleanup.
+        await wait_until(lambda: cache.scratch.used <= 17)
+        assert cache.scratch.used <= 17
+        await seek.aclose()
+        clock.advance(1)
+        assert await anext(fast) == payload
+        await wait_until(lambda: cache.scratch.used <= 3)
+        assert cache.scratch.used <= 3
+    finally:
+        await seek.aclose()
+        await fast.aclose()
+        assert cache.scratch.used == cache._active_streams == 0
+        assert not cache.memory.flights
+        await cache.close()
+        await pool.stop()
diff --git a/tests/media/test_book_range_admission.py b/tests/media/test_book_range_admission.py
new file mode 100644
index 00000000..3eee9190
--- /dev/null
+++ b/tests/media/test_book_range_admission.py
@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tests.media.test_pooled_media import account
+from tgdrive.media.books import read_range
+from tgdrive.media.media_reader import BLOCK
+from tgdrive.media.media_scheduler import effective_priority, media_priority
+from tgdrive.media.previews import lease_media
+from tgdrive.telegram.client_pool import ClientPool
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("background", [False, True])
+async def test_cold_book_range_uses_single_account_slot_without_nested_reservation(
+    tmp_path, background
+):
+    payload = b"a" * BLOCK + b"book tail"
+    client = account("only-bot", payload)
+    metadata = client.get_messages.side_effect
+    priorities = []
+
+    def fetch(*args, **kwargs):
+        priorities.append(effective_priority(media_priority.get()))
+        return metadata(*args, **kwargs)
+
+    client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool([client], media_per_bot=1, media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        result = await asyncio.wait_for(
+            read_range(
+                pool,
+                -1000000000123,
+                {"message_id": 77, "size": len(payload)},
+                11,
+                len(payload) - 11,
+                AsyncMock(),
+                background=background,
+            ),
+            2,
+        )
+        assert result == payload[11:]
+        assert priorities == ["preload" if background else "demand"]
+        assert media_priority.get() == "demand"
+        assert client.native.requests and client.native.peak == 1
+        assert not pool._origin_waiters and not pool._origin_active
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "error", [OSError("metadata failed"), asyncio.CancelledError()]
+)
+async def test_background_metadata_failure_releases_lease_and_priority(error):
+    client = account("only-bot", b"book")
+
+    async def fail(*_args, **_kwargs):
+        assert effective_priority(media_priority.get()) == "preload"
+        raise error
+
+    client.get_messages = AsyncMock(side_effect=fail)
+    pool = ClientPool([client], media_per_bot=1)
+    await pool.start()
+    try:
+        with pytest.raises(type(error)):
+            async with lease_media(pool, -1000000000123, 77, background=True):
+                pytest.fail("Failed metadata cannot yield a media lease")
+        assert media_priority.get() == "demand"
+        assert not pool._origin_waiters and not pool._origin_active
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        await pool.stop()
diff --git a/tests/media/test_books.py b/tests/media/test_books.py
new file mode 100644
index 00000000..f281a2a4
--- /dev/null
+++ b/tests/media/test_books.py
@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import base64
+import io
+import struct
+import zlib
+from zipfile import ZIP_DEFLATED, ZipFile
+
+import pytest
+from fastapi import HTTPException
+
+from tests.support.book_samples import cbr, cbz, epub, png
+from tgdrive.media.book_worker import BookError, ChapterParser, RemoteFile, read_book
+from tgdrive.media.books import parse_book
+
+
+def source(data):
+    requests = []
+
+    def fetch(start, size):
+        requests.append((start, size))
+        return data[start : start + size]
+
+    return RemoteFile(len(data), fetch), requests
+
+
+RASTER_HEADERS = [
+    ("png", ".png", "image/png"),
+    ("jpeg", ".jpg", "image/jpeg"),
+    ("jpeg-progressive", ".jpg", "image/jpeg"),
+    ("gif", ".gif", "image/gif"),
+    ("webp-lossy", ".webp", "image/webp"),
+    ("webp-lossless", ".webp", "image/webp"),
+    ("webp-extended", ".webp", "image/webp"),
+    ("avif", ".avif", "image/avif"),
+    ("avif-sequence", ".avif", "image/avif"),
+]
+
+
+def raster_header(kind, width, height):
+    """Authored format headers; fixtures are never passed to an image decoder."""
+    if kind == "png":
+        content = bytearray(png())
+        struct.pack_into(">II", content, 16, width, height)
+        struct.pack_into(">I", content, 29, zlib.crc32(content[12:29]))
+        return bytes(content)
+    if kind.startswith("jpeg"):
+        frame = b"\x08" + struct.pack(">HHB", height, width, 1) + b"\x01\x11\x00"
+        marker = b"\xff\xc2" if kind.endswith("progressive") else b"\xff\xc0"
+        return (
+            b"\xff\xd8\xff\xe1\x00\x06meta"
+            + marker
+            + struct.pack(">H", len(frame) + 2)
+            + frame
+            + b"\xff\xd9"
+        )
+    if kind == "gif":
+        return (
+            b"GIF89a"
+            + struct.pack("<HH", width, height)
+            + b"\x00\x00\x00\x2c"
+            + struct.pack("<HHHHB", 0, 0, width, height, 0)
+            + b"\x02\x02\x44\x01\x00\x3b"
+        )
+    if kind.startswith("webp"):
+        if kind.endswith("lossless"):
+            tag = b"VP8L"
+            content = b"\x2f" + struct.pack("<I", (height - 1) << 14 | (width - 1))
+        elif kind.endswith("extended"):
+            tag = b"VP8X"
+            content = (
+                b"\x00" * 4
+                + (width - 1).to_bytes(3, "little")
+                + (height - 1).to_bytes(3, "little")
+            )
+        else:
+            tag = b"VP8 "
+            content = b"\x00\x00\x00\x9d\x01\x2a" + struct.pack("<HH", width, height)
+        chunk = tag + struct.pack("<I", len(content)) + content
+        chunk += b"\x00" * (len(content) & 1)
+        return b"RIFF" + struct.pack("<I", len(chunk) + 4) + b"WEBP" + chunk
+
+    def box(tag, content):
+        return struct.pack(">I4s", len(content) + 8, tag) + content
+
+    if kind == "avif":
+        content = box(b"ispe", b"\x00" * 4 + struct.pack(">II", width, height))
+        content = box(b"meta", b"\x00" * 4 + box(b"iprp", box(b"ipco", content)))
+        return box(b"ftyp", b"avif\x00\x00\x00\x00mif1") + content
+    if kind == "avif-sequence":
+        entry = bytearray(78)
+        struct.pack_into(">HH", entry, 24, width, height)
+        content = box(
+            b"stsd", b"\x00\x00\x00\x00\x00\x00\x00\x01" + box(b"av01", entry)
+        )
+        for tag in (b"stbl", b"minf", b"mdia", b"trak", b"moov"):
+            content = box(tag, content)
+        return box(b"ftyp", b"avis\x00\x00\x00\x00msf1") + content
+    raise AssertionError(kind)
+
+
+def book_page(content, suffix):
+    output = io.BytesIO()
+    with ZipFile(output, "w") as archive:
+        archive.writestr("page" + suffix, content)
+    return output.getvalue()
+
+
+@pytest.mark.parametrize("kind,suffix,mime", RASTER_HEADERS)
+@pytest.mark.parametrize("raw_images", [False, True])
+def test_bounded_raster_headers_preserve_original_bytes(kind, suffix, mime, raw_images):
+    image = raster_header(kind, 4000, 4000)
+    data = book_page(image, suffix)
+    result = read_book(source(data)[0], "cbz", "page" + suffix, raw_images=raw_images)
+    assert result["mime"] == mime
+    assert (
+        result["content"] if raw_images else base64.b64decode(result["data"])
+    ) == image
+
+
+@pytest.mark.parametrize("kind,suffix,_mime", RASTER_HEADERS)
+def test_compressed_page_dimensions_are_bounded_before_delivery(kind, suffix, _mime):
+    data = book_page(raster_header(kind, 4001, 4000), suffix)
+    with pytest.raises(BookError, match=r"16 million pixel.*Download"):
+        read_book(source(data)[0], "cbz", "page" + suffix, raw_images=True)
+
+
+@pytest.mark.parametrize("kind,suffix,_mime", RASTER_HEADERS)
+def test_truncated_raster_headers_are_rejected(kind, suffix, _mime):
+    image = raster_header(kind, 48, 72)
+    image = image[:10] if kind.startswith("jpeg") else image[:-1]
+    with pytest.raises(BookError, match=r"invalid or overly complex.*Download"):
+        read_book(source(book_page(image, suffix))[0], "cbz", "page" + suffix)
+
+
+@pytest.mark.parametrize("width,height", [(0, 720), (480, 0), (32769, 1)])
+def test_impossible_or_extreme_page_edges_are_rejected(width, height):
+    data = book_page(raster_header("png", width, height), ".png")
+    with pytest.raises(BookError, match=r"dimensions|32768-pixel edge"):
+        read_book(source(data)[0], "epub", "page.png", raw_images=True)
+
+
+def test_jpeg_standalone_tem_marker_preserves_original_bytes():
+    image = raster_header("jpeg", 480, 720)
+    image = image[:2] + b"\xff\x01" + image[2:]
+    data = book_page(image, ".jpg")
+    result = read_book(source(data)[0], "cbz", "page.jpg", raw_images=True)
+    assert result["mime"] == "image/jpeg"
+    assert result["content"] == image
+
+
+@pytest.mark.parametrize(
+    "kind,suffix", [("png", ".png"), ("gif", ".gif"), ("webp", ".webp")]
+)
+def test_small_canvas_cannot_hide_an_oversized_frame(kind, suffix):
+    if kind == "png":
+        image = raster_header("png", 480, 720)
+        frame = struct.pack(">IIIIIHHBB", 0, 4001, 4000, 0, 0, 1, 10, 0, 0)
+        chunk = (
+            struct.pack(">I", len(frame))
+            + b"fcTL"
+            + frame
+            + struct.pack(">I", zlib.crc32(b"fcTL" + frame))
+        )
+        image = image[:33] + chunk + image[33:]
+    elif kind == "gif":
+        image = bytearray(raster_header("gif", 48, 72))
+        struct.pack_into("<HH", image, 18, 4001, 4000)
+        image = bytes(image)
+    else:
+        image = bytearray(raster_header("webp-extended", 48, 72))
+        image += raster_header("webp-lossless", 4001, 4000)[12:]
+        struct.pack_into("<I", image, 4, len(image) - 8)
+        image = bytes(image)
+    with pytest.raises(BookError, match="16 million pixel"):
+        read_book(source(book_page(image, suffix))[0], "cbz", "page" + suffix)
+
+
+@pytest.mark.parametrize("raw_images", [False, True])
+async def test_worker_reports_pixel_limit_without_emitting_image(raw_images):
+    data = book_page(raster_header("png", 4001, 4000), ".png")
+
+    async def fetch(start, count):
+        return data[start : start + count]
+
+    with pytest.raises(HTTPException, match="16 million pixel") as error:
+        await parse_book(
+            {"name": "oversized.cbz", "size": len(data)},
+            fetch,
+            "page.png",
+            raw_images=raw_images,
+        )
+    assert error.value.status_code == 422
+
+
+def test_epub_index_and_selected_chapter_do_not_download_unused_payload():
+    data = epub(padding=12 * 1024**2, unsafe=True)
+    stream, requests = source(data)
+    index = read_book(stream, "epub")
+    assert index["title"] == "The little journey"
+    assert [entry["label"] for entry in index["entries"]] == [
+        "A quiet morning",
+        "Across the city",
+    ]
+    chapter = read_book(stream, "epub", index["entries"][0]["name"])
+    text = str(chapter)
+    assert "The station was quiet" in text
+    assert "bookExecuted" not in text and "external.invalid" not in text
+    assert "javascript:" not in text
+    assert sum(count for _, count in requests) < len(data) / 2
+
+
+def test_cbz_natural_page_order_and_one_resource():
+    data = cbz(padding=12 * 1024**2)
+    stream, requests = source(data)
+    index = read_book(stream, "cbz")
+    assert [entry["name"] for entry in index["entries"]] == [
+        "pages/1.png",
+        "pages/2.png",
+        "pages/10.png",
+    ]
+    page = read_book(stream, "cbz", "pages/2.png")
+    assert base64.b64decode(page["data"]) == png(2)
+    assert page["mime"] == "image/png"
+    assert sum(count for _, count in requests) < 4 * 1024**2
+
+
+def test_cbr_real_rar_archive_and_page():
+    try:
+        import libarchive  # noqa: F401
+    except ImportError, OSError, AttributeError:
+        pytest.skip("Install libarchive for the native CBR test")
+    stream, _ = source(cbr())
+    index = read_book(stream, "cbr")
+    assert [entry["name"] for entry in index["entries"]] == ["1.png", "2.png"]
+    page = read_book(stream, "cbr", "1.png")
+    assert base64.b64decode(page["data"]) == png(1)
+
+
+@pytest.mark.parametrize(
+    "name", ["../page.png", "/page.png", "a/../page.png", "a\\page.png"]
+)
+def test_archive_paths_are_rejected(name):
+    output = io.BytesIO()
+    with ZipFile(output, "w") as archive:
+        archive.writestr(name, png())
+    with pytest.raises(BookError, match="path"):
+        read_book(source(output.getvalue())[0], "cbz")
+
+
+def test_zip_bomb_and_duplicate_resources_are_rejected():
+    output = io.BytesIO()
+    with ZipFile(output, "w", ZIP_DEFLATED) as archive:
+        archive.writestr("page.png", b"x" * (17 * 1024**2))
+    with pytest.raises(BookError, match="16 MiB"):
+        read_book(source(output.getvalue())[0], "cbz", "page.png")
+    output = io.BytesIO()
+    with ZipFile(output, "w") as archive:
+        archive.writestr("page.png", png())
+        with pytest.warns(UserWarning):
+            archive.writestr("page.png", png(2))
+    with pytest.raises(BookError, match="Duplicate"):
+        read_book(source(output.getvalue())[0], "cbz")
+
+
+def test_chapter_parser_drops_active_content_and_external_resources():
+    parser = ChapterParser("OPS/chapter.xhtml")
+    parser.feed(
+        '<p id="start" onclick="alert(1)">Hello <em>reader</em></p>'
+        "<style>body{display:none}</style><script>alert(1)</script>"
+        '<img src="//external.invalid/x"/><a '
+        'href="../next.xhtml#x">Next</a>'
+    )
+    text = str(parser.root)
+    assert "onclick" not in text and "alert" not in text and "external" not in text
+    assert "next.xhtml#x" in text and "reader" in text
+
+
+async def test_real_isolated_worker_protocol_and_fetch_bounds():
+    data = cbz(padding=8 * 1024**2)
+    reads = []
+
+    async def fetch(start, count):
+        reads.append((start, count))
+        return data[start : start + count]
+
+    index = await parse_book({"name": "comic.cbz", "size": len(data)}, fetch)
+    assert len(index["entries"]) == 3
+    assert sum(n for _, n in reads) < len(data) / 2
+
+    async def broken(_start, count):
+        return b"x" * count
+
+    with pytest.raises(HTTPException) as error:
+        await parse_book({"name": "broken.epub", "size": 100}, broken)
+    assert error.value.status_code == 422
+
+
+async def test_large_selected_page_keeps_original_bytes_without_reading_whole_archive():
+    from tgdrive.media.book_worker import BLOCK
+
+    image = png() + b"p" * (39 * BLOCK)
+    output = io.BytesIO()
+    with ZipFile(output, "w") as archive:
+        archive.writestr("unused.bin", b"x" * (48 * BLOCK))
+        archive.writestr("page.png", image)
+    data = output.getvalue()
+    reads = []
+
+    async def fetch(start, count):
+        reads.append((start, count))
+        return data[start : start + count]
+
+    result = await parse_book(
+        {"name": "large.cbz", "size": len(data)}, fetch, "page.png", raw_images=True
+    )
+    assert result["content"] == image
+    assert "data" not in result
+    assert sum(count for _, count in reads) < 43 * BLOCK
+    assert all(count <= BLOCK for _, count in reads)
+
+
+def test_selected_image_limit_does_not_expand_text_or_legacy_thumbnail_limits():
+    from tgdrive.media.book_worker import BLOCK, MAX_PAGE_READ
+
+    image = png() + b"p" * (17 * BLOCK)
+    output = io.BytesIO()
+    with ZipFile(output, "w") as archive:
+        archive.writestr("page.png", image)
+        archive.writestr("chapter.xhtml", b"x" * (3 * BLOCK))
+    data = output.getvalue()
+
+    def stream():
+        return RemoteFile(
+            len(data),
+            lambda start, count: data[start : start + count],
+            maximum=MAX_PAGE_READ,
+        )
+
+    with pytest.raises(BookError, match="16 MiB"):
+        read_book(stream(), "cbz", "page.png")
+    with pytest.raises(BookError, match="2 MiB"):
+        read_book(stream(), "epub", "chapter.xhtml", raw_images=True)
+
+
+async def test_book_cache_bounds_expiry_and_same_page_waiters(monkeypatch):
+    import asyncio
+
+    import tgdrive.media.books as books
+
+    clock = [100]
+    monkeypatch.setattr(books.time, "monotonic", lambda: clock[0])
+    cache = books.BookCache(maximum=8, entries=2, ttl=5)
+
+    def result(content):
+        return {"kind": "image", "mime": "image/png", "content": content}
+
+    cache.put("a", result(b"12345"))
+    cache.put("b", result(b"6789"))
+    assert cache.get("a") is None and cache.bytes == 4
+    clock[0] += 6
+    assert cache.get("b") is None and cache.bytes == 0
+    calls = []
+
+    async def request():
+        async with cache.hold("shared"):
+            value = cache.get("shared")
+            if value is None:
+                calls.append(1)
+                await asyncio.sleep(0)
+                value = cache.put("shared", result(b"page"))
+            return value[0]
+
+    assert await asyncio.gather(request(), request()) == [b"page", b"page"]
+    assert len(calls) == 1 and not cache.locks
diff --git a/tests/media/test_books_api.py b/tests/media/test_books_api.py
new file mode 100644
index 00000000..6f620800
--- /dev/null
+++ b/tests/media/test_books_api.py
@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import pytest
+
+import tests.support.app_fixtures as fixtures
+from tests.support.book_samples import cbz, epub
+
+app_client = fixtures.app_client
+
+
+def test_book_owner_share_revocation_and_passive_resources(app_client, monkeypatch):
+    client, store, _, _ = app_client
+    content = epub(unsafe=True)
+    file = store.add_file("/", "book.epub", 250, len(content))
+    path = "/" + file["id"]
+    reads = []
+
+    async def fetch(_pool, _channel, data, start, count, authorize):
+        await authorize()
+        reads.append((start, count))
+        return content[start : start + count]
+
+    monkeypatch.setattr("tgdrive.media.books.read_range", fetch)
+    assert client.get("/api/v1/books", params={"path": path}).status_code == 403
+    assert reads == []
+    fixtures.login(client)
+    index = client.get("/api/v1/books", params={"path": path})
+    assert index.status_code == 200 and index.json()["kind"] == "epub"
+    first = store.create_share(path)
+    second = store.create_share(path)
+    chapter = client.get(
+        "/api/v1/books", params={"path": path, "auth": first, "entry": "OPS/one.xhtml"}
+    )
+    assert chapter.status_code == 200
+    assert "bookExecuted" not in chapter.text and "external.invalid" not in chapter.text
+    image = client.get(
+        "/api/v1/books",
+        params={"path": path, "auth": second, "entry": "OPS/images/page.png"},
+    )
+    assert image.status_code == 200 and image.headers["content-type"] == "image/png"
+    assert image.headers["cache-control"] == "private, no-cache"
+    row = store.list_shares(path)[0]
+    store.revoke_share(row["id"])
+    assert (
+        client.get("/api/v1/books", params={"path": path, "auth": first}).status_code
+        == 403
+    )
+    assert (
+        client.get("/api/v1/books", params={"path": path, "auth": second}).status_code
+        == 200
+    )
+    store.set_trashed(path, True)
+    assert (
+        client.get("/api/v1/books", params={"path": path, "auth": second}).status_code
+        == 403
+    )
+
+
+def test_book_revoked_during_fetch_cannot_return_cached_or_parsed_data(
+    app_client, monkeypatch
+):
+    client, store, _, _ = app_client
+    content = cbz()
+    file = store.add_file("/", "comic.cbz", 251, len(content))
+    path = "/" + file["id"]
+    token = store.create_share(path)
+
+    async def fetch(_pool, _channel, data, start, count, authorize):
+        store.revoke_share(path)
+        return content[start : start + count]
+
+    monkeypatch.setattr("tgdrive.media.books.read_range", fetch)
+    response = client.get("/api/v1/books", params={"path": path, "auth": token})
+    assert response.status_code == 403
+
+
+@pytest.mark.parametrize("entry", ["../secret", "/etc/passwd", "missing.xhtml"])
+def test_book_resource_requests_are_bounded(app_client, monkeypatch, entry):
+    client, store, _, _ = app_client
+    content = epub()
+    file = store.add_file("/", "book.epub", 252, len(content))
+    path = "/" + file["id"]
+
+    async def fetch(_pool, _channel, data, start, count, authorize):
+        return content[start : start + count]
+
+    monkeypatch.setattr("tgdrive.media.books.read_range", fetch)
+    fixtures.login(client)
+    assert (
+        client.get("/api/v1/books", params={"path": path, "entry": entry}).status_code
+        == 422
+    )
+
+
+def test_cached_book_bytes_and_conditional_responses_still_require_access(
+    app_client, monkeypatch
+):
+    client, store, _, _ = app_client
+    content = cbz()
+    file = store.add_file("/", "cached.cbz", 253, len(content))
+    path = "/" + file["id"]
+    share = store.create_share(path)
+    reads = []
+
+    async def fetch(_pool, _channel, data, start, count, authorize):
+        await authorize()
+        reads.append((start, count))
+        return content[start : start + count]
+
+    monkeypatch.setattr("tgdrive.media.books.read_range", fetch)
+    params = {"path": path, "auth": share, "entry": "pages/2.png"}
+    first = client.get("/api/v1/books", params=params)
+    assert first.status_code == 200
+    before = len(reads)
+    second = client.get("/api/v1/books", params=params)
+    assert second.content == first.content and len(reads) == before
+    conditional = client.get(
+        "/api/v1/books", params=params, headers={"If-None-Match": first.headers["etag"]}
+    )
+    assert (
+        conditional.status_code == 304
+        and not conditional.content
+        and len(reads) == before
+    )
+    store.revoke_share(path)
+    assert (
+        client.get(
+            "/api/v1/books",
+            params=params,
+            headers={"If-None-Match": first.headers["etag"]},
+        ).status_code
+        == 403
+    )
diff --git a/tests/media/test_cache_policy.py b/tests/media/test_cache_policy.py
new file mode 100644
index 00000000..30e01c1e
--- /dev/null
+++ b/tests/media/test_cache_policy.py
@@ -0,0 +1,494 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import threading
+from types import SimpleNamespace
+
+import pytest
+
+from tgdrive.media.media_cache import DiskMediaCache
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import BLOCK, MediaReadCache, _PayloadCache
+
+CHANNEL = -1000000000123
+
+
+def key(index=0, size=3 * BLOCK, message=77):
+    return (CHANNEL, message, "document", message + 100, size, index)
+
+
+@pytest.mark.asyncio
+async def test_download_during_inventory_write_is_persisted_before_close(
+    tmp_path, monkeypatch
+):
+    cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(memory_max_bytes=8 * BLOCK, min_free_bytes=0),
+    )
+    first = cache.register_file(channel_id=CHANNEL, message_id=77, size=3, name="First")
+    second = cache.register_file(
+        channel_id=CHANNEL, message_id=88, size=3, name="Second"
+    )
+    started, release = threading.Event(), threading.Event()
+    original = cache._write_index
+    writes = 0
+
+    def delayed_write(value):
+        nonlocal writes
+        writes += 1
+        if writes == 1:
+            # Freeze the state as a real writer can do before a later download
+            # changes the cache while the disk operation is still in progress.
+            value = json.loads(json.dumps(value))
+            started.set()
+            assert release.wait(5)
+        original(value)
+
+    monkeypatch.setattr(cache, "_write_index", delayed_write)
+    try:
+        await cache.get(key(size=3), 3, lambda: asyncio.sleep(0, result=b"one"))
+        assert await asyncio.to_thread(started.wait, 2)
+        await cache.get(
+            key(size=3, message=88), 3, lambda: asyncio.sleep(0, result=b"two")
+        )
+        release.set()
+        await cache.close()
+        cache = MediaReadCache(tmp_path, cache.policy)
+        files = {row["id"]: row for row in (await cache.snapshot())["files"]}
+        assert set(files) == {first, second}
+        assert all(row["complete"] for row in files.values())
+        assert files[first]["name"] == "First"
+        assert files[second]["name"] == "Second"
+    finally:
+        release.set()
+        await cache.close()
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        {"disk_max_bytes": -1},
+        {"memory_max_bytes": True},
+        {"ttl_seconds": float("nan")},
+        {"max_background_jobs": 0},
+        {"max_file_fraction": 0},
+        {"protected_fraction": 1},
+    ],
+)
+def test_policy_rejects_invalid_capacity(change):
+    with pytest.raises(ValueError):
+        MediaCachePolicy(**change)
+
+
+def test_disk_protects_reused_blocks_from_sequential_scan(tmp_path):
+    cache = DiskMediaCache(tmp_path, max_bytes=5 * 132)
+    for index in range(3):
+        cache.write((index,), bytes([index]) * 100)
+        assert cache.read((index,), 100) is not None
+    for index in range(3, 40):
+        cache.write((index,), bytes([index]) * 100)
+    assert all(cache.read((index,), 100) == bytes([index]) * 100 for index in range(3))
+    assert cache.snapshot()["bytes"] <= 5 * 132
+
+
+def test_disk_entry_bound_scales_and_restart_does_not_evict_at_exact_limit(tmp_path):
+    cache = DiskMediaCache(tmp_path, max_bytes=2 * 1024**3)
+    assert cache.max_entries > 2048
+    cache = DiskMediaCache(tmp_path, max_bytes=100, max_entries=2)
+    cache.write((1,), b"one")
+    cache.write((2,), b"two")
+    restarted = DiskMediaCache(tmp_path, max_bytes=100, max_entries=2)
+    assert restarted.read((1,), 3) == b"one"
+    assert restarted.read((2,), 3) == b"two"
+
+
+def test_disk_reserves_free_space_and_never_recursively_removes_other_files(
+    tmp_path, monkeypatch
+):
+    sentinel = tmp_path / "upload.pending"
+    sentinel.write_text("keep")
+    cache = DiskMediaCache(tmp_path, max_bytes=4096, min_free_bytes=1024)
+    monkeypatch.setattr(
+        "tgdrive.media.media_cache.shutil.disk_usage",
+        lambda _: SimpleNamespace(free=100),
+    )
+    assert cache.write((1,), b"payload") is False
+    cache.clear()
+    assert sentinel.read_text() == "keep"
+
+
+def test_memory_protected_segment_survives_scan():
+    cache = _PayloadCache(max_bytes=500, max_entries=100, ttl=60, read_slots=2)
+    for index in range(3):
+        cache._put((index,), bytes([index]) * 100)
+        cache._hit((index,))
+    for index in range(3, 40):
+        cache._put((index,), bytes([index]) * 100)
+    assert all(cache._hit((index,)) is not None for index in range(3))
+    assert cache.bytes_used <= 500
+
+
+@pytest.mark.asyncio
+async def test_disk_write_is_deferred_and_included_in_memory_budget(
+    tmp_path, monkeypatch
+):
+    cache = MediaReadCache(
+        tmp_path, MediaCachePolicy(memory_max_bytes=8 * BLOCK, min_free_bytes=0)
+    )
+    started, release = threading.Event(), threading.Event()
+    original = cache.disk.write
+
+    def slow_write(*args):
+        started.set()
+        release.wait(5)
+        return original(*args)
+
+    monkeypatch.setattr(cache.disk, "write", slow_write)
+    try:
+        payload = b"x" * BLOCK
+        assert (
+            await asyncio.wait_for(
+                cache.get(
+                    key(size=BLOCK), BLOCK, lambda: asyncio.sleep(0, result=payload)
+                ),
+                1,
+            )
+            == payload
+        )
+        await asyncio.to_thread(started.wait, 1)
+        assert cache._pending_bytes == BLOCK
+        assert (
+            cache.memory.bytes_used + cache._pending_bytes
+            <= cache.effective_memory_bytes
+        )
+    finally:
+        release.set()
+        await cache.close()
+    assert cache.disk.read(key(size=BLOCK), BLOCK) == payload
+
+
+@pytest.mark.asyncio
+async def test_zero_cache_budget_still_serves_remote_without_retaining_bytes(tmp_path):
+    cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(memory_max_bytes=0, disk_max_bytes=0, min_free_bytes=0),
+    )
+    count = 0
+
+    async def remote():
+        nonlocal count
+        count += 1
+        return b"abc"
+
+    try:
+        assert await cache.get(key(size=3), 3, remote) == b"abc"
+        assert await cache.get(key(size=3), 3, remote) == b"abc"
+        assert count == 2
+        state = await cache.snapshot()
+        assert state["memory"]["bytes"] == state["disk"]["bytes"] == 0
+        assert state["files"] == []
+    finally:
+        await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_inventory_survives_restart_and_tracks_demand_bytes(tmp_path):
+    policy = MediaCachePolicy(memory_max_bytes=0, disk_max_bytes=4096, min_free_bytes=0)
+    cache = MediaReadCache(tmp_path, policy)
+    file_id = cache.register_file(
+        channel_id=CHANNEL, message_id=77, size=3, name="friend.mp4"
+    )
+    await cache.get(key(size=3), 3, lambda: asyncio.sleep(0, result=b"abc"))
+    await cache.close()
+    restarted = MediaReadCache(tmp_path, policy)
+    try:
+        state = await restarted.snapshot()
+        assert state["files"] == [state["files"][0]]
+        row = state["files"][0]
+        assert row["id"] == file_id and row["name"] == "friend.mp4"
+        assert row["disk_ranges"] == row["ready_ranges"] == [[0, 3]]
+        assert row["complete"] and row["ready_bytes"] == 3
+        assert (tmp_path / "inventory.json").stat().st_mode & 0o777 == 0o600
+    finally:
+        await restarted.close()
+
+
+@pytest.mark.asyncio
+async def test_inventory_exposes_gaps_and_clear_is_per_logical_file(tmp_path):
+    cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=8 * BLOCK, disk_max_bytes=0, min_free_bytes=0
+        ),
+    )
+    first = cache.register_file(
+        channel_id=CHANNEL, message_id=77, size=3 * BLOCK, name="video"
+    )
+    second = cache.register_file(channel_id=CHANNEL, message_id=88, size=3, name="tiny")
+    try:
+        for index in (0, 2):
+            await cache.get(
+                key(index), BLOCK, lambda: asyncio.sleep(0, result=b"x" * BLOCK)
+            )
+        await cache.get(
+            key(size=3, message=88), 3, lambda: asyncio.sleep(0, result=b"abc")
+        )
+        files = {row["id"]: row for row in (await cache.snapshot())["files"]}
+        assert files[first]["ready_ranges"] == [[0, BLOCK], [2 * BLOCK, 3 * BLOCK]]
+        assert not files[first]["complete"]
+        await cache.clear(first)
+        assert [row["id"] for row in (await cache.snapshot())["files"]] == [second]
+    finally:
+        await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_clear_during_inflight_read_does_not_resurrect_payload(tmp_path):
+    cache = MediaReadCache(tmp_path)
+    started, gate = asyncio.Event(), asyncio.Event()
+
+    async def remote():
+        started.set()
+        await gate.wait()
+        return b"abc"
+
+    task = asyncio.create_task(cache.get(key(size=3), 3, remote))
+    await started.wait()
+    await cache.clear()
+    gate.set()
+    assert await task == b"abc"
+    assert not cache.memory.entries
+    assert cache.disk.read(key(size=3), 3) is None
+    await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_reconfigure_shrinks_both_tiers_immediately(tmp_path):
+    cache = MediaReadCache(tmp_path)
+    await cache.get(key(size=3), 3, lambda: asyncio.sleep(0, result=b"abc"))
+    await cache.reconfigure(
+        MediaCachePolicy(memory_max_bytes=0, disk_max_bytes=0, min_free_bytes=0)
+    )
+    state = await cache.snapshot()
+    assert state["memory"]["bytes"] == state["disk"]["bytes"] == 0
+    assert state["files"] == []
+    await cache.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "value", [[], None, {"files": [{"id": "bad", "parts": [{"bogus": True}]}]}]
+)
+async def test_corrupt_inventory_never_breaks_remote_availability(tmp_path, value):
+    (tmp_path / "inventory.json").write_text(json.dumps(value))
+    cache = MediaReadCache(tmp_path)
+    assert (
+        await cache.get(key(size=3), 3, lambda: asyncio.sleep(0, result=b"abc"))
+        == b"abc"
+    )
+    assert len((await cache.snapshot())["files"]) == 1
+    await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_alternate_representations_do_not_combine_ready_ranges(tmp_path):
+    cache = MediaReadCache(tmp_path, MediaCachePolicy(disk_max_bytes=0))
+    cache.register_file(channel_id=CHANNEL, message_id=77, size=2 * BLOCK, name="movie")
+    original = key(size=2 * BLOCK)
+    alternate = list(key(index=1, size=2 * BLOCK))
+    alternate[3] += 1
+    try:
+        await cache.get(original, BLOCK, lambda: asyncio.sleep(0, result=b"a" * BLOCK))
+        await cache.get(
+            tuple(alternate), BLOCK, lambda: asyncio.sleep(0, result=b"b" * BLOCK)
+        )
+        files = (await cache.snapshot())["files"]
+        assert len(files) == 2
+        assert all(not row["complete"] for row in files)
+        assert sorted(row["ready_ranges"] for row in files) == [
+            [[0, BLOCK]],
+            [[BLOCK, 2 * BLOCK]],
+        ]
+    finally:
+        await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_many_waiting_preloads_leave_demand_fill_capacity(tmp_path):
+    cache = MediaReadCache(tmp_path)
+    gate = asyncio.Event()
+    foreground_started = asyncio.Event()
+
+    async def held_foreground():
+        foreground_started.set()
+        await gate.wait()
+        return b"abc"
+
+    foreground = asyncio.create_task(cache.get(key(size=3), 3, held_foreground))
+    await foreground_started.wait()
+    speculative = [
+        asyncio.create_task(
+            cache.get(
+                key(size=3, message=index),
+                3,
+                lambda: asyncio.sleep(0, result=b"xyz"),
+                background=True,
+            )
+        )
+        for index in range(100, 130)
+    ]
+    try:
+        assert (
+            await asyncio.wait_for(
+                cache.get(
+                    key(size=3, message=88), 3, lambda: asyncio.sleep(0, result=b"new")
+                ),
+                1,
+            )
+            == b"new"
+        )
+        gate.set()
+        assert await foreground == b"abc"
+        assert all(value == b"xyz" for value in await asyncio.gather(*speculative))
+    finally:
+        gate.set()
+        await asyncio.gather(foreground, *speculative, return_exceptions=True)
+        await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_inventory_poll_during_queued_fills_preserves_later_readiness(tmp_path):
+    cache = MediaReadCache(tmp_path, MediaCachePolicy(disk_max_bytes=0))
+    gate = asyncio.Event()
+
+    async def remote():
+        await gate.wait()
+        return b"abc"
+
+    tasks = [
+        asyncio.create_task(cache.get(key(size=3, message=index), 3, remote))
+        for index in range(100, 125)
+    ]
+    try:
+        for _ in range(100):
+            if (
+                len(cache.memory.flights) == min(25, cache.scratch.limit)
+                and len(cache._active_keys) == 25
+            ):
+                break
+            await asyncio.sleep(0.001)
+        assert (await cache.snapshot())["files"] == []
+        gate.set()
+        await asyncio.gather(*tasks)
+        assert len((await cache.snapshot())["files"]) == 25
+    finally:
+        gate.set()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_current_availability_refresh_shrinks_and_recovers_retention_and_scratch(
+    tmp_path, monkeypatch
+):
+    available, now = [8 * BLOCK], [0.0]
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory",
+        lambda value: min(value, available[0]),
+    )
+    cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=8 * BLOCK, disk_max_bytes=0, scratch_max_bytes=8 * BLOCK
+        ),
+        clock=lambda: now[0],
+    )
+    try:
+        for index in range(4):
+            await cache.get(
+                key(index, size=4 * BLOCK),
+                BLOCK,
+                lambda: asyncio.sleep(0, result=b"x" * BLOCK),
+            )
+        assert (await cache.snapshot())["memory"]["bytes"] == 4 * BLOCK
+        for _ in range(4):
+            await cache.scratch.acquire()
+        available[0] = 2 * BLOCK
+        now[0] = 4
+        assert (await cache.snapshot())["memory"]["effective_max_bytes"] == 8 * BLOCK
+        now[0] = 5
+        reduced = await cache.snapshot()
+        assert reduced["memory"]["bytes"] <= 2 * BLOCK
+        assert reduced["memory"]["effective_max_bytes"] == 2 * BLOCK
+        assert reduced["memory"]["max_fills"] == 2
+        assert reduced["scratch"]["max_bytes"] == 2 * BLOCK
+        assert reduced["scratch"]["bytes"] == 4 * BLOCK  # Existing frames drain.
+        for _ in range(4):
+            cache.scratch.release()
+        available[0] = 8 * BLOCK
+        now[0] = 10
+        recovered = await cache.snapshot()
+        assert recovered["memory"]["effective_max_bytes"] == 8 * BLOCK
+        assert recovered["memory"]["max_fills"] == 8
+        assert recovered["scratch"]["max_bytes"] == 8 * BLOCK
+        assert recovered["scratch"]["bytes"] == 0
+    finally:
+        await cache.close()
+
+
+async def test_inventory_orders_actual_downloads_not_cache_hits_and_retains_order(
+    tmp_path, monkeypatch
+):
+    cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=8 * BLOCK, disk_max_bytes=8 * BLOCK, min_free_bytes=0
+        ),
+    )
+    clock = [1000.0]
+    monkeypatch.setattr("tgdrive.media.media_reader.time.time", lambda: clock[0])
+    first = cache.register_file(
+        channel_id=CHANNEL, message_id=77, size=2 * BLOCK, name="First"
+    )
+    second = cache.register_file(
+        channel_id=CHANNEL, message_id=88, size=3, name="Second"
+    )
+    try:
+        await cache.get(
+            key(0, 2 * BLOCK), BLOCK, lambda: asyncio.sleep(0, result=b"a" * BLOCK)
+        )
+        clock[0] = 1001.0
+        await cache.get(
+            key(size=3, message=88), 3, lambda: asyncio.sleep(0, result=b"abc")
+        )
+        assert [row["id"] for row in (await cache.snapshot())["files"]] == [
+            second,
+            first,
+        ]
+        clock[0] = 1002.0
+        cache.register_file(
+            channel_id=CHANNEL, message_id=77, size=2 * BLOCK, name="First"
+        )
+        await cache.get(
+            key(0, 2 * BLOCK), BLOCK, lambda: pytest.fail("must reuse cached bytes")
+        )
+        assert [row["id"] for row in (await cache.snapshot())["files"]] == [
+            second,
+            first,
+        ]
+        clock[0] = 1003.0
+        await cache.get(
+            key(1, 2 * BLOCK), BLOCK, lambda: asyncio.sleep(0, result=b"b" * BLOCK)
+        )
+        rows = (await cache.snapshot())["files"]
+        assert [row["id"] for row in rows] == [first, second]
+        assert rows[0]["last_download"] == 1003.0
+        await cache.close()
+        cache = MediaReadCache(tmp_path, cache.policy)
+        assert [row["id"] for row in (await cache.snapshot())["files"]] == [
+            first,
+            second,
+        ]
+    finally:
+        await cache.close()
diff --git a/tests/media/test_cached_http_concurrency.py b/tests/media/test_cached_http_concurrency.py
new file mode 100644
index 00000000..cd1a964d
--- /dev/null
+++ b/tests/media/test_cached_http_concurrency.py
@@ -0,0 +1,524 @@
+from __future__ import annotations
+
+import asyncio
+import socket
+from pathlib import Path
+from unittest.mock import AsyncMock
+
+import httpx2
+import pytest
+import uvicorn
+from fastapi import FastAPI, Request
+from starlette.requests import ClientDisconnect
+
+from tests.media.test_media_scheduler import wait_until
+from tests.media.test_multipart_streaming import build_parts
+from tests.media.test_pooled_media import account
+from tests.media.test_stream_delivery import request
+from tests.media.test_streaming import response_body
+from tests.media.test_telegram_cache import message
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import BLOCK, MediaReadCache
+from tgdrive.media.streaming import stream_telegram_file
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+
+CHANNEL = -1000000000123
+ASGI_SCOPE = {"type": "http", "asgi": {"spec_version": "2.4"}}
+
+
+async def receive():
+    return {"type": "http.disconnect"}
+
+
+async def stream(pool, payload, header=None, *, method="GET", **options):
+    req = request(header, accept_encoding="gzip, br, zstd")
+    req.scope["method"] = method
+    for name, value in options.pop("headers", {}).items():
+        req.scope["headers"].append((name.encode(), value.encode()))
+    return await stream_telegram_file(
+        pool=pool,
+        channel_id=CHANNEL,
+        message_id=77,
+        file_name="movie_टेस्ट.mkv",
+        expected_size=len(payload),
+        request=req,
+        **options,
+    )
+
+
+async def assert_clean(pool):
+    cache = pool._media_read_cache
+    state = await cache.snapshot()
+    assert state["scratch"]["bytes"] == 0
+    assert state["scratch"]["active_streams"] == 0
+    assert state["scratch"]["waiting_heads"] == 0
+    assert state["scratch"]["peak_bytes"] <= 32 * BLOCK
+    assert not cache.memory.flights
+    assert not cache._active_keys
+    assert not cache._foreground
+    assert all(row.active_leases == 0 for row in await pool.status())
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tier", ["ram", "persisted-disk"])
+async def test_fully_cached_http_seeks_tail_and_download_pass_a_stalled_full_response(
+    tier, tmp_path, monkeypatch
+):
+    """ASGI backpressure must not let one viewer pin all speculative frames."""
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    payload = b"".join(bytes([index]) * BLOCK for index in range(40)) + b"exact-tail"
+    clients = [account(str(index), payload) for index in range(3)]
+    policy = MediaCachePolicy(
+        memory_max_bytes=128 * BLOCK if tier == "ram" else 0,
+        disk_max_bytes=128 * BLOCK if tier == "persisted-disk" else 0,
+        min_free_bytes=0,
+        scratch_max_bytes=32 * BLOCK,
+    )
+    pool = ClientPool(clients, media_cache_dir=tmp_path)
+    pool._media_read_cache = MediaReadCache(tmp_path, policy)
+    await pool.start()
+    stalled = None
+    release_send = asyncio.Event()
+    entered_send = asyncio.Event()
+    sent = bytearray()
+    try:
+        initial = await stream(pool, payload)
+        etag = initial.headers["etag"]
+        assert await response_body(initial) == payload
+        await pool._media_read_cache.flush()
+        if tier == "persisted-disk":
+            await pool._media_read_cache.close()
+            pool._media_read_cache = MediaReadCache(tmp_path, policy)
+        cache = pool._media_read_cache
+        ready = (await cache.snapshot())["files"]
+        assert len(ready) == 1 and ready[0]["complete"]
+        reads = sum(sum(client.native.requests.values()) for client in clients)
+
+        head = await stream(pool, payload, method="HEAD")
+        assert head.body == b"" and head.status_code == 200
+        assert head.headers["content-length"] == str(len(payload))
+        assert head.headers["accept-ranges"] == "bytes"
+        assert head.headers["content-encoding"] == "identity"
+        assert cache.scratch.used == 0
+
+        slow = await stream(pool, payload, request_id="stalled-viewer")
+
+        async def slow_send(value):
+            if value["type"] == "http.response.body" and value.get("body"):
+                sent.extend(value["body"])
+                if not entered_send.is_set():
+                    entered_send.set()
+                    await release_send.wait()
+
+        stalled = asyncio.create_task(slow(ASGI_SCOPE, receive, slow_send))
+        await entered_send.wait()
+        # A consumer blocked on its first send must shed speculative frames;
+        # the yielded head remains owned while other requests pass it.
+        await wait_until(lambda: cache.scratch.used == 1)
+        assert not stalled.done()
+
+        selections = [
+            ("bytes=0-0", 0, 1),
+            (
+                f"bytes={31 * BLOCK - 7}-{31 * BLOCK + 8}",
+                31 * BLOCK - 7,
+                31 * BLOCK + 9,
+            ),
+            (
+                f"bytes={35 * BLOCK + 13}-{36 * BLOCK + 22}",
+                35 * BLOCK + 13,
+                36 * BLOCK + 23,
+            ),
+            ("bytes=-257", len(payload) - 257, len(payload)),
+            (f"bytes={39 * BLOCK}-", 39 * BLOCK, len(payload)),
+        ]
+
+        async def selected(header, start, end):
+            result = await stream(
+                pool,
+                payload,
+                header,
+                headers={"if-range": etag},
+                request_id=f"seek-{start}",
+            )
+            assert result.status_code == 206
+            assert (
+                result.headers["content-range"]
+                == f"bytes {start}-{end - 1}/{len(payload)}"
+            )
+            assert result.headers["content-length"] == str(end - start)
+            assert result.headers["content-encoding"] == "identity"
+            assert result.headers["etag"] == etag
+            assert await response_body(result) == payload[start:end]
+
+        async def full_download():
+            result = await stream(
+                pool, payload, download=True, request_id="another-download"
+            )
+            assert result.status_code == 200
+            assert result.headers["content-length"] == str(len(payload))
+            assert result.headers["content-disposition"].startswith("attachment;")
+            assert "filename*=UTF-8''movie_" in result.headers["content-disposition"]
+            assert result.headers["content-encoding"] == "identity"
+            assert await response_body(result) == payload
+
+        # The deadline guards liveness rather than asserting a throughput target.
+        # Every byte is local; a blocked reader has no dependency on the slow send.
+        async with asyncio.timeout(10):
+            await asyncio.gather(
+                *(selected(*selection) for selection in selections), full_download()
+            )
+        assert not stalled.done() and sent == payload[:BLOCK]
+        assert sum(sum(client.native.requests.values()) for client in clients) == reads
+        assert all(row.active_leases == 0 for row in await pool.status())
+
+        release_send.set()
+        await asyncio.wait_for(stalled, 10)
+        assert bytes(sent) == payload
+        assert sum(sum(client.native.requests.values()) for client in clients) == reads
+        await assert_clean(pool)
+    finally:
+        if stalled is not None and not stalled.done():
+            stalled.cancel()
+            await asyncio.gather(stalled, return_exceptions=True)
+        release_send.set()
+        await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_cached_http_disconnect_resumes_exactly_with_strong_validator(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    payload = b"".join(bytes([index]) * BLOCK for index in range(6)) + b"last"
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=16 * BLOCK, disk_max_bytes=0, min_free_bytes=0
+        ),
+    )
+    await pool.start()
+    received = bytearray()
+    try:
+        assert await response_body(await stream(pool, payload)) == payload
+        reads = sum(client.native.requests.values())
+        interrupted = await stream(pool, payload, download=True)
+        etag = interrupted.headers["etag"]
+
+        async def failed_send(value):
+            if value["type"] == "http.response.body" and value.get("body"):
+                if received:
+                    raise OSError("client disconnected")
+                received.extend(value["body"])
+
+        with pytest.raises(ClientDisconnect):
+            await interrupted(ASGI_SCOPE, receive, failed_send)
+        assert received == payload[:BLOCK]
+        await assert_clean(pool)
+
+        resumed = await stream(
+            pool,
+            payload,
+            f"bytes={len(received)}-",
+            headers={"if-range": etag},
+            download=True,
+        )
+        assert resumed.status_code == 206
+        assert resumed.headers["content-length"] == str(len(payload) - len(received))
+        received.extend(await response_body(resumed))
+        assert bytes(received) == payload
+        assert sum(client.native.requests.values()) == reads
+        await assert_clean(pool)
+    finally:
+        await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tier", ["ram", "persisted-disk"])
+async def test_cached_multipart_http_head_boundaries_and_resume_are_byte_exact(
+    tier, tmp_path, monkeypatch
+):
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    contents = [b"a" * BLOCK + b"first-seam", b"b" * BLOCK + b"second-seam", b"tail"]
+    payload = b"".join(contents)
+    parts = build_parts(contents)
+    client = account("bot", b"")
+    client.native.payloads = {
+        9001 + index: content for index, content in enumerate(contents)
+    }
+
+    async def fetch(_channel, *, message_ids):
+        index = message_ids - 101
+        native = message(9001 + index, len(contents[index]))
+        native.id = message_ids
+        return TelegramMessage(client, native)
+
+    client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    policy = MediaCachePolicy(
+        memory_max_bytes=16 * BLOCK if tier == "ram" else 0,
+        disk_max_bytes=16 * BLOCK if tier == "persisted-disk" else 0,
+        min_free_bytes=0,
+    )
+    pool._media_read_cache = MediaReadCache(tmp_path, policy)
+    await pool.start()
+
+    async def get(header=None, *, method="GET", **headers):
+        req = request(header, accept_encoding="gzip", **headers)
+        req.scope["method"] = method
+        return await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=101,
+            file_name="split-movie.mkv",
+            expected_size=len(payload),
+            parts=parts,
+            request=req,
+        )
+
+    try:
+        first = await get()
+        etag = first.headers["etag"]
+        assert await response_body(first) == payload
+        await pool._media_read_cache.flush()
+        if tier == "persisted-disk":
+            await pool._media_read_cache.close()
+            pool._media_read_cache = MediaReadCache(tmp_path, policy)
+        reads = sum(client.native.requests.values())
+        metadata = client.get_messages.call_count
+        head = await get(method="HEAD")
+        assert head.status_code == 200 and head.body == b""
+        assert head.headers["content-length"] == str(len(payload))
+        assert head.headers["etag"] == etag
+        assert (
+            client.get_messages.call_count == metadata + 1
+        )  # Fresh metadata, no payload.
+        assert sum(client.native.requests.values()) == reads
+
+        for boundary in (len(contents[0]), len(contents[0]) + len(contents[1])):
+            start, end = boundary - 3, min(len(payload), boundary + 3)
+            partial = await get(f"bytes={start}-{end - 1}", if_range=etag)
+            assert partial.status_code == 206
+            assert (
+                partial.headers["content-range"]
+                == f"bytes {start}-{end - 1}/{len(payload)}"
+            )
+            assert partial.headers["content-length"] == str(end - start)
+            assert partial.headers["content-encoding"] == "identity"
+            assert await response_body(partial) == payload[start:end]
+        stale = await get("bytes=2-3", if_range='"old-file"')
+        assert stale.status_code == 200
+        assert await response_body(stale) == payload
+        conditional = await get(if_none_match=etag)
+        assert conditional.status_code == 304 and conditional.body == b""
+        invalid = await get(f"bytes={len(payload)}-")
+        assert invalid.status_code == 416
+        assert invalid.headers["content-range"] == f"bytes */{len(payload)}"
+        assert sum(client.native.requests.values()) == reads
+        await assert_clean(pool)
+    finally:
+        await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_tcp_stalled_cached_download_does_not_block_a_different_video(
+    tmp_path, monkeypatch
+):
+    """Exercise Uvicorn/TCP backpressure, not an eagerly collected ASGI client."""
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    binary = b"".join(bytes([index]) * BLOCK for index in range(128))
+    video = (
+        Path(__file__).resolve().parents[1] / "fixtures" / "multitrack.mkv"
+    ).read_bytes()
+    clients = [account(str(index), binary) for index in range(3)]
+    for client in clients:
+        client.native.payloads[2] = video
+
+        def fetch(_channel, *, message_ids, owner=client):
+            identity, payload = (1, binary) if message_ids == 77 else (2, video)
+            native = message(identity, len(payload))
+            native.id = message_ids
+            return TelegramMessage(owner, native)
+
+        client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool(clients, media_cache_dir=tmp_path)
+    pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=256 * BLOCK,
+            disk_max_bytes=0,
+            min_free_bytes=0,
+            scratch_max_bytes=32 * BLOCK,
+        ),
+    )
+    await pool.start()
+    cache = pool._media_read_cache
+    app = FastAPI()
+
+    @app.api_route("/media/{kind}", methods=["GET", "HEAD"])
+    async def media(kind: str, request: Request):
+        is_binary = kind == "binary"
+        return await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=77 if is_binary else 78,
+            file_name="large.bin" if is_binary else "multitrack.mkv",
+            expected_size=len(binary if is_binary else video),
+            download=is_binary,
+            request=request,
+        )
+
+    listener = socket.socket()
+    listener.bind(("127.0.0.1", 0))
+    listener.listen(128)
+    listener.setblocking(False)
+    port = listener.getsockname()[1]
+    server = uvicorn.Server(
+        uvicorn.Config(
+            app, host="127.0.0.1", port=port, log_level="warning", lifespan="off"
+        )
+    )
+    serving = None
+    slow_writer = None
+    try:
+        assert await response_body(await stream(pool, binary)) == binary
+        warm_video = await media("video", request())
+        assert await response_body(warm_video) == video
+        reads = sum(sum(client.native.requests.values()) for client in clients)
+        serving = asyncio.create_task(server.serve(sockets=[listener]))
+        await wait_until(lambda: server.started)
+        # StreamReader pauses socket reads at a small bounded buffer. The 128MiB
+        # response quickly exceeds TCP/ASGI buffers and suspends its body send.
+        slow_reader, slow_writer = await asyncio.open_connection(
+            "127.0.0.1", port, limit=4096
+        )
+        slow_writer.write(
+            b"GET /media/binary HTTP/1.1\r\nHost: localhost\r\n"
+            b"Connection: close\r\n\r\n"
+        )
+        await slow_writer.drain()
+        headers = await asyncio.wait_for(slow_reader.readuntil(b"\r\n\r\n"), 5)
+        assert headers.startswith(b"HTTP/1.1 200")
+        assert b"content-length: 134217728" in headers.lower()
+        # TCP backpressure leaves only the response head reserved after the
+        # adaptive pipeline retires unused read-ahead.
+        await wait_until(lambda: cache.scratch.used == 1)
+
+        async with httpx2.AsyncClient(
+            base_url=f"http://127.0.0.1:{port}", timeout=10
+        ) as http:
+            head = await http.head("/media/video")
+            assert head.status_code == 200 and head.headers["content-length"] == str(
+                len(video)
+            )
+            results = await asyncio.gather(
+                http.get("/media/video", headers={"Range": "bytes=0-4095"}),
+                http.get("/media/video", headers={"Range": "bytes=-4096"}),
+                http.get("/media/video"),
+                http.get(
+                    "/media/binary", headers={"Range": f"bytes={127 * BLOCK + 11}-"}
+                ),
+            )
+            assert [result.status_code for result in results] == [206, 206, 200, 206]
+            assert results[0].content == video[:4096]
+            assert results[1].content == video[-4096:]
+            assert results[2].content == video
+            assert results[3].content == binary[127 * BLOCK + 11 :]
+            assert all(
+                result.headers["content-encoding"] == "identity" for result in results
+            )
+        assert (
+            cache._active_streams == 1
+        )  # The deliberately unread download remains live.
+        assert sum(sum(client.native.requests.values()) for client in clients) == reads
+        assert all(row.active_leases == 0 for row in await pool.status())
+        slow_writer.close()
+        await slow_writer.wait_closed()
+        slow_writer = None
+        await wait_until(lambda: cache._active_streams == 0)
+        await assert_clean(pool)
+    finally:
+        if slow_writer is not None:
+            slow_writer.close()
+            await slow_writer.wait_closed()
+        if serving is not None:
+            server.should_exit = True
+            await asyncio.wait_for(serving, 10)
+        listener.close()
+        await cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_browser_fixture_uses_the_real_pooled_cache_and_closes_it():
+    """Browser decoding tests must not silently bypass cache/backpressure code."""
+    from tests.support.browser_transfer_app import FixtureRuntime, settings
+    from tgdrive.telegram.clients import _block_identity
+
+    runtime = FixtureRuntime()
+    await runtime.start()
+    cache = runtime.pool._media_read_cache
+    try:
+        async with runtime.pool.lease() as client:
+            source = await client.get_messages(
+                settings.storage_channel, message_ids=101
+            )
+        assert _block_identity(source, 0) is not None
+        selected = await stream_telegram_file(
+            pool=runtime.pool,
+            channel_id=settings.storage_channel,
+            message_id=101,
+            file_name="résumé.txt",
+            expected_size=14,
+            request=request("bytes=0-3"),
+        )
+        assert await response_body(selected) == b"publ"
+        files = (await cache.snapshot())["files"]
+        assert len(files) == 1 and files[0]["ready_ranges"] == [[0, 14]]
+        assert runtime.preloads.cache is cache
+        # Match production's wrapper metadata as well as its immutable native
+        # document. Size-only native documents break logical multipart reads.
+        assert source.document.file_size == 14
+        import hashlib
+
+        manifest = [
+            {
+                "index": index,
+                "offset": 0 if index == 0 else 14,
+                "size": len(runtime.payloads[message_id]),
+                "message_id": message_id,
+                "sha256": hashlib.sha256(runtime.payloads[message_id]).hexdigest(),
+            }
+            for index, message_id in enumerate((101, 102))
+        ]
+        boundary = await stream_telegram_file(
+            pool=runtime.pool,
+            channel_id=settings.storage_channel,
+            message_id=101,
+            file_name="logical.bin",
+            expected_size=29,
+            parts=manifest,
+            request=request("bytes=12-16"),
+        )
+        assert boundary.status_code == 206
+        assert boundary.headers["content-range"] == "bytes 12-16/29"
+        assert boundary.headers["content-length"] == "5"
+        assert await response_body(boundary) == b"ntpri"
+        await assert_clean(runtime.pool)
+    finally:
+        await runtime.stop()
+    assert cache._closed and runtime.preloads._closed
diff --git a/tests/media/test_cached_thumbnail_repair.py b/tests/media/test_cached_thumbnail_repair.py
new file mode 100644
index 00000000..2626affa
--- /dev/null
+++ b/tests/media/test_cached_thumbnail_repair.py
@@ -0,0 +1,576 @@
+"""A missing derivative can reuse complete local data, never refill its source."""
+
+from __future__ import annotations
+
+import asyncio
+import errno
+import hashlib
+import threading
+from types import SimpleNamespace
+
+import pytest
+
+from tgdrive.media.generated_thumbnails import CachedThumbnailRepair, read
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import BLOCK, MediaReadCache
+from tgdrive.media.thumbnails import Thumbnail, ThumbnailBusy, ThumbnailCache
+
+JPEG = b"\xff\xd8\xffsmall cover\xff\xd9"
+
+
+def source(size, message_id=1, parts=None):
+    return dict(channel_id=-100, message_id=message_id, size=size, parts=parts)
+
+
+def media_cache(tmp_path, *, disk=False):
+    return MediaReadCache(
+        tmp_path / "media" if disk else None,
+        MediaCachePolicy(
+            disk_max_bytes=8 * BLOCK if disk else 0,
+            memory_max_bytes=0 if disk else 8 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+
+
+async def fill(cache, metadata, payload, *, blocks=None):
+    cache.register_file(**metadata, name="clip.mov")
+    keys = []
+    for part in metadata["parts"] or [
+        dict(message_id=metadata["message_id"], offset=0, size=metadata["size"])
+    ]:
+        for index in range((part["size"] + BLOCK - 1) // BLOCK):
+            key = (
+                metadata["channel_id"],
+                part["message_id"],
+                "document",
+                part["message_id"] * 100,
+                part["size"],
+                index,
+            )
+            keys.append(key)
+            if blocks is not None and len(keys) > blocks:
+                continue
+            lo = part["offset"] + index * BLOCK
+            data = payload[lo : min(lo + BLOCK, part["offset"] + part["size"])]
+
+            async def remote(data=data):
+                return data
+
+            await cache.get(key, len(data), remote)
+    await cache.flush()
+    return keys
+
+
+def forbid_origin(monkeypatch, cache):
+    async def forbidden(*_args, **_kwargs):
+        raise AssertionError("A thumbnail repair must not call the origin-fill path")
+
+    monkeypatch.setattr(cache, "get", forbidden)
+
+
+async def repair(helper, cache, metadata):
+    return await helper.get(
+        cache,
+        source=metadata,
+        name="clip.mov",
+        version=cache.cached_source_version(**metadata),
+        authorize=lambda: None,
+    )
+
+
+@pytest.mark.parametrize("disk", [False, True])
+async def test_complete_multipart_original_is_spooled_verified_and_saved(
+    tmp_path, monkeypatch, disk
+):
+    payload = b"a" * (BLOCK + 7) + b"second part"
+    part_sizes = [BLOCK + 7, len(b"second part")]
+    parts = []
+    offset = 0
+    for index, size in enumerate(part_sizes):
+        parts.append(
+            dict(
+                index=index,
+                message_id=index + 1,
+                offset=offset,
+                size=size,
+                sha256=hashlib.sha256(payload[offset : offset + size]).hexdigest(),
+            )
+        )
+        offset += size
+    metadata = source(len(payload), parts=parts)
+    cache = media_cache(tmp_path, disk=disk)
+    await fill(cache, metadata, payload)
+    version = cache.cached_source_version(**metadata)
+    forbid_origin(monkeypatch, cache)
+    directory = tmp_path / "covers"
+    helper = CachedThumbnailRepair(directory)
+    calls = []
+
+    async def generate(path, name, **_kwargs):
+        calls.append(path)
+        assert name == "clip.mov" and path.read_bytes() == payload
+        assert path.stat().st_mode & 0o077 == 0
+        return JPEG
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", generate)
+    assert await repair(helper, cache, metadata) == JPEG
+    assert len(calls) == 1 and not calls[0].exists()
+    assert read(directory, -100, 1) == JPEG
+    assert not list(directory.glob(".repair-*"))
+    assert cache.cached_source_version(**metadata) == version
+    await cache.close()
+
+
+@pytest.mark.parametrize("state", ["cold", "partial", "oversized"])
+async def test_uncached_partial_and_oversized_sources_never_refill_or_render(
+    tmp_path, monkeypatch, state
+):
+    cache = media_cache(tmp_path)
+    metadata = source(129 * BLOCK if state == "oversized" else 2 * BLOCK)
+    cache.register_file(**metadata, name="clip.mov")
+    if state == "partial":
+        await fill(cache, metadata, b"a" * metadata["size"], blocks=1)
+    forbid_origin(monkeypatch, cache)
+
+    async def forbidden(*_args, **_kwargs):
+        raise AssertionError("A partial source must not be rendered")
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", forbidden)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    assert await repair(helper, cache, metadata) is None
+    assert not list(tmp_path.rglob(".repair-*"))
+    await cache.close()
+
+
+@pytest.mark.parametrize("change", ["eviction", "clear", "checksum"])
+async def test_source_changes_abort_copy_and_remove_temporary_files(
+    tmp_path, monkeypatch, change
+):
+    payload = b"a" * BLOCK + b"b" * BLOCK
+    metadata = source(len(payload))
+    if change == "checksum":
+        metadata["parts"] = [
+            dict(index=0, message_id=1, offset=0, size=len(payload), sha256="0" * 64)
+        ]
+    cache = media_cache(tmp_path)
+    keys = await fill(cache, metadata, payload)
+    original = cache.cached_file_blocks
+
+    async def changing(**kwargs):
+        count = 0
+        async for block in original(**kwargs):
+            yield block
+            count += 1
+            if count == 1 and change == "clear":
+                await cache.clear(cache.cached_source_version(**metadata).file_id)
+            elif count == 1 and change == "eviction":
+                _, data = cache.memory.entries.pop(keys[1])
+                cache.memory.bytes_used -= len(data)
+
+    monkeypatch.setattr(cache, "cached_file_blocks", changing)
+    forbid_origin(monkeypatch, cache)
+
+    async def forbidden(*_args, **_kwargs):
+        raise AssertionError("Changed/incomplete source must not be rendered")
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", forbidden)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    if change == "clear":
+        with pytest.raises(ThumbnailBusy):
+            await repair(helper, cache, metadata)
+    else:
+        assert await repair(helper, cache, metadata) is None
+    assert not helper._slot.locked()
+    assert not list(tmp_path.rglob(".repair-*"))
+    await cache.close()
+
+
+async def test_corrupt_disk_digest_is_rejected_before_render(tmp_path, monkeypatch):
+    metadata = source(20)
+    cache = media_cache(tmp_path, disk=True)
+    keys = await fill(cache, metadata, b"a" * 20)
+    block = cache.disk.directory / (cache.disk._key(keys[0]) + ".block")
+    block.write_bytes(block.read_bytes()[:-1] + b"z")
+    forbid_origin(monkeypatch, cache)
+
+    async def forbidden(*_args, **_kwargs):
+        raise AssertionError("Corrupt source must not be rendered")
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", forbidden)
+    assert (
+        await repair(CachedThumbnailRepair(tmp_path / "covers"), cache, metadata)
+        is None
+    )
+    assert not list(tmp_path.rglob(".repair-*"))
+    await cache.close()
+
+
+async def test_cancelled_repair_cleans_source_and_can_retry(tmp_path, monkeypatch):
+    metadata = source(20)
+    cache = media_cache(tmp_path)
+    await fill(cache, metadata, b"a" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    entered = asyncio.Event()
+    paths = []
+
+    async def blocked(path, _name, **_kwargs):
+        paths.append(path)
+        entered.set()
+        await asyncio.Event().wait()
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", blocked)
+    task = asyncio.create_task(repair(helper, cache, metadata))
+    await entered.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert not paths[0].exists() and not helper._slot.locked()
+
+    async def ready(*_args, **_kwargs):
+        return JPEG
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", ready)
+    assert await repair(helper, cache, metadata) == JPEG
+    await cache.close()
+
+
+@pytest.mark.parametrize("stage", ["open", "write", "cleanup"])
+async def test_repeated_cancellation_drains_owned_files_before_releasing_slot(
+    tmp_path, monkeypatch, stage
+):
+    metadata = source(20)
+    cache = media_cache(tmp_path)
+    await fill(cache, metadata, b"a" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    entered, release = threading.Event(), threading.Event()
+    outputs, paths = [], []
+    original_open, original_cleanup = helper._open_source, helper._cleanup_source
+
+    def pause():
+        entered.set()
+        assert release.wait(5)
+
+    class Writer:
+        def __init__(self, output):
+            self.output = output
+
+        def write(self, data):
+            if stage == "write":
+                pause()
+            return self.output.write(data)
+
+        def close(self):
+            self.output.close()
+
+        def flush(self):
+            self.output.flush()
+
+    def opening(size, reserve):
+        if stage == "open":
+            pause()
+        output, path = original_open(size, reserve)
+        outputs.append(output)
+        paths.append(path)
+        return Writer(output), path
+
+    def cleanup(output, path):
+        if stage == "cleanup":
+            pause()
+        original_cleanup(output, path)
+
+    async def ready(*_args, **_kwargs):
+        return JPEG
+
+    monkeypatch.setattr(helper, "_open_source", opening)
+    monkeypatch.setattr(helper, "_cleanup_source", cleanup)
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", ready)
+    task = asyncio.create_task(repair(helper, cache, metadata))
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        await asyncio.sleep(0)
+        assert not task.done() and helper._slot.locked()
+    finally:
+        release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert not helper._slot.locked()
+    assert outputs and all(output.closed for output in outputs)
+    assert paths and all(not path.exists() for path in paths)
+    await cache.close()
+
+
+async def test_failed_render_waits_for_new_data_not_metadata_or_cache_reads(
+    tmp_path, monkeypatch
+):
+    metadata = source(20)
+    cache = media_cache(tmp_path)
+    keys = await fill(cache, metadata, b"a" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    calls = 0
+
+    async def failed(*_args, **kwargs):
+        nonlocal calls
+        calls += 1
+        kwargs["on_start"]()
+        return None
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", failed)
+    version = cache.cached_source_version(**metadata)
+    assert await repair(helper, cache, metadata) is None
+    cache.register_file(**metadata, name="renamed.mov")
+
+    async def forbidden():
+        raise AssertionError("Existing cache read must not download")
+
+    assert await cache.get(keys[0], 20, forbidden) == b"a" * 20
+    assert cache.cached_source_version(**metadata) == version
+    assert await repair(helper, cache, metadata) is None
+    assert calls == 1
+    await cache.clear(version.file_id)
+    await fill(cache, metadata, b"a" * 20)
+    assert cache.cached_source_version(**metadata).revision > version.revision
+    assert await repair(helper, cache, metadata) is None
+    assert calls == 2
+    await cache.close()
+
+
+async def test_unrelated_cache_clear_does_not_suppress_a_valid_source_retry(
+    tmp_path, monkeypatch
+):
+    cache = media_cache(tmp_path)
+    first, second = source(20), source(20, message_id=2)
+    await fill(cache, first, b"a" * 20)
+    await fill(cache, second, b"b" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    original = cache.cached_file_blocks
+    revision = cache.cached_source_version(**first).data_revision
+
+    async def clearing(**kwargs):
+        async for block in original(**kwargs):
+            yield block
+            await cache.clear(cache.cached_source_version(**second).file_id)
+
+    calls = 0
+
+    async def ready(*_args, **_kwargs):
+        nonlocal calls
+        calls += 1
+        return JPEG
+
+    monkeypatch.setattr(cache, "cached_file_blocks", clearing)
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", ready)
+    with pytest.raises(ThumbnailBusy):
+        await repair(helper, cache, first)
+    assert calls == 0
+    assert cache.cached_source_version(**first).data_revision == revision
+    monkeypatch.setattr(cache, "cached_file_blocks", original)
+    assert await repair(helper, cache, first) == JPEG
+    assert calls == 1
+    assert not list(tmp_path.rglob(".repair-*"))
+    await cache.close()
+
+
+async def test_spool_respects_configured_floor_and_space_recovery_can_retry(
+    tmp_path, monkeypatch
+):
+    cache = media_cache(tmp_path)
+    cache.policy = MediaCachePolicy(
+        memory_max_bytes=8 * BLOCK, min_free_bytes=128 * BLOCK
+    )
+    metadata = source(20)
+    await fill(cache, metadata, b"a" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    free = 64 * BLOCK + metadata["size"]
+    monkeypatch.setattr(
+        "tgdrive.media.generated_thumbnails.shutil.disk_usage",
+        lambda _directory: SimpleNamespace(free=free),
+    )
+    calls = 0
+
+    async def ready(*_args, **_kwargs):
+        nonlocal calls
+        calls += 1
+        return JPEG
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", ready)
+    with pytest.raises(ThumbnailBusy):
+        await repair(helper, cache, metadata)
+    assert calls == 0
+    free = 129 * BLOCK
+    assert await repair(helper, cache, metadata) == JPEG
+    assert calls == 1
+    await cache.close()
+
+
+def test_only_unlocked_owned_repair_leftovers_are_removed(tmp_path):
+    fcntl = pytest.importorskip("fcntl")
+    directory = tmp_path / "covers"
+    directory.mkdir()
+    orphan = directory / (".repair-" + "a" * 32 + ".source")
+    active = directory / (".repair-" + "b" * 32 + ".source")
+    symlink = directory / (".repair-" + "c" * 32 + ".source")
+    other = directory / ".repair-unowned.source"
+    private = directory / "private.txt"
+    for path in (orphan, active, other, private):
+        path.write_bytes(b"retained")
+    symlink.symlink_to(private)
+    helper = CachedThumbnailRepair(directory)
+    with active.open("r+b") as held:
+        fcntl.flock(held, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        output, path = helper._open_source(20, 64 * BLOCK)
+        try:
+            assert not orphan.exists()
+            assert active.exists() and other.exists() and symlink.is_symlink()
+            assert private.read_bytes() == b"retained"
+            assert path.exists()
+            helper._cleanup_stale_sources()
+            assert path.exists(), "An active current source must retain its lock"
+        finally:
+            helper._cleanup_source(output, path)
+    helper._cleanup_stale_sources()
+    assert not active.exists() and not path.exists()
+    assert other.exists() and private.exists() and symlink.is_symlink()
+
+
+async def test_startup_removes_owned_crash_leftovers_before_any_cache_fill(tmp_path):
+    directory = tmp_path / "covers"
+    directory.mkdir()
+    orphan = directory / (".repair-" + "d" * 32 + ".source")
+    orphan.write_bytes(b"abandoned source")
+    await CachedThumbnailRepair(directory).start()
+    assert not orphan.exists()
+
+
+@pytest.mark.parametrize("timeout", ["admission", "outer"])
+async def test_busy_native_renderer_never_marks_source_as_failed(
+    tmp_path, monkeypatch, timeout
+):
+    import tgdrive.media.generated_thumbnails as module
+
+    cache = media_cache(tmp_path)
+    metadata = source(20)
+    await fill(cache, metadata, b"a" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    held = asyncio.Semaphore(0)
+    monkeypatch.setitem(module._slots, asyncio.get_running_loop(), held)
+    monkeypatch.setattr(
+        module, "NATIVE_ADMISSION_SECONDS", 0.02 if timeout == "admission" else 2
+    )
+    monkeypatch.setattr(module, "REPAIR_SECONDS", 8 if timeout == "admission" else 0.03)
+    with pytest.raises(ThumbnailBusy):
+        await repair(helper, cache, metadata)
+    assert not helper._slot.locked()
+    assert not list(tmp_path.rglob(".repair-*"))
+    held.release()
+    monkeypatch.setattr(module, "REPAIR_SECONDS", 8)
+
+    async def ready(*_args, **_kwargs):
+        return JPEG
+
+    monkeypatch.setattr(module, "generate", ready)
+    assert await repair(helper, cache, metadata) == JPEG
+    await cache.close()
+
+
+async def test_transient_native_process_spawn_failure_can_retry_same_source(
+    tmp_path, monkeypatch
+):
+    import tgdrive.media.generated_thumbnails as module
+
+    cache = media_cache(tmp_path)
+    metadata = source(20)
+    await fill(cache, metadata, b"a" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+
+    async def unavailable(*_args, **_kwargs):
+        raise OSError(errno.EAGAIN, "Transient process admission failure")
+
+    monkeypatch.setattr(module.asyncio, "create_subprocess_exec", unavailable)
+    with pytest.raises(ThumbnailBusy):
+        await repair(helper, cache, metadata)
+
+    async def ready(*_args, **_kwargs):
+        return JPEG
+
+    monkeypatch.setattr(module, "generate", ready)
+    assert await repair(helper, cache, metadata) == JPEG
+    assert not list(tmp_path.rglob(".repair-*"))
+    await cache.close()
+
+
+async def test_repair_deadline_cleans_source_and_does_not_repeat(tmp_path, monkeypatch):
+    metadata = source(20)
+    cache = media_cache(tmp_path)
+    await fill(cache, metadata, b"a" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.REPAIR_SECONDS", 0.03)
+    calls = 0
+
+    async def blocked(*_args, **kwargs):
+        nonlocal calls
+        calls += 1
+        kwargs["on_start"]()
+        await asyncio.Event().wait()
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", blocked)
+    assert await repair(helper, cache, metadata) is None
+    assert await repair(helper, cache, metadata) is None
+    assert calls == 1 and not helper._slot.locked()
+    assert not list(tmp_path.rglob(".repair-*"))
+    await cache.close()
+
+
+async def test_only_one_file_repairs_at_once_without_a_long_queue(
+    tmp_path, monkeypatch
+):
+    cache = media_cache(tmp_path)
+    first, second = source(20), source(20, message_id=2)
+    await fill(cache, first, b"a" * 20)
+    await fill(cache, second, b"b" * 20)
+    helper = CachedThumbnailRepair(tmp_path / "covers")
+    entered = asyncio.Event()
+
+    async def blocked(*_args, **_kwargs):
+        entered.set()
+        await asyncio.Event().wait()
+
+    monkeypatch.setattr("tgdrive.media.generated_thumbnails.generate", blocked)
+    task = asyncio.create_task(repair(helper, cache, first))
+    await entered.wait()
+    with pytest.raises(ThumbnailBusy):
+        await repair(helper, cache, second)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    await cache.close()
+
+
+async def test_only_negative_thumbnail_entries_follow_source_revision():
+    cache = ThumbnailCache()
+    calls = 0
+
+    async def missing():
+        nonlocal calls
+        calls += 1
+        return None
+
+    assert await cache.get((1,), missing, missing_revision=1) is None
+    assert await cache.get((1,), missing, missing_revision=1) is None
+    assert calls == 1
+    assert await cache.get((2,), missing, missing_revision=2) is None
+    assert await cache.get((1,), missing, missing_revision=1) is None
+    assert calls == 2
+    assert await cache.get((1,), missing, missing_revision=3) is None
+    assert calls == 3
+
+    async def image():
+        return Thumbnail(JPEG, "image/jpeg")
+
+    assert (await cache.get((3,), image, missing_revision=1)).content == JPEG
+    assert (await cache.get((3,), missing, missing_revision=2)).content == JPEG
+    assert calls == 3
+    await cache.close()
diff --git a/tests/media/test_download_ranges.py b/tests/media/test_download_ranges.py
new file mode 100644
index 00000000..0eda6cb0
--- /dev/null
+++ b/tests/media/test_download_ranges.py
@@ -0,0 +1,201 @@
+"""Resumed and segmented HTTP downloads only fetch their requested file blocks."""
+
+from __future__ import annotations
+
+import asyncio
+from concurrent.futures import ThreadPoolExecutor
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.media.test_multipart_streaming import build_parts
+from tests.media.test_pooled_media import account
+from tests.media.test_preload_api import MediaRuntime
+from tests.media.test_telegram_cache import message
+from tests.support.app_fixtures import login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.media.media_reader import BLOCK
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+from tgdrive.web.app import create_app
+
+
+@pytest.fixture(params=[False, True], ids=["single", "multipart"])
+def download_drive(tmp_path, request, monkeypatch):
+    settings = make_settings(tmp_path)
+    settings.storage_channel = -1000000000123
+    settings.auto_preload = True
+    payload = b"".join(bytes([index]) * BLOCK for index in range(32)) + b"tail"
+    telegram = account("bot", payload)
+    telegram.configure_transport = Mock()
+    parts = None
+    if request.param:
+        contents = [payload[: 13 * BLOCK + 17], payload[13 * BLOCK + 17 :]]
+        parts = build_parts(contents)
+        telegram.native.payloads = {9001: contents[0], 9002: contents[1]}
+
+        async def fetch(_channel, *, message_ids):
+            part = parts[message_ids - 101]
+            native = message(part["document_id"], part["size"])
+            native.id = message_ids
+            return TelegramMessage(telegram, native)
+
+        telegram.get_messages = AsyncMock(side_effect=fetch)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    item = store.add_file(
+        "/",
+        "movie.mp4",
+        parts[0]["message_id"] if parts else 77,
+        len(payload),
+        parts=parts,
+    )
+    runtime = MediaRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    runtime.pool = ClientPool([telegram], media_cache_dir=settings.cache_dir)
+    app = create_app(settings, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            login(client)
+            assert client.get("/api/v1/settings/performance").status_code == 200
+            yield client, runtime, telegram, "/" + item["id"], payload, parts
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
+
+
+def requested_blocks(parts, size, intervals):
+    allowed = set()
+    manifest = parts or [{"offset": 0, "size": size, "document_id": 1}]
+    for start, end in intervals:
+        for part in manifest:
+            lo = max(start, part["offset"])
+            hi = min(end, part["offset"] + part["size"] - 1)
+            if lo <= hi:
+                allowed.update(
+                    (part["document_id"], index)
+                    for index in range(
+                        (lo - part["offset"]) // BLOCK,
+                        (hi - part["offset"]) // BLOCK + 1,
+                    )
+                )
+    return allowed
+
+
+def assert_no_unrequested_reads(telegram, parts, payload, intervals):
+    actual = {
+        (identity, offset // BLOCK) for identity, offset in telegram.native.requests
+    }
+    assert actual == requested_blocks(parts, len(payload), intervals)
+
+
+def settle_background(client, runtime):
+    async def settle():
+        tasks = list(runtime.preloads._auto_tasks.values())
+        tasks += list(runtime.preloads._tasks.values())
+        if tasks:
+            await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), 5)
+
+    client.portal.call(settle)
+    assert client.get("/api/v1/preloads").json()["jobs"] == []
+
+
+@pytest.mark.parametrize(
+    "attachment", [False, True], ids=["inline-url", "download-url"]
+)
+def test_resumed_overlapping_suffix_and_open_ended_ranges_do_not_warm_whole_file(
+    download_drive, attachment
+):
+    client, runtime, telegram, path, payload, parts = download_drive
+    intervals = []
+    cases = [
+        (4 * BLOCK + 37, 10 * BLOCK + 22, None),
+        # A manager may retry overlapping bytes; that is not a second viewing.
+        (5 * BLOCK + 17, 9 * BLOCK + 99, None),
+        (29 * BLOCK + 5, len(payload) - 1, f"bytes={29 * BLOCK + 5}-"),
+        (len(payload) - BLOCK - 9, len(payload) - 1, f"bytes=-{BLOCK + 9}"),
+        # Seek backwards across a Telegram part boundary.
+        (12 * BLOCK + 7, 17 * BLOCK + 31, None),
+    ]
+    params = {"path": path, "request_id": "download-manager-source"}
+    if attachment:
+        params["download"] = "1"
+    for start, end, header in cases:
+        response = client.get(
+            "/file",
+            params=params,
+            headers={"Range": header or f"bytes={start}-{end}"},
+        )
+        assert response.status_code == 206
+        assert response.headers["content-length"] == str(end - start + 1)
+        assert (
+            response.headers["content-range"] == f"bytes {start}-{end}/{len(payload)}"
+        )
+        assert response.content == payload[start : end + 1]
+        intervals.append((start, end))
+        settle_background(client, runtime)
+        assert_no_unrequested_reads(telegram, parts, payload, intervals)
+
+
+def test_parallel_missing_ranges_reassemble_original_and_reuse_overlaps(download_drive):
+    client, runtime, telegram, path, payload, parts = download_drive
+    # Simulate a partial device file whose other sections were saved earlier.
+    device = bytearray(payload)
+    intervals = [
+        (19 * BLOCK + 13, 24 * BLOCK + 1),
+        (2 * BLOCK + 23, 7 * BLOCK + 3),
+        (12 * BLOCK + 9, 17 * BLOCK + 19),
+    ]
+    for start, end in intervals:
+        device[start : end + 1] = b"\0" * (end - start + 1)
+
+    def fetch(interval):
+        start, end = interval
+        result = client.get(
+            "/file",
+            params={"path": path, "download": "1"},
+            headers={"Range": f"bytes={start}-{end}"},
+        )
+        assert result.status_code == 206
+        assert result.content == payload[start : end + 1]
+        return interval, result.content
+
+    with ThreadPoolExecutor(max_workers=3) as workers:
+        for (start, end), content in workers.map(fetch, intervals):
+            device[start : end + 1] = content
+    assert bytes(device) == payload
+    settle_background(client, runtime)
+    assert_no_unrequested_reads(telegram, parts, payload, intervals)
+    reads = telegram.native.requests.copy()
+    with ThreadPoolExecutor(max_workers=3) as workers:
+        list(workers.map(fetch, reversed(intervals)))
+    assert telegram.native.requests == reads
+
+
+def test_range_resume_requires_matching_representation(download_drive):
+    client, runtime, telegram, path, payload, parts = download_drive
+    params = {"path": path, "download": "1"}
+    start, end = 5 * BLOCK + 17, 10 * BLOCK + 3
+    first = client.get(
+        "/file", params=params, headers={"Range": f"bytes={start}-{end}"}
+    )
+    assert first.status_code == 206
+    reads = telegram.native.requests.copy()
+    resumed = client.get(
+        "/file",
+        params=params,
+        headers={"Range": f"bytes={start}-{end}", "If-Range": first.headers["etag"]},
+    )
+    assert resumed.status_code == 206 and resumed.content == first.content
+    assert telegram.native.requests == reads
+    assert_no_unrequested_reads(telegram, parts, payload, [(start, end)])
+    stale = client.get(
+        "/file",
+        params=params,
+        headers={"Range": f"bytes={start}-{end}", "If-Range": '"old-file-version"'},
+    )
+    # The client must restart rather than splice bytes from different versions.
+    assert stale.status_code == 200 and stale.content == payload
+    assert "content-range" not in stale.headers
+    settle_background(client, runtime)
diff --git a/tests/media/test_file_status.py b/tests/media/test_file_status.py
new file mode 100644
index 00000000..329310b0
--- /dev/null
+++ b/tests/media/test_file_status.py
@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi.responses import Response
+
+import tests.support.app_fixtures as fixtures
+from tgdrive.media.streaming import _prime_response
+from tgdrive.telegram.client_pool import MediaQueueFull
+
+app_client = fixtures.app_client
+
+
+def test_file_status_keeps_retry_guidance_scoped_to_authorized_file(
+    app_client, monkeypatch
+):
+    client, store, runtime, _settings = app_client
+    file = store.add_file("/", "image.png", 77, 5)
+    path = "/" + file["id"]
+    auth = store.create_share(path)
+    params = {"path": path, "auth": auth, "request_id": "viewer"}
+    runtime.pool = SimpleNamespace(queue_estimate=lambda _id: None)
+
+    async def overloaded(**kwargs):
+        assert kwargs["request_status"]["phase"] == "checking_file"
+        raise MediaQueueFull(retry_after=17)
+
+    monkeypatch.setattr("tgdrive.web.app.stream_telegram_file", overloaded)
+    response = client.get("/file", params=params)
+    assert response.status_code == 503
+    assert response.headers["retry-after"] == "17"
+    status = client.get("/api/v1/file-status", params=params).json()
+    assert status["phase"] == "retry_wait"
+    assert status["code"] == "TELEGRAM_QUEUE_FULL"
+    assert 0 < status["retry_after"] <= 17
+    assert status["queue"] is None
+
+    other = store.add_file("/", "other.png", 78, 8)
+    other_path = "/" + other["id"]
+    unrelated = client.get(
+        "/api/v1/file-status",
+        params=params | {"path": other_path, "auth": store.create_share(other_path)},
+    ).json()
+    assert unrelated["phase"] is None and unrelated["code"] is None
+    assert unrelated["retry_after"] is None and unrelated["queue"] is None
+    assert (
+        client.get(
+            "/api/v1/file-status", params={"path": path, "request_id": "viewer"}
+        ).status_code
+        == 403
+    )
+
+    async def conditional(**kwargs):
+        assert kwargs["request_status"]["phase"] == "checking_file"
+        assert kwargs["request_status"]["code"] is None
+        return Response(status_code=304)
+
+    monkeypatch.setattr("tgdrive.web.app.stream_telegram_file", conditional)
+    assert client.get("/file", params=params).status_code == 304
+    status = client.get("/api/v1/file-status", params=params).json()
+    assert status["phase"] is None and status["retry_after"] is None
+    store.revoke_share(path)
+    assert client.get("/api/v1/file-status", params=params).status_code == 403
+
+
+def test_file_status_reports_metadata_and_origin_admission_separately(app_client):
+    client, store, runtime, settings = app_client
+    file = store.add_file("/", "image.png", 77, 5)
+    path = "/" + file["id"]
+    params = {"path": path, "auth": store.create_share(path), "request_id": "viewer"}
+    queue = None
+    runtime.pool = SimpleNamespace(
+        queue_estimate=lambda _id: queue,
+        _request_files={
+            "viewer": dict(
+                file=(settings.storage_channel, 77, 5),
+                phase="checking_file",
+                code=None,
+                retry_at=None,
+            )
+        },
+    )
+    status = client.get("/api/v1/file-status", params=params).json()
+    assert status["phase"] == "checking_file" and status["queue"] is None
+    queue = dict(position=2, queued_operations=1, active_operations=0)
+    status = client.get("/api/v1/file-status", params=params).json()
+    assert status["phase"] == "waiting_for_telegram" and status["queue"] == queue
+    runtime.pool._request_files["viewer"]["phase"] = "receiving"
+    queue = None
+    assert (
+        client.get("/api/v1/file-status", params=params).json()["phase"] == "receiving"
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("after_headers", [False, True])
+@pytest.mark.parametrize("asgi_version", ["2.3", "2.4"])
+async def test_stream_overload_preserves_retry_status_before_and_after_headers(
+    after_headers, asgi_version
+):
+    progress = dict(phase="checking_file", code=None, retry_at=None)
+    release = AsyncMock()
+
+    async def source():
+        if after_headers:
+            yield b"first"
+        raise MediaQueueFull(retry_after=9)
+
+    response = await _prime_response(
+        source(),
+        release=release,
+        status=200,
+        mime_type="image/png",
+        headers={},
+        request_status=progress,
+    )
+    if after_headers:
+        assert progress["phase"] == "receiving"
+
+        async def receive():
+            await asyncio.Event().wait()
+
+        with pytest.raises(MediaQueueFull):
+            await response(
+                {"type": "http", "asgi": {"spec_version": asgi_version}},
+                receive,
+                AsyncMock(),
+            )
+    else:
+        assert response.status_code == 503 and response.headers["retry-after"] == "9"
+    assert progress["phase"] == "retry_wait"
+    assert progress["code"] == "TELEGRAM_QUEUE_FULL"
+    assert progress["retry_at"] is not None
+    release.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_completed_response_clears_receiving_status():
+    progress = dict(phase="checking_file", code=None, retry_at=None)
+
+    async def source():
+        yield b"image"
+
+    response = await _prime_response(
+        source(),
+        release=AsyncMock(),
+        status=200,
+        mime_type="image/png",
+        headers={},
+        request_status=progress,
+    )
+    assert progress["phase"] == "receiving"
+    await response(
+        {"type": "http", "asgi": {"spec_version": "2.4"}}, AsyncMock(), AsyncMock()
+    )
+    assert progress["phase"] is None
+
+
+@pytest.mark.asyncio
+async def test_cancelled_lease_cleanup_still_clears_receiving_status():
+    progress = dict(phase="checking_file", code=None, retry_at=None)
+
+    async def source():
+        yield b"image"
+
+    response = await _prime_response(
+        source(),
+        release=AsyncMock(side_effect=asyncio.CancelledError()),
+        status=200,
+        mime_type="image/png",
+        headers={},
+        request_status=progress,
+    )
+    with pytest.raises(asyncio.CancelledError):
+        await response(
+            {"type": "http", "asgi": {"spec_version": "2.4"}},
+            AsyncMock(),
+            AsyncMock(),
+        )
+    assert progress["phase"] is None
diff --git a/tests/media/test_generated_thumbnails.py b/tests/media/test_generated_thumbnails.py
new file mode 100644
index 00000000..31404d00
--- /dev/null
+++ b/tests/media/test_generated_thumbnails.py
@@ -0,0 +1,335 @@
+from __future__ import annotations
+
+import asyncio
+import shutil
+import subprocess
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon import types
+from telethon.errors import RPCError
+
+from tests.support.book_samples import png
+from tgdrive.media.generated_thumbnails import MAX_BYTES, generate, read, save
+from tgdrive.telegram.clients import Client
+
+
+@pytest.mark.parametrize("name", ["cover.png", "clip.mp4", "clip.mov"])
+async def test_native_generation_is_small_and_preserves_original(tmp_path, name):
+    if not shutil.which("ffmpeg"):
+        pytest.skip("native ffmpeg not installed")
+    path = tmp_path / name
+    original = (
+        png(3)
+        if name.endswith("png")
+        else (
+            Path(__file__).resolve().parents[1] / "fixtures/movtext-subtitles.mp4"
+        ).read_bytes()
+    )
+    path.write_bytes(original)
+    cover = await generate(path, name)
+    assert cover and cover.startswith(b"\xff\xd8\xff") and cover.endswith(b"\xff\xd9")
+    assert len(cover) <= MAX_BYTES
+    assert path.read_bytes() == original
+
+
+async def test_native_uhd_hevc_mov_has_a_cover_with_bounded_worker_memory(tmp_path):
+    ffmpeg = shutil.which("ffmpeg")
+    if not ffmpeg:
+        pytest.skip("native ffmpeg not installed")
+    path = tmp_path / "uhd-hevc.mov"
+    encoded = await asyncio.to_thread(
+        subprocess.run,
+        [
+            ffmpeg,
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-f",
+            "lavfi",
+            "-i",
+            "color=c=blue:s=3840x2160:r=24",
+            "-frames:v",
+            "12",
+            "-c:v",
+            "libx265",
+            "-preset",
+            "ultrafast",
+            "-threads",
+            "1",
+            "-x265-params",
+            "pools=none:frame-threads=1:log-level=error",
+            "-tag:v",
+            "hvc1",
+            str(path),
+        ],
+        capture_output=True,
+        timeout=30,
+        check=False,
+    )
+    if b"Unknown encoder" in encoded.stderr:
+        pytest.skip("native HEVC encoder not installed")
+    assert encoded.returncode == 0, encoded.stderr.decode(errors="replace")
+    original = path.read_bytes()
+    cover = await generate(path, path.name)
+    assert cover and cover.startswith(b"\xff\xd8\xff") and cover.endswith(b"\xff\xd9")
+    assert len(cover) <= MAX_BYTES
+    assert path.read_bytes() == original
+
+
+@pytest.mark.parametrize("failure", ["timeout", "error", "partial", "oversized"])
+def test_video_first_frame_fallback_after_unsuccessful_seek(monkeypatch, failure):
+    from tgdrive.media import thumbnail_worker
+
+    cover = b"\xff\xd8\xffcover\xff\xd9"
+    calls = []
+
+    def run(command, **kwargs):
+        calls.append((command.copy(), kwargs["timeout"]))
+        if len(calls) == 1:
+            if failure == "timeout":
+                raise subprocess.TimeoutExpired(command, kwargs["timeout"])
+            return SimpleNamespace(
+                returncode=1 if failure == "error" else 0,
+                stdout=(
+                    cover + b"x" * MAX_BYTES
+                    if failure == "oversized"
+                    else cover
+                    if failure == "error"
+                    else cover[:-2]
+                ),
+            )
+        return SimpleNamespace(returncode=0, stdout=cover)
+
+    monkeypatch.setattr(thumbnail_worker, "video_seek_time", lambda *_: "600")
+    monkeypatch.setattr(thumbnail_worker.subprocess, "run", run)
+    assert thumbnail_worker.render(Path("staged.mov"), ".mov") == cover
+    assert [command[command.index("-ss") + 1] for command, _ in calls] == ["600", "0"]
+    assert [timeout for _, timeout in calls] == [6, 3]
+
+
+def test_video_first_frame_fallback_remains_bounded(monkeypatch):
+    from tgdrive.media import thumbnail_worker
+
+    timeouts = []
+
+    def run(command, **kwargs):
+        timeouts.append(kwargs["timeout"])
+        raise subprocess.TimeoutExpired(command, kwargs["timeout"])
+
+    monkeypatch.setattr(thumbnail_worker, "video_seek_time", lambda *_: "600")
+    monkeypatch.setattr(thumbnail_worker.subprocess, "run", run)
+    assert thumbnail_worker.render(Path("staged.mov"), ".mov") == b""
+    assert timeouts == [6, 3]
+
+
+async def test_disguised_playlist_and_invalid_images_do_not_render(tmp_path):
+    image = tmp_path / "private.png"
+    image.write_bytes(png(2))
+    path = tmp_path / "fake.mp4"
+    path.write_text(
+        "#EXTM3U\n#EXT-X-TARGETDURATION:1\n#EXTINF:1,\n"
+        + str(image)
+        + "\n#EXT-X-ENDLIST"
+    )
+    assert await generate(path, path.name) is None
+    path.write_bytes(b"bad source")
+    assert await generate(path, "bad.png") is None
+    assert await generate(path, "script.svg") is None
+
+
+def test_disk_cover_cache_is_small_private_and_channel_scoped(tmp_path, monkeypatch):
+    import tgdrive.media.generated_thumbnails as module
+
+    cover = b"\xff\xd8\xff" + b"cover" * 100
+    monkeypatch.setattr(module, "MAX_ENTRIES", 2)
+    for message in [10, 11, 12]:
+        save(tmp_path, -100, message, cover)
+    assert len(list(tmp_path.glob("*.jpg"))) == 2
+    assert read(tmp_path, -100, 12) == cover
+    assert read(tmp_path, -200, 12) is None
+    save(tmp_path, -100, 13, b"x" * (MAX_BYTES + 1))
+    assert read(tmp_path, -100, 13) is None
+    if __import__("os").name == "posix":
+        assert next(iter(tmp_path.glob("*.jpg"))).stat().st_mode & 0o077 == 0
+
+
+@pytest.mark.parametrize("reject", ["none", "thumbnail_upload", "thumbnail_publish"])
+async def test_native_upload_keeps_original_and_own_cover_when_thumbnail_is_optional(
+    tmp_path, reject
+):
+    if not shutil.which("ffmpeg"):
+        pytest.skip("native ffmpeg not installed")
+    path = tmp_path / "photo.png"
+    original = png(1)
+    path.write_bytes(original)
+    calls = []
+    published = []
+
+    class Native:
+        async def upload_parts(self, source, *, length, file_name, progress):
+            payload = source.read()
+            assert len(payload) == length
+            calls.append(payload)
+            if file_name == "thumbnail.jpg" and reject == "thumbnail_upload":
+                raise OSError("optional transport failed")
+            return types.InputFile(1, len(payload), file_name, "")
+
+        async def get_input_entity(self, channel):
+            return channel
+
+        async def __call__(self, request):
+            published.append(request)
+            if request.media.thumb and reject == "thumbnail_publish":
+                raise RPCError(None, "THUMB_INVALID", 400)
+            return SimpleNamespace()
+
+    client = Client.__new__(Client)
+    client.native = Native()
+    client._upload_parts = AsyncMock(side_effect=client.native.upload_parts)
+    client._thumbnail_directory = tmp_path / "covers"
+    client._sent = AsyncMock(return_value=SimpleNamespace(id=50))
+    result = await client.send_staged(
+        -100,
+        path,
+        file_name="photo.png.tgdrive-part-0001",
+        preview_name="photo.png",
+        random_id=22,
+        size=len(original) // 2,
+    )
+    assert result.id == 50 and calls[0] == original[: len(original) // 2]
+    assert calls[1].startswith(b"\xff\xd8\xff")
+    assert read(client._thumbnail_directory, -100, 50) == calls[1]
+    assert published[-1].random_id == 22
+    assert bool(published[-1].media.thumb) == (reject == "none")
+    assert path.read_bytes() == original
+
+
+@pytest.mark.parametrize("kind", ["epub", "cbz", "cbr", "docx"])
+async def test_archive_cover_generation_is_bounded_and_preserves_original(
+    tmp_path, kind
+):
+    from tests.support.book_samples import cbr, cbz, epub
+
+    if kind == "cbr":
+        try:
+            import libarchive  # noqa: F401
+        except ImportError, OSError, AttributeError:
+            pytest.skip("Native libarchive is not installed")
+
+    if not shutil.which("ffmpeg"):
+        pytest.skip("native ffmpeg not installed")
+    if kind == "docx":
+        import io
+        from zipfile import ZipFile
+
+        archive = io.BytesIO()
+        with ZipFile(archive, "w") as output:
+            output.writestr("docProps/thumbnail.png", png())
+        original = archive.getvalue()
+    else:
+        original = epub() if kind == "epub" else cbr() if kind == "cbr" else cbz()
+    path = tmp_path / ("book." + kind)
+    path.write_bytes(original)
+    cover = await generate(path, path.name)
+    assert cover and cover.startswith(b"\xff\xd8\xff") and cover.endswith(b"\xff\xd9")
+    assert len(cover) <= MAX_BYTES
+    assert path.read_bytes() == original
+
+
+def test_large_jpeg_uses_decoder_downsampling_before_scaling(tmp_path, monkeypatch):
+    from tgdrive.media import thumbnail_worker
+
+    path = tmp_path / "large.jpg"
+    with path.open("wb") as source:
+        source.truncate(9 * 1024**2)
+    commands = []
+    cover = b"\xff\xd8\xffcover\xff\xd9"
+
+    def run(command, **kwargs):
+        commands.append(command)
+        return SimpleNamespace(returncode=0, stdout=cover)
+
+    monkeypatch.setattr(thumbnail_worker.subprocess, "run", run)
+    assert thumbnail_worker.render(path, ".jpg") == cover
+    assert commands[0][commands[0].index("-lowres") + 1] == "3"
+    assert commands[0].index("-lowres") < commands[0].index("-i")
+
+
+@pytest.mark.parametrize("duration", [60, 7200])
+@pytest.mark.parametrize("offset", [0, 10, 20])
+def test_video_thumbnail_chooses_middle_duration_with_bounded_probe(
+    monkeypatch, duration, offset
+):
+    from tgdrive.media import thumbnail_worker
+
+    def run(command, **kwargs):
+        assert command[0] == "ffprobe"
+        assert command[command.index("-f") + 1] == "mov"
+        assert command[command.index("-protocol_whitelist") + 1] == "file,pipe"
+        assert kwargs["timeout"] == 1.5
+        return SimpleNamespace(returncode=0, stdout=str(duration).encode())
+
+    monkeypatch.setattr(thumbnail_worker.subprocess, "run", run)
+    monkeypatch.setattr(thumbnail_worker.secrets, "randbelow", lambda limit: offset)
+    position = float(thumbnail_worker.video_seek_time(Path("staged.mov"), ".mov"))
+    assert position == duration * (40 + offset) / 100
+    assert duration * 0.4 <= position <= duration * 0.6
+
+
+@pytest.mark.parametrize("duration", [b"N/A", b"nan", b"inf", b"-1", b"0"])
+def test_video_unknown_duration_uses_safe_seek_fallback(monkeypatch, duration):
+    from tgdrive.media import thumbnail_worker
+
+    monkeypatch.setattr(
+        thumbnail_worker.subprocess,
+        "run",
+        lambda *_, **__: SimpleNamespace(returncode=0, stdout=duration),
+    )
+    assert thumbnail_worker.video_seek_time(Path("staged.mov"), ".mov") == "10"
+
+
+async def test_audio_embedded_artwork_generates_cover_without_altering_audio(tmp_path):
+    if not shutil.which("ffmpeg"):
+        pytest.skip("native encoder unavailable")
+    image = tmp_path / "cover.png"
+    image.write_bytes(png())
+    audio = tmp_path / "music.flac"
+    encoded = await asyncio.to_thread(
+        subprocess.run,
+        [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-f",
+            "lavfi",
+            "-i",
+            "anullsrc=r=8000:cl=mono",
+            "-i",
+            str(image),
+            "-map",
+            "0:a",
+            "-map",
+            "1:v",
+            "-t",
+            "1",
+            "-c:a",
+            "flac",
+            "-c:v",
+            "png",
+            "-disposition:v",
+            "attached_pic",
+            str(audio),
+        ],
+        capture_output=True,
+        timeout=15,
+        check=False,
+    )
+    assert encoded.returncode == 0, encoded.stderr
+    original = audio.read_bytes()
+    cover = await generate(audio, audio.name)
+    assert cover and cover.startswith(b"\xff\xd8\xff")
+    assert audio.read_bytes() == original
diff --git a/tests/media/test_media_admission_priority.py b/tests/media/test_media_admission_priority.py
new file mode 100644
index 00000000..a576d839
--- /dev/null
+++ b/tests/media/test_media_admission_priority.py
@@ -0,0 +1,261 @@
+"""Demand FIFO and priority inheritance through real shared payload fills."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from tests.media.test_media_scheduler import wait_until
+from tests.media.test_pooled_media import account
+from tests.media.test_preloading import CHANNEL, finish, manager_for
+from tests.media.test_telegram_cache import Native
+from tgdrive.media.media_metadata import get_message
+from tgdrive.media.media_reader import BLOCK, stream_pooled_media
+from tgdrive.media.media_scheduler import (
+    MediaPriorityScope,
+    MediaScheduler,
+    media_priority,
+)
+from tgdrive.telegram.client_pool import ClientPool
+
+
+class OrderedNative(Native):
+    def __init__(self, *args):
+        super().__init__(*args)
+        self.order = []
+
+    def iter_download(self, target, *, offset, request_size, limit):
+        self.order.append(offset)
+        return super().iter_download(
+            target, offset=offset, request_size=request_size, limit=limit
+        )
+
+
+@pytest.mark.asyncio
+async def test_shared_background_fill_inherits_demand_without_overtaking_older_demand():
+    payload = b"".join(bytes([index]) * BLOCK for index in range(4))
+    client = account("bot", payload, native_type=OrderedNative)
+    pool = ClientPool([client], media_per_bot=1)
+    await pool.start()
+    message = await client.get_messages(CHANNEL, message_ids=77)
+    tasks = []
+
+    async def read(index, request_id, *, background=False):
+        stream = stream_pooled_media(
+            pool,
+            client,
+            message,
+            channel=CHANNEL,
+            offset=index,
+            limit=1,
+            background=background,
+            request_id=request_id,
+        )
+        return b"".join([data async for data in stream])
+
+    try:
+        async with pool.lease(download=True, request_id="occupied"):
+            tasks.append(asyncio.create_task(read(0, "shared", background=True)))
+            await wait_until(lambda: len(pool._origin_waiters) == 1)
+            tasks.append(asyncio.create_task(read(1, "background", background=True)))
+            await wait_until(lambda: len(pool._origin_waiters) == 2)
+            tasks.append(asyncio.create_task(read(2, "first-demand")))
+            await wait_until(lambda: len(pool._origin_waiters) == 3)
+            tasks.append(asyncio.create_task(read(0, "joined-demand")))
+            await wait_until(lambda: pool._origin_waiters[-1]["priority"] == "demand")
+            tasks.append(asyncio.create_task(read(3, "later-demand")))
+            await wait_until(lambda: len(pool._origin_waiters) == 4)
+            queue = pool.performance_snapshot()["queue"]
+            assert [row["request_id"] for row in queue] == [
+                "first-demand",
+                "shared",
+                "later-demand",
+                "background",
+            ]
+        results = await asyncio.wait_for(asyncio.gather(*tasks), 3)
+        assert results == [
+            payload[:BLOCK],
+            payload[BLOCK : 2 * BLOCK],
+            payload[2 * BLOCK : 3 * BLOCK],
+            payload[:BLOCK],
+            payload[3 * BLOCK :],
+        ]
+        assert [offset // BLOCK for offset in client.native.order] == [2, 0, 3, 1]
+        assert sum(client.native.requests.values()) == 8  # Two RPCs/MiB, no duplicate.
+        cache = pool._media_read_cache
+        assert not cache.memory.flights and not cache._fill_priorities
+        assert not cache._foreground and not cache._active_keys
+        assert pool.performance_snapshot()["active"] == 0
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_account_priority_promotion_respects_demand_arrival_order():
+    scheduler = MediaScheduler(limit=1, rate=512)
+    scope = MediaPriorityScope("preload")
+    order = []
+    tasks = []
+
+    async def request(label, priority):
+        token = media_priority.set(priority)
+        try:
+            async with scheduler.request():
+                order.append(label)
+        finally:
+            media_priority.reset(token)
+
+    try:
+        async with scheduler.request():
+            tasks.append(asyncio.create_task(request("shared", scope)))
+            await wait_until(lambda: len(scheduler._waiting) == 1)
+            tasks.append(asyncio.create_task(request("earlier-demand", "demand")))
+            await wait_until(lambda: len(scheduler._waiting) == 2)
+            await scope.promote()
+            tasks.append(asyncio.create_task(request("later-demand", "demand")))
+            await wait_until(lambda: len(scheduler._waiting) == 3)
+            assert all(
+                row["priority"] == "demand" for row in scheduler.snapshot()["queue"]
+            )
+        await asyncio.wait_for(asyncio.gather(*tasks), 2)
+        assert order == ["earlier-demand", "shared", "later-demand"]
+        assert not scope._conditions and not scope._updates
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_manual_preload_yields_next_origin_slot_to_new_demand(tmp_path):
+    gate = asyncio.Event()
+    payload = b"x" * (8 * BLOCK)
+    manager, pool, client = await manager_for(tmp_path, payload, gate)
+    await pool.set_media_per_bot(1)
+    order = []
+    original = client.native.iter_download
+
+    def tracked(target, *, offset, request_size, limit):
+        order.append(offset)
+        return original(target, offset=offset, request_size=request_size, limit=limit)
+
+    client.native.iter_download = tracked
+    demand = None
+    try:
+        job = await manager.prepare(
+            channel_id=CHANNEL, message_id=77, size=len(payload)
+        )
+        await wait_until(
+            lambda: client.native.active > 0 and len(pool._origin_waiters) > 0
+        )
+        message = await client.get_messages(CHANNEL, message_ids=77)
+
+        async def read():
+            stream = stream_pooled_media(
+                pool,
+                client,
+                message,
+                channel=CHANNEL,
+                offset=5,
+                limit=1,
+                request_id="playback-seek",
+            )
+            return b"".join([data async for data in stream])
+
+        demand = asyncio.create_task(read())
+        await wait_until(
+            lambda: any(
+                row["request_id"] == "playback-seek" for row in pool._origin_waiters
+            )
+        )
+        gate.set()
+        assert await asyncio.wait_for(demand, 3) == payload[5 * BLOCK : 6 * BLOCK]
+        assert (await finish(manager, job))["state"] == "ready"
+        assert order[0] // BLOCK in (0, 1)  # One existing background block can finish.
+        assert order[1] // BLOCK == 5  # The next free slot belongs to demand.
+        assert sorted(offset // BLOCK for offset in order) == list(range(8))
+        assert sum(client.native.requests.values()) == 16
+    finally:
+        gate.set()
+        if demand is not None:
+            demand.cancel()
+            await asyncio.gather(demand, return_exceptions=True)
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_shared_metadata_validation_inherits_demand_without_duplicate_rpc():
+    scheduler = MediaScheduler(limit=1, rate=512)
+    calls = []
+
+    class MetadataClient:
+        async def get_messages(self, _channel, *, message_ids):
+            async with scheduler.request():
+                calls.append(message_ids)
+                return message_ids
+
+    client = MetadataClient()
+    tasks = []
+
+    async def read(message_id, priority="demand"):
+        token = media_priority.set(priority)
+        try:
+            return await get_message(client, CHANNEL, message_id)
+        finally:
+            media_priority.reset(token)
+
+    try:
+        async with scheduler.request():
+            tasks.append(asyncio.create_task(read(77, "preload")))
+            await wait_until(lambda: len(scheduler._waiting) == 1)
+            assert scheduler.snapshot()["queue"][0]["priority"] == "preload"
+            tasks.append(asyncio.create_task(read(88)))
+            await wait_until(lambda: len(scheduler._waiting) == 2)
+            tasks.append(asyncio.create_task(read(77)))
+            await wait_until(
+                lambda: all(
+                    row["priority"] == "demand" for row in scheduler.snapshot()["queue"]
+                )
+            )
+        assert await asyncio.wait_for(asyncio.gather(*tasks), 2) == [77, 88, 77]
+        assert calls == [88, 77]
+        assert media_priority.get() == "demand"
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_cancelled_promoted_pool_waiter_detaches_priority_notifications():
+    from tests.media.test_media_scheduler import Account
+
+    pool = ClientPool([Account()], media_per_bot=1)
+    scope = MediaPriorityScope("preload")
+    await pool.start()
+    task = None
+
+    async def wait():
+        async with pool.lease(download=True, priority=scope):
+            pytest.fail("Occupied slot cannot be acquired")
+
+    try:
+        async with pool.lease(download=True):
+            task = asyncio.create_task(wait())
+            await wait_until(lambda: len(pool._origin_waiters) == 1)
+            await scope.promote()
+            task.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await task
+            assert not pool._origin_waiters
+            assert not scope._conditions and not scope._updates
+    finally:
+        if task is not None:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+        await pool.stop()
diff --git a/tests/media/test_media_csp.py b/tests/media/test_media_csp.py
new file mode 100644
index 00000000..cbb4c962
--- /dev/null
+++ b/tests/media/test_media_csp.py
@@ -0,0 +1,34 @@
+"""Decoder data and local subtitles must not widen executable origins."""
+
+import pytest
+from starlette.applications import Starlette
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+from tgdrive.web.http_guard import SecurityHeadersMiddleware
+
+
+@pytest.mark.parametrize("path", ["/", "/static/decoder.js", "/api/v1/preview"])
+def test_decoder_data_fetch_keeps_network_and_execution_policy_restricted(path):
+    async def respond(request):
+        return PlainTextResponse("fixture")
+
+    app = Starlette(routes=[Route(path, respond)])
+    app.add_middleware(SecurityHeadersMiddleware, secure=False)
+    with TestClient(app) as client:
+        response = client.get(path)
+    values = {}
+    for directive in response.headers["content-security-policy"].split(";"):
+        tokens = directive.split()
+        if tokens:
+            values[tokens[0]] = set(tokens[1:])
+    assert values["connect-src"] == {"'self'", "data:", "blob:"}
+    assert values["script-src"] == {"'self'", "'wasm-unsafe-eval'"}
+    assert values["worker-src"] == {"'self'", "blob:"}
+    assert values["default-src"] == {"'self'"}
+    assert values["object-src"] == {"'none'"}
+    assert values["base-uri"] == {"'none'"}
+    assert values["style-src-elem"] == {"'self'"}
+    assert "data:" not in values["script-src"]
+    assert "'unsafe-eval'" not in values["script-src"]
diff --git a/tests/media/test_media_metadata.py b/tests/media/test_media_metadata.py
new file mode 100644
index 00000000..aeff16da
--- /dev/null
+++ b/tests/media/test_media_metadata.py
@@ -0,0 +1,102 @@
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tgdrive.media.media_metadata import get_message
+
+
+async def test_concurrent_validation_coalesces_but_later_request_is_fresh():
+    gate = asyncio.Event()
+    calls = 0
+
+    async def fetch(*args, **kwargs):
+        nonlocal calls
+        calls += 1
+        await gate.wait()
+        return calls
+
+    client = SimpleNamespace(get_messages=fetch)
+    tasks = [asyncio.create_task(get_message(client, -1001, 5)) for _ in range(12)]
+    await asyncio.sleep(0.01)
+    assert calls == 1
+    tasks[0].cancel()
+    gate.set()
+    result = await asyncio.gather(*tasks, return_exceptions=True)
+    assert isinstance(result[0], asyncio.CancelledError)
+    assert result[1:] == [1] * 11
+    assert await get_message(client, -1001, 5) == 2
+
+
+async def test_last_waiter_cancel_stops_orphan_validation():
+    stopped = asyncio.Event()
+
+    async def fetch(*args, **kwargs):
+        try:
+            await asyncio.Event().wait()
+        finally:
+            stopped.set()
+
+    client = SimpleNamespace(get_messages=fetch)
+    task = asyncio.create_task(get_message(client, 1, 2))
+    await asyncio.sleep(0.01)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    await asyncio.wait_for(stopped.wait(), 1)
+    client.get_messages = AsyncMock(return_value=None)
+    assert await get_message(client, 1, 2) is None
+
+
+async def test_new_seek_does_not_join_abandoned_metadata_validation():
+    cancelling, finish_cleanup = asyncio.Event(), asyncio.Event()
+    calls = 0
+
+    async def fetch(*args, **kwargs):
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            try:
+                await asyncio.Event().wait()
+            finally:
+                cancelling.set()
+                await finish_cleanup.wait()
+        return "fresh"
+
+    client = SimpleNamespace(get_messages=fetch)
+    abandoned = asyncio.create_task(get_message(client, 1, 2))
+    await asyncio.sleep(0)
+    await asyncio.sleep(0)
+    abandoned.cancel()
+    await cancelling.wait()
+    replacement = asyncio.create_task(get_message(client, 1, 2))
+    await asyncio.sleep(0)
+    assert not replacement.done()
+    finish_cleanup.set()
+    assert await replacement == "fresh"
+    assert calls == 2
+    with pytest.raises(asyncio.CancelledError):
+        await abandoned
+
+
+async def test_distinct_metadata_work_is_bounded_without_rejecting_shared_waiters():
+    gate = asyncio.Event()
+
+    async def fetch(*args, **kwargs):
+        await gate.wait()
+        return kwargs["message_ids"]
+
+    client = SimpleNamespace(
+        get_messages=fetch, _identity_pool=SimpleNamespace(_max_media_queue=2)
+    )
+    tasks = [asyncio.create_task(get_message(client, 1, i)) for i in (1, 2)]
+    await asyncio.sleep(0.01)
+    from tgdrive.telegram.client_pool import MediaQueueFull
+
+    with pytest.raises(MediaQueueFull):
+        await get_message(client, 1, 3)
+    shared = asyncio.create_task(get_message(client, 1, 1))
+    gate.set()
+    assert await asyncio.gather(*tasks, shared) == [1, 2, 1]
+    assert await get_message(client, 1, 3) == 3
diff --git a/tests/media/test_media_request_fairness.py b/tests/media/test_media_request_fairness.py
new file mode 100644
index 00000000..c2e31fc4
--- /dev/null
+++ b/tests/media/test_media_request_fairness.py
@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from tests.media.test_media_scheduler import Account, wait_until
+from tests.media.test_pooled_media import account
+from tests.media.test_telegram_cache import message
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import (
+    BLOCK,
+    MediaReadCache,
+    _AdaptiveReadAhead,
+    stream_pooled_media,
+)
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("priority", ["demand", "preload"])
+async def test_download_turn_rotates_read_ahead_behind_other_requests(priority):
+    pool = ClientPool([Account()], media_per_bot=1)
+    await pool.start()
+    order, tasks = [], []
+
+    async def read(request_id, block):
+        async with pool.lease(download=True, priority=priority, request_id=request_id):
+            order.append((request_id, block))
+
+    try:
+        async with pool.lease(download=True):
+            for request_id, block in [("a", 0), ("a", 1), ("b", 0), ("c", 0)]:
+                tasks.append(asyncio.create_task(read(request_id, block)))
+                await wait_until(lambda: len(pool._origin_waiters) == len(tasks))
+        await asyncio.wait_for(asyncio.gather(*tasks), 2)
+        assert order == [("a", 0), ("b", 0), ("c", 0), ("a", 1)]
+        assert pool.performance_snapshot()["active"] == 0
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_one_bot_serves_distinct_anonymous_files_and_drops_cancelled_waiter(
+    tmp_path, monkeypatch
+):
+    class SustainedReadAhead(_AdaptiveReadAhead):
+        def __init__(self, maximum):
+            super().__init__(maximum)
+            self.window = self.maximum
+
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._AdaptiveReadAhead", SustainedReadAhead
+    )
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    client = account("only-bot", b"")
+    pool = ClientPool([client])  # The default three media operations serve four files.
+    cache = pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(memory_max_bytes=0, disk_max_bytes=0, min_free_bytes=0),
+    )
+    release = asyncio.Event()
+    calls, tasks = [], []
+    active = peak = 0
+
+    async def remote(source, *, offset, limit, **_kwargs):
+        nonlocal active, peak
+        document = source.native.document.id
+        calls.append((document, offset))
+        active += 1
+        peak = max(peak, active)
+        try:
+            assert limit == 1
+            await release.wait()
+            yield bytes([document]) * BLOCK
+        finally:
+            active -= 1
+
+    client.stream_media = remote
+
+    async def read(document, count):
+        native = message(document, count * BLOCK)
+        native.id = 100 + document
+        stream = stream_pooled_media(
+            pool,
+            client,
+            TelegramMessage(client, native),
+            channel=1,
+            offset=0,
+            limit=count,
+        )
+        try:
+            return b"".join([data async for data in stream])
+        finally:
+            await stream.aclose()
+
+    await pool.start()
+    try:
+        tasks.append(asyncio.create_task(read(1, 6)))
+        await wait_until(lambda: len(pool._origin_waiters) == 3 and active == 3)
+        first_ids = {row["request_id"] for row in pool._origin_waiters}
+        assert len(first_ids) == 1  # Every block of an anonymous stream shares a turn.
+        for document in (2, 3, 4):
+            tasks.append(asyncio.create_task(read(document, 2)))
+            await wait_until(
+                lambda: len(pool._origin_waiters) == 3 + 2 * (len(tasks) - 1)
+            )
+        queued_ids = {row["request_id"] for row in pool._origin_waiters}
+        assert len(queued_ids) == 4  # Distinct streams never collapse into one turn.
+        cancelled_ids = {row["request_id"] for row in pool._origin_waiters[-2:]}
+        tasks[-1].cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await tasks[-1]
+        assert not cancelled_ids.intersection(
+            row["request_id"] for row in pool._origin_waiters
+        )
+        assert len(pool._origin_waiters) == 7
+        release.set()
+        results = await asyncio.wait_for(asyncio.gather(*tasks[:-1]), 3)
+        assert results == [
+            b"\x01" * (6 * BLOCK),
+            b"\x02" * (2 * BLOCK),
+            b"\x03" * (2 * BLOCK),
+        ]
+        assert [document for document, _offset in calls[3:6]] == [1, 2, 3]
+        assert sorted(calls) == [
+            (document, offset)
+            for document, count in ((1, 6), (2, 2), (3, 2))
+            for offset in range(count)
+        ]
+        assert peak == 3 and active == 0
+        assert cache.scratch.used == cache._active_streams == 0
+        assert not cache.memory.flights
+        assert not pool._origin_waiters and not pool._origin_active
+    finally:
+        release.set()
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await cache.close()
+        await pool.stop()
diff --git a/tests/media/test_media_scheduler.py b/tests/media/test_media_scheduler.py
new file mode 100644
index 00000000..694467c0
--- /dev/null
+++ b/tests/media/test_media_scheduler.py
@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import asyncio
+import time
+
+import pytest
+
+from tgdrive.media.media_scheduler import MediaScheduler, media_priority
+from tgdrive.telegram.client_pool import ClientPool, MediaQueueFull
+
+
+class Account:
+    name = "storage-bot-1"
+    is_connected = True
+
+    async def start(self):
+        pass
+
+    async def stop(self):
+        pass
+
+
+async def wait_until(predicate):
+    async with asyncio.timeout(2):
+        while not predicate():  # noqa: ASYNC110 - bounded scheduler-state observation.
+            await asyncio.sleep(0)
+
+
+@pytest.mark.asyncio
+async def test_account_requests_bound_concurrency_and_prioritize_demand():
+    scheduler = MediaScheduler(limit=1, rate=512)
+    release = asyncio.Event()
+    order = []
+
+    async def request(label, priority):
+        token = media_priority.set(priority)
+        try:
+            async with scheduler.request():
+                order.append(label)
+                if label == "active":
+                    await release.wait()
+        finally:
+            media_priority.reset(token)
+
+    active = asyncio.create_task(request("active", "demand"))
+    await wait_until(lambda: order == ["active"])
+    preload = asyncio.create_task(request("preload", "preload"))
+    await wait_until(lambda: len(scheduler.snapshot()["queue"]) == 1)
+    demand = asyncio.create_task(request("demand", "demand"))
+    await wait_until(lambda: len(scheduler.snapshot()["queue"]) == 2)
+    assert scheduler.snapshot()["queue"][0]["priority"] == "demand"
+    release.set()
+    await asyncio.gather(active, preload, demand)
+    assert order == ["active", "demand", "preload"]
+    assert scheduler.active == 0
+    assert scheduler.completed == 3
+
+
+@pytest.mark.asyncio
+async def test_cancelled_waiter_is_removed_and_flood_reduces_shared_budget():
+    scheduler = MediaScheduler(limit=8, rate=24)
+    async with scheduler.request():
+        await scheduler.flood(60)
+        waiter = asyncio.create_task(scheduler.request().__aenter__())
+        await wait_until(lambda: len(scheduler.snapshot()["queue"]) == 1)
+        waiter.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await waiter
+        snapshot = scheduler.snapshot()
+        assert snapshot["queue"] == []
+        assert snapshot["effective_limit"] == 4
+        assert snapshot["effective_parts_per_second"] == 12
+        assert snapshot["cooldown_seconds"] > 59
+    assert scheduler.active == 0
+
+
+@pytest.mark.asyncio
+async def test_pool_combined_cap_demand_priority_and_metadata_independence():
+    pool = ClientPool([Account()], media_per_bot=1)
+    await pool.start()
+    release = asyncio.Event()
+    order = []
+
+    async def work(label, *, download=False, priority="demand"):
+        async with pool.lease(media=not download, download=download, priority=priority):
+            order.append(label)
+            if label == "upload":
+                await release.wait()
+
+    upload = asyncio.create_task(work("upload"))
+    await wait_until(lambda: order == ["upload"])
+    preload = asyncio.create_task(work("preload", download=True, priority="preload"))
+    await wait_until(lambda: pool.performance_snapshot()["queued"] == 1)
+    demand = asyncio.create_task(work("demand", download=True))
+    await wait_until(lambda: pool.performance_snapshot()["queued"] == 2)
+    async with pool.lease():
+        assert pool.performance_snapshot()["active"] == 1
+    assert pool.performance_snapshot()["queue"][0]["priority"] == "demand"
+    release.set()
+    await asyncio.gather(upload, preload, demand)
+    assert order == ["upload", "demand", "preload"]
+    assert pool.performance_snapshot()["active"] == 0
+    assert pool.performance_snapshot()["mean_activity_seconds"] is not None
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_pool_cancelled_preload_does_not_leak_queue_or_context():
+    pool = ClientPool([Account()], media_per_bot=1)
+    await pool.start()
+
+    async def queued():
+        async with pool.lease(download=True, priority="preload"):
+            pytest.fail("occupied origin slot must not be acquired")
+
+    async with pool.lease(media=True):
+        task = asyncio.create_task(queued())
+        await wait_until(lambda: pool.performance_snapshot()["queued"] == 1)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert pool.performance_snapshot()["queue"] == []
+        assert media_priority.get() == "demand"
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_bounded_origin_queue_is_retryable_and_does_not_block_metadata():
+    pool = ClientPool([Account()], media_per_bot=1, max_media_queue=1)
+    await pool.start()
+
+    async def waiting():
+        async with pool.lease(download=True, request_id="visitor-range"):
+            pass
+
+    async with pool.lease(media=True, request_id="active-upload"):
+        task = asyncio.create_task(waiting())
+        await wait_until(lambda: pool.performance_snapshot()["queued"] == 1)
+        estimate = pool.queue_estimate("visitor-range")
+        assert estimate["position"] == 1
+        assert estimate["estimated_wait_seconds"] is None
+        assert pool.queue_estimate("active-upload")["active_operations"] == 1
+        with pytest.raises(MediaQueueFull) as error:
+            async with pool.lease(download=True):
+                pytest.fail("a full queue cannot admit another origin request")
+        assert error.value.code == "TELEGRAM_QUEUE_FULL"
+        assert error.value.retry_after >= 1
+        async with pool.lease():
+            pass
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+    assert pool.queue_estimate("visitor-range") is None
+    assert pool.performance_snapshot()["active_requests"] == []
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_configured_media_capacity_allows_four_reads_and_bounds_fifth():
+    pool = ClientPool([Account()], media_per_bot=4)
+    await pool.start()
+    release = asyncio.Event()
+    acquired = []
+
+    async def read(index):
+        async with pool.lease(download=True):
+            acquired.append(index)
+            await release.wait()
+
+    tasks = [asyncio.create_task(read(index)) for index in range(5)]
+    try:
+        await wait_until(lambda: len(acquired) == 4)
+        snapshot = pool.performance_snapshot()
+        assert await pool.download_capacity() == 4
+        assert snapshot["accounts"][0]["downloads"] == 4
+        assert snapshot["active"] == 4 and snapshot["queued"] == 1
+    finally:
+        release.set()
+        await asyncio.gather(*tasks)
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_waiting_upload_gets_released_combined_slot_before_later_read():
+    pool = ClientPool([Account()], media_per_bot=4)
+    await pool.start()
+    gates = [asyncio.Event() for _ in range(5)]
+    order = []
+
+    async def work(label, gate=None, *, upload=False):
+        async with pool.lease(media=upload, download=not upload):
+            order.append(label)
+            if gate is not None:
+                await gate.wait()
+
+    readers = [
+        asyncio.create_task(work(str(index), gates[index])) for index in range(4)
+    ]
+    upload = later = None
+    try:
+        await wait_until(lambda: len(order) == 4)
+        upload = asyncio.create_task(work("upload", gates[4], upload=True))
+        await wait_until(lambda: pool.performance_snapshot()["queued"] == 1)
+        later = asyncio.create_task(work("later-read"))
+        await wait_until(lambda: pool.performance_snapshot()["queued"] == 2)
+        gates[0].set()
+        await wait_until(lambda: "upload" in order)
+        assert "later-read" not in order
+        account = pool.performance_snapshot()["accounts"][0]
+        assert account["downloads"] == 3 and account["uploads"] == 1
+        gates[4].set()
+        await wait_until(lambda: "later-read" in order)
+        assert order.index("upload") < order.index("later-read")
+    finally:
+        for gate in gates:
+            gate.set()
+        await asyncio.gather(
+            *readers, *[task for task in (upload, later) if task is not None]
+        )
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_demand_upload_overtakes_preload_upload_without_fifo_deadlock():
+    pool = ClientPool([Account()], media_per_bot=1)
+    await pool.start()
+    release = asyncio.Event()
+    order = []
+
+    async def work(label, priority="demand"):
+        async with pool.lease(media=True, priority=priority):
+            order.append(label)
+            if label == "active":
+                await release.wait()
+
+    active = asyncio.create_task(work("active"))
+    await wait_until(lambda: order == ["active"])
+    preload = asyncio.create_task(work("preload", "preload"))
+    await wait_until(lambda: pool.performance_snapshot()["queued"] == 1)
+    demand = asyncio.create_task(work("demand"))
+    await wait_until(lambda: pool.performance_snapshot()["queued"] == 2)
+    try:
+        release.set()
+        await asyncio.wait_for(asyncio.gather(active, preload, demand), 2)
+        assert order == ["active", "demand", "preload"]
+    finally:
+        release.set()
+        for task in (active, preload, demand):
+            task.cancel()
+        await asyncio.gather(active, preload, demand, return_exceptions=True)
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_channel_upload_cooldown_does_not_strand_ready_read_lane():
+    pool = ClientPool([Account()], media_per_bot=4)
+    await pool.start()
+    await pool.defer_channel(time.time() + 60)
+
+    async def upload():
+        async with pool.lease(media=True):
+            pytest.fail("Channel cooldown must still gate uploads")
+
+    pending = asyncio.create_task(upload())
+    try:
+        await wait_until(lambda: pool.performance_snapshot()["queued"] == 1)
+        async with asyncio.timeout(1):
+            async with pool.lease(download=True):
+                assert pool.performance_snapshot()["active"] == 1
+    finally:
+        pending.cancel()
+        await asyncio.gather(pending, return_exceptions=True)
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_upload_queue_estimate_includes_known_channel_cooldown():
+    pool = ClientPool([Account()], media_per_bot=3)
+    await pool.start()
+    pool._origin_durations.append(2.0)
+    await pool.defer_channel(time.time() + 60)
+
+    async def upload():
+        async with pool.lease(media=True, request_id="cooling-upload"):
+            pytest.fail("Channel cooldown must still gate this upload")
+
+    pending = asyncio.create_task(upload())
+    try:
+        await wait_until(lambda: pool.performance_snapshot()["queued"] == 1)
+        estimate = pool.queue_estimate("cooling-upload")
+        assert 59 <= estimate["estimated_wait_seconds"] <= 60
+        owner_queue = pool.performance_snapshot()["queue"][0]
+        assert owner_queue["request_id"] == "cooling-upload"
+        assert 59 <= owner_queue["estimated_wait_seconds"] <= 60
+        # Upload-only cooldowns cannot add latency to a ready download lane.
+        async with pool.lease(download=True, request_id="ready-read"):
+            assert pool.queue_estimate("ready-read")["estimated_wait_seconds"] == 0
+    finally:
+        pending.cancel()
+        await asyncio.gather(pending, return_exceptions=True)
+        await pool.stop()
diff --git a/tests/media/test_multipart_previews.py b/tests/media/test_multipart_previews.py
new file mode 100644
index 00000000..c67a8e86
--- /dev/null
+++ b/tests/media/test_multipart_previews.py
@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import asyncio
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+
+from tests.media.test_multipart_streaming import MultipartClient, build_parts
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.media.previews import (
+    PDF_PREVIEW_BYTES,
+    TEXT_PREVIEW_BYTES,
+    describe_media,
+    describe_preview,
+)
+from tgdrive.media.streaming import TelegramFileNotFound
+from tgdrive.telegram.client_pool import ClientPool
+
+
+async def preview(pool, contents, name="note.txt", **options):
+    return await describe_preview(
+        pool=pool,
+        channel_id=-100,
+        message_id=101,
+        file_name=name,
+        size=sum(map(len, contents)),
+        path="/folder/file",
+        auth="scope&token",
+        parts=build_parts(contents),
+        **options,
+    )
+
+
+@pytest.mark.asyncio
+async def test_unicode_and_inert_html_join_across_part_boundaries():
+    contents = [b"caf\xc3", b"\xa9 \xe2", b"\x98\x83<script>bad()</script>"]
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await preview(pool, contents, "source.html")
+        assert result["kind"] == "text" and result["language"] == "html"
+        assert result["text"] == "café ☃<script>bad()</script>"
+        assert not result["truncated"]
+        assert client.fetches == [101, 102, 103]
+        assert client.closed == [101, 102, 103]
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_bounded_prefix_crosses_parts_without_fetching_unneeded_tail():
+    contents = [b"a" * (100 * 1024), b"b" * (200 * 1024), b"private-tail" * 100000]
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await preview(pool, contents)
+        assert (
+            result["text"] == (contents[0] + contents[1])[:TEXT_PREVIEW_BYTES].decode()
+        )
+        assert result["truncated"] and result["preview_bytes"] == TEXT_PREVIEW_BYTES
+        assert client.fetches == [101, 102]
+        assert client.reads == [(101, 0, 1), (102, 0, 1)]
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+def transport_packets():
+    return (b"\x47\x40\x00\x10" + b"\xff" * 184) * 6
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("binary", [True, False])
+async def test_ts_preview_sniffs_reassembled_packets_instead_of_extension(binary):
+    data = transport_packets() if binary else b"export const answer: number = 42;"
+    contents = [data[:3], data[3:190], data[190:]] if binary else [data[:8], data[8:]]
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await preview(pool, contents, "source.ts")
+        assert result["kind"] == ("video" if binary else "text")
+        if not binary:
+            assert (
+                result["language"] == "typescript" and result["text"] == data.decode()
+            )
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_pdf_descriptor_has_bounded_inline_url_without_telegram_fetch():
+    contents = [b"%PDF-", b"1.7 sample"]
+    result = await preview(object(), contents, "manual.pdf")
+    assert result["kind"] == "pdf"
+    assert parse_qs(urlsplit(result["url"]).query) == {
+        "path": ["/folder/file"],
+        "auth": ["scope&token"],
+        "preview": ["1"],
+    }
+    parts = build_parts(contents)
+    parts[-1]["size"] += PDF_PREVIEW_BYTES
+    result = await describe_preview(
+        pool=object(),
+        channel_id=-100,
+        message_id=101,
+        file_name="large.pdf",
+        size=PDF_PREVIEW_BYTES + 100,
+        path="/file",
+        auth=None,
+        parts=parts,
+    )
+    assert result["kind"] == "unsupported" and "url" not in result
+
+
+@pytest.mark.asyncio
+async def test_media_descriptor_has_only_logical_original_without_private_manifest():
+    contents = [b"first-video-bytes", b"second-video-bytes"]
+    result = await describe_media(
+        pool=object(),
+        channel_id=-100,
+        message_id=101,
+        file_name="movie.mp4",
+        size=sum(map(len, contents)),
+        parts=build_parts(contents),
+    )
+    assert result["variants"] == []
+    assert result["original"]["id"] == "original"
+    assert result["original"]["mime_type"] == "video/mp4"
+    assert result["original"]["size"] == sum(map(len, contents))
+    assert not {"parts", "message_id", "sha256", "document_id"}.intersection(
+        result["original"]
+    )
+
+
+@pytest.mark.asyncio
+async def test_missing_later_preview_part_releases_previous_and_failed_leases():
+    contents = [b"hello ", b"world"]
+    client = MultipartClient(contents)
+    client.contents.pop(102)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        with pytest.raises(TelegramFileNotFound):
+            await preview(pool, contents)
+        assert client.closed == [101]
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_cancelled_preview_prefix_closes_source_and_balances_pool():
+    contents = [b"hello ", b"world"]
+    client = MultipartClient(contents)
+    entered = asyncio.Event()
+
+    async def block(identity, _index):
+        if identity == 102:
+            entered.set()
+            await asyncio.Event().wait()
+
+    client.before_chunk = block
+    pool = ClientPool([client])
+    await pool.start()
+    task = asyncio.create_task(preview(pool, contents))
+    try:
+        await entered.wait()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert client.closed == [101, 102]
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+def test_http_multipart_owner_share_scope_stable_move_trash_and_revocation(
+    tmp_path, monkeypatch
+):
+    import hashlib
+
+    from fastapi.testclient import TestClient
+
+    from tests.support.app_fixtures import FakeRuntime, make_settings
+    from tgdrive.storage.store import DriveStore
+    from tgdrive.web.app import create_app
+
+    configured = make_settings(tmp_path)
+    store = DriveStore.create()
+    public = store.create_folder("/", "Shared")
+    shared_path = "/" + public["id"]
+    nested = store.create_folder(shared_path, "Nested")
+    nested_path = shared_path + "/" + nested["id"]
+    private = store.create_folder("/", "Private")
+    private_path = "/" + private["id"]
+    contents = [b"hello ", b"world"]
+    whole = b"".join(contents)
+    item = store.add_file(
+        shared_path,
+        "note.txt",
+        101,
+        len(whole),
+        parts=build_parts(contents),
+        sha256=hashlib.sha256(whole).hexdigest(),
+    )
+    original_path = shared_path + "/" + item["id"]
+    folder_token = store.create_share(shared_path)
+    file_token = store.create_share(original_path)
+    transport = MultipartClient(contents)
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, configured)
+    runtime.pool = ClientPool([transport])
+    app = create_app(configured, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            client.portal.call(runtime.pool.start)
+            try:
+                assert (
+                    client.get("/file", params={"path": original_path}).status_code
+                    == 403
+                )
+                for route in ("/api/v1/preview", "/api/v1/media"):
+                    assert (
+                        client.get(route, params={"path": original_path}).status_code
+                        == 403
+                    )
+                params = {"path": original_path, "auth": folder_token}
+                result = client.get("/file", params=params | {"download": "1"})
+                assert result.status_code == 200 and result.content == whole
+                assert (
+                    hashlib.sha256(result.content).hexdigest()
+                    == hashlib.sha256(whole).hexdigest()
+                )
+                assert result.headers["content-disposition"].startswith("attachment;")
+                descriptor = client.get("/api/v1/preview", params=params).json()
+                assert (
+                    descriptor["kind"] == "text" and descriptor["text"] == "hello world"
+                )
+                media = client.get("/api/v1/media", params=params).json()
+                assert (
+                    media["original"]["size"] == len(whole) and media["variants"] == []
+                )
+                assert not any(
+                    key in str(media)
+                    for key in ("message_id", "document_id", "parts", "sha256")
+                )
+                head = client.head(
+                    "/file", params=params, headers={"Range": "bytes=5-7"}
+                )
+                assert head.status_code == 206 and head.content == b""
+                assert head.headers["content-range"] == "bytes 5-7/11"
+                assert (
+                    client.get(
+                        "/file", params=params, headers={"Range": "bytes=5-7"}
+                    ).content
+                    == b" wo"
+                )
+                client.post(
+                    "/api/checkPassword", json={"pass": "correct horse battery staple"}
+                )
+                assert (
+                    client.get("/file", params={"path": original_path}).content == whole
+                )
+                store.move(original_path, nested_path)
+                # UUID resolution keeps old item URLs valid inside the shared subtree.
+                assert (
+                    client.get("/file", params={"path": original_path}).content == whole
+                )
+                client.post("/api/logout", json={})
+                assert client.get("/file", params=params).content == whole
+                current_path = nested_path + "/" + item["id"]
+                store.set_trashed(current_path, True)
+                assert client.get("/file", params=params).status_code == 403
+                store.set_trashed(current_path, False)
+                assert client.get("/file", params=params).content == whole
+                store.move(current_path, private_path)
+                for route in ("/file", "/api/v1/preview", "/api/v1/media"):
+                    assert client.get(route, params=params).status_code == 403
+                # A separate explicit file share follows that same file only.
+                assert (
+                    client.get(
+                        "/file", params={"path": original_path, "auth": file_token}
+                    ).status_code
+                    == 403
+                )
+                # Trash revoked the explicit file token; create a fresh scoped link.
+                moved_path = private_path + "/" + item["id"]
+                fresh = store.create_share(moved_path)
+                assert (
+                    client.get(
+                        "/file", params={"path": original_path, "auth": fresh}
+                    ).content
+                    == whole
+                )
+                store.revoke_share(moved_path)
+                assert (
+                    client.get(
+                        "/file", params={"path": original_path, "auth": fresh}
+                    ).status_code
+                    == 403
+                )
+                assert client.portal.call(runtime.pool.health).active_leases == 0
+            finally:
+                client.portal.call(runtime.pool.stop)
+    finally:
+        store.close()
+        runtime.transfers.registry.close()
diff --git a/tests/media/test_multipart_streaming.py b/tests/media/test_multipart_streaming.py
new file mode 100644
index 00000000..097b3f4d
--- /dev/null
+++ b/tests/media/test_multipart_streaming.py
@@ -0,0 +1,449 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from types import SimpleNamespace
+
+import pytest
+from starlette.requests import ClientDisconnect
+
+from tests.media.test_streaming import make_request, response_body
+from tgdrive.media.streaming import (
+    TelegramFileNotFound,
+    TelegramVariantNotFound,
+    stream_telegram_file,
+)
+from tgdrive.telegram.client_pool import ClientPool, NoClientAvailable
+
+CHUNK = 1024**2
+
+
+def build_parts(contents, *, identities=True):
+    result = []
+    offset = 0
+    for index, content in enumerate(contents):
+        part = {
+            "index": index,
+            "offset": offset,
+            "size": len(content),
+            "message_id": index + 101,
+            "sha256": hashlib.sha256(content).hexdigest(),
+        }
+        if identities:
+            part["document_id"] = index + 9001
+        result.append(part)
+        offset += len(content)
+    return result
+
+
+class MultipartClient:
+    def __init__(self, contents, *, name="multipart-test"):
+        self.contents = {index + 101: content for index, content in enumerate(contents)}
+        self.sizes = {
+            identity: len(content) for identity, content in self.contents.items()
+        }
+        self.document_ids = {
+            identity: identity - 101 + 9001 for identity in self.contents
+        }
+        self.name = name
+        self.is_connected = False
+        self.fetches = []
+        self.reads = []
+        self.closed = []
+        self.fetch_error = None
+        self.before_fetch = None
+        self.before_chunk = None
+
+    async def start(self):
+        self.is_connected = True
+
+    async def stop(self):
+        self.is_connected = False
+
+    async def get_messages(self, _channel, *, message_ids):
+        self.fetches.append(message_ids)
+        if self.before_fetch:
+            await self.before_fetch(message_ids)
+        if self.fetch_error:
+            raise self.fetch_error
+        if message_ids not in self.contents:
+            return None
+        return SimpleNamespace(
+            id=message_ids,
+            empty=False,
+            document=SimpleNamespace(
+                id=self.document_ids[message_ids],
+                file_size=self.sizes[message_ids],
+            ),
+        )
+
+    async def stream_media(self, message, *, offset, limit):
+        self.reads.append((message.id, offset, limit))
+        try:
+            for index in range(offset, offset + limit):
+                if self.before_chunk:
+                    await self.before_chunk(message.id, index)
+                content = self.contents[message.id][index * CHUNK : (index + 1) * CHUNK]
+                if not content:
+                    break
+                yield content
+        finally:
+            self.closed.append(message.id)
+
+
+async def stream(
+    pool,
+    contents,
+    range_header=None,
+    *,
+    method="GET",
+    name="movie.mp4",
+    parts=None,
+    **options,
+):
+    request = make_request(range_header)
+    request.scope["method"] = method
+    return await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=101,
+        parts=parts if parts is not None else build_parts(contents),
+        expected_size=sum(map(len, contents)),
+        file_name=name,
+        request=request,
+        **options,
+    )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "selection",
+    [
+        None,
+        "bytes=0-0",
+        f"bytes={CHUNK - 1}-{CHUNK + 1}",
+        f"bytes={CHUNK + 15}-{CHUNK + 20}",
+        f"bytes={CHUNK + 17}-{CHUNK + 17}",
+        "bytes=-9",
+        "bytes=5-",
+        "bytes=0-999999999",
+    ],
+)
+async def test_logical_ranges_are_byte_exact_across_chunk_and_part_boundaries(
+    selection,
+):
+    from tgdrive.media.ranges import parse_byte_range
+
+    contents = [
+        bytes(range(256)) * 4096 + b"FIRST-PART-END!!!?",
+        b"second-part-body",
+        b"tail-data",
+    ]
+    whole = b"".join(contents)
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        response = await stream(pool, contents, selection)
+        selected = parse_byte_range(selection, len(whole))
+        body = await response_body(response)
+        assert body == whole[selected.start : selected.end + 1]
+        assert int(response.headers["content-length"]) == selected.length
+        assert response.status_code == (206 if selection else 200)
+        if selection:
+            assert response.headers["content-range"] == selected.content_range
+        assert (
+            hashlib.sha256(body).digest()
+            == hashlib.sha256(whole[selected.start : selected.end + 1]).digest()
+        )
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_boundary_range_reads_only_intersecting_part_and_head_never_streams():
+    contents = [b"abc", b"defg", b"hij"]
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        response = await stream(pool, contents, "bytes=3-6")
+        assert await response_body(response) == b"defg"
+        assert client.fetches == [102] and client.reads == [(102, 0, 1)]
+        client.fetches.clear()
+        client.reads.clear()
+        response = await stream(pool, contents, "bytes=-3", method="HEAD")
+        assert response.status_code == 206
+        assert response.headers["content-range"] == "bytes 7-9/10"
+        assert response.body == b"" and response.headers["content-length"] == "3"
+        assert client.fetches == [103] and client.reads == []
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("header", "status"),
+    [
+        ("bytes=10-", 416),
+        ("bytes=5-4", 416),
+        ("bytes=-0", 416),
+        ("bytes=0-1,3-4", 400),
+        ("garbage", 400),
+    ],
+)
+async def test_invalid_ranges_are_rejected_before_any_telegram_rpc(header, status):
+    contents = [b"abc", b"defg", b"hij"]
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await stream(pool, contents, header)
+        assert result.status_code == status
+        assert not client.fetches and not client.reads
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["missing", "size", "replacement"])
+async def test_bad_first_part_is_rejected_before_response_headers(failure):
+    contents = [b"abc", b"def"]
+    client = MultipartClient(contents)
+    if failure == "missing":
+        client.contents.pop(101)
+    elif failure == "size":
+        client.sizes[101] += 1
+    else:
+        client.document_ids[101] += 1
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        with pytest.raises(TelegramFileNotFound):
+            await stream(pool, contents)
+        assert not client.reads and (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["missing", "size", "short", "checksum"])
+async def test_late_part_failure_cannot_satisfy_content_length_and_releases_all(
+    failure,
+):
+    contents = [b"abc", b"defgh"]
+    client = MultipartClient(contents)
+    if failure == "missing":
+        client.contents.pop(102)
+    elif failure == "size":
+        client.sizes[102] += 1
+    elif failure == "short":
+        client.contents[102] = b"def"
+    else:
+        client.contents[102] = b"WRONG"  # Same size, same document id: byte corruption.
+    pool = ClientPool([client])
+    await pool.start()
+    received = bytearray()
+    try:
+        response = await stream(pool, contents)
+        with pytest.raises(OSError):
+            async for chunk in response.body_iterator:
+                received.extend(chunk)
+        assert len(received) < int(response.headers["content-length"])
+        assert client.closed[0] == 101
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_partial_range_uses_immutable_identity_without_hashing_unread_bytes():
+    contents = [b"x" * (3 * CHUNK), b"tail"]
+    parts = build_parts(contents)
+    parts[0]["sha256"] = "0" * 64
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await stream(pool, contents, "bytes=2-5", parts=parts)
+        assert await response_body(result) == b"xxxx"
+        assert client.reads == [(101, 0, 1)]
+        assert client.fetches == [101]
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("at_header", [True, False])
+async def test_asgi_send_failure_closes_unstarted_or_started_body_and_releases(
+    at_header,
+):
+    contents = [b"a" * (2 * CHUNK), b"tail"]
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        response = await stream(pool, contents)
+
+        async def send(message):
+            if (message["type"] == "http.response.start") == at_header:
+                raise OSError("synthetic browser disconnect")
+
+        async def receive():
+            return {"type": "http.disconnect"}
+
+        with pytest.raises(ClientDisconnect):
+            await response(
+                {"type": "http", "asgi": {"spec_version": "2.4"}}, receive, send
+            )
+        assert (await pool.health()).active_leases == 0
+        if not at_header:
+            assert client.closed == [101]
+        assert 102 not in client.fetches
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("phase", ["metadata", "body"])
+async def test_cancellation_at_metadata_or_second_part_drains_leases(phase):
+    contents = [b"abc", b"def"]
+    client = MultipartClient(contents)
+    entered = asyncio.Event()
+
+    async def block(identity, *_args):
+        if identity == (101 if phase == "metadata" else 102):
+            entered.set()
+            await asyncio.Event().wait()
+
+    if phase == "metadata":
+        client.before_fetch = block
+    else:
+        client.before_chunk = block
+    pool = ClientPool([client])
+    await pool.start()
+
+    async def consume():
+        response = await stream(pool, contents)
+        return await response_body(response)
+
+    task = asyncio.create_task(consume())
+    try:
+        await entered.wait()
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert (await pool.health()).active_leases == 0
+        if phase == "body":
+            assert client.closed == [101, 102]
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_premium_fallback_and_unavailable_bot_preserve_original_failure():
+    contents = [b"abc", b"def"]
+    premium = MultipartClient(contents, name="premium")
+    premium.fetch_error = PermissionError("channel unavailable to optional account")
+    bot = MultipartClient(contents, name="bot")
+    pool = ClientPool([bot], [premium])
+    await pool.start()
+    try:
+        response = await stream(pool, contents)
+        assert await response_body(response) == b"abcdef"
+        assert len(bot.fetches) == 2 and len(premium.fetches) == 2
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+    pool = ClientPool([], [premium])
+    await pool.start()
+    try:
+        with pytest.raises(NoClientAvailable):
+            await stream(pool, contents)
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_download_forces_original_and_active_content_stays_attachment():
+    contents = [b"<script>", b"bad()</script>"]
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        with pytest.raises(TelegramVariantNotFound):
+            await stream(pool, contents, quality="invented")
+        assert not client.fetches
+        result = await stream(
+            pool, contents, name="unsafe.html", download=True, quality="invented"
+        )
+        assert result.headers["content-disposition"].startswith("attachment;")
+        assert result.headers["content-security-policy"].startswith("sandbox")
+        assert await response_body(result) == b"".join(contents)
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_full_part_checksum_withholds_final_block_after_prior_blocks_were_sent():
+    contents = [b"a" * (2 * CHUNK), b"tail"]
+    client = MultipartClient(contents)
+    client.contents[101] = b"a" * CHUNK + b"X" * CHUNK
+    pool = ClientPool([client])
+    await pool.start()
+    received = bytearray()
+    try:
+        response = await stream(pool, contents)
+        with pytest.raises(OSError, match="checksum"):
+            async for chunk in response.body_iterator:
+                received.extend(chunk)
+        assert bytes(received) == b"a" * CHUNK
+        assert len(received) < int(response.headers["content-length"])
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("download", [False, True])
+async def test_multipart_pdf_cap_is_preview_only_and_head_never_reads_payload(download):
+    contents = [b"first", b"last"]
+    parts = build_parts(contents)
+    from tgdrive.media.streaming import PDF_PREVIEW_BYTES
+
+    cap_chunks = PDF_PREVIEW_BYTES // CHUNK
+    parts[0]["size"] = cap_chunks * CHUNK
+    parts[1].update(offset=cap_chunks * CHUNK, size=CHUNK)
+    client = MultipartClient(contents)
+    client.sizes.update({101: cap_chunks * CHUNK, 102: CHUNK})
+    pool = ClientPool([client])
+    await pool.start()
+    request = make_request()
+    request.scope["method"] = "HEAD"
+    try:
+        response = await stream_telegram_file(
+            pool=pool,
+            channel_id=-100,
+            message_id=101,
+            file_name="large.pdf",
+            expected_size=(cap_chunks + 1) * CHUNK,
+            parts=parts,
+            request=request,
+            preview=True,
+            download=download,
+        )
+        assert response.status_code == (200 if download else 413)
+        assert not client.reads
+        if download:
+            assert response.headers["content-length"] == str((cap_chunks + 1) * CHUNK)
+            assert response.headers["content-disposition"].startswith("attachment;")
+        else:
+            assert not client.fetches
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
diff --git a/tests/media/test_pdf_range_policy.py b/tests/media/test_pdf_range_policy.py
new file mode 100644
index 00000000..26bd4343
--- /dev/null
+++ b/tests/media/test_pdf_range_policy.py
@@ -0,0 +1,52 @@
+"""PDF preview purpose retains demand bytes without bulk preload admission."""
+
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+from tests.media.test_multipart_streaming import MultipartClient, build_parts
+from tests.media.test_streaming import FakeStreamClient, make_request, response_body
+from tgdrive.media.streaming import stream_telegram_file
+from tgdrive.telegram.client_pool import ClientPool
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("multipart", [False, True])
+@pytest.mark.parametrize("download", [False, True])
+async def test_pdf_preview_and_download_do_not_start_extra_preloading(
+    multipart, download
+):
+    contents = [b"A" * 3 * 1024**2, b"B" * 3 * 1024**2]
+    client = (
+        MultipartClient(contents) if multipart else FakeStreamClient(b"".join(contents))
+    )
+    pool = ClientPool([client])
+    manager = SimpleNamespace(
+        register_file=Mock(),
+        observe=Mock(return_value="pdf-file"),
+        begin=Mock(),
+        delivered=Mock(),
+        finished=Mock(),
+    )
+    pool._preload_manager = manager
+    await pool.start()
+    try:
+        response = await stream_telegram_file(
+            pool=pool,
+            channel_id=-100,
+            message_id=101 if multipart else 7,
+            file_name="book.pdf",
+            expected_size=6 * 1024**2,
+            request=make_request("bytes=0-4194303"),
+            preview=True,
+            download=download,
+            parts=build_parts(contents) if multipart else None,
+        )
+        assert response.status_code == 206
+        assert await response_body(response) == b"".join(contents)[: 4 * 1024**2]
+        manager.observe.assert_not_called()
+        manager.delivered.assert_not_called()
+        manager.register_file.assert_called_once()
+    finally:
+        await pool.stop()
diff --git a/tests/media/test_pooled_media.py b/tests/media/test_pooled_media.py
new file mode 100644
index 00000000..6b7aa1d5
--- /dev/null
+++ b/tests/media/test_pooled_media.py
@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon.errors import FloodPremiumWaitError, FloodWaitError
+
+from tests.media.test_streaming import make_request, response_body
+from tests.media.test_telegram_cache import MIB, Native, message, transport
+from tgdrive.media.media_cache import DiskMediaCache
+from tgdrive.media.media_reader import MediaReadCache, stream_pooled_media
+from tgdrive.media.streaming import stream_telegram_file
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+
+
+def account(name, payload, gate=None, native_type=Native):
+    native = native_type({1: payload}, gate)
+    client = transport(native, name)
+    client.start = AsyncMock()
+    client.stop = AsyncMock()
+    native.is_connected = lambda: True
+    client.get_messages = AsyncMock(
+        side_effect=lambda *_args, **_kwargs: TelegramMessage(
+            client, message(1, len(payload))
+        )
+    )
+    return client
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "unavailable", [None, "busy", "cooling", "unhealthy", "disconnected"]
+)
+async def test_payload_prefers_ready_premium_with_bot_fallback(unavailable):
+    payload = b"original payload"
+    bot, user = account("bot", payload), account("premium", payload)
+    pool = ClientPool([bot], [user], media_per_bot=1)
+    await pool.start()
+    occupied = None
+    try:
+        if unavailable == "busy":
+            occupied = pool.lease(
+                download=True, allow_users=True, client_name=user.name
+            )
+            await occupied.__aenter__()
+        elif unavailable == "cooling":
+            await pool.defer_client(user.name, time.time() + 60)
+        elif unavailable == "unhealthy":
+            await pool.mark_unhealthy(user)
+        elif unavailable == "disconnected":
+            user.native.is_connected = lambda: False
+        response = await stream_telegram_file(
+            pool=pool,
+            channel_id=-100123,
+            message_id=77,
+            file_name="data.bin",
+            expected_size=len(payload),
+            request=make_request(),
+        )
+        assert await asyncio.wait_for(response_body(response), 2) == payload
+        assert bool(user.native.requests) is (unavailable is None)
+        assert bool(bot.native.requests) is (unavailable is not None)
+    finally:
+        if occupied is not None:
+            await occupied.__aexit__(None, None, None)
+        assert all(row.active_leases == 0 for row in await pool.status())
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_all_accounts_share_ordered_reads_and_repeated_ranges_hit_cache(tmp_path):
+    payload = b"".join(bytes([i]) * MIB for i in range(12)) + b"tail"
+    accounts = [account(str(i), payload) for i in range(3)]
+    pool = ClientPool(accounts, media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+
+        async def request():
+            return await stream_telegram_file(
+                pool=pool,
+                channel_id=-100123,
+                message_id=77,
+                file_name="video.mkv",
+                expected_size=len(payload),
+                request=make_request(),
+            )
+
+        assert await response_body(await request()) == payload
+        assert all(client.native.requests for client in accounts)
+        assert all(client.native.peak <= 3 for client in accounts)
+        assert all(client.native.active == 0 for client in accounts)
+        reads = sum(sum(client.native.requests.values()) for client in accounts)
+        assert reads == 25  # One remote fetch per block, exact final tail.
+        # Rotate the metadata account, then discard RAM; both caches are shared.
+        assert await response_body(await request()) == payload
+        pool._media_read_cache = MediaReadCache(tmp_path)
+        assert await response_body(await request()) == payload
+        assert sum(sum(client.native.requests.values()) for client in accounts) == reads
+        assert len(list(tmp_path.glob("*.block"))) == 13
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_two_same_bot_responses_do_not_deadlock_or_duplicate_remote_reads():
+    payload = b"x" * (6 * MIB)
+    client = account("only", payload)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+
+        async def request():
+            response = await stream_telegram_file(
+                pool=pool,
+                channel_id=-100123,
+                message_id=77,
+                file_name="video.mkv",
+                expected_size=len(payload),
+                request=make_request(),
+            )
+            return await response_body(response)
+
+        a, b = await asyncio.wait_for(asyncio.gather(request(), request()), 2)
+        assert a == b == payload
+        assert sum(client.native.requests.values()) == 12
+        assert client.native.peak <= 3
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_read_ahead_is_bounded_and_disconnect_drains_workers():
+    payload = b"x" * (64 * MIB)
+    clients = [account(str(i), payload) for i in range(3)]
+    pool = ClientPool(clients)
+    await pool.start()
+    iterator = stream_pooled_media(
+        pool,
+        clients[0],
+        await clients[0].get_messages(1, message_ids=77),
+        channel=1,
+        offset=0,
+        limit=64,
+    )
+    try:
+        assert await anext(iterator) == payload[:MIB]
+        await asyncio.sleep(0.03)
+        fetched = sum(sum(c.native.requests.values()) for c in clients)
+        # A new response probes one block ahead until the consumer demonstrates
+        # sustained demand. Each MiB uses two native Telegram requests here.
+        assert fetched == 4
+        await iterator.aclose()
+        assert all(c.native.active == 0 for c in clients)
+        assert all(row.active_leases == 0 for row in await pool.status())
+        assert not pool._media_read_cache.memory.flights
+    finally:
+        await iterator.aclose()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("flood_error", [FloodWaitError, FloodPremiumWaitError])
+async def test_flood_wait_defers_account_and_other_account_continues(flood_error):
+    class Flooded(Native):
+        def iter_download(self, *args, **kwargs):
+            raise flood_error(request=None, capture=60)
+
+    payload = b"x" * (4 * MIB)
+    flooded = account("flooded", payload, native_type=Flooded)
+    healthy = account("healthy", payload)
+    pool = ClientPool([flooded, healthy])
+    await pool.start()
+    try:
+        response = await stream_telegram_file(
+            pool=pool,
+            channel_id=-100123,
+            message_id=77,
+            file_name="video.mkv",
+            expected_size=len(payload),
+            request=make_request(),
+        )
+        assert await asyncio.wait_for(response_body(response), 2) == payload
+        assert await pool.account_retry_at("flooded") > time.time() + 50
+        assert healthy.native.requests and healthy.native.peak <= 3
+    finally:
+        await pool.stop()
+
+
+def test_disk_cache_survives_restart_evicts_and_rejects_corruption(tmp_path):
+    cache = DiskMediaCache(tmp_path, max_bytes=70, max_entries=2)
+    cache.write(("a",), b"aaa")
+    cache.write(("b",), b"bbb")
+    assert cache.read(("a",), 3) == b"aaa"
+    cache.write(("c",), b"ccc")
+    assert cache.read(("b",), 3) is None
+    restarted = DiskMediaCache(tmp_path, max_bytes=70, max_entries=2)
+    assert restarted.read(("a",), 3) == b"aaa"
+    path = tmp_path / (cache._key(("a",)) + ".block")
+    path.write_bytes(b"z" * 35)
+    assert restarted.read(("a",), 3) is None
+    assert not path.exists()
+    assert tmp_path.stat().st_mode & 0o777 == 0o700
+
+
+def test_disk_cache_expiry_and_unavailable_path_are_safe(tmp_path):
+    cache = DiskMediaCache(tmp_path / "cache", ttl=0.001)
+    cache.write(("expired",), b"abc")
+    time.sleep(0.005)
+    assert cache.read(("expired",), 3) is None
+    blocked = tmp_path / "not-a-directory"
+    blocked.write_text("blocked")
+    unavailable = DiskMediaCache(blocked)
+    assert unavailable.read(("a",), 3) is None
+    unavailable.write(("a",), b"abc")
+
+
+@pytest.mark.asyncio
+async def test_multipart_boundary_and_cached_reads_still_validate_message():
+    from tests.media.test_multipart_streaming import build_parts
+    from tgdrive.media.streaming import TelegramFileNotFound
+
+    contents = [b"a" * (3 * MIB), b"b" * (3 * MIB)]
+    clients = [account(str(i), b"") for i in range(3)]
+    for client in clients:
+        client.native.payloads = {9001: contents[0], 9002: contents[1]}
+
+        def fetch(_channel, *, message_ids, owner=client):
+            index = message_ids - 101
+            native = message(9001 + index, len(contents[index]))
+            native.id = message_ids
+            return TelegramMessage(owner, native)
+
+        client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool(clients)
+    await pool.start()
+    try:
+
+        async def request():
+            return await stream_telegram_file(
+                pool=pool,
+                channel_id=-100123,
+                message_id=101,
+                parts=build_parts(contents),
+                file_name="movie.mkv",
+                expected_size=6 * MIB,
+                request=make_request(f"bytes={3 * MIB - 5}-{3 * MIB + 9}"),
+            )
+
+        assert await response_body(await request()) == b"a" * 5 + b"b" * 10
+        before = sum(sum(c.native.requests.values()) for c in clients)
+        assert await response_body(await request()) == b"a" * 5 + b"b" * 10
+        assert sum(sum(c.native.requests.values()) for c in clients) == before
+        for client in clients:
+            client.get_messages = AsyncMock(return_value=None)
+        with pytest.raises(TelegramFileNotFound):
+            await request()
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_cooling_premium_metadata_uses_idle_bot():
+    bot, user = account("bot", b"data"), account("premium", b"data")
+    pool = ClientPool([bot], [user])
+    await pool.start()
+    try:
+        await pool.defer_client("premium", time.time() + 60)
+
+        async def acquire():
+            async with pool.lease(prefer_premium=True, respect_cooldown=True) as chosen:
+                assert chosen is bot
+
+        await asyncio.wait_for(acquire(), 0.5)
+    finally:
+        await pool.stop()
diff --git a/tests/media/test_preload_api.py b/tests/media/test_preload_api.py
new file mode 100644
index 00000000..b3e9ee01
--- /dev/null
+++ b/tests/media/test_preload_api.py
@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.media.test_multipart_streaming import build_parts
+from tests.media.test_pooled_media import account
+from tests.media.test_telegram_cache import message
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.media.media_reader import BLOCK
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+from tgdrive.web.app import create_app
+
+
+class MediaRuntime(FakeRuntime):
+    async def start(self):
+        await self.pool.start()
+        await super().start()
+
+    async def stop(self):
+        try:
+            if hasattr(self, "preloads"):
+                await self.preloads.close()
+        finally:
+            await self.pool.stop()
+            await super().stop()
+
+
+@pytest.mark.parametrize("multipart", [False, True])
+def test_manual_preload_api_caches_entire_original_for_download_and_seek(
+    tmp_path, multipart, monkeypatch
+):
+    settings = make_settings(tmp_path)
+    settings.storage_channel = -1000000000123
+    settings.auto_preload = False
+    contents = [b"a" * (2 * BLOCK + 77), b"b" * (BLOCK + 13)]
+    payload = b"".join(contents)
+    telegram = account("bot", payload)
+    telegram.configure_transport = Mock()
+    parts = build_parts(contents) if multipart else None
+    if parts:
+        telegram.native.payloads = {9001: contents[0], 9002: contents[1]}
+
+        async def fetch(_channel, *, message_ids):
+            part = parts[message_ids - 101]
+            native = message(part["document_id"], part["size"])
+            native.id = message_ids
+            return TelegramMessage(telegram, native)
+
+        telegram.get_messages = AsyncMock(side_effect=fetch)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    item = store.add_file(
+        "/",
+        "movie.mp4",
+        parts[0]["message_id"] if parts else 77,
+        len(payload),
+        parts=parts,
+    )
+    path = "/" + item["id"]
+    runtime = MediaRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    runtime.pool = ClientPool([telegram], media_cache_dir=settings.cache_dir)
+    app = create_app(settings, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            login(client)
+            prepared = client.post("/api/v1/preloads", json={"path": path})
+            assert prepared.status_code == 202, prepared.text
+            assert prepared.headers["cache-control"] == "no-store"
+            job = prepared.json()
+            assert job["mode"] == "manual"
+            assert job["start"] == 0 and job["end"] == len(payload)
+            assert job["target_bytes"] == len(payload)
+
+            async def finish():
+                task = runtime.preloads._tasks.get(job["id"])
+                if task is not None:
+                    await asyncio.wait_for(asyncio.shield(task), 5)
+
+            client.portal.call(finish)
+            state = client.get("/api/v1/preloads").json()
+            assert state["jobs"][0]["state"] == "ready", state
+            cached = state["cache"]["files"][0]
+            assert cached["complete"]
+            assert cached["ready_ranges"] == [[0, len(payload)]]
+            reads = telegram.native.requests.copy()
+            assert reads
+            # Preloading is private server work and never creates a public link.
+            assert store.list_shares() == []
+            downloaded = client.get("/file", params={"path": path, "download": True})
+            assert downloaded.status_code == 200
+            assert downloaded.content == payload
+            assert "attachment" in downloaded.headers["content-disposition"]
+            start, end = len(contents[0]) - 10, len(contents[0]) + 9
+            seek = client.get(
+                "/file",
+                params={"path": path},
+                headers={"Range": f"bytes={start}-{end}"},
+            )
+            assert seek.status_code == 206
+            assert (
+                seek.headers["content-range"] == f"bytes {start}-{end}/{len(payload)}"
+            )
+            assert seek.content == payload[start : end + 1]
+            assert telegram.native.requests == reads
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
+
+
+def test_preload_rejects_disabled_cache_but_direct_download_still_works(
+    tmp_path, monkeypatch
+):
+    settings = make_settings(tmp_path)
+    settings.storage_channel = -1000000000123
+    settings.cache_memory_bytes = settings.cache_disk_bytes = 0
+    payload = b"original file bytes"
+    telegram = account("bot", payload)
+    telegram.configure_transport = Mock()
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    item = store.add_file("/", "hello.txt", 77, len(payload))
+    path = "/" + item["id"]
+    runtime = MediaRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    runtime.pool = ClientPool([telegram], media_cache_dir=settings.cache_dir)
+    app = create_app(settings, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            login(client)
+            prepared = client.post("/api/v1/preloads", json={"path": path})
+            assert prepared.status_code == 409
+            assert "budget" in prepared.json()["detail"]
+            assert not telegram.native.requests
+            assert client.get("/api/v1/preloads").json()["jobs"] == []
+            download = client.get("/file", params={"path": path, "download": True})
+            assert download.status_code == 200
+            assert download.content == payload
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/media/test_preloading.py b/tests/media/test_preloading.py
new file mode 100644
index 00000000..901be36d
--- /dev/null
+++ b/tests/media/test_preloading.py
@@ -0,0 +1,1157 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from tests.media.test_pooled_media import account
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import BLOCK, stream_pooled_media
+from tgdrive.media.preloading import PreloadCapacityError, PreloadManager
+from tgdrive.telegram.client_pool import ClientPool
+
+CHANNEL = -1000000000123
+
+
+async def manager_for(tmp_path, payload, gate=None, **changes):
+    client = account("bot", payload, gate)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    policy = MediaCachePolicy(
+        **(
+            {
+                "memory_max_bytes": 8 * BLOCK,
+                "disk_max_bytes": 32 * BLOCK,
+                "min_free_bytes": 0,
+            }
+            | changes
+        )
+    )
+    return PreloadManager(pool, policy=policy), pool, client
+
+
+async def finish(manager, job):
+    task = manager._tasks.get(job["id"])
+    if task is not None:
+        await asyncio.wait_for(asyncio.shield(task), 3)
+    return manager._jobs[job["id"]]
+
+
+@pytest.mark.asyncio
+async def test_manual_prepare_ready_and_foreground_reuses_every_block(tmp_path):
+    payload = b"a" * (6 * BLOCK) + b"tail"
+    manager, pool, client = await manager_for(tmp_path, payload)
+    try:
+        job = await manager.prepare(
+            channel_id=CHANNEL, message_id=77, size=len(payload), name="movie.mp4"
+        )
+        assert (await finish(manager, job))["state"] == "ready"
+        state = await manager.snapshot()
+        row = state["cache"]["files"][0]
+        assert row["complete"] and row["ready_ranges"] == [[0, len(payload)]]
+        requests = sum(client.native.requests.values())
+        message = await client.get_messages(CHANNEL, message_ids=77)
+        stream = stream_pooled_media(
+            pool, client, message, channel=CHANNEL, offset=0, limit=7
+        )
+        assert b"".join([chunk async for chunk in stream]) == payload
+        assert sum(client.native.requests.values()) == requests
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_cancel_preload_preserves_other_viewer_shared_fills(tmp_path):
+    gate = asyncio.Event()
+    payload = b"x" * (3 * BLOCK)
+    manager, pool, client = await manager_for(tmp_path, payload, gate)
+    try:
+        job = await manager.prepare(
+            channel_id=CHANNEL, message_id=77, size=len(payload)
+        )
+        for _ in range(100):
+            if client.native.active:
+                break
+            await asyncio.sleep(0.001)
+        message = await client.get_messages(CHANNEL, message_ids=77)
+
+        async def consume():
+            stream = stream_pooled_media(
+                pool, client, message, channel=CHANNEL, offset=0, limit=3
+            )
+            return b"".join([chunk async for chunk in stream])
+
+        reader = asyncio.create_task(consume())
+        for _ in range(100):
+            if any(
+                flight.waiters > 1 for flight in manager.cache.memory.flights.values()
+            ):
+                break
+            await asyncio.sleep(0.001)
+        assert any(
+            flight.waiters > 1 for flight in manager.cache.memory.flights.values()
+        )
+        assert (await manager.cancel(job["id"]))["state"] == "cancelled"
+        gate.set()
+        assert await asyncio.wait_for(reader, 3) == payload
+        assert sum(client.native.requests.values()) == 6
+        assert all(status.active_leases == 0 for status in await pool.status())
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_head_and_metadata_observation_never_trigger_preload(tmp_path):
+    manager, pool, client = await manager_for(
+        tmp_path, b"x" * (8 * BLOCK), auto_preload=True
+    )
+    try:
+        manager.observe(
+            channel_id=CHANNEL, message_id=77, size=8 * BLOCK, method="HEAD"
+        )
+        for index in range(5):
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        await asyncio.sleep(0)
+        assert not manager._jobs and not manager._auto_tasks
+        assert not client.native.requests
+        manager.observe(channel_id=CHANNEL, message_id=77, size=8 * BLOCK, method="GET")
+        await asyncio.sleep(0)
+        assert not manager._jobs
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_one_viewer_replaying_a_segment_does_not_promote_whole_file(tmp_path):
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (8 * BLOCK), auto_preload=True
+    )
+    try:
+        identity = manager.observe(channel_id=CHANNEL, message_id=77, size=8 * BLOCK)
+        manager.begin(identity, None)
+        for index in range(3):
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        await asyncio.sleep(0)
+        assert not manager._jobs
+        manager.delivered(
+            channel_id=CHANNEL, message_id=77, offset=3 * BLOCK, length=BLOCK
+        )
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        job = next(iter(manager._jobs.values()))
+        assert job["mode"] == "auto" and job["target_bytes"] == BLOCK
+        assert (await finish(manager, job))["state"] == "ready"
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        await asyncio.sleep(0)
+        assert len(manager._jobs) == 1
+        assert manager._observed[identity]["hot_until"] == 0
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_manual_whole_file_refuses_capacity_and_combined_reservations(tmp_path):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (6 * BLOCK), gate, memory_max_bytes=0, disk_max_bytes=8 * BLOCK
+    )
+    try:
+        with pytest.raises(PreloadCapacityError, match="budget"):
+            await manager.prepare(channel_id=CHANNEL, message_id=77, size=9 * BLOCK)
+        await manager.prepare(channel_id=CHANNEL, message_id=77, size=6 * BLOCK)
+        with pytest.raises(PreloadCapacityError, match="reserved"):
+            await manager.prepare(channel_id=CHANNEL, message_id=88, size=6 * BLOCK)
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_disk_failure_never_claims_whole_file_ready(tmp_path, monkeypatch):
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (4 * BLOCK), memory_max_bytes=0
+    )
+    monkeypatch.setattr(manager.cache.disk, "write", lambda *args: False)
+    try:
+        job = await manager.prepare(channel_id=CHANNEL, message_id=77, size=4 * BLOCK)
+        row = await finish(manager, job)
+        assert row["state"] == "failed" and "capacity" in row["error"].lower()
+        assert (await manager.snapshot())["cache"]["files"] == []
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_revoke_during_preparation_stops_with_no_leaked_leases(tmp_path):
+    manager, pool, _client = await manager_for(tmp_path, b"x" * (8 * BLOCK))
+    calls = 0
+
+    async def authorize():
+        nonlocal calls
+        calls += 1
+        if calls >= 5:
+            raise PermissionError("Share was revoked")
+
+    try:
+        job = await manager.prepare(
+            channel_id=CHANNEL, message_id=77, size=8 * BLOCK, authorize=authorize
+        )
+        row = await finish(manager, job)
+        assert row["state"] == "failed" and "revoked" in row["error"]
+        assert all(status.active_leases == 0 for status in await pool.status())
+        assert not manager.cache.memory.flights
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_budget_shrink_during_preparation_is_not_false_ready(tmp_path):
+    gate = asyncio.Event()
+    manager, pool, client = await manager_for(tmp_path, b"x" * (4 * BLOCK), gate)
+    try:
+        job = await manager.prepare(channel_id=CHANNEL, message_id=77, size=4 * BLOCK)
+        for _ in range(100):
+            if client.native.active:
+                break
+            await asyncio.sleep(0.001)
+        await manager.reconfigure(
+            MediaCachePolicy(memory_max_bytes=0, disk_max_bytes=0, min_free_bytes=0)
+        )
+        gate.set()
+        row = await finish(manager, job)
+        assert row["state"] == "failed"
+        state = await manager.snapshot()
+        assert state["cache"]["files"] == []
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_far_seek_cancels_obsolete_automatic_ahead_job(tmp_path):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path,
+        b"x" * (64 * BLOCK),
+        gate,
+        memory_max_bytes=4 * BLOCK,
+        disk_max_bytes=16 * BLOCK,
+        auto_preload=True,
+    )
+    try:
+        identity = manager.observe(channel_id=CHANNEL, message_id=77, size=64 * BLOCK)
+        manager.begin(identity, None)
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        row = next(iter(manager._jobs.values()))
+        assert row["target_bytes"] == BLOCK
+        manager.delivered(
+            channel_id=CHANNEL, message_id=77, offset=48 * BLOCK, length=BLOCK
+        )
+        task = manager._tasks.get(row["id"])
+        if task is not None:
+            await asyncio.gather(task, return_exceptions=True)
+        assert row["state"] == "cancelled"
+        assert not manager.cache.memory.flights
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_explicit_full_prepare_can_replace_old_protected_bytes(tmp_path):
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (8 * BLOCK), memory_max_bytes=0, disk_max_bytes=10 * BLOCK
+    )
+    try:
+        for index in range(6):
+            old = (CHANNEL, 88, "document", 999, 6 * BLOCK, index)
+            manager.cache.disk.write(old, b"o" * BLOCK)
+            manager.cache.disk.promote(old)
+        job = await manager.prepare(channel_id=CHANNEL, message_id=77, size=8 * BLOCK)
+        assert (await finish(manager, job))["state"] == "ready"
+        assert (await manager.snapshot())["cache"]["files"][0]["complete"]
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_first_cold_view_only_preloads_ahead_and_stops_when_viewer_leaves(
+    tmp_path,
+):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path,
+        b"x" * (64 * BLOCK),
+        gate,
+        disk_max_bytes=256 * BLOCK,
+        auto_preload=True,
+    )
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=64 * BLOCK, request_id="first-view"
+        )
+        manager.begin(identity, "first-view")
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL,
+                message_id=77,
+                offset=index * BLOCK,
+                length=BLOCK,
+                request_id="first-view",
+            )
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        row = next(iter(manager._jobs.values()))
+        assert BLOCK <= row["target_bytes"] <= 128 * BLOCK
+        assert row["target_bytes"] < row["size"]
+        manager.finished(identity, "first-view")
+        task = manager._tasks.get(row["id"])
+        if task is not None:
+            await asyncio.gather(task, return_exceptions=True)
+        assert row["state"] == "cancelled"
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "interval,fill,window", [(1, 2, 8), (1, 0.5, 16), (0.05, 40, 60)]
+)
+async def test_ahead_window_uses_consumption_and_fill_speed(
+    tmp_path, interval, fill, window
+):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path,
+        b"x" * (64 * BLOCK),
+        gate,
+        disk_max_bytes=256 * BLOCK,
+        auto_preload=True,
+    )
+    now = [0.0]
+    manager._clock = lambda: now[0]
+    try:
+        identity = manager.observe(channel_id=CHANNEL, message_id=77, size=64 * BLOCK)
+        manager._observed[identity]["fill_rate"] = fill * BLOCK
+        manager.begin(identity, None)
+        for index in range(4):
+            now[0] = index * interval
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        row = next(iter(manager._jobs.values()))
+        assert row["start"] == 4 * BLOCK
+        assert row["target_bytes"] == window * BLOCK
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_two_qualified_overlapping_viewers_earn_full_completion(tmp_path):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (8 * BLOCK), gate, auto_preload=True
+    )
+    try:
+        identity = None
+        for viewer in ("friend-one", "friend-two"):
+            identity = manager.observe(
+                channel_id=CHANNEL, message_id=77, size=8 * BLOCK, request_id=viewer
+            )
+            manager.begin(identity, viewer)
+            for index in range(4):
+                manager.delivered(
+                    channel_id=CHANNEL,
+                    message_id=77,
+                    offset=index * BLOCK,
+                    length=BLOCK,
+                    request_id=viewer,
+                )
+            for _ in range(100):
+                expected = 1 if viewer == "friend-one" else 2
+                if len(manager._jobs) >= expected:
+                    break
+                await asyncio.sleep(0.001)
+        full = list(manager._jobs.values())[-1]
+        assert full["target_bytes"] == 8 * BLOCK
+        manager.finished(identity, "friend-one")
+        manager.finished(identity, "friend-two")
+        gate.set()
+        assert (await finish(manager, full))["state"] == "ready"
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_manual_prepare_exact_ram_budget_does_not_charge_disk_digest_overhead(
+    tmp_path,
+):
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (4 * BLOCK), memory_max_bytes=4 * BLOCK, disk_max_bytes=0
+    )
+    try:
+        job = await manager.prepare(channel_id=CHANNEL, message_id=77, size=4 * BLOCK)
+        assert (await finish(manager, job))["state"] == "ready"
+        state = await manager.snapshot()
+        assert state["cache"]["files"][0]["complete"]
+        assert state["cache"]["memory"]["bytes"] == 4 * BLOCK
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_finished_viewer_history_is_bounded_without_forgetting_active_playback(
+    tmp_path,
+):
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (8 * BLOCK), auto_preload=True
+    )
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL,
+            message_id=77,
+            size=8 * BLOCK,
+            request_id="still-playing",
+        )
+        manager.begin(identity, "still-playing")
+        for index in range(1024):
+            viewer = f"finished-{index}"
+            manager.observe(
+                channel_id=CHANNEL, message_id=77, size=8 * BLOCK, request_id=viewer
+            )
+            manager.begin(identity, viewer)
+            manager.finished(identity, viewer)
+        viewers = manager._observed[identity]["viewers"]
+        assert len(viewers) <= 128
+        assert viewers["still-playing"]["active"] == 1
+        manager.finished(identity, "still-playing")
+        assert not any(viewer["active"] for viewer in viewers.values())
+        assert not manager._jobs and not manager._auto_tasks
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_disabled_automatic_preloading_keeps_inventory_without_viewer_history(
+    tmp_path,
+):
+    manager, pool, _client = await manager_for(tmp_path, b"x" * (8 * BLOCK))
+    try:
+        for index in range(1024):
+            identity = manager.observe(
+                channel_id=CHANNEL, message_id=77, size=8 * BLOCK, request_id=str(index)
+            )
+            manager.begin(identity, str(index))
+            manager.finished(identity, str(index))
+        assert not manager._observed
+        assert len(manager.cache._files) == 1
+        assert not manager._jobs and not manager._auto_tasks
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_concurrent_manual_prepare_admits_one_shared_job(tmp_path, monkeypatch):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (4 * BLOCK), gate, disk_max_bytes=64 * BLOCK
+    )
+    original_capacity = manager._capacity
+
+    async def capacity():
+        await asyncio.sleep(0)
+        return await original_capacity()
+
+    monkeypatch.setattr(manager, "_capacity", capacity)
+    try:
+        first, second = await asyncio.gather(
+            *(
+                manager.prepare(channel_id=CHANNEL, message_id=77, size=4 * BLOCK)
+                for _ in range(2)
+            )
+        )
+        assert first["id"] == second["id"]
+        assert len(manager._jobs) == 1
+        assert len(manager._tasks) == 1
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_ahead_preload_renews_when_playback_reaches_previous_window(tmp_path):
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (20 * BLOCK), auto_preload=True
+    )
+    manager._clock = lambda: 1.0
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=20 * BLOCK, media_rate=BLOCK / 2
+        )
+        manager.begin(identity, None)
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        first = next(iter(manager._jobs.values()))
+        assert first["start"] == 4 * BLOCK and first["end"] == 8 * BLOCK
+        assert (await finish(manager, first))["state"] == "ready"
+        for index in range(4, 8):
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        for _ in range(100):
+            if len(manager._jobs) > 1:
+                break
+            await asyncio.sleep(0.001)
+        assert len(manager._jobs) == 2
+        second = list(manager._jobs.values())[-1]
+        assert second["start"] == 8 * BLOCK and second["end"] == 12 * BLOCK
+        assert (await finish(manager, second))["state"] == "ready"
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_partial_preload_reserves_aligned_blocks_before_admission(tmp_path):
+    manager, pool, client = await manager_for(
+        tmp_path, b"x" * (2 * BLOCK), memory_max_bytes=BLOCK, disk_max_bytes=0
+    )
+    try:
+        with pytest.raises(PreloadCapacityError, match="budget"):
+            await manager.prepare(
+                channel_id=CHANNEL,
+                message_id=77,
+                size=2 * BLOCK,
+                start=BLOCK - 1,
+                end=BLOCK + 1,
+            )
+        assert not manager._jobs and not client.native.requests
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_multipart_preload_reserves_a_digest_for_each_telegram_part(tmp_path):
+    from tests.media.test_multipart_streaming import build_parts
+
+    contents = [b"one", b"two"]
+    parts = build_parts(contents)
+    manager, pool, client = await manager_for(
+        tmp_path, b"", memory_max_bytes=0, disk_max_bytes=6 + 32
+    )
+    try:
+        with pytest.raises(PreloadCapacityError, match="budget"):
+            await manager.prepare(
+                channel_id=CHANNEL,
+                message_id=parts[0]["message_id"],
+                size=6,
+                parts=parts,
+            )
+        assert not manager._jobs and not client.native.requests
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_manual_preload_replaces_full_automatic_job_and_its_authorization(
+    tmp_path,
+):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(tmp_path, b"x" * (4 * BLOCK), gate)
+    revoked = False
+
+    async def authorize_auto():
+        if revoked:
+            raise PermissionError("The original viewer's share was revoked")
+
+    try:
+        automatic = await manager.prepare(
+            channel_id=CHANNEL,
+            message_id=77,
+            size=4 * BLOCK,
+            mode="auto",
+            authorize=authorize_auto,
+        )
+        manual = await manager.prepare(
+            channel_id=CHANNEL, message_id=77, size=4 * BLOCK
+        )
+        assert manual["id"] != automatic["id"] and manual["mode"] == "manual"
+        assert manager._jobs[automatic["id"]]["state"] == "cancelled"
+        revoked = True
+        gate.set()
+        assert (await finish(manager, manual))["state"] == "ready"
+        assert (await manager.snapshot())["cache"]["files"][0]["complete"]
+    finally:
+        gate.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("blocks,complete", [(20, False), (8, True)])
+async def test_hot_auto_admission_after_last_viewer_leaves_only_allows_full_file(
+    tmp_path, monkeypatch, blocks, complete
+):
+    manager, pool, client = await manager_for(
+        tmp_path, b"x" * (blocks * BLOCK), auto_preload=True
+    )
+    manager._clock = lambda: 1.0
+    at_admission = asyncio.Event()
+    release_admission = asyncio.Event()
+    original_capacity = manager._capacity
+    inspections = 0
+
+    async def capacity():
+        nonlocal inspections
+        inspections += 1
+        if inspections == 2:
+            at_admission.set()
+            await release_admission.wait()
+        return await original_capacity()
+
+    monkeypatch.setattr(manager, "_capacity", capacity)
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=blocks * BLOCK
+        )
+        # Independent viewers qualify overlapping runs as hot-file demand.
+        for viewer in ("first", "second"):
+            manager.observe(
+                channel_id=CHANNEL,
+                message_id=77,
+                size=blocks * BLOCK,
+                request_id=viewer,
+            )
+            manager.begin(identity, viewer)
+            for index in range(4):
+                manager.delivered(
+                    channel_id=CHANNEL,
+                    message_id=77,
+                    offset=index * BLOCK,
+                    length=BLOCK,
+                    request_id=viewer,
+                )
+        await asyncio.wait_for(at_admission.wait(), 3)
+        assert not manager._jobs
+        manager.finished(identity, "first")
+        manager.finished(identity, "second")
+        release_admission.set()
+        await asyncio.wait_for(manager._auto_tasks[identity], 3)
+        if complete:
+            job = next(iter(manager._jobs.values()))
+            assert job["target_bytes"] == blocks * BLOCK
+            assert (await finish(manager, job))["state"] == "ready"
+        else:
+            assert not manager._jobs and not client.native.requests
+            assert not manager.cache.memory.flights
+    finally:
+        release_admission.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "media_rate,qualification,window",
+    [
+        (BLOCK / 64, 1, 1),
+        (2 * BLOCK, 4, 16),
+        (32 * BLOCK, 4, 128),
+        (1e308, 4, 128),
+    ],
+)
+async def test_metadata_bitrate_scales_qualification_and_ahead_without_network_bursts(
+    tmp_path, media_rate, qualification, window
+):
+    from unittest.mock import AsyncMock
+
+    from tests.media.test_telegram_cache import message
+    from tgdrive.telegram.clients import TelegramMessage
+
+    gate = asyncio.Event()
+    size = 256 * BLOCK
+    manager, pool, client = await manager_for(
+        tmp_path, b"", gate, disk_max_bytes=512 * BLOCK, auto_preload=True
+    )
+    client.get_messages = AsyncMock(
+        return_value=TelegramMessage(client, message(1, size))
+    )
+    manager._clock = lambda: 1.0
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=size, media_rate=media_rate
+        )
+        manager.begin(identity, None)
+        for index in range(qualification - 1):
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        await asyncio.sleep(0)
+        assert not manager._jobs
+        manager.delivered(
+            channel_id=CHANNEL,
+            message_id=77,
+            offset=(qualification - 1) * BLOCK,
+            length=BLOCK,
+        )
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        job = next(iter(manager._jobs.values()))
+        assert job["start"] == qualification * BLOCK
+        assert job["target_bytes"] == window * BLOCK
+        viewer = manager._observed[identity]["viewers"]["default"]
+        assert viewer["rate"] == 0
+        assert viewer["media_rate"] == media_rate
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "times,expected_rate",
+    [
+        ([index * 0.01 for index in range(11)], 100 * BLOCK),
+        ([0, 1, 1.001, 1.002, 1.003, 2], 1.75 * BLOCK),
+        ([index * 0.00001 for index in range(11)], 0),
+        ([0, 0.1, 50], 0),
+    ],
+)
+async def test_fallback_rate_aggregates_fast_chunks_and_bursts_but_rejects_idle_gaps(
+    tmp_path, times, expected_rate
+):
+    manager, pool, _client = await manager_for(tmp_path, b"", auto_preload=True)
+    now = [0.0]
+    manager._clock = lambda: now[0]
+    try:
+        identity = manager.observe(channel_id=CHANNEL, message_id=77, size=64 * BLOCK)
+        manager.begin(identity, None)
+        for index, at in enumerate(times):
+            now[0] = at
+            manager.delivered(
+                channel_id=CHANNEL, message_id=77, offset=index * BLOCK, length=BLOCK
+            )
+        viewer = manager._observed[identity]["viewers"]["default"]
+        assert viewer["rate"] == pytest.approx(expected_rate)
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_playback_seek_resets_delivery_rate_without_affecting_other_viewer(
+    tmp_path,
+):
+    manager, pool, _client = await manager_for(tmp_path, b"", auto_preload=True)
+    now = [0.0]
+    manager._clock = lambda: now[0]
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=64 * BLOCK, request_id="first"
+        )
+        manager.observe(
+            channel_id=CHANNEL, message_id=77, size=64 * BLOCK, request_id="second"
+        )
+        manager.begin(identity, "first")
+        manager.begin(identity, "second")
+        for index in range(3):
+            now[0] = index
+            for viewer in ("first", "second"):
+                manager.delivered(
+                    channel_id=CHANNEL,
+                    message_id=77,
+                    offset=index * BLOCK,
+                    length=BLOCK,
+                    request_id=viewer,
+                )
+        now[0] += 0.000001
+        manager.delivered(
+            channel_id=CHANNEL,
+            message_id=77,
+            offset=40 * BLOCK,
+            length=BLOCK,
+            request_id="first",
+        )
+        viewers = manager._observed[identity]["viewers"]
+        assert viewers["first"]["rate"] == 0
+        assert viewers["second"]["rate"] == BLOCK
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_fill_rate_for_another_file_does_not_change_playback_ahead(tmp_path):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path,
+        b"x" * (64 * BLOCK),
+        gate,
+        disk_max_bytes=256 * BLOCK,
+        auto_preload=True,
+    )
+    manager._clock = lambda: 1.0
+    try:
+        identities = []
+        for message_id, fill in ((77, BLOCK / 2), (88, 2 * BLOCK)):
+            identity = manager.observe(
+                channel_id=CHANNEL,
+                message_id=message_id,
+                size=64 * BLOCK,
+                media_rate=BLOCK,
+            )
+            identities.append(identity)
+            manager._observed[identity]["fill_rate"] = fill
+            manager.begin(identity, None)
+            for index in range(4):
+                manager.delivered(
+                    channel_id=CHANNEL,
+                    message_id=message_id,
+                    offset=index * BLOCK,
+                    length=BLOCK,
+                )
+        for _ in range(100):
+            if len(manager._jobs) == 2:
+                break
+            await asyncio.sleep(0.001)
+        targets = {
+            job["file_id"]: job["target_bytes"] for job in manager._jobs.values()
+        }
+        assert targets == {identities[0]: 16 * BLOCK, identities[1]: 8 * BLOCK}
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_anonymous_player_requests_do_not_qualify_as_distinct_full_file_viewers(
+    tmp_path,
+):
+    manager, pool, _client = await manager_for(tmp_path, b"", auto_preload=True)
+    try:
+        for index in range(3):
+            viewer = f"anonymous-http-{index}"
+            identity = manager.observe(
+                channel_id=CHANNEL,
+                message_id=77,
+                size=8 * BLOCK,
+                request_id=viewer,
+                allow_full=False,
+            )
+            manager.begin(identity, viewer)
+            for block in range(4):
+                manager.delivered(
+                    channel_id=CHANNEL,
+                    message_id=77,
+                    offset=block * BLOCK,
+                    length=BLOCK,
+                    request_id=viewer,
+                )
+        assert manager._observed[identity]["hot_until"] == 0
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_independent_playback_runs_can_qualify_after_growing_into_overlap(
+    tmp_path,
+):
+    manager, pool, _client = await manager_for(tmp_path, b"", auto_preload=True)
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=16 * BLOCK, request_id="first"
+        )
+        for viewer, start in (("first", 0), ("second", 8)):
+            manager.observe(
+                channel_id=CHANNEL, message_id=77, size=16 * BLOCK, request_id=viewer
+            )
+            manager.begin(identity, viewer)
+            for index in range(start, start + 4):
+                manager.delivered(
+                    channel_id=CHANNEL,
+                    message_id=77,
+                    offset=index * BLOCK,
+                    length=BLOCK,
+                    request_id=viewer,
+                )
+        assert manager._observed[identity]["hot_until"] == 0
+        for index in range(4, 12):
+            manager.delivered(
+                channel_id=CHANNEL,
+                message_id=77,
+                offset=index * BLOCK,
+                length=BLOCK,
+                request_id="first",
+            )
+        assert manager._observed[identity]["hot_until"] > manager._clock()
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("media_rate", [0, -1, float("nan"), float("inf"), True, "60"])
+async def test_invalid_media_rate_hint_is_ignored(tmp_path, media_rate):
+    manager, pool, _client = await manager_for(tmp_path, b"", auto_preload=True)
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=8 * BLOCK, media_rate=media_rate
+        )
+        assert manager._observed[identity]["viewers"]["default"]["media_rate"] is None
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("change", ["seek", "owner_leaves"])
+async def test_pending_ahead_admission_rechecks_its_own_viewer_after_capacity_wait(
+    tmp_path, monkeypatch, change
+):
+    manager, pool, client = await manager_for(tmp_path, b"", auto_preload=True)
+    entered = asyncio.Event()
+    release = asyncio.Event()
+    original_capacity = manager._capacity
+    inspections = 0
+
+    async def capacity():
+        nonlocal inspections
+        inspections += 1
+        if inspections == 2:
+            entered.set()
+            await release.wait()
+        return await original_capacity()
+
+    monkeypatch.setattr(manager, "_capacity", capacity)
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=64 * BLOCK, request_id="first"
+        )
+        manager.observe(
+            channel_id=CHANNEL, message_id=77, size=64 * BLOCK, request_id="second"
+        )
+        manager.begin(identity, "first")
+        manager.begin(identity, "second")
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL,
+                message_id=77,
+                offset=index * BLOCK,
+                length=BLOCK,
+                request_id="first",
+            )
+        await asyncio.wait_for(entered.wait(), 3)
+        pending = manager._auto_tasks[identity]
+        if change == "seek":
+            manager.delivered(
+                channel_id=CHANNEL,
+                message_id=77,
+                offset=40 * BLOCK,
+                length=BLOCK,
+                request_id="first",
+            )
+        else:
+            manager.finished(identity, "first")
+        release.set()
+        await asyncio.wait_for(pending, 3)
+        assert not manager._jobs and not client.native.requests
+        assert manager._observed[identity]["viewers"]["second"]["active"] == 1
+    finally:
+        release.set()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_ahead_owner_leaving_cancels_work_while_another_viewer_remains(tmp_path):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (64 * BLOCK), gate, auto_preload=True
+    )
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=64 * BLOCK, request_id="first"
+        )
+        manager.observe(
+            channel_id=CHANNEL, message_id=77, size=64 * BLOCK, request_id="second"
+        )
+        manager.begin(identity, "first")
+        manager.begin(identity, "second")
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL,
+                message_id=77,
+                offset=index * BLOCK,
+                length=BLOCK,
+                request_id="first",
+            )
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        job = next(iter(manager._jobs.values()))
+        manager.finished(identity, "first")
+        task = manager._tasks.get(job["id"])
+        if task is not None:
+            await asyncio.gather(task, return_exceptions=True)
+        assert job["state"] == "cancelled"
+        assert manager._observed[identity]["viewers"]["second"]["active"] == 1
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_completed_range_grace_expires_and_cancels_unfinished_ahead(
+    tmp_path, monkeypatch
+):
+    monkeypatch.setattr("tgdrive.media.preloading.PLAYBACK_RANGE_GRACE_SECONDS", 0.03)
+    gate = asyncio.Event()
+    manager, pool, client = await manager_for(
+        tmp_path, b"x" * (16 * BLOCK), gate, auto_preload=True
+    )
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=16 * BLOCK, request_id="player"
+        )
+        manager.begin(identity, "player")
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL,
+                message_id=77,
+                offset=index * BLOCK,
+                length=BLOCK,
+                request_id="player",
+            )
+        manager.finished(identity, "player", completed=True)
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        job = next(iter(manager._jobs.values()))
+        assert manager._viewer_timers
+        for _ in range(100):
+            if job["state"] == "cancelled":
+                break
+            await asyncio.sleep(0.001)
+        assert job["state"] == "cancelled"
+        viewer = manager._observed[identity]["viewers"]["player"]
+        assert viewer["active"] == 0 and viewer["warm_until"] == 0
+        assert not manager._viewer_timers
+        assert not manager.cache.memory.flights and not client.native.active
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_new_player_request_abort_revokes_completed_range_grace_immediately(
+    tmp_path,
+):
+    gate = asyncio.Event()
+    manager, pool, _client = await manager_for(
+        tmp_path, b"x" * (16 * BLOCK), gate, auto_preload=True
+    )
+    try:
+        identity = manager.observe(
+            channel_id=CHANNEL, message_id=77, size=16 * BLOCK, request_id="player"
+        )
+        manager.begin(identity, "player")
+        for index in range(4):
+            manager.delivered(
+                channel_id=CHANNEL,
+                message_id=77,
+                offset=index * BLOCK,
+                length=BLOCK,
+                request_id="player",
+            )
+        manager.finished(identity, "player", completed=True)
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        job = next(iter(manager._jobs.values()))
+        manager.begin(identity, "player")
+        manager.finished(identity, "player")
+        task = manager._tasks.get(job["id"])
+        if task is not None:
+            await asyncio.gather(task, return_exceptions=True)
+        assert job["state"] == "cancelled"
+        assert not manager._viewer_timers
+        assert not manager._viewer_active(
+            manager._observed[identity]["viewers"]["player"]
+        )
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_cache_shutdown_disposes_completed_player_range_timers(tmp_path):
+    manager, pool, _client = await manager_for(tmp_path, b"", auto_preload=True)
+    try:
+        identity = manager.observe(channel_id=CHANNEL, message_id=77, size=BLOCK)
+        manager.begin(identity, None)
+        manager.finished(identity, None, completed=True)
+        timers = list(manager._viewer_timers.values())
+        assert timers and all(not timer.cancelled() for timer in timers)
+        await manager.close()
+        assert not manager._viewer_timers
+        assert all(timer.cancelled() for timer in timers)
+    finally:
+        await manager.close()
+        await pool.stop()
diff --git a/tests/media/test_preview_cache.py b/tests/media/test_preview_cache.py
new file mode 100644
index 00000000..22e29747
--- /dev/null
+++ b/tests/media/test_preview_cache.py
@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from tests.media.test_pooled_media import account
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import BLOCK
+from tgdrive.media.preloading import PreloadManager
+from tgdrive.media.previews import TEXT_PREVIEW_BYTES, describe_preview
+from tgdrive.telegram.client_pool import ClientPool
+
+CHANNEL = -1000000000123
+
+
+async def setup_preview(tmp_path, *, enabled, gate=None):
+    payload = b"line\n" * BLOCK
+    client = account("preview-bot", payload, gate)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    manager = PreloadManager(
+        pool,
+        policy=MediaCachePolicy(
+            memory_max_bytes=2 * BLOCK if enabled else 0,
+            disk_max_bytes=4 * BLOCK if enabled else 0,
+            min_free_bytes=0,
+            auto_preload=True,
+        ),
+    )
+    return manager, pool, client, payload
+
+
+async def preview(pool, size):
+    return await describe_preview(
+        pool=pool,
+        channel_id=CHANNEL,
+        message_id=77,
+        file_name="server.log",
+        size=size,
+        path="/server.log",
+        auth=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_disabled_preview_cache_never_retains_in_transport(tmp_path):
+    manager, pool, client, payload = await setup_preview(tmp_path, enabled=False)
+    try:
+        for _ in range(2):
+            result = await preview(pool, len(payload))
+            assert result["kind"] == "text"
+            assert result["text"] == payload[:TEXT_PREVIEW_BYTES].decode()
+            assert result["truncated"]
+        assert sum(client.native.requests.values()) == 4
+        assert not hasattr(client, "_download_block_cache")
+        state = await manager.cache.snapshot()
+        assert state["files"] == []
+        assert state["memory"]["bytes"] == state["disk"]["bytes"] == 0
+        assert state["scratch"]["bytes"] == 0
+        assert not manager._observed and not manager._jobs
+        assert client.get_messages.await_count == 2  # Warm metadata is never reused.
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_preview_prefix_appears_in_shared_inventory_without_preload(tmp_path):
+    manager, pool, client, payload = await setup_preview(tmp_path, enabled=True)
+    try:
+        for _ in range(2):
+            result = await preview(pool, len(payload))
+            assert result["preview_bytes"] == TEXT_PREVIEW_BYTES
+            assert result["size"] == len(payload)
+        await manager.cache.flush()
+        state = await manager.cache.snapshot()
+        assert len(state["files"]) == 1
+        row = state["files"][0]
+        assert row["name"] == "server.log"
+        assert row["size"] == len(payload)
+        assert row["ready_ranges"] == [[0, BLOCK]]
+        assert row["disk_ranges"] == [[0, BLOCK]]
+        assert not row["complete"]
+        assert sum(client.native.requests.values()) == 2
+        assert not hasattr(client, "_download_block_cache")
+        assert not manager._observed and not manager._jobs
+        assert client.get_messages.await_count == 2
+        assert all(iterator.closed for iterator in client.native.iterators)
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_cancelled_preview_drains_shared_fill_and_reservations(
+    tmp_path, monkeypatch
+):
+    gate = asyncio.Event()
+    manager, pool, client, payload = await setup_preview(
+        tmp_path, enabled=True, gate=gate
+    )
+    entered = asyncio.Event()
+    make_iterator = client.native.iter_download
+
+    def observe_origin(*args, **kwargs):
+        iterator = make_iterator(*args, **kwargs)
+        entered.set()
+        return iterator
+
+    monkeypatch.setattr(client.native, "iter_download", observe_origin)
+    task = asyncio.create_task(preview(pool, len(payload)))
+    try:
+        # Cache admission can consult the real filesystem in a worker thread.
+        # Await actual origin entry rather than a fixed number of loop turns.
+        await asyncio.wait_for(entered.wait(), 2)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(task, 1)
+        assert client.native.active == 0
+        assert all(iterator.closed for iterator in client.native.iterators)
+        assert not manager.cache.memory.flights
+        assert (await manager.cache.snapshot())["scratch"]["bytes"] == 0
+        assert all(row.active_leases == 0 for row in await pool.status())
+        assert not manager._observed and not manager._jobs
+    finally:
+        gate.set()
+        if not task.done():
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+        await manager.close()
+        await pool.stop()
diff --git a/tests/media/test_preview_routing.py b/tests/media/test_preview_routing.py
new file mode 100644
index 00000000..42cedb57
--- /dev/null
+++ b/tests/media/test_preview_routing.py
@@ -0,0 +1,148 @@
+"""Ambiguous suffixes require bounded content evidence, not a filename/MIME guess."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from tgdrive.media.previews import TEXT_PREVIEW_BYTES, describe_preview
+from tgdrive.telegram.client_pool import ClientPool
+
+
+class RoutingClient:
+    name = "preview-routing"
+    is_connected = False
+
+    def __init__(self, content, mime_type=None):
+        self.content = content
+        self.mime_type = mime_type
+        self.windows = []
+        self.closed = False
+
+    async def start(self):
+        self.is_connected = True
+
+    async def stop(self):
+        self.is_connected = False
+
+    async def get_messages(self, channel, *, message_ids):
+        # Match the facade, whose small media summary omits native MIME.
+        return SimpleNamespace(
+            id=message_ids,
+            document=SimpleNamespace(file_size=len(self.content)),
+            native=SimpleNamespace(document=SimpleNamespace(mime_type=self.mime_type)),
+        )
+
+    async def stream_media(self, message, *, limit, offset):
+        self.windows.append((limit, offset))
+        try:
+            yield self.content[: 1024**2]
+        finally:
+            self.closed = True
+
+
+async def preview(content, *, name="sample.ts", mime_type=None):
+    client = RoutingClient(content, mime_type)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await describe_preview(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name=name,
+            size=len(content),
+            path="/id",
+            auth=None,
+        )
+        assert client.windows == [(1, 0)]
+        assert client.closed
+        assert (await pool.health()).active_leases == 0
+        return result
+    finally:
+        await pool.stop()
+
+
+def transport_packets(count=5, stride=188, *, invalid_header=False):
+    # Transport sync/header and binary payload, independent of any file suffix.
+    packet = b"\x47\x40\x00" + (b"\x00" if invalid_header else b"\x10")
+    packet += b"\x00" * 184
+    if stride == 192:
+        return (b"\x00" * 4 + packet) * count
+    return (packet + b"\xff" * (stride - 188)) * count
+
+
+@pytest.mark.parametrize("mime_type", [None, "text/plain", "video/mp2t"])
+@pytest.mark.parametrize("name", ["sample.ts", "module.mts", "module.cts"])
+async def test_typescript_stays_inert_text_even_with_video_mime(mime_type, name):
+    content = b"export async function main(): Promise<string> { return '<video/>'; }"
+    result = await preview(content, name=name, mime_type=mime_type)
+    assert result["kind"] == "text"
+    assert result["language"] == "typescript"
+    assert result["text"].encode() == content
+
+
+async def test_packet_shaped_printable_source_does_not_override_text():
+    content = (b"GAA3 " + b" " * 183) * 8
+    result = await preview(content, mime_type="video/mp2t")
+    assert result["kind"] == "text"
+    assert result["text"].encode() == content
+
+
+@pytest.mark.parametrize("stride", [188, 192, 204])
+@pytest.mark.parametrize("mime_type", [None, "text/plain", "video/mp2t"])
+async def test_transport_packet_content_is_video_despite_wrong_or_missing_mime(
+    stride, mime_type
+):
+    result = await preview(transport_packets(stride=stride), mime_type=mime_type)
+    assert result["kind"] == "video"
+    assert "text" not in result
+    assert "url" not in result
+
+
+async def test_timestamp_prefixed_mts_is_also_content_classified():
+    result = await preview(
+        transport_packets(stride=192), name="camera.mts", mime_type="text/plain"
+    )
+    assert result["kind"] == "video"
+
+
+async def test_mime_only_corroborates_repeated_complete_packet_evidence():
+    sample = transport_packets(count=3)
+    assert (await preview(sample, mime_type="video/mp2t"))["kind"] == "video"
+    assert (await preview(sample, mime_type="text/plain"))["kind"] == "unsupported"
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        b"binary\x00data",
+        b"\x47" + b"\x00" * 1000,
+        transport_packets(count=1),
+        transport_packets(invalid_header=True),
+        b"\xff\xfa\xfe\x00" * 100,
+    ],
+)
+async def test_unproven_binary_does_not_enter_either_source_or_video(content):
+    result = await preview(content, mime_type="video/mp2t")
+    assert result["kind"] == "unsupported"
+    assert "Download the original" in result["reason"]
+    assert "text" not in result
+
+
+async def test_utf16_typescript_and_utf8_truncation_remain_readable():
+    source = "export const greeting = 'hello ☃';"
+    result = await preview(source.encode("utf-16"), mime_type="video/mp2t")
+    assert result["kind"] == "text"
+    assert result["text"] == source
+    content = b"x" * (TEXT_PREVIEW_BYTES - 1) + "🙂".encode() + b"tail"
+    result = await preview(content, name="large.ts")
+    assert result["kind"] == "text"
+    assert result["truncated"]
+    assert result["text"] == "x" * (TEXT_PREVIEW_BYTES - 1)
+    assert "�" not in result["text"]
+
+
+async def test_invalid_text_encoding_offers_original_instead_of_garbled_source():
+    result = await preview(b"hello\xffworld", name="sample.txt")
+    assert result["kind"] == "unsupported"
+    assert "supported encoding" in result["reason"]
diff --git a/tests/media/test_previews.py b/tests/media/test_previews.py
new file mode 100644
index 00000000..6c10331d
--- /dev/null
+++ b/tests/media/test_previews.py
@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from urllib.parse import parse_qs, urlsplit
+
+import pytest
+
+from tgdrive.media.previews import (
+    PDF_PREVIEW_BYTES,
+    TEXT_PREVIEW_BYTES,
+    describe_media,
+    describe_preview,
+)
+from tgdrive.telegram.client_pool import ClientPool
+
+
+class PreviewClient:
+    def __init__(self, content: bytes):
+        self.content = content
+        self.is_connected = False
+        self.name = "preview-test"
+        self.reads = 0
+        self.closed = False
+
+    async def start(self):
+        self.is_connected = True
+
+    async def stop(self):
+        self.is_connected = False
+
+    async def get_messages(self, _channel, *, message_ids):
+        return SimpleNamespace(
+            id=message_ids, document=SimpleNamespace(file_size=len(self.content))
+        )
+
+    async def stream_media(self, _message, *, limit, offset):
+        try:
+            for index in range(offset, offset + limit):
+                self.reads += 1
+                yield self.content[index * 1024**2 : (index + 1) * 1024**2]
+        finally:
+            self.closed = True
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("name", "content", "language", "expected"),
+    [
+        ("readme.md", b"# hello", "markdown", "# hello"),
+        (
+            "unsafe.html",
+            b"<script>window.bad=true</script>",
+            "html",
+            "<script>window.bad=true</script>",
+        ),
+        ("unicode.txt", "hello ☃".encode("utf-16"), "text", "hello ☃"),
+        ("config.json", b'{"answer":42}', "json", '{"answer":42}'),
+        ("table.csv", b"name,value\nalpha,1", "csv", "name,value\nalpha,1"),
+    ],
+)
+async def test_text_previews_return_inert_content_and_release(
+    name, content, language, expected
+):
+    client = PreviewClient(content)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await describe_preview(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name=name,
+            size=len(content),
+            path="/file",
+            auth=None,
+        )
+        assert result["kind"] == "text"
+        assert result["text"] == expected
+        assert result["language"] == language
+        assert not result["truncated"]
+        assert client.closed
+        assert all(status.active_leases == 0 for status in await pool.status())
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_large_text_reads_one_bounded_window_and_reports_truncation():
+    content = b"x" * (5 * 1024**2)
+    client = PreviewClient(content)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await describe_preview(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="large.log",
+            size=len(content),
+            path="/file",
+            auth=None,
+        )
+        assert result["text"] == "x" * TEXT_PREVIEW_BYTES
+        assert result["truncated"]
+        assert result["preview_bytes"] == TEXT_PREVIEW_BYTES
+        assert client.reads == 1
+        assert client.closed
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_binary_text_name_does_not_send_binary_to_text_renderer():
+    client = PreviewClient(b"binary\x00data")
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await describe_preview(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="not-text.txt",
+            size=11,
+            path="/file",
+            auth=None,
+        )
+        assert result["kind"] == "unsupported"
+        assert "text" not in result
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_pdf_descriptor_encodes_share_and_bounds_memory_without_fetch():
+    kwargs = dict(
+        pool=object(),
+        channel_id=-100,
+        message_id=7,
+        file_name="manual.pdf",
+        path="/folder/file",
+        auth="share&token",
+    )
+    result = await describe_preview(size=1024, **kwargs)
+    assert result["kind"] == "pdf"
+    assert parse_qs(urlsplit(result["url"]).query) == {
+        "path": ["/folder/file"],
+        "auth": ["share&token"],
+        "preview": ["1"],
+    }
+    for size in (21 * 1024**2, PDF_PREVIEW_BYTES):
+        assert (await describe_preview(size=size, **kwargs))["kind"] == "pdf"
+    result = await describe_preview(size=PDF_PREVIEW_BYTES + 1, **kwargs)
+    assert result["kind"] == "unsupported"
+    assert "url" not in result
+
+
+@pytest.mark.asyncio
+async def test_media_metadata_fallback_has_no_fake_quality_variants():
+    client = PreviewClient(b"original")
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        result = await describe_media(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="movie.mp4",
+            size=8,
+        )
+        assert result["original"]["id"] == "original"
+        assert result["original"]["mime_type"] == "video/mp4"
+        assert result["variants"] == []
+        assert client.reads == 0
+        assert all(status.active_leases == 0 for status in await pool.status())
+    finally:
+        await pool.stop()
diff --git a/tests/media/test_ranges.py b/tests/media/test_ranges.py
new file mode 100644
index 00000000..2cd6ceaa
--- /dev/null
+++ b/tests/media/test_ranges.py
@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import unittest
+
+from tgdrive.media.ranges import (
+    TELEGRAM_CHUNK_SIZE,
+    ByteRange,
+    MalformedRange,
+    RangeNotSatisfiable,
+    parse_byte_range,
+    plan_telegram_chunks,
+)
+
+
+class ParseByteRangeTests(unittest.TestCase):
+    def test_absent_header_selects_full_representation(self) -> None:
+        selected = parse_byte_range(None, 10)
+
+        self.assertEqual(selected, ByteRange(0, 9, 10, is_partial=False))
+        self.assertEqual(selected.length, 10)
+        self.assertIsNone(selected.content_range)
+
+    def test_explicit_and_open_ended_ranges(self) -> None:
+        explicit = parse_byte_range("bytes=2-6", 10)
+        open_ended = parse_byte_range("bytes=7-", 10)
+
+        self.assertEqual((explicit.start, explicit.end, explicit.length), (2, 6, 5))
+        self.assertEqual(explicit.content_range, "bytes 2-6/10")
+        self.assertEqual((open_ended.start, open_ended.end), (7, 9))
+        self.assertEqual(parse_byte_range("Bytes=0-1", 10).end, 1)
+
+    def test_end_is_clamped_to_eof(self) -> None:
+        selected = parse_byte_range("bytes=7-999", 10)
+        self.assertEqual((selected.start, selected.end), (7, 9))
+
+    def test_suffix_range_and_oversized_suffix(self) -> None:
+        self.assertEqual(
+            parse_byte_range("bytes=-3", 10),
+            ByteRange(7, 9, 10, is_partial=True),
+        )
+        self.assertEqual(
+            parse_byte_range("bytes=-99", 10),
+            ByteRange(0, 9, 10, is_partial=True),
+        )
+
+    def test_empty_file_without_range_is_representable(self) -> None:
+        selected = parse_byte_range(None, 0)
+        self.assertEqual((selected.start, selected.end, selected.length), (0, -1, 0))
+
+    def test_malformed_and_multiple_ranges_are_rejected(self) -> None:
+        for value in (
+            "items=0-1",
+            "bytes=",
+            "bytes=-",
+            "bytes=1-2,4-5",
+            "bytes =1-2",
+            "bytes=one-two",
+            "bytes= 1-2",
+            "",
+            "   ",
+        ):
+            with self.subTest(value=value), self.assertRaises(MalformedRange):
+                parse_byte_range(value, 10)
+
+    def test_large_range_numerals_preserve_http_semantics_without_int_overflow(self):
+        enormous = "9" * 5000
+        self.assertEqual(
+            parse_byte_range(f"bytes=2-{enormous}", 10),
+            ByteRange(2, 9, 10, is_partial=True),
+        )
+        self.assertEqual(
+            parse_byte_range(f"bytes=-{enormous}", 10),
+            ByteRange(0, 9, 10, is_partial=True),
+        )
+        self.assertEqual(
+            parse_byte_range("bytes=" + "0" * 5000 + "2-6", 10),
+            ByteRange(2, 6, 10, is_partial=True),
+        )
+        with self.assertRaises(RangeNotSatisfiable):
+            parse_byte_range(f"bytes={enormous}-", 10)
+        with self.assertRaises(MalformedRange):
+            parse_byte_range("bytes=٢-٦", 10)
+
+    def test_unsatisfiable_ranges_include_416_header_value(self) -> None:
+        for value in ("bytes=10-", "bytes=8-2", "bytes=-0"):
+            with self.subTest(value=value):
+                with self.assertRaises(RangeNotSatisfiable) as raised:
+                    parse_byte_range(value, 10)
+                self.assertEqual(raised.exception.content_range, "bytes */10")
+
+        with self.assertRaises(RangeNotSatisfiable):
+            parse_byte_range("bytes=0-0", 0)
+
+
+class TelegramChunkPlanTests(unittest.TestCase):
+    def test_single_chunk_plan_uses_exact_half_open_cuts(self) -> None:
+        selected = ByteRange(100, 199, 1000, is_partial=True)
+        plan = plan_telegram_chunks(selected)
+
+        self.assertEqual(plan.offset, 0)
+        self.assertEqual(plan.part_count, 1)
+        self.assertEqual(plan.first_part_cut, 100)
+        self.assertEqual(plan.last_part_cut, 200)
+        self.assertEqual(plan.requested_length, 100)
+        chunks = list(plan.iter_chunks())
+        self.assertEqual(chunks[0].output_length, 100)
+
+    def test_cross_chunk_plan_is_exact(self) -> None:
+        chunk = TELEGRAM_CHUNK_SIZE
+        selected = ByteRange(chunk - 10, chunk + 19, chunk * 3, is_partial=True)
+        plan = plan_telegram_chunks(selected)
+        chunks = list(plan.iter_chunks())
+
+        self.assertEqual(plan.offset, 0)
+        self.assertEqual(plan.part_count, 2)
+        self.assertEqual(plan.first_part_cut, chunk - 10)
+        self.assertEqual(plan.last_part_cut, 20)
+        self.assertEqual(sum(part.output_length for part in chunks), 30)
+        self.assertEqual([part.offset for part in chunks], [0, chunk])
+
+    def test_aligned_multi_chunk_plan_has_no_off_by_one(self) -> None:
+        chunk = TELEGRAM_CHUNK_SIZE
+        selected = ByteRange(chunk, chunk * 3 - 1, chunk * 4, is_partial=True)
+        plan = plan_telegram_chunks(selected)
+
+        self.assertEqual(plan.offset, chunk)
+        self.assertEqual(plan.part_count, 2)
+        self.assertEqual(plan.first_part_cut, 0)
+        self.assertEqual(plan.last_part_cut, chunk)
+        self.assertEqual(
+            sum(part.output_length for part in plan.iter_chunks()),
+            chunk * 2,
+        )
+
+    def test_empty_representation_produces_no_reads(self) -> None:
+        plan = plan_telegram_chunks(ByteRange(0, -1, 0, is_partial=False))
+        self.assertEqual(plan.part_count, 0)
+        self.assertEqual(list(plan.iter_chunks()), [])
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/media/test_stream_delivery.py b/tests/media/test_stream_delivery.py
new file mode 100644
index 00000000..9e3fbf81
--- /dev/null
+++ b/tests/media/test_stream_delivery.py
@@ -0,0 +1,763 @@
+from __future__ import annotations
+
+import json
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi import HTTPException
+
+from tests.media.test_multipart_streaming import MultipartClient, build_parts
+from tests.media.test_pooled_media import account
+from tests.media.test_streaming import make_request, response_body
+from tests.media.test_telegram_cache import document, message
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import BLOCK
+from tgdrive.media.preloading import PreloadManager
+from tgdrive.media.streaming import _not_modified, media_etag, stream_telegram_file
+from tgdrive.telegram.client_pool import ClientPool, MediaQueueFull
+from tgdrive.telegram.clients import TelegramMessage
+
+CHANNEL = -1000000000123
+
+
+def request(header=None, **headers):
+    result = make_request(header)
+    result.scope["headers"].extend(
+        (name.replace("_", "-").encode(), value.encode())
+        for name, value in headers.items()
+    )
+    return result
+
+
+async def response(pool, payload, req=None, **kwargs):
+    return await stream_telegram_file(
+        pool=pool,
+        channel_id=CHANNEL,
+        message_id=77,
+        file_name="video.mp4",
+        expected_size=len(payload),
+        request=req or request(),
+        **kwargs,
+    )
+
+
+@pytest.mark.asyncio
+async def test_strong_etag_if_range_and_no_transform_preserve_exact_bytes(tmp_path):
+    payload = b"abcdefghij"
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        first = await response(pool, payload)
+        etag = first.headers["etag"]
+        assert etag.startswith('"tg-')
+        assert "no-transform" in first.headers["cache-control"]
+        assert first.headers["content-encoding"] == "identity"
+        assert await response_body(first) == payload
+        partial = await response(pool, payload, request("bytes=2-5", if_range=etag))
+        assert partial.status_code == 206
+        assert partial.headers["content-length"] == "4"
+        assert partial.headers["content-range"] == "bytes 2-5/10"
+        assert await response_body(partial) == b"cdef"
+        for validator in ('"different"', "W/" + etag, "Sat, 01 Jan 2000 00:00:00 GMT"):
+            full = await response(
+                pool, payload, request("bytes=2-5", if_range=validator)
+            )
+            assert full.status_code == 200
+            assert "content-range" not in full.headers
+            assert await response_body(full) == payload
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_conditional_request_revalidates_metadata_without_reading_payload(
+    tmp_path,
+):
+    payload = b"abcdefghij"
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        first = await response(pool, payload)
+        assert await response_body(first) == payload
+        metadata = client.get_messages.call_count
+        reads = sum(client.native.requests.values())
+        conditional = await response(
+            pool, payload, request(if_none_match=first.headers["etag"])
+        )
+        assert conditional.status_code == 304 and conditional.body == b""
+        assert client.get_messages.call_count == metadata + 1
+        assert sum(client.native.requests.values()) == reads
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_same_size_telegram_replacement_invalidates_resume_validator(tmp_path):
+    original, replacement = b"abcdefghij", b"0123456789"
+    client = account("bot", original)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        first = await response(pool, original)
+        assert await response_body(first) == original
+        client.native.payloads[2] = replacement
+        client.get_messages = AsyncMock(
+            return_value=TelegramMessage(client, message(2, len(replacement)))
+        )
+        changed = await response(
+            pool, replacement, request("bytes=2-5", if_range=first.headers["etag"])
+        )
+        assert changed.status_code == 200
+        assert changed.headers["etag"] != first.headers["etag"]
+        assert await response_body(changed) == replacement
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_origin_overload_returns_retryable_503_before_stream_headers(tmp_path):
+    class OverloadedPool(ClientPool):
+        @asynccontextmanager
+        async def lease(self, **kwargs):
+            if kwargs.get("download"):
+                raise MediaQueueFull(7)
+            async with super().lease(**kwargs) as client:
+                yield client
+
+    client = account("bot", b"hello")
+    pool = OverloadedPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        overloaded = await response(pool, b"hello")
+        assert overloaded.status_code == 503
+        assert overloaded.headers["retry-after"] == "7"
+        assert json.loads(overloaded.body)["code"] == "TELEGRAM_QUEUE_FULL"
+        assert not client.native.requests
+        assert all(row.active_leases == 0 for row in await pool.status())
+        assert not pool._media_read_cache.memory.flights
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_warm_cache_holds_no_origin_or_metadata_lease(tmp_path):
+    payload = b"x" * (2 * BLOCK)
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        assert await response_body(await response(pool, payload)) == payload
+        reads = sum(client.native.requests.values())
+        warm = await response(pool, payload)
+        assert all(row.active_leases == 0 for row in await pool.status())
+        assert await response_body(warm) == payload
+        assert sum(client.native.requests.values()) == reads
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_revocation_before_headers_closes_primed_iterator(tmp_path):
+    payload = b"x" * (2 * BLOCK)
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    revoked = False
+
+    async def authorize():
+        if revoked:
+            raise PermissionError("Share revoked")
+
+    try:
+        prepared = await response(pool, payload, authorize=authorize)
+        revoked = True
+        sent = []
+
+        async def send(value):
+            sent.append(value)
+
+        async def receive():
+            return {"type": "http.disconnect"}
+
+        with pytest.raises(PermissionError, match="revoked"):
+            await prepared(
+                {"type": "http", "asgi": {"spec_version": "2.4"}}, receive, send
+            )
+        assert not sent
+        assert not pool._media_read_cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_request_id_reaches_origin_leases(tmp_path):
+    client = account("bot", b"hello")
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    leased = pool.lease
+    origins = []
+
+    @asynccontextmanager
+    async def tracked(**kwargs):
+        if kwargs.get("download"):
+            origins.append(kwargs.get("request_id"))
+        async with leased(**kwargs) as owner:
+            yield owner
+
+    pool.lease = tracked
+    try:
+        result = await response(pool, b"hello", request_id="viewer-123")
+        assert await response_body(result) == b"hello"
+        assert origins and set(origins) == {"viewer-123"}
+    finally:
+        await pool.stop()
+
+
+def test_catalog_only_head_tag_is_weak_until_document_identity_is_known():
+    assert media_etag(CHANNEL, 77, 10).startswith("W/")
+    assert not media_etag(
+        CHANNEL, 77, 10, document_identity=("document", 1, 10)
+    ).startswith("W/")
+
+
+def test_if_none_match_uses_weak_comparison_for_catalog_head():
+    tag = media_etag(CHANNEL, 77, 10)
+    assert _not_modified(request(if_none_match=tag), tag)
+    assert _not_modified(request(if_none_match=tag.removeprefix("W/")), tag)
+
+
+@pytest.mark.asyncio
+async def test_revocation_mid_response_stops_body_and_cancels_pending_reads(tmp_path):
+    payload = b"x" * (8 * BLOCK)
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    revoked = False
+
+    async def authorize():
+        if revoked:
+            raise HTTPException(403, "Share revoked")
+
+    try:
+        prepared = await response(pool, payload, authorize=authorize)
+        delivered = bytearray()
+
+        async def send(value):
+            nonlocal revoked
+            if value["type"] == "http.response.body" and value.get("body"):
+                delivered.extend(value["body"])
+                revoked = True
+
+        async def receive():
+            return {"type": "http.disconnect"}
+
+        with pytest.raises(HTTPException, match="revoked"):
+            await prepared(
+                {"type": "http", "asgi": {"spec_version": "2.4"}}, receive, send
+            )
+        assert bytes(delivered) == payload[:BLOCK]
+        assert not pool._media_read_cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_multipart_if_range_uses_catalog_manifest_tag():
+    contents = [b"abc", b"def"]
+    parts = build_parts(contents)
+    client = MultipartClient(contents)
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        tag = media_etag(CHANNEL, 101, 6, parts=parts)
+        selected = await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=101,
+            file_name="movie.mp4",
+            expected_size=6,
+            parts=parts,
+            request=request("bytes=2-3", if_range=tag),
+        )
+        assert selected.headers["etag"] == tag
+        assert selected.headers["content-encoding"] == "identity"
+        assert selected.status_code == 206
+        assert await response_body(selected) == b"cd"
+        full = await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=101,
+            file_name="movie.mp4",
+            expected_size=6,
+            parts=parts,
+            request=request("bytes=2-3", if_range='"stale"'),
+        )
+        assert full.status_code == 200
+        assert await response_body(full) == b"abcdef"
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_multipart_demand_cache_inventory_is_one_logical_file(tmp_path):
+    contents = [b"a" * BLOCK, b"b" * BLOCK]
+    parts = build_parts(contents)
+    client = account("bot", b"")
+    client.native.payloads = {9001: contents[0], 9002: contents[1]}
+
+    async def fetch(_channel, *, message_ids):
+        index = message_ids - 101
+        native = message(9001 + index, len(contents[index]))
+        native.id = message_ids
+        return TelegramMessage(client, native)
+
+    client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        selected = await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=101,
+            file_name="movie.mp4",
+            expected_size=2 * BLOCK,
+            parts=parts,
+            request=request(f"bytes={BLOCK - 10}-{BLOCK + 9}"),
+        )
+        assert await response_body(selected) == b"a" * 10 + b"b" * 10
+        files = (await pool._media_read_cache.snapshot())["files"]
+        assert len(files) == 1
+        assert files[0]["name"] == "movie.mp4" and files[0]["complete"]
+        assert files[0]["ready_ranges"] == [[0, 2 * BLOCK]]
+    finally:
+        if pool._media_read_cache is not None:
+            await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_tiny_http_range_probes_do_not_count_whole_telegram_blocks_as_playback(
+    tmp_path,
+):
+    payload = b"x" * (8 * BLOCK)
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    manager = PreloadManager(
+        pool, policy=MediaCachePolicy(auto_preload=True, min_free_bytes=0)
+    )
+    try:
+        for index in range(5):
+            offset = index * BLOCK
+            probe = await response(
+                pool,
+                payload,
+                request(f"bytes={offset}-{offset}"),
+                request_id="same-video",
+                preview=True,
+            )
+            assert await response_body(probe) == b"x"
+        assert not manager._jobs and not manager._auto_tasks
+        row = next(iter(manager._observed.values()))
+        assert not row["runs"]
+        assert all(not viewer["active"] for viewer in row["viewers"].values())
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_alternate_quality_does_not_schedule_original_file_preloads(tmp_path):
+    original = b"o" * (8 * BLOCK)
+    alternate = b"a" * (5 * BLOCK)
+    client = account("bot", original)
+    client.native.payloads[2] = alternate
+    source = TelegramMessage(
+        client, message(1, len(original), [document(2, len(alternate))])
+    )
+    client.get_messages = AsyncMock(return_value=source)
+    quality = client.describe_media(source)["variants"][0]["id"]
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    manager = PreloadManager(
+        pool, policy=MediaCachePolicy(auto_preload=True, min_free_bytes=0)
+    )
+    try:
+        selected = await response(pool, original, quality=quality)
+        assert await response_body(selected) == alternate
+        assert not manager._observed and not manager._jobs and not manager._auto_tasks
+        assert all(identity == 2 for identity, _offset in client.native.requests)
+        files = (await manager.cache.snapshot())["files"]
+        assert len(files) == 1 and files[0]["complete"]
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "preview,media_destination,download,classified",
+    [
+        (False, False, False, False),
+        (True, False, False, True),
+        (False, True, False, True),
+        (True, True, True, False),
+    ],
+)
+async def test_only_identified_playback_uses_media_duration_for_background_warming(
+    tmp_path, preview, media_destination, download, classified
+):
+    from telethon import types
+
+    payload = b"x" * (2 * BLOCK)
+    client = account("bot", payload)
+    source = message(1, len(payload))
+    source.document.attributes.append(
+        types.DocumentAttributeVideo(duration=3600, w=1920, h=1080)
+    )
+    client.get_messages = AsyncMock(return_value=TelegramMessage(client, source))
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    manager = PreloadManager(
+        pool, policy=MediaCachePolicy(auto_preload=True, min_free_bytes=0)
+    )
+    req = request(
+        f"bytes=0-{BLOCK - 1}",
+        **({"sec_fetch_dest": "video"} if media_destination else {}),
+    )
+    try:
+        selected = await response(
+            pool, payload, req, preview=preview, download=download
+        )
+        assert await response_body(selected) == payload[:BLOCK]
+        assert bool(manager._observed) is classified
+        if classified:
+            observed = next(iter(manager._observed.values()))
+            viewer = next(iter(observed["viewers"].values()))
+            assert viewer["media_rate"] == len(payload) / 3600
+            assert not viewer["allow_full"]
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.parametrize(
+    "duration", [0, -1, float("nan"), float("inf"), 1e-320, True, "60"]
+)
+def test_invalid_telegram_duration_cannot_create_unbounded_bitrate(duration):
+    from types import SimpleNamespace
+
+    from tgdrive.media.streaming import _media_byte_rate
+
+    source = SimpleNamespace(
+        document=SimpleNamespace(attributes=[SimpleNamespace(duration=duration)])
+    )
+    assert _media_byte_rate(source, BLOCK) is None
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("multipart", [False, True])
+async def test_completed_finite_playback_range_warms_next_chunk_for_reuse(
+    tmp_path, multipart
+):
+    import asyncio
+
+    contents = [b"a" * (6 * BLOCK), b"b" * (6 * BLOCK)]
+    payload = b"".join(contents)
+    client = account("bot", payload)
+    parts = build_parts(contents) if multipart else None
+    if parts:
+        client.native.payloads = {9001: contents[0], 9002: contents[1]}
+
+        async def fetch(_channel, *, message_ids):
+            part = parts[message_ids - 101]
+            source = message(part["document_id"], part["size"])
+            source.id = message_ids
+            return TelegramMessage(client, source)
+
+        client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    manager = PreloadManager(
+        pool, policy=MediaCachePolicy(auto_preload=True, min_free_bytes=0)
+    )
+    try:
+        selected = await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=101 if parts else 77,
+            file_name="video.mov",
+            expected_size=len(payload),
+            parts=parts,
+            request=request(f"bytes=0-{4 * BLOCK - 1}"),
+            preview=True,
+            request_id="finite-player",
+        )
+        assert await response_body(selected) == payload[: 4 * BLOCK]
+        for _ in range(100):
+            if manager._jobs:
+                break
+            await asyncio.sleep(0.001)
+        job = next(iter(manager._jobs.values()))
+        task = manager._tasks.get(job["id"])
+        if task is not None:
+            await asyncio.wait_for(asyncio.shield(task), 3)
+        assert job["state"] == "ready"
+        assert job["start"] == 4 * BLOCK and job["end"] == 5 * BLOCK
+        observed = next(iter(manager._observed.values()))
+        viewer = observed["viewers"]["finite-player"]
+        assert viewer["active"] == 0 and viewer["warm_until"] > manager._clock()
+        reads = client.native.requests.copy()
+        following = await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=101 if parts else 77,
+            file_name="video.mov",
+            expected_size=len(payload),
+            parts=parts,
+            request=request(f"bytes={4 * BLOCK}-{5 * BLOCK - 1}"),
+            download=True,
+        )
+        assert await response_body(following) == payload[4 * BLOCK : 5 * BLOCK]
+        assert client.native.requests == reads
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_asgi_abort_does_not_grant_completed_playback_range_grace(tmp_path):
+    import asyncio
+
+    from starlette.requests import ClientDisconnect
+
+    payload = b"x" * (12 * BLOCK)
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    manager = PreloadManager(
+        pool, policy=MediaCachePolicy(auto_preload=True, min_free_bytes=0)
+    )
+    delivered = 0
+
+    async def send(value):
+        nonlocal delivered
+        if value["type"] == "http.response.body":
+            delivered += len(value.get("body", b""))
+            if delivered >= 4 * BLOCK:
+                raise OSError("Client disconnected during playback")
+        await asyncio.sleep(0)
+
+    async def receive():
+        return {"type": "http.disconnect"}
+
+    try:
+        selected = await response(
+            pool, payload, preview=True, request_id="aborted-player"
+        )
+        with pytest.raises(ClientDisconnect):
+            await selected(
+                {"type": "http", "asgi": {"spec_version": "2.4"}}, receive, send
+            )
+        await asyncio.gather(
+            *list(manager._auto_tasks.values()),
+            *list(manager._tasks.values()),
+            return_exceptions=True,
+        )
+        viewer = next(iter(manager._observed.values()))["viewers"]["aborted-player"]
+        assert delivered == 4 * BLOCK
+        assert viewer["active"] == 0 and viewer["warm_until"] == 0
+        assert not manager._viewer_timers
+        assert all(
+            job["state"] not in {"queued", "preparing"}
+            for job in manager._jobs.values()
+        )
+        assert not manager.cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("damaged_length", [0, BLOCK // 2 + 13], ids=["empty", "short"])
+async def test_incomplete_origin_first_block_fails_over_before_headers_and_reuses_cache(
+    tmp_path, damaged_length
+):
+    payload = b"x" * (3 * BLOCK // 4)
+    bot, premium = account("bot", payload), account("premium", payload)
+    premium.native.payloads[1] = payload[:damaged_length]
+    pool = ClientPool([bot], [premium], media_cache_dir=tmp_path)
+    await pool.start()
+    try:
+        selected = await response(pool, payload, request("bytes=17-255"), download=True)
+        assert selected.status_code == 206
+        assert selected.headers["content-length"] == "239"
+        assert await response_body(selected) == payload[17:256]
+        assert premium.native.iterators and bot.native.requests
+        reads = (premium.native.requests.copy(), bot.native.requests.copy())
+        repeated = await response(pool, payload, request("bytes=7-199"), download=True)
+        assert await response_body(repeated) == payload[7:200]
+        assert (premium.native.requests, bot.native.requests) == reads
+        cache = pool._media_read_cache
+        assert not cache.memory.flights and cache.scratch.used == 0
+        assert all(
+            len(entry[1]) == len(payload) for entry in cache.memory.entries.values()
+        )
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        if pool._media_read_cache is not None:
+            await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("damaged_length", [0, BLOCK // 2 + 13], ids=["empty", "short"])
+async def test_incomplete_origin_exhaustion_leaves_no_cache_or_lease_and_retry_recovers(
+    tmp_path, damaged_length
+):
+    payload = b"x" * (3 * BLOCK // 4)
+    client = account("bot", payload)
+    client.native.payloads[1] = payload[:damaged_length]
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    # The synthetic account remains immediately available between attempts.
+    pool.defer_client = AsyncMock()
+    await pool.start()
+    try:
+        with pytest.raises(OSError, match="declared block length"):
+            await response(pool, payload, request("bytes=17-255"), download=True)
+        cache = pool._media_read_cache
+        assert not cache.memory.entries and not cache.memory.flights
+        assert not list(tmp_path.glob("*.block"))
+        assert cache.scratch.used == 0 and not client.native.active
+        assert all(row.active_leases == 0 for row in await pool.status())
+        assert len(client.native.iterators) == 3
+        client.native.payloads[1] = payload
+        retried = await response(pool, payload, request("bytes=17-255"), download=True)
+        assert await response_body(retried) == payload[17:256]
+    finally:
+        if pool._media_read_cache is not None:
+            await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("multipart", [False, True])
+@pytest.mark.parametrize("finish_old", [False, True], ids=["abort-old", "finish-old"])
+async def test_old_response_cannot_change_reopened_viewer_after_cache_clear(
+    tmp_path, multipart, finish_old
+):
+    contents = [b"a" * (6 * BLOCK), b"b" * (6 * BLOCK)]
+    payload = b"".join(contents)
+    client = account("bot", payload)
+    parts = build_parts(contents) if multipart else None
+    if parts:
+        client.native.payloads = {9001: contents[0], 9002: contents[1]}
+
+        async def fetch(_channel, *, message_ids):
+            part = parts[message_ids - 101]
+            source = message(part["document_id"], part["size"])
+            source.id = message_ids
+            return TelegramMessage(client, source)
+
+        client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    manager = PreloadManager(
+        pool, policy=MediaCachePolicy(auto_preload=True, min_free_bytes=0)
+    )
+    first = second = None
+
+    async def selected(start):
+        return await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=101 if parts else 77,
+            file_name="movie.mov",
+            expected_size=len(payload),
+            parts=parts,
+            request=request(f"bytes={start}-{start + 4 * BLOCK - 1}"),
+            preview=True,
+            request_id="reopened-player",
+        )
+
+    try:
+        first = await selected(0)
+        identity = next(iter(manager._observed))
+        await manager.clear(identity)
+        second = await selected(4 * BLOCK)
+        viewer = manager._observed[identity]["viewers"]["reopened-player"]
+        assert viewer["active"] == 1
+        if finish_old:
+            assert await response_body(first) == payload[: 4 * BLOCK]
+        else:
+            await first.body_iterator.aclose()
+        assert viewer["active"] == 1 and viewer["warm_until"] == 0
+        assert viewer["last_end"] is None and viewer["sequential"] == 0
+        assert not manager._jobs and not manager._auto_tasks
+        assert await response_body(second) == payload[4 * BLOCK : 8 * BLOCK]
+        assert viewer["active"] == 0 and viewer["warm_until"] > manager._clock()
+        assert viewer["sequential"] == 4 * BLOCK
+    finally:
+        if first is not None:
+            await first.body_iterator.aclose()
+        if second is not None:
+            await second.body_iterator.aclose()
+        await manager.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_repeated_cancel_before_headers_drains_owned_metadata_lease(tmp_path):
+    import asyncio
+
+    payload = b"exact payload"
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    await pool.start()
+    metadata_started = asyncio.Event()
+    release_started = asyncio.Event()
+    release_allowed = asyncio.Event()
+    metadata_allowed = asyncio.Event()
+    original_lease = pool.lease
+
+    async def metadata(*_args, **_kwargs):
+        metadata_started.set()
+        await metadata_allowed.wait()
+        return TelegramMessage(client, message(1, len(payload)))
+
+    @asynccontextmanager
+    async def delayed_release(**options):
+        async with original_lease(**options) as owner:
+            try:
+                yield owner
+            finally:
+                release_started.set()
+                await release_allowed.wait()
+
+    client.get_messages = AsyncMock(side_effect=metadata)
+    pool.lease = delayed_release
+    pending = asyncio.create_task(response(pool, payload))
+    try:
+        await asyncio.wait_for(metadata_started.wait(), 2)
+        pending.cancel()
+        await asyncio.wait_for(release_started.wait(), 2)
+        pending.cancel()
+        await asyncio.sleep(0)
+        assert not pending.done()
+        release_allowed.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(pending, 2)
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        release_allowed.set()
+        metadata_allowed.set()
+        if not pending.done():
+            pending.cancel()
+        await asyncio.gather(pending, return_exceptions=True)
+        await pool.stop()
diff --git a/tests/media/test_stream_scratch.py b/tests/media/test_stream_scratch.py
new file mode 100644
index 00000000..2cd60546
--- /dev/null
+++ b/tests/media/test_stream_scratch.py
@@ -0,0 +1,444 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tests.media.test_media_scheduler import wait_until
+from tests.media.test_pooled_media import account
+from tests.media.test_telegram_cache import message
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import (
+    BLOCK,
+    MediaReadCache,
+    _AdaptiveReadAhead,
+    stream_pooled_media,
+)
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+
+CHANNEL = -1000000000123
+
+
+@pytest.fixture
+def sustained_reader(monkeypatch):
+    """Stress reclamation after a reader has already demonstrated fast demand.
+
+    Adaptation itself is exercised with real generator advancement and a
+    deterministic clock in test_adaptive_read_ahead; these tests need a full
+    speculative pipeline to preserve their cancellation/fairness edge cases.
+    """
+
+    class SustainedReadAhead(_AdaptiveReadAhead):
+        def __init__(self, maximum):
+            now = 0.0
+            super().__init__(maximum, clock=lambda: now)
+            self.observe_fetch(1)
+            for _ in range(5):
+                now += 0.25
+                self.consumed(100 * BLOCK)
+            self.clock = time.monotonic
+            self._sample_at = self.clock()
+
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._AdaptiveReadAhead", SustainedReadAhead
+    )
+
+
+@pytest.mark.asyncio
+async def test_twenty_slow_distinct_readers_share_bounded_scratch_and_release_on_cancel(
+    tmp_path,
+):
+    payload = b"x" * (6 * BLOCK)
+    accounts = [account(str(index), payload) for index in range(20)]
+    for client in accounts:
+        client.native.payloads = {identity: payload for identity in range(1, 21)}
+
+        async def fetch(_channel, *, message_ids, owner=client):
+            native = message(message_ids - 99, len(payload))
+            native.id = message_ids
+            return TelegramMessage(owner, native)
+
+        client.get_messages = AsyncMock(side_effect=fetch)
+    pool = ClientPool(accounts, media_cache_dir=tmp_path)
+    pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=0,
+            disk_max_bytes=0,
+            scratch_max_bytes=4 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+    await pool.start()
+    iterators, readers = [], []
+    try:
+        for index, client in enumerate(accounts):
+            source = await client.get_messages(CHANNEL, message_ids=index + 100)
+            iterator = stream_pooled_media(
+                pool, client, source, channel=CHANNEL, offset=0, limit=6
+            )
+            iterators.append(iterator)
+            readers.append(asyncio.create_task(anext(iterator)))
+        cache = pool._media_read_cache
+        await wait_until(lambda: any(task.done() for task in readers))
+        await wait_until(lambda: cache._active_streams == 20)
+        await wait_until(lambda: sum(task.done() for task in readers) == 4)
+        completed = sum(task.done() for task in readers)
+        assert cache._active_streams == 20
+        state = await cache.snapshot()
+        assert state["memory"]["bytes"] == state["disk"]["bytes"] == 0
+        assert state["scratch"]["bytes"] == state["scratch"]["peak_bytes"] == 4 * BLOCK
+        assert state["scratch"]["waiting_heads"] == 20 - completed
+        first = next(index for index, task in enumerate(readers) if task.done())
+        assert readers[first].result() == payload[:BLOCK]
+        await iterators[first].aclose()
+        await wait_until(lambda: sum(task.done() for task in readers) > completed)
+        assert cache.scratch.peak == 4
+    finally:
+        for task in readers:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*readers, return_exceptions=True)
+        for iterator in iterators:
+            await iterator.aclose()
+        assert pool._media_read_cache.scratch.used == 0
+        assert pool._media_read_cache._active_streams == 0
+        assert not pool._media_read_cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+        await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_repeated_cancellation_drains_inflight_scratch_reservations(tmp_path):
+    gate = asyncio.Event()
+    client = account("bot", b"x" * (8 * BLOCK), gate)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=0,
+            disk_max_bytes=0,
+            scratch_max_bytes=8 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+    await pool.start()
+    source = await client.get_messages(CHANNEL, message_ids=77)
+    iterator = stream_pooled_media(
+        pool, client, source, channel=CHANNEL, offset=0, limit=8
+    )
+    reader = asyncio.create_task(anext(iterator))
+    try:
+        await wait_until(lambda: client.native.active > 0)
+        reader.cancel()
+        await asyncio.sleep(0)
+        reader.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await reader
+        assert pool._media_read_cache.scratch.used == 0
+        assert pool._media_read_cache._active_streams == 0
+        assert not pool._media_read_cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+    finally:
+        gate.set()
+        await iterator.aclose()
+        await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_sustained_reader_can_use_full_scratch_and_many_origin_fills(
+    tmp_path, monkeypatch, sustained_reader
+):
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    gate = asyncio.Event()
+    payload = b"x" * (64 * BLOCK)
+    accounts = [account(str(index), payload, gate) for index in range(20)]
+    pool = ClientPool(accounts, media_cache_dir=tmp_path)
+    pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=0,
+            disk_max_bytes=0,
+            scratch_max_bytes=32 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+    await pool.start()
+    source = await accounts[0].get_messages(CHANNEL, message_ids=77)
+    iterator = stream_pooled_media(
+        pool, accounts[0], source, channel=CHANNEL, offset=0, limit=64
+    )
+    reader = asyncio.create_task(anext(iterator))
+    try:
+        await wait_until(lambda: sum(client.native.active for client in accounts) == 32)
+        state = await pool._media_read_cache.snapshot()
+        assert state["scratch"]["bytes"] == 32 * BLOCK
+        assert state["memory"]["active_fills"] == 32
+        assert state["memory"]["max_fills"] == 32
+        assert state["scratch"]["active_streams"] == 1
+    finally:
+        reader.cancel()
+        await asyncio.gather(reader, return_exceptions=True)
+        gate.set()
+        await iterator.aclose()
+        assert pool._media_read_cache.scratch.used == 0
+        assert all(client.native.active == 0 for client in accounts)
+        await pool._media_read_cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("tier", ["ram", "disk"])
+async def test_paused_warm_reader_relinquishes_ahead_to_new_heads_and_resumes_in_order(
+    tmp_path, monkeypatch, tier, sustained_reader
+):
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    payload = b"".join(bytes([index]) * BLOCK for index in range(24)) + b"tail"
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path)
+    cache = pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=64 * BLOCK if tier == "ram" else 0,
+            disk_max_bytes=64 * BLOCK if tier == "disk" else 0,
+            scratch_max_bytes=8 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+    await pool.start()
+    source = await client.get_messages(CHANNEL, message_ids=77)
+
+    def stream(offset=0, limit=25):
+        return stream_pooled_media(
+            pool, client, source, channel=CHANNEL, offset=offset, limit=limit
+        )
+
+    paused, seeks, readers = stream(), [], []
+    try:
+        assert b"".join([data async for data in stream()]) == payload
+        await cache.flush()
+        requests = sum(client.native.requests.values())
+        first = await anext(paused)
+        assert first == payload[:BLOCK]
+        await wait_until(lambda: cache.scratch.used == 8)
+        # None of these consumers advance the original reader. Its suspended
+        # read-ahead must make room for new beginning/end/seek probes itself.
+        for index in (24, 10, 3, 20):
+            seek = stream(index, 1)
+            seeks.append(seek)
+            readers.append(asyncio.create_task(anext(seek)))
+        async with asyncio.timeout(2):
+            results = await asyncio.gather(*readers)
+        for index, result in zip((24, 10, 3, 20), results, strict=True):
+            assert result == payload[index * BLOCK : (index + 1) * BLOCK]
+        assert cache.scratch.used <= cache.scratch.peak == 8
+        assert sum(client.native.requests.values()) == requests
+        assert cache.scratch.waiters == 0
+        for seek in seeks:
+            await seek.aclose()
+        # Reclaimed offsets are loaded again from shared retention, without
+        # losing/duplicating any bytes or losing a newer frame's reservation.
+        async with asyncio.timeout(3):
+            assert first + b"".join([data async for data in paused]) == payload
+        assert sum(client.native.requests.values()) == requests
+    finally:
+        for reader in readers:
+            reader.cancel()
+        await asyncio.gather(*readers, return_exceptions=True)
+        for iterator in [paused, *seeks]:
+            await iterator.aclose()
+        assert cache.scratch.used == cache._active_streams == 0
+        assert cache.scratch._streams == set()
+        assert not cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+        await cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cancel_waiter", [False, True])
+async def test_cold_ahead_reclamation_keeps_payload_reserved_until_remote_cleanup(
+    tmp_path, monkeypatch, cancel_waiter, sustained_reader
+):
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    payload = b"".join(bytes([index]) * BLOCK for index in range(16))
+    client = account("bot", payload)
+    release_data, release_cleanup, cancelling = (
+        asyncio.Event(),
+        asyncio.Event(),
+        asyncio.Event(),
+    )
+    active = set()
+
+    async def remote(_source, *, offset, limit, **_kwargs):
+        assert limit == 1
+        active.add(offset)
+        try:
+            if 1 <= offset <= 7:
+                try:
+                    await release_data.wait()
+                except asyncio.CancelledError:
+                    cancelling.set()
+                    await release_cleanup.wait()
+                    raise
+            yield payload[offset * BLOCK : (offset + 1) * BLOCK]
+        finally:
+            active.discard(offset)
+
+    client.stream_media = remote
+    pool = ClientPool([client], media_cache_dir=tmp_path, media_per_bot=16)
+    cache = pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=0,
+            disk_max_bytes=0,
+            scratch_max_bytes=8 * BLOCK,
+            min_free_bytes=0,
+        ),
+    )
+    await pool.start()
+    source = await client.get_messages(CHANNEL, message_ids=77)
+
+    def stream(offset=0, limit=16):
+        return stream_pooled_media(
+            pool, client, source, channel=CHANNEL, offset=offset, limit=limit
+        )
+
+    paused, seek = stream(), stream(15, 1)
+    reader = None
+    try:
+        first = await anext(paused)
+        await wait_until(lambda: active == set(range(1, 8)))
+        assert cache.scratch.used == 8
+        reader = asyncio.create_task(anext(seek))
+        await asyncio.wait_for(cancelling.wait(), 2)
+        assert not reader.done()
+        assert cache.scratch.used == 8  # cancelled I/O still owns its frame
+        assert 15 not in active
+        if cancel_waiter:
+            reader.cancel()
+            await asyncio.sleep(0)
+            reader.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await reader
+            await seek.aclose()
+            seek = stream(15, 1)
+            reader = asyncio.create_task(anext(seek))
+            await wait_until(lambda: cache.scratch.waiters == 1)
+        release_cleanup.set()
+        assert await asyncio.wait_for(reader, 2) == payload[15 * BLOCK :]
+        assert cache.scratch.peak == 8
+        await seek.aclose()
+        release_data.set()
+        async with asyncio.timeout(3):
+            assert first + b"".join([data async for data in paused]) == payload
+    finally:
+        release_cleanup.set()
+        release_data.set()
+        if reader is not None:
+            reader.cancel()
+            await asyncio.gather(reader, return_exceptions=True)
+        await seek.aclose()
+        await paused.aclose()
+        assert cache.scratch.used == cache._active_streams == 0
+        assert not cache.memory.flights
+        assert not active
+        assert all(row.active_leases == 0 for row in await pool.status())
+        await cache.close()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_reclaiming_shared_ahead_keeps_another_viewers_origin_fill_alive(
+    tmp_path, monkeypatch, sustained_reader
+):
+    monkeypatch.setattr(
+        "tgdrive.media.media_reader._effective_memory", lambda value: value
+    )
+    payload = b"".join(bytes([index]) * BLOCK for index in range(16))
+    client = account("bot", payload)
+    release_data = asyncio.Event()
+    calls, cancelled = [], []
+
+    async def remote(_source, *, offset, limit, **_kwargs):
+        assert limit == 1
+        calls.append(offset)
+        try:
+            if offset in (1, 2):
+                await release_data.wait()
+            yield payload[offset * BLOCK : (offset + 1) * BLOCK]
+        except asyncio.CancelledError:
+            cancelled.append(offset)
+            raise
+
+    client.stream_media = remote
+    pool = ClientPool([client], media_cache_dir=tmp_path, media_per_bot=16)
+    cache = pool._media_read_cache = MediaReadCache(
+        tmp_path,
+        MediaCachePolicy(
+            memory_max_bytes=64 * BLOCK,
+            disk_max_bytes=0,
+            scratch_max_bytes=6 * BLOCK,
+            read_ahead_blocks=3,
+            min_free_bytes=0,
+        ),
+    )
+    await pool.start()
+    source = await client.get_messages(CHANNEL, message_ids=77)
+
+    def stream(offset=0, limit=16):
+        return stream_pooled_media(
+            pool, client, source, channel=CHANNEL, offset=offset, limit=limit
+        )
+
+    paused, follower, probe = stream(), stream(2, 1), stream(15, 1)
+    holders = [stream(10, 1), stream(11, 1)]
+    reader = None
+    try:
+        first = await anext(paused)
+        reader = asyncio.create_task(anext(follower))
+        await wait_until(
+            lambda: any(flight.waiters == 2 for flight in cache.memory.flights.values())
+        )
+        for holder in holders:
+            await anext(holder)
+        assert cache.scratch.used == 6
+        assert await asyncio.wait_for(anext(probe), 2) == payload[15 * BLOCK :]
+        # The original reader's farthest ahead was reclaimed, but the shared
+        # fill for block two remains owned by the still-waiting follower.
+        assert calls.count(2) == 1
+        assert 2 not in cancelled
+        assert not reader.done()
+        assert cache.scratch.peak == 6
+        await probe.aclose()
+        for holder in holders:
+            await holder.aclose()
+        release_data.set()
+        assert await asyncio.wait_for(reader, 2) == payload[2 * BLOCK : 3 * BLOCK]
+        await follower.aclose()
+        async with asyncio.timeout(3):
+            assert first + b"".join([data async for data in paused]) == payload
+        assert calls.count(2) == 1
+    finally:
+        release_data.set()
+        if reader is not None:
+            reader.cancel()
+            await asyncio.gather(reader, return_exceptions=True)
+        for iterator in [paused, follower, probe, *holders]:
+            await iterator.aclose()
+        assert cache.scratch.used == cache._active_streams == 0
+        assert not cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+        await cache.close()
+        await pool.stop()
diff --git a/tests/media/test_streaming.py b/tests/media/test_streaming.py
new file mode 100644
index 00000000..ba71d5da
--- /dev/null
+++ b/tests/media/test_streaming.py
@@ -0,0 +1,561 @@
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+from starlette.requests import ClientDisconnect, Request
+
+from tgdrive.media.streaming import TelegramFileNotFound, stream_telegram_file
+from tgdrive.telegram.client_pool import ClientPool
+
+
+class FakeStreamClient:
+    def __init__(self, content: bytes) -> None:
+        self.content = content
+        self.is_connected = False
+        self.name = "stream-test"
+
+    async def start(self) -> None:
+        self.is_connected = True
+
+    async def stop(self) -> None:
+        self.is_connected = False
+
+    async def get_messages(self, _channel: int, *, message_ids: int):
+        assert message_ids == 7
+        return SimpleNamespace(
+            empty=False,
+            document=SimpleNamespace(file_size=len(self.content)),
+            id=message_ids,
+        )
+
+    async def stream_media(self, _message: object, *, limit: int, offset: int):
+        chunk_size = 1024 * 1024
+        end = offset + limit if limit else None
+        chunks = [
+            self.content[index : index + chunk_size]
+            for index in range(0, len(self.content), chunk_size)
+        ]
+        for chunk in chunks[offset:end]:
+            yield chunk
+
+
+def make_request(range_header: str | None = None) -> Request:
+    headers = [] if range_header is None else [(b"range", range_header.encode())]
+    return Request(
+        {
+            "type": "http",
+            "method": "GET",
+            "path": "/file",
+            "headers": headers,
+            "query_string": b"",
+            "server": ("test", 443),
+            "client": ("test", 123),
+            "scheme": "https",
+        }
+    )
+
+
+async def response_body(response: object) -> bytes:
+    return b"".join([chunk async for chunk in response.body_iterator])
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("range_header", "expected", "status"),
+    [
+        (None, b"a" * (1024 * 1024) + b"bc", 200),
+        ("bytes=0-0", b"a", 206),
+        ("bytes=1048575-1048576", b"ab", 206),
+        ("bytes=-2", b"bc", 206),
+    ],
+    ids=["full", "first-byte", "chunk-boundary", "suffix"],
+)
+async def test_streaming_emits_exact_ranges(
+    range_header: str | None, expected: bytes, status: int
+) -> None:
+    content = b"a" * (1024 * 1024) + b"bc"
+    pool = ClientPool([FakeStreamClient(content)])
+    await pool.start()
+
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="video.mp4",
+        expected_size=len(content),
+        request=make_request(range_header),
+    )
+
+    assert response.status_code == status
+    assert int(response.headers["content-length"]) == len(expected)
+    assert await response_body(response) == expected
+    assert all(item.active_leases == 0 for item in await pool.status())
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_active_content_is_attachment_with_sandbox() -> None:
+    pool = ClientPool([FakeStreamClient(b"<script>bad()</script>")])
+    await pool.start()
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="payload.html",
+        expected_size=22,
+        request=make_request(),
+    )
+
+    assert response.headers["content-disposition"].startswith("attachment;")
+    assert response.headers["content-security-policy"].startswith("sandbox")
+    assert response.headers["x-content-type-options"] == "nosniff"
+    await response_body(response)
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_unsatisfiable_range_releases_lease() -> None:
+    pool = ClientPool([FakeStreamClient(b"abc")])
+    await pool.start()
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="a.bin",
+        expected_size=3,
+        request=make_request("bytes=3-"),
+    )
+
+    assert response.status_code == 416
+    assert response.headers["content-range"] == "bytes */3"
+    assert all(item.active_leases == 0 for item in await pool.status())
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_cancellation_before_stream_response_releases_lease() -> None:
+    entered = asyncio.Event()
+
+    class WaitingClient(FakeStreamClient):
+        async def get_messages(self, _channel: int, *, message_ids: int):
+            entered.set()
+            await asyncio.Event().wait()
+
+    pool = ClientPool([WaitingClient(b"abc")])
+    await pool.start()
+    task = asyncio.create_task(
+        stream_telegram_file(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="a.bin",
+            expected_size=3,
+            request=make_request(),
+        )
+    )
+    await entered.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+    assert (await pool.health()).active_leases == 0
+    await pool.stop(drain_timeout=1)
+
+
+@pytest.mark.asyncio
+async def test_response_header_failure_releases_unstarted_stream_lease() -> None:
+    pool = ClientPool([FakeStreamClient(b"abc")])
+    await pool.start()
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="a.bin",
+        expected_size=3,
+        request=make_request(),
+    )
+
+    async def send(_message: object) -> None:
+        raise OSError("browser disconnected before response headers")
+
+    async def receive() -> dict[str, str]:
+        return {"type": "http.disconnect"}
+
+    with pytest.raises(ClientDisconnect):
+        await response({"type": "http", "asgi": {"spec_version": "2.4"}}, receive, send)
+
+    assert (await pool.health()).active_leases == 0
+    await pool.stop(drain_timeout=1)
+
+
+class TrackingStreamClient(FakeStreamClient):
+    def __init__(
+        self,
+        content: bytes,
+        *,
+        name: str,
+        error: Exception | None = None,
+        missing: bool = False,
+    ) -> None:
+        super().__init__(content)
+        self.name = name
+        self.error = error
+        self.missing = missing
+        self.fetches = 0
+        self.streams = 0
+
+    async def get_messages(self, channel: int, *, message_ids: int):
+        self.fetches += 1
+        if self.error:
+            raise self.error
+        if self.missing:
+            return None
+        return await super().get_messages(channel, message_ids=message_ids)
+
+    async def stream_media(self, message: object, *, limit: int, offset: int):
+        self.streams += 1
+        async for chunk in super().stream_media(message, limit=limit, offset=offset):
+            yield chunk
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["GET", "HEAD"])
+async def test_streaming_prefers_premium_for_ranges_and_head(method: str) -> None:
+    bot = TrackingStreamClient(b"bot", name="bot")
+    premium = TrackingStreamClient(b"user", name="premium")
+    pool = ClientPool([bot], [premium])
+    await pool.start()
+
+    request = make_request("bytes=1-2")
+    request.scope["method"] = method
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="video.mp4",
+        expected_size=4,
+        request=request,
+    )
+    assert response.status_code == 206
+    assert response.headers["content-range"] == "bytes 1-2/4"
+    assert premium.fetches == 1
+    assert bot.fetches == 0
+    if method == "GET":
+        assert (await pool.status())[1].active_leases == 1
+        assert await response_body(response) == b"se"
+        assert premium.streams == 1
+    else:
+        assert response.body == b""
+        assert premium.streams == 0
+    assert (await pool.health()).active_leases == 0
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["unhealthy", "disconnected"])
+async def test_streaming_uses_bot_when_premium_unavailable(failure: str) -> None:
+    bot = TrackingStreamClient(b"bot", name="bot")
+    premium = TrackingStreamClient(b"user", name="premium")
+    pool = ClientPool([bot], [premium])
+    await pool.start()
+    if failure == "unhealthy":
+        await pool.mark_unhealthy(premium)
+    else:
+        premium.is_connected = False
+
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="a.bin",
+        expected_size=3,
+        request=make_request(),
+    )
+    assert await response_body(response) == b"bot"
+    assert premium.fetches == 0
+    assert bot.fetches == 1
+    assert (await pool.health()).active_leases == 0
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("method", ["GET", "HEAD"])
+@pytest.mark.parametrize("failure", ["permission", "connection", "missing", "rpc"])
+async def test_premium_metadata_failure_releases_then_retries_bot(
+    method: str, failure: str
+) -> None:
+    from telethon.errors import ChannelPrivateError
+
+    errors = {
+        "permission": PermissionError("synthetic access failure"),
+        "connection": ConnectionError("synthetic connection failure"),
+        "rpc": ChannelPrivateError(request=None),
+    }
+    bot = TrackingStreamClient(b"bot", name="bot")
+    premium = TrackingStreamClient(
+        b"user", name="premium", error=errors.get(failure), missing=failure == "missing"
+    )
+    pool = ClientPool([bot], [premium])
+    await pool.start()
+    request = make_request()
+    request.scope["method"] = method
+
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="a.bin",
+        expected_size=3,
+        request=request,
+    )
+    assert premium.fetches == 1
+    assert bot.fetches == 1
+    assert (await pool.status())[1].active_leases == 0
+    if method == "GET":
+        assert await response_body(response) == b"bot"
+    assert (await pool.health()).active_leases == 0
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_failed_premium_fallback_with_no_bot_does_not_mask_error() -> None:
+    from tgdrive.telegram.client_pool import NoClientAvailable
+
+    premium = TrackingStreamClient(
+        b"user", name="premium", error=PermissionError("synthetic access failure")
+    )
+    pool = ClientPool([], [premium])
+    await pool.start()
+    with pytest.raises(NoClientAvailable):
+        await stream_telegram_file(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="a.bin",
+            expected_size=3,
+            request=make_request(),
+        )
+    assert (await pool.health()).active_leases == 0
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_bot_metadata_failure_is_not_retried() -> None:
+    bot = TrackingStreamClient(
+        b"bot", name="bot", error=PermissionError("synthetic access failure")
+    )
+    pool = ClientPool([bot])
+    await pool.start()
+    with pytest.raises(PermissionError):
+        await stream_telegram_file(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="a.bin",
+            expected_size=3,
+            request=make_request(),
+        )
+    assert bot.fetches == 1
+    assert (await pool.health()).active_leases == 0
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_premium_cancellation_does_not_fall_back_or_leak() -> None:
+    entered = asyncio.Event()
+
+    class WaitingClient(TrackingStreamClient):
+        async def get_messages(self, _channel: int, *, message_ids: int):
+            entered.set()
+            await asyncio.Event().wait()
+
+    premium = WaitingClient(b"user", name="premium")
+    bot = TrackingStreamClient(b"bot", name="bot")
+    pool = ClientPool([bot], [premium])
+    await pool.start()
+    task = asyncio.create_task(
+        stream_telegram_file(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="a.bin",
+            expected_size=3,
+            request=make_request(),
+        )
+    )
+    await entered.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert bot.fetches == 0
+    assert (await pool.health()).active_leases == 0
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_video_download_forces_attachment_and_original_even_with_quality():
+    content = b"original-video-bytes"
+    pool = ClientPool([FakeStreamClient(content)])
+    await pool.start()
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="movie.mp4",
+        expected_size=len(content),
+        request=make_request(),
+        download=True,
+        quality="unrelated-variant",
+    )
+    assert response.headers["content-disposition"].startswith("attachment;")
+    assert await response_body(response) == content
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_pdf_preview_inline_only_with_explicit_preview_flag():
+    content = b"%PDF-1.7 sample"
+    pool = ClientPool([FakeStreamClient(content)])
+    await pool.start()
+    for preview, expected in ((False, "attachment;"), (True, "inline;")):
+        response = await stream_telegram_file(
+            pool=pool,
+            channel_id=-100,
+            message_id=7,
+            file_name="manual.pdf",
+            expected_size=len(content),
+            request=make_request(),
+            preview=preview,
+        )
+        assert response.headers["content-disposition"].startswith(expected)
+        if preview:
+            assert response.headers["x-frame-options"] == "SAMEORIGIN"
+        assert await response_body(response) == content
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_video_inline_policy_allows_native_document_to_read_media():
+    content = b"video"
+    pool = ClientPool([FakeStreamClient(content)])
+    await pool.start()
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="movie.mp4",
+        expected_size=len(content),
+        request=make_request(),
+    )
+    assert "media-src 'self'" in response.headers["content-security-policy"]
+    assert not response.headers["content-security-policy"].startswith("sandbox")
+    assert await response_body(response) == content
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_response_body_send_failure_closes_iterator_before_lease_release() -> (
+    None
+):
+    closed = asyncio.Event()
+    produced = []
+
+    class CancellableClient(FakeStreamClient):
+        async def stream_media(self, message: object, *, limit: int, offset: int):
+            try:
+                async for chunk in super().stream_media(
+                    message, limit=limit, offset=offset
+                ):
+                    produced.append(chunk)
+                    yield chunk
+            finally:
+                closed.set()
+
+    pool = ClientPool([CancellableClient(b"a" * (2 * 1024**2))])
+    await pool.start()
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="movie.mp4",
+        expected_size=2 * 1024**2,
+        request=make_request(),
+    )
+
+    async def send(message):
+        if message["type"] == "http.response.body":
+            raise OSError("browser disconnected during playback")
+
+    async def receive():
+        return {"type": "http.disconnect"}
+
+    with pytest.raises(ClientDisconnect):
+        await response({"type": "http", "asgi": {"spec_version": "2.4"}}, receive, send)
+    assert closed.is_set()
+    assert len(produced) == 1
+    assert (await pool.health()).active_leases == 0
+    await pool.stop(drain_timeout=1)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(("download", "status"), [(False, 413), (True, 200)])
+async def test_large_pdf_download_overrides_preview_size_cap(download, status):
+    from tgdrive.media.streaming import PDF_PREVIEW_BYTES
+
+    size = PDF_PREVIEW_BYTES + 1
+
+    class LargePdfClient(FakeStreamClient):
+        async def get_messages(self, _channel: int, *, message_ids: int):
+            return SimpleNamespace(
+                empty=False, document=SimpleNamespace(file_size=size), id=message_ids
+            )
+
+    pool = ClientPool([LargePdfClient(b"")])
+    await pool.start()
+    request = make_request()
+    request.scope["method"] = "HEAD"
+    response = await stream_telegram_file(
+        pool=pool,
+        channel_id=-100,
+        message_id=7,
+        file_name="large.pdf",
+        expected_size=size,
+        request=request,
+        preview=True,
+        download=download,
+    )
+    assert response.status_code == status
+    if download:
+        assert response.headers["content-disposition"].startswith("attachment;")
+        assert int(response.headers["content-length"]) == size
+    assert (await pool.health()).active_leases == 0
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("missing", [True, False])
+async def test_missing_or_changed_storage_message_fails_before_stream_headers(missing):
+    class DamagedClient(FakeStreamClient):
+        async def get_messages(self, channel, *, message_ids):
+            if missing:
+                return None
+            return await super().get_messages(channel, message_ids=message_ids)
+
+    pool = ClientPool([DamagedClient(b"changed payload")])
+    await pool.start()
+    try:
+        with pytest.raises(TelegramFileNotFound) as error:
+            await stream_telegram_file(
+                pool=pool,
+                channel_id=-100,
+                message_id=7,
+                file_name="original.bin",
+                expected_size=3,
+                request=make_request(),
+            )
+        assert "missing or changed" in error.value.public_detail
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
diff --git a/tests/media/test_telegram_cache.py b/tests/media/test_telegram_cache.py
new file mode 100644
index 00000000..9d59b058
--- /dev/null
+++ b/tests/media/test_telegram_cache.py
@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import asyncio
+from collections import Counter
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+import pytest
+from telethon import types, utils
+
+from tgdrive.telegram.clients import Client, TelegramMessage, _BlockCache
+
+MIB = 1024**2
+
+
+def document(identity, size):
+    return types.Document(
+        id=identity,
+        access_hash=2,
+        file_reference=b"current",
+        date=datetime.now(UTC),
+        mime_type="video/mp4",
+        size=size,
+        dc_id=2,
+        attributes=[types.DocumentAttributeFilename(file_name="original.mp4")],
+    )
+
+
+def message(identity, size, alternates=()):
+    return types.Message(
+        id=77,
+        peer_id=types.PeerChannel(123),
+        date=datetime.now(UTC),
+        message="",
+        media=types.MessageMediaDocument(
+            document=document(identity, size), alt_documents=list(alternates)
+        ),
+    )
+
+
+class Iterator:
+    def __init__(self, owner, identity, offset, limit):
+        self.owner, self.identity, self.offset, self.limit = (
+            owner,
+            identity,
+            offset,
+            limit,
+        )
+        self.count = 0
+        self.closed = False
+        owner.active += 1
+        owner.peak = max(owner.peak, owner.active)
+        owner.iterators.append(self)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        data = self.owner.payloads[self.identity]
+        if self.count >= self.limit or self.offset >= len(data):
+            raise StopAsyncIteration
+        self.owner.requests[(self.identity, self.offset)] += 1
+        self.count += 1
+        if self.owner.gate is not None:
+            await self.owner.gate.wait()
+        await asyncio.sleep(0)
+        result = data[self.offset : self.offset + MIB // 2]
+        self.offset += len(result)
+        return result
+
+    async def close(self):
+        if not self.closed:
+            self.closed = True
+            self.owner.active -= 1
+
+
+class Native:
+    def __init__(self, payloads, gate=None):
+        self.payloads, self.gate = payloads, gate
+        self.requests = Counter()
+        self.active = self.peak = 0
+        self.iterators = []
+
+    def iter_download(self, target, *, offset, request_size, limit):
+        dc, location = utils.get_input_location(target)
+        assert dc == 2 and request_size == MIB // 2
+        return Iterator(self, location.id, offset, limit)
+
+
+def transport(native, name="account-one"):
+    value = Client.__new__(Client)
+    value.native, value.name = native, name
+    return value
+
+
+async def read(client, source, limit=1, offset=0):
+    return b"".join(
+        [part async for part in client.stream_media(source, limit=limit, offset=offset)]
+    )
+
+
+async def wait_for(predicate):
+    for _ in range(100):
+        if predicate():
+            return
+        await asyncio.sleep(0)
+    raise AssertionError("state did not settle")
+
+
+@pytest.mark.asyncio
+async def test_repeated_overlapping_and_final_window_reads_reuse_confirmed_bytes():
+    payload = b"a" * MIB + b"b" * MIB + b"c" * MIB + b"tail"
+    native = Native({1: payload})
+    client = transport(native)
+    source = TelegramMessage(client, message(1, len(payload)))
+    assert await read(client, source) == payload[:MIB]
+    assert await read(client, source) == payload[:MIB]
+    assert await read(client, source, limit=2) == payload[: 2 * MIB]
+    assert await read(client, source, offset=3) == b"tail"
+    assert await read(client, source, offset=3) == b"tail"
+    assert sum(native.requests.values()) == 5  # two complete windows + one tail
+    assert all(count == 1 for count in native.requests.values())
+    assert client._download_block_cache.bytes_used == 2 * MIB + 4
+    assert native.active == 0
+
+
+@pytest.mark.asyncio
+async def test_variants_replacements_and_accounts_never_share_wrong_bytes():
+    payloads = {1: b"o" * MIB, 2: b"v" * MIB, 3: b"n" * MIB}
+    native = Native(payloads)
+    client = transport(native)
+    source = TelegramMessage(client, message(1, MIB, [document(2, MIB)]))
+    variant = client.select_media_variant(
+        source, client.describe_media(source)["variants"][0]["id"]
+    )
+    for _ in range(2):
+        assert await read(client, source) == payloads[1]
+        assert await read(client, variant) == payloads[2]
+    replacement = TelegramMessage(client, message(3, MIB))
+    assert await read(client, replacement) == payloads[3]
+    assert sum(native.requests.values()) == 6
+    other_native = Native(payloads)
+    other = transport(other_native, "account-two")
+    assert await read(other, TelegramMessage(other, message(1, MIB))) == payloads[1]
+    assert sum(other_native.requests.values()) == 2
+    assert other._download_block_cache is client._download_block_cache
+
+
+@pytest.mark.asyncio
+async def test_partial_windows_are_not_cached_as_confirmed_bytes():
+    native = Native({1: b"x" * (MIB // 2)})
+    client = transport(native)
+    source = TelegramMessage(client, message(1, MIB))
+    assert len(await read(client, source)) == MIB // 2
+    assert len(await read(client, source)) == MIB // 2
+    assert sum(native.requests.values()) == 2
+    assert client._download_block_cache.bytes_used == 0
+
+
+@pytest.mark.asyncio
+async def test_one_cancelled_waiter_does_not_cancel_other_shared_readers():
+    gate = asyncio.Event()
+    native = Native({1: b"x" * MIB}, gate)
+    client = transport(native)
+    source = TelegramMessage(client, message(1, MIB))
+    readers = [asyncio.create_task(read(client, source)) for _ in range(3)]
+    await wait_for(
+        lambda: (
+            getattr(client, "_download_block_cache", None) is not None
+            and any(
+                f.waiters == 3 for f in client._download_block_cache.flights.values()
+            )
+        )
+    )
+    readers[0].cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await readers[0]
+    assert native.active == 1 and not native.iterators[0].closed
+    gate.set()
+    assert await readers[1] == await readers[2] == b"x" * MIB
+    assert sum(native.requests.values()) == 2
+    assert native.active == 0 and not client._download_block_cache.flights
+
+
+@pytest.mark.asyncio
+async def test_last_waiter_cancel_drains_read_and_a_new_request_starts_cleanly():
+    gate = asyncio.Event()
+    native = Native({1: b"x" * MIB}, gate)
+    client = transport(native)
+    source = TelegramMessage(client, message(1, MIB))
+    first = asyncio.create_task(read(client, source))
+    await wait_for(lambda: native.active == 1)
+    first.cancel()
+    second = asyncio.create_task(read(client, source))
+    with pytest.raises(asyncio.CancelledError):
+        await first
+    gate.set()
+    assert await second == b"x" * MIB
+    assert native.peak == 1
+    assert all(iterator.closed for iterator in native.iterators)
+    assert not client._download_block_cache.flights
+
+
+@pytest.mark.asyncio
+async def test_cache_lru_byte_entry_and_expiry_bounds():
+    clock = SimpleNamespace(now=0.0)
+    cache = _BlockCache(max_bytes=4, max_entries=2, ttl=30, clock=lambda: clock.now)
+    loads = []
+
+    async def load(value):
+        loads.append(value)
+        return value
+
+    async def get(key, value):
+        return await cache.get((key,), len(value), lambda: load(value))
+
+    await get("a", b"aa")
+    await get("b", b"bb")
+    await get("a", b"aa")
+    await get("c", b"cc")
+    assert list(cache.entries) == [("a",), ("c",)]
+    assert cache.bytes_used == 4 and len(loads) == 3
+    clock.now = 29
+    assert await get("a", b"aa") == b"aa"
+    clock.now = 30
+    assert await get("a", b"aa") == b"aa"
+    assert len(loads) == 4 and cache.bytes_used == 2
+    # Tiny payloads are also bounded by entry count, independent of byte budget.
+    await get("d", b"d")
+    await get("e", b"e")
+    assert len(cache.entries) == 2 and cache.bytes_used == 2
+
+
+@pytest.mark.asyncio
+async def test_global_unique_read_bound_and_cancelled_admission_leave_no_tasks():
+    cache = _BlockCache(read_slots=2)
+    gate = asyncio.Event()
+    state = SimpleNamespace(active=0, peak=0)
+
+    async def load():
+        state.active += 1
+        state.peak = max(state.peak, state.active)
+        try:
+            await gate.wait()
+            return b"x"
+        finally:
+            state.active -= 1
+
+    readers = [asyncio.create_task(cache.get((index,), 1, load)) for index in range(5)]
+    await wait_for(lambda: state.active == 2)
+    assert len(cache.flights) == 2
+    for reader in readers:
+        reader.cancel()
+    await asyncio.gather(*readers, return_exceptions=True)
+    assert state.peak == 2 and state.active == 0
+    assert not cache.flights and cache.bytes_used == 0
+    assert await cache.get((99,), 1, lambda: asyncio.sleep(0, result=b"y")) == b"y"
+
+
+@pytest.mark.asyncio
+async def test_failed_reads_release_capacity_and_are_not_cached():
+    cache = _BlockCache(read_slots=1)
+
+    async def fail():
+        raise RuntimeError("synthetic provider failure")
+
+    with pytest.raises(RuntimeError, match="provider failure"):
+        await cache.get((1,), 1, fail)
+    assert not cache.entries and not cache.flights
+    assert await cache.get((1,), 1, lambda: asyncio.sleep(0, result=b"z")) == b"z"
+
+
+@pytest.mark.asyncio
+async def test_controlled_player_seek_pattern_halves_native_part_requests(monkeypatch):
+    import tgdrive.telegram.clients as module
+
+    class Uncached:
+        async def get(self, key, expected, load):
+            return await load()
+
+    payload = b"a" * MIB + b"b" * MIB + b"c" * MIB + b"tail"
+    pattern = [(0, 1), (0, 1), (0, 2), (3, 1), (3, 1), (1, 2)]
+    observed = []
+    for cached in (False, True):
+        native = Native({1: payload})
+        client = transport(native)
+        source = TelegramMessage(client, message(1, len(payload)))
+        with monkeypatch.context() as patch:
+            if not cached:
+                patch.setattr(module, "_client_block_cache", lambda _: Uncached())
+            for offset, limit in pattern:
+                assert (
+                    await read(client, source, limit=limit, offset=offset)
+                    == payload[offset * MIB : (offset + limit) * MIB]
+                )
+        observed.append(sum(native.requests.values()))
+        assert native.active == 0
+    assert observed == [14, 7]
+
+
+def test_cached_payloads_are_not_reused_across_event_loops():
+    native = Native({1: b"x" * MIB})
+    client = transport(native)
+    source = TelegramMessage(client, message(1, MIB))
+    assert asyncio.run(read(client, source)) == b"x" * MIB
+    first = client._download_block_cache
+    assert asyncio.run(read(client, source)) == b"x" * MIB
+    assert client._download_block_cache is not first
+    assert sum(native.requests.values()) == 4
diff --git a/tests/media/test_telegram_prefetch.py b/tests/media/test_telegram_prefetch.py
new file mode 100644
index 00000000..aea84886
--- /dev/null
+++ b/tests/media/test_telegram_prefetch.py
@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from fastapi import FastAPI, Request
+from fastapi.testclient import TestClient
+from telethon import types, utils
+from telethon.errors import FileReferenceExpiredError
+
+from tgdrive.telegram.clients import Client, TelegramMessage
+
+MIB = 1024**2
+CHANNEL = -1001234567890
+
+
+def client(native):
+    value = Client.__new__(Client)
+    value.native = native
+    return value
+
+
+class PartIterator:
+    def __init__(self, owner, offset, limit):
+        self.owner, self.offset, self.limit = owner, offset, limit
+        self.count = 0
+        self.closed = False
+        owner.iterators.append(self)
+        owner.active += 1
+        owner.peak = max(owner.peak, owner.active)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if self.count >= self.limit or self.offset >= len(self.owner.payload):
+            raise StopAsyncIteration
+        self.count += 1
+        self.owner.requests += 1
+        if self.owner.gate:
+            await self.owner.gate.wait()
+        else:
+            await asyncio.sleep(0.001 * (4 - self.offset // MIB % 4))
+        part = self.owner.payload[self.offset : self.offset + MIB // 2]
+        self.offset += len(part)
+        return part
+
+    async def close(self):
+        if not self.closed:
+            self.closed = True
+            self.owner.active -= 1
+
+
+class Native:
+    def __init__(self, payload, gate=None):
+        self.payload, self.gate = payload, gate
+        self.requests = self.active = self.peak = 0
+        self.iterators = []
+
+    def iter_download(self, message, *, offset, request_size, limit):
+        assert request_size == MIB // 2
+        return PartIterator(self, offset, limit)
+
+
+@pytest.mark.asyncio
+async def test_prefetch_reorders_completed_windows_and_preserves_exact_tail():
+    payload = b"".join(bytes([i]) * MIB for i in range(7)) + b"tail"
+    native = Native(payload)
+    parts = [
+        part
+        async for part in client(native).stream_media(
+            SimpleNamespace(), limit=6, offset=2
+        )
+    ]
+    assert b"".join(parts) == payload[2 * MIB :]
+    assert native.peak == 4 and native.active == 0
+    assert all(item.closed for item in native.iterators)
+
+
+@pytest.mark.asyncio
+async def test_slow_consumer_has_bounded_read_ahead_and_close_drains_every_iterator():
+    native = Native(b"x" * (32 * MIB))
+    stream = client(native).stream_media(SimpleNamespace(), limit=32, offset=0)
+    assert len(await anext(stream)) == MIB
+    await asyncio.sleep(0.03)
+    assert native.requests == 8
+    assert len(native.iterators) == 4
+    await stream.aclose()
+    assert native.active == 0 and all(item.closed for item in native.iterators)
+
+
+@pytest.mark.asyncio
+async def test_request_cancellation_drains_blocked_prefetch_workers():
+    native = Native(b"x" * (8 * MIB), asyncio.Event())
+
+    async def consume():
+        return [
+            part
+            async for part in client(native).stream_media(
+                SimpleNamespace(), limit=8, offset=0
+            )
+        ]
+
+    task = asyncio.create_task(consume())
+    for _ in range(20):
+        await asyncio.sleep(0)
+        if native.active == 4:
+            break
+    assert native.active == 4
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert native.active == 0 and all(item.closed for item in native.iterators)
+
+
+def document(identity, size=2 * MIB, reference=b"current"):
+    return types.Document(
+        id=identity,
+        access_hash=123,
+        file_reference=reference,
+        date=datetime.now(UTC),
+        mime_type="video/mp4",
+        size=size,
+        dc_id=2,
+        attributes=[
+            types.DocumentAttributeVideo(
+                duration=3.0, w=1280, h=720, supports_streaming=True
+            )
+        ],
+    )
+
+
+def message(original, alternatives=(), message_id=77):
+    return SimpleNamespace(
+        id=message_id,
+        chat_id=CHANNEL,
+        document=original,
+        photo=None,
+        media=types.MessageMediaDocument(
+            document=original, alt_documents=list(alternatives)
+        ),
+    )
+
+
+def test_variant_descriptors_and_selection_are_bound_to_the_source_message():
+    original, alternate = document(1, 3 * MIB), document(2)
+    transport = client(SimpleNamespace())
+    source = message(original, [alternate])
+    info = transport.describe_media(source)
+    assert info["original"]["id"] == "original"
+    assert info["original"]["is_original"] is True
+    descriptor = info["variants"][0]
+    assert descriptor["height"] == 720 and descriptor["label"] == "720p"
+    assert set(descriptor) == {
+        "id",
+        "label",
+        "width",
+        "height",
+        "duration",
+        "size",
+        "mime_type",
+        "is_original",
+    }
+    selected = transport.select_media_variant(source, descriptor["id"])
+    assert selected.download_media is alternate
+    assert selected.document.file_size == 2 * MIB
+    assert transport.select_media_variant(source, "original") is source
+    assert transport.select_media_variant(selected, "original") is source
+    with pytest.raises(ValueError, match="unavailable"):
+        transport.select_media_variant(
+            message(original, [alternate], message_id=78), descriptor["id"]
+        )
+    assert transport.describe_media(message(original))["variants"] == []
+
+
+@pytest.mark.asyncio
+async def test_selected_document_is_downloaded_and_reselected_after_reference_refresh():
+    original = document(1)
+    stale, fresh = document(2, reference=b"stale"), document(2, reference=b"fresh")
+    source, refreshed = message(original, [stale]), message(original, [fresh])
+    closed = []
+
+    class Iterator:
+        def __init__(self, media):
+            self.media = media
+
+        def __aiter__(self):
+            return self
+
+        async def __anext__(self):
+            if self.media.file_reference == b"stale":
+                raise FileReferenceExpiredError(request=None)
+            if getattr(self, "sent", False):
+                raise StopAsyncIteration
+            self.sent = True
+            return b"video"
+
+        async def close(self):
+            closed.append(self.media)
+
+    native = SimpleNamespace(
+        iter_download=Mock(side_effect=lambda media, **_: Iterator(media)),
+        get_messages=AsyncMock(return_value=refreshed),
+    )
+    transport = client(native)
+    # Avoid wrapping synthetic messages: refresh still exercises bound reselection.
+    transport.get_messages = AsyncMock(return_value=refreshed)
+    quality = transport.describe_media(source)["variants"][0]["id"]
+    selected = transport.select_media_variant(source, quality)
+    assert (
+        b"".join(
+            [part async for part in transport.stream_media(selected, limit=1, offset=0)]
+        )
+        == b"video"
+    )
+    assert [call.args[0] for call in native.iter_download.call_args_list] == [
+        stale,
+        fresh,
+    ]
+    transport.get_messages.assert_awaited_once_with(CHANNEL, message_ids=77)
+    assert closed == [stale, fresh]
+
+
+def test_photo_sizes_are_discovered_without_claiming_document_image_variants():
+    sizes = [
+        types.PhotoSize(type="m", w=320, h=240, size=100),
+        types.PhotoSizeProgressive(type="x", w=1280, h=960, sizes=[200, 400]),
+    ]
+    photo = types.Photo(
+        id=7,
+        access_hash=8,
+        file_reference=b"ref",
+        date=datetime.now(UTC),
+        sizes=sizes,
+        dc_id=2,
+    )
+    source = SimpleNamespace(id=77, chat_id=CHANNEL, document=None, photo=photo)
+    transport = client(SimpleNamespace())
+    info = transport.describe_media(source)
+    assert info["original"]["size"] == 400
+    assert info["variants"][0]["width"] == 320
+    selection = transport.select_media_variant(source, info["variants"][0]["id"])
+    assert selection.download_media.sizes == [sizes[0]]
+    assert source.photo.sizes == sizes
+    assert transport.describe_media(
+        SimpleNamespace(id=77, chat_id=CHANNEL, document=None, photo=None)
+    ) == {"original": None, "variants": []}
+
+
+@pytest.mark.asyncio
+async def test_scheduled_processing_identity_is_never_committed_as_channel_message():
+    native = SimpleNamespace(get_messages=AsyncMock())
+    result = SimpleNamespace(
+        updates=[
+            types.UpdateNewScheduledMessage(
+                message=SimpleNamespace(id=77, video_processing_pending=True)
+            )
+        ]
+    )
+    with pytest.raises(RuntimeError, match="processing scheduled"):
+        await client(native)._sent(CHANNEL, result)
+    native.get_messages.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_reference_refresh_refuses_to_switch_to_replaced_original_media():
+    source = message(document(1))
+    replacement = message(document(99))
+
+    class BrokenIterator:
+        closed = False
+
+        def __aiter__(self):
+            return self
+
+        async def __anext__(self):
+            raise FileReferenceExpiredError(request=None)
+
+        async def close(self):
+            self.closed = True
+
+    iterator = BrokenIterator()
+    transport = client(SimpleNamespace(iter_download=Mock(return_value=iterator)))
+    transport.get_messages = AsyncMock(return_value=replacement)
+    with pytest.raises(FileNotFoundError, match="replaced"):
+        _ = [part async for part in transport.stream_media(source, limit=1, offset=0)]
+    assert iterator.closed
+
+
+@pytest.mark.asyncio
+async def test_parallel_reference_failures_share_one_message_refresh():
+    source, refreshed = message(document(1)), message(document(1, reference=b"fresh"))
+    base = Native(b"x" * (4 * MIB))
+    stale_closed = []
+
+    class ExpiredIterator:
+        def __aiter__(self):
+            return self
+
+        async def __anext__(self):
+            await asyncio.sleep(0)
+            raise FileReferenceExpiredError(request=None)
+
+        async def close(self):
+            stale_closed.append(True)
+
+    def iterator(target, **options):
+        if target is source:
+            return ExpiredIterator()
+        return base.iter_download(target, **options)
+
+    transport = client(SimpleNamespace(iter_download=Mock(side_effect=iterator)))
+
+    async def fetch(*_args, **_kwargs):
+        await asyncio.sleep(0.005)
+        return refreshed
+
+    transport.get_messages = AsyncMock(side_effect=fetch)
+    result = b"".join(
+        [part async for part in transport.stream_media(source, limit=4, offset=0)]
+    )
+    assert result == base.payload
+    transport.get_messages.assert_awaited_once_with(CHANNEL, message_ids=77)
+    assert len(stale_closed) == 4 and base.active == 0
+
+
+class ValidatingNative(Native):
+    """Exercise Telethon's actual file-location coercion before yielding bytes."""
+
+    def iter_download(self, target, **options):
+        dc_id, location = utils.get_input_location(target)
+        assert dc_id == 2 and isinstance(location, types.InputDocumentFileLocation)
+        assert location.id == 1
+        return super().iter_download(target, **options)
+
+
+def real_message():
+    return types.Message(
+        id=77,
+        peer_id=types.PeerChannel(123),
+        date=datetime.now(UTC),
+        message="",
+        media=types.MessageMediaDocument(document=document(1, size=8)),
+    )
+
+
+@pytest.mark.asyncio
+async def test_real_message_download_method_is_never_mistaken_for_media_target():
+    native = ValidatingNative(b"original")
+    transport = client(native)
+    wrapped = TelegramMessage(transport, real_message())
+    assert callable(wrapped.download_media)
+    chunks = [part async for part in transport.stream_media(wrapped, limit=1, offset=0)]
+    assert b"".join(chunks) == b"original"
+    assert native.active == 0
+
+
+def test_real_message_first_yield_survives_base_http_middleware():
+    from tgdrive.media.streaming import stream_telegram_file
+
+    native = ValidatingNative(b"original")
+    native.get_messages = AsyncMock(return_value=real_message())
+    transport = client(native)
+
+    class Pool:
+        @asynccontextmanager
+        async def lease(self, **options):
+            yield transport
+
+        def kind_of(self, value):
+            return "bot"
+
+    pool = Pool()
+    app = FastAPI()
+
+    @app.middleware("http")
+    async def headers(request, call_next):
+        response = await call_next(request)
+        response.headers["X-Test"] = "wrapped"
+        return response
+
+    @app.get("/file")
+    async def file(request: Request):
+        return await stream_telegram_file(
+            pool=pool,
+            channel_id=CHANNEL,
+            message_id=77,
+            file_name="video.mp4",
+            expected_size=8,
+            request=request,
+        )
+
+    with TestClient(app) as http:
+        response = http.get("/file")
+        repeated = http.get("/file")
+    assert response.content == repeated.content
+    assert native.get_messages.await_count == 2
+    assert native.requests == 1  # The second HTTP request reuses bytes, not metadata.
+    assert response.status_code == 200
+    assert response.content == b"original"
+    assert response.headers["Content-Length"] == "8"
+    assert response.headers["X-Test"] == "wrapped"
+    assert native.active == 0
diff --git a/tests/media/test_thumbnail_rebuild.py b/tests/media/test_thumbnail_rebuild.py
new file mode 100644
index 00000000..60e5bfcf
--- /dev/null
+++ b/tests/media/test_thumbnail_rebuild.py
@@ -0,0 +1,286 @@
+"""Synthetic, offline regeneration: bounded reads, isolation and owner controls."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import shutil
+from pathlib import Path
+from types import SimpleNamespace
+
+import aiohttp
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.errors import TrashedItemError
+from tgdrive.media import thumbnail_rebuild as module
+from tgdrive.media.generated_thumbnails import read, save
+from tgdrive.media.thumbnails import Thumbnail, ThumbnailCache
+from tgdrive.storage.store import DriveStore
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+from tgdrive.web.app import create_app
+
+COVER = b"\xff\xd8\xffnew cover\xff\xd9"
+
+
+@pytest.fixture
+async def rebuild(tmp_path):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "store.json")
+    registry = TransferRegistry()
+    runtime = SimpleNamespace(store=store, pool=object(), registry=registry)
+    manager = module.ThumbnailRebuild(settings, lambda: runtime, ThumbnailCache())
+    yield manager, store, runtime
+    await manager.close()
+    await manager.thumbnails.close()
+    store.close()
+    registry.close()
+
+
+async def test_force_replaces_existing_covers_counts_skips_and_ignores_trash(
+    rebuild, monkeypatch
+):
+    manager, store, _ = rebuild
+    folder = store.create_folder("/", "Nested")
+    photo = store.add_file("/" + folder["id"], "photo.jpg", 2, 10)
+    store.add_file("/", "notes.txt", 3, 10)
+    hidden = store.create_folder("/", "Hidden")
+    store.add_file("/" + hidden["id"], "hidden.jpg", 4, 10)
+    store.set_trashed("/" + hidden["id"], True)
+    save(manager.directory, manager.settings.storage_channel, 2, b"\xff\xd8\xffold")
+    calls = []
+
+    async def render(source):
+        calls.append(source.data["id"])
+        return COVER
+
+    monkeypatch.setattr(manager, "render_file", render)
+    await manager.start()
+    await manager.task
+    assert calls == [photo["id"]]
+    assert manager.state["status"] == "completed"
+    assert manager.state["total"] == manager.state["processed"] == 2
+    assert manager.state["generated"] == manager.state["skipped"] == 1
+    assert read(manager.directory, manager.settings.storage_channel, 2) == COVER
+    assert store.get_file(store.resolve_id(photo["id"]))["message_id"] == 2
+    assert json.loads(manager.path.read_text())["status"] == "completed"
+    if os.name == "posix":
+        assert manager.path.stat().st_mode & 0o077 == 0
+
+
+async def test_single_run_yields_to_active_work_and_can_be_cancelled(
+    rebuild, monkeypatch
+):
+    manager, store, runtime = rebuild
+    store.add_file("/", "photo.jpg", 2, 10)
+    active = await runtime.registry.create("uploading")
+    active.status = TransferStatus.RUNNING
+    calls = []
+
+    async def render(source):
+        calls.append(source)
+        return COVER
+
+    monkeypatch.setattr(manager, "render_file", render)
+    waiting = asyncio.Event()
+    persist_progress = manager.persist_progress
+
+    async def observe_wait():
+        if manager.state["phase"] == "Waiting for active transfers or playback":
+            waiting.set()
+        await persist_progress()
+
+    monkeypatch.setattr(manager, "persist_progress", observe_wait)
+    first, second = await asyncio.gather(manager.start(), manager.start())
+    assert first["id"] == second["id"]
+    await asyncio.wait_for(waiting.wait(), 2)
+    assert not calls
+    stopped = await manager.cancel()
+    assert stopped["status"] == "cancelled"
+    assert stopped["processed"] == 0
+    assert manager.task.done()
+
+
+async def test_sparse_reader_bounds_origin_work_and_reuses_hot_blocks(
+    rebuild, monkeypatch
+):
+    manager, store, _ = rebuild
+    item = store.add_file("/", "movie.mov", 9, 5 * 1024**3)
+    manager.drive_id = store.drive_id
+    manager.state["source_bytes"] = 0
+    source = module.RebuildSource(manager, item)
+    source.budget = module.BLOCK
+    calls = []
+
+    async def fetch(pool, channel, data, start, length, authorize, *, background):
+        assert background is True
+        await authorize()
+        calls.append((start, length))
+        return b"x" * length
+
+    monkeypatch.setattr(module, "read_range", fetch)
+    monkeypatch.setattr(module, "RATE", 10**12)
+    offset = 3 * 1024**3
+    assert await source.read(offset, 16) == b"x" * 16
+    assert await source.read(offset + 10, 16) == b"x" * 16
+    with pytest.raises(module.SourceLimit):
+        await source.read(offset + module.BLOCK, 1)
+    assert calls == [(offset, module.BLOCK)]
+    assert manager.state["source_bytes"] == module.BLOCK
+    store.set_trashed(store.resolve_id(item["id"]), True)
+    with pytest.raises(TrashedItemError):
+        await source.read(offset, 1)
+
+
+async def test_loopback_decoder_source_checks_token_and_exact_http_ranges(
+    rebuild, monkeypatch
+):
+    manager, store, _ = rebuild
+    item = store.add_file("/", "picture.png", 10, 6)
+    manager.drive_id = store.drive_id
+
+    async def fetch(*args, **kwargs):
+        return b"abcdef"
+
+    monkeypatch.setattr(module, "read_range", fetch)
+    monkeypatch.setattr(module, "RATE", 10**12)
+    source = module.RebuildSource(manager, item)
+    url = await source.open()
+    try:
+        async with aiohttp.ClientSession() as client:
+            async with client.get(url, headers={"Range": "bytes=2-4"}) as response:
+                assert response.status == 206
+                assert response.headers["Content-Range"] == "bytes 2-4/6"
+                assert await response.read() == b"cde"
+            async with client.head(url) as response:
+                assert response.headers["Content-Length"] == "6"
+                assert await response.read() == b""
+            async with client.get(url + "wrong") as response:
+                assert response.status == 404
+            async with client.get(url, headers={"Range": "bytes=99-"}) as response:
+                assert response.status == 416
+    finally:
+        await source.close()
+
+
+@pytest.mark.parametrize("name", ["photo.png", "movie.mov", "manga.epub", "comic.cbz"])
+async def test_native_rebuild_uses_selected_bytes_and_preserves_originals(
+    rebuild, monkeypatch, name
+):
+    from tests.support.book_samples import cbz, epub, png
+
+    if not shutil.which("ffmpeg"):
+        pytest.skip("native decoder unavailable")
+    manager, store, _ = rebuild
+    original = (
+        png()
+        if name.endswith("png")
+        else (
+            Path(__file__).resolve().parents[1] / "fixtures/movtext-subtitles.mp4"
+        ).read_bytes()
+        if name.endswith("mov")
+        else epub(padding=48 * module.BLOCK)
+        if name.endswith("epub")
+        else cbz(padding=48 * module.BLOCK)
+    )
+    item = store.add_file("/", name, 12, len(original))
+    calls = []
+
+    async def fetch(pool, channel, data, start, count, authorize, *, background):
+        assert background is True
+        await authorize()
+        calls.append((start, count))
+        return original[start : start + count]
+
+    monkeypatch.setattr(module, "read_range", fetch)
+    monkeypatch.setattr(module, "RATE", 10**12)
+    await manager.start()
+    await manager.task
+    assert manager.state["generated"] == 1, manager.snapshot()
+    assert manager.state["failed"] == manager.state["skipped"] == 0
+    assert read(manager.directory, manager.settings.storage_channel, item["message_id"])
+    assert sum(count for _, count in calls) < 4 * module.BLOCK
+    assert original.startswith(
+        b"\x89PNG"
+        if name.endswith("png")
+        else b"PK"
+        if name.endswith(("epub", "cbz"))
+        else b"\x00"
+    )
+    assert not list(manager.directory.glob(".repair-*.source"))
+
+
+async def test_failed_optional_render_retains_existing_thumbnail(rebuild, monkeypatch):
+    manager, store, _ = rebuild
+    store.add_file("/", "broken.jpg", 3, 1)
+    save(manager.directory, manager.settings.storage_channel, 3, COVER)
+
+    async def render(source):
+        return None
+
+    monkeypatch.setattr(manager, "render_file", render)
+    await manager.start()
+    await manager.task
+    assert manager.state["skipped"] == 1
+    assert manager.state["status"] == "completed"
+    assert read(manager.directory, manager.settings.storage_channel, 3) == COVER
+
+
+async def test_restart_retains_progress_but_does_not_silently_restart_bandwidth_work(
+    rebuild,
+):
+    manager, _, _ = rebuild
+    manager.state.update(
+        status="running", phase="Regenerating thumbnail", total=10, processed=3
+    )
+    await manager.persist()
+    restored = module.ThumbnailRebuild(
+        manager.settings, manager.runtime, manager.thumbnails
+    )
+    await restored.restore()
+    assert restored.snapshot()["status"] == "interrupted"
+    assert restored.snapshot()["processed"] == 3
+    assert restored.task is None
+
+
+async def test_force_invalidates_the_small_cover_cache():
+    cache = ThumbnailCache()
+    key = (-100, 2, 100, ())
+
+    async def old():
+        return Thumbnail(b"old", "image/jpeg")
+
+    async def new():
+        return Thumbnail(b"new", "image/jpeg")
+
+    await cache.get(key, old)
+    await cache.invalidate_file(-100, 2)
+    assert (await cache.get(key, new)).content == b"new"
+    assert cache.bytes == 3
+    await cache.close()
+
+
+def test_rebuild_routes_require_owner_confirmation_and_offer_progress(
+    tmp_path, monkeypatch
+):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "store.json")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    app = create_app(settings, runtime=runtime)
+    url = "/api/v1/settings/thumbnails/rebuild"
+    with TestClient(app, base_url="https://testserver") as client:
+        assert client.get(url).status_code == 401
+        assert client.post(url, json={"confirmed": True}).status_code == 401
+        login(client)
+        assert client.post(url, json={"confirmed": False}).status_code == 422
+        assert client.post(url, json={}).status_code == 422
+        assert client.get(url).json()["status"] == "idle"
+        response = client.post(url, json={"confirmed": True})
+        assert response.status_code == 202
+        assert response.json()["id"]
+        assert client.post(url + "/cancel", json={}).status_code == 200
+    store.close()
diff --git a/tests/media/test_thumbnail_repair_access.py b/tests/media/test_thumbnail_repair_access.py
new file mode 100644
index 00000000..626a4f6e
--- /dev/null
+++ b/tests/media/test_thumbnail_repair_access.py
@@ -0,0 +1,89 @@
+"""Warm-cache cover repair never extends current file or share access."""
+
+from types import SimpleNamespace
+
+import pytest
+
+from tests.media.test_thumbnails import use_thumbnail_pool
+from tests.support.app_fixtures import login
+
+pytest_plugins = ("tests.media.test_thumbnails",)
+
+COVER = b"\xff\xd8\xffcached-cover\xff\xd9"
+
+
+def install_repair(client, pool, *, before_return=None):
+    version = SimpleNamespace(data_revision=("cached-original", 1))
+    pool._media_read_cache = SimpleNamespace(
+        cached_source_version=lambda **_source: version
+    )
+    calls = []
+
+    async def repair(cache, **kwargs):
+        assert cache is pool._media_read_cache
+        assert kwargs["version"] is version
+        kwargs["authorize"]()
+        calls.append(kwargs["source"])
+        if before_return is not None:
+            before_return()
+        return COVER
+
+    client.app.state.thumbnail_repair = SimpleNamespace(get=repair)
+    return calls
+
+
+def test_repaired_thumbnail_reuses_payload_but_rechecks_access(app_client):
+    client, store, pool, account, path = use_thumbnail_pool(app_client, content=None)
+    calls = install_repair(client, pool)
+    login(client)
+    token = store.create_share(path)
+    client.post("/api/logout")
+    params = {"path": path, "auth": token}
+    response = client.get("/api/v1/thumbnail", params=params)
+    assert response.status_code == 200
+    assert response.content == COVER
+    assert response.headers["cache-control"] == "private, no-cache"
+    assert len(calls) == 1
+    assert calls[0]["message_id"] == 123
+    conditional = {"If-None-Match": response.headers["etag"]}
+    assert (
+        client.get("/api/v1/thumbnail", params=params, headers=conditional).status_code
+        == 304
+    )
+    assert len(calls) == account.reads == 1
+    store.revoke_share(path)
+    assert (
+        client.get("/api/v1/thumbnail", params=params, headers=conditional).status_code
+        == 403
+    )
+    assert len(calls) == account.reads == 1
+
+
+@pytest.mark.parametrize("change", ["revoke", "replace"])
+def test_repair_cannot_return_bytes_after_access_or_source_changes(
+    app_client, monkeypatch, change
+):
+    client, store, pool, _account, path = use_thumbnail_pool(app_client, content=None)
+    login(client)
+    token = store.create_share(path)
+    client.post("/api/logout")
+    original = store.get_file
+    replaced = False
+
+    def file_data(value):
+        data = original(value)
+        return {**data, "message_id": 999} if replaced else data
+
+    def change_during_repair():
+        nonlocal replaced
+        if change == "revoke":
+            store.revoke_share(path)
+        else:
+            replaced = True
+
+    monkeypatch.setattr(store, "get_file", file_data)
+    calls = install_repair(client, pool, before_return=change_during_repair)
+    response = client.get("/api/v1/thumbnail", params={"path": path, "auth": token})
+    assert response.status_code == (403 if change == "revoke" else 409)
+    assert response.content != COVER
+    assert len(calls) == 1
diff --git a/tests/media/test_thumbnails.py b/tests/media/test_thumbnails.py
new file mode 100644
index 00000000..c9d7a3b9
--- /dev/null
+++ b/tests/media/test_thumbnails.py
@@ -0,0 +1,519 @@
+from __future__ import annotations
+
+import asyncio
+import base64
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from types import SimpleNamespace
+
+import pytest
+from fastapi.testclient import TestClient
+from telethon import types
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.media.thumbnails import (
+    THUMBNAIL_BYTES,
+    Thumbnail,
+    ThumbnailBusy,
+    ThumbnailCache,
+    image_type,
+    load_thumbnail,
+)
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.clients import Client
+from tgdrive.web.app import create_app
+
+PNG = base64.b64decode(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aWZkA"
+    "AAAASUVORK5CYII="
+)
+
+
+@pytest.fixture
+def app_client(tmp_path, monkeypatch):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    with TestClient(
+        create_app(settings, runtime=runtime), base_url="https://testserver"
+    ) as client:
+        yield client, store, runtime, settings
+    store.close()
+
+
+class ThumbnailClient:
+    def __init__(self, content=PNG, before_download=None):
+        self.content = content
+        self.before_download = before_download
+        self.reads = 0
+        self.metadata_reads = 0
+
+    async def get_messages(self, _channel, *, message_ids):
+        self.metadata_reads += 1
+        return SimpleNamespace(id=message_ids, empty=False)
+
+    async def download_thumbnail(self, _message, **kwargs):
+        self.reads += 1
+        assert kwargs == dict(
+            max_bytes=THUMBNAIL_BYTES, target_size=320, max_dimension=640
+        )
+        if self.before_download:
+            self.before_download()
+        return self.content
+
+    async def stream_media(self, *_args, **_kwargs):
+        raise AssertionError("Thumbnails must never fetch original-file windows")
+
+
+class ThumbnailPool:
+    def __init__(self, client):
+        self.client = client
+        self.active = 0
+        self.leases = []
+
+    @asynccontextmanager
+    async def lease(self, **kwargs):
+        self.leases.append(kwargs)
+        self.active += 1
+        try:
+            yield self.client
+        finally:
+            self.active -= 1
+
+
+def use_thumbnail_pool(app_client, *, content=PNG, before_download=None):
+    client, store, runtime, _settings = app_client
+    account = ThumbnailClient(content, before_download)
+    pool = ThumbnailPool(account)
+    runtime.pool = pool
+    file = store.add_file("/", "cover.jpg", 123, 100_000_000)
+    return client, store, pool, account, "/" + file["id"]
+
+
+def test_thumbnail_requires_access_before_fetch_or_cached_response(app_client):
+    client, _store, pool, account, path = use_thumbnail_pool(app_client)
+    assert client.get("/api/v1/thumbnail", params={"path": path}).status_code == 403
+    assert account.reads == 0
+    login(client)
+    response = client.get("/api/v1/thumbnail", params={"path": path})
+    assert response.status_code == 200
+    assert response.content == PNG
+    assert response.headers["content-type"] == "image/png"
+    assert response.headers["cache-control"] == "private, no-cache"
+    assert response.headers["vary"] == "Cookie"
+    assert response.headers["x-content-type-options"] == "nosniff"
+    assert account.reads == 1
+    assert pool.active == 0
+    assert pool.leases == [
+        dict(download=True, allow_users=True, respect_cooldown=True, priority="preload")
+    ]
+    conditional = client.get(
+        "/api/v1/thumbnail",
+        params={"path": path},
+        headers={"If-None-Match": response.headers["etag"]},
+    )
+    assert conditional.status_code == 304
+    assert conditional.content == b""
+    assert account.reads == 1
+    client.post("/api/logout")
+    assert (
+        client.get(
+            "/api/v1/thumbnail",
+            params={"path": path},
+            headers={"If-None-Match": response.headers["etag"]},
+        ).status_code
+        == 403
+    )
+    assert account.reads == 1
+
+
+def test_thumbnail_share_scope_revocation_and_trash_do_not_leak_cached_payload(
+    app_client,
+):
+    client, store, _pool, account, path = use_thumbnail_pool(app_client)
+    other = store.add_file("/", "private.jpg", 124, 50)
+    login(client)
+    token = client.post("/api/getFileShareAuth", json={"path": path}).json()["auth"]
+    client.post("/api/logout")
+    shared = {"path": path, "auth": token}
+    response = client.get("/api/v1/thumbnail", params=shared)
+    assert response.status_code == 200
+    assert (
+        client.get(
+            "/api/v1/thumbnail",
+            params={
+                "path": "/" + other["id"],
+                "auth": token,
+            },
+        ).status_code
+        == 403
+    )
+    assert account.reads == 1
+    store.revoke_share(path)
+    assert (
+        client.get(
+            "/api/v1/thumbnail",
+            params=shared,
+            headers={"If-None-Match": response.headers["etag"]},
+        ).status_code
+        == 403
+    )
+    login(client)
+    store.set_trashed(path, True)
+    assert client.get("/api/v1/thumbnail", params={"path": path}).status_code == 404
+    assert account.reads == 1
+
+
+def test_thumbnail_share_revoked_during_fetch_is_not_returned(app_client):
+    client, store, pool, _account, path = use_thumbnail_pool(app_client)
+    login(client)
+    token = client.post("/api/getFileShareAuth", json={"path": path}).json()["auth"]
+    client.post("/api/logout")
+    pool.client.before_download = lambda: store.revoke_share(path)
+    response = client.get("/api/v1/thumbnail", params={"path": path, "auth": token})
+    assert response.status_code == 403
+    assert response.content != PNG
+    assert pool.active == 0
+
+
+def test_thumbnail_recovery_and_changed_file_abort_before_payload(
+    app_client, monkeypatch
+):
+    client, store, pool, account, path = use_thumbnail_pool(app_client)
+    login(client)
+    original = store.get_file
+    changed = False
+
+    def file_data(value):
+        data = original(value)
+        return {**data, "message_id": 999} if changed else data
+
+    def replace_during_read():
+        nonlocal changed
+        changed = True
+
+    monkeypatch.setattr(store, "get_file", file_data)
+    pool.client.before_download = replace_during_read
+    response = client.get("/api/v1/thumbnail", params={"path": path})
+    assert response.status_code == 409
+    assert response.content != PNG
+    assert account.reads == 1
+    app_client[2].backup = SimpleNamespace(recovery_required=True)
+    assert client.get("/api/v1/thumbnail", params={"path": path}).status_code == 409
+    assert account.reads == 1
+
+
+def test_explicit_invalid_share_cannot_use_owner_cookie_or_cached_image(app_client):
+    client, _store, _pool, account, path = use_thumbnail_pool(app_client)
+    login(client)
+    assert client.get("/api/v1/thumbnail", params={"path": path}).status_code == 200
+    response = client.get(
+        "/api/v1/thumbnail", params={"path": path, "auth": "invalid-share"}
+    )
+    assert response.status_code == 403
+    assert response.content != PNG
+    assert account.reads == 1
+
+
+@pytest.mark.parametrize(
+    "content", [None, b"<svg>unsafe</svg>", b"x" * (THUMBNAIL_BYTES + 1)]
+)
+def test_missing_or_unsafe_thumbnail_is_small_cached_fallback(app_client, content):
+    client, _store, _pool, account, path = use_thumbnail_pool(
+        app_client, content=content
+    )
+    login(client)
+    for _ in range(2):
+        response = client.get("/api/v1/thumbnail", params={"path": path})
+        assert response.status_code == 204
+        assert response.content == b""
+    assert account.reads == 1
+
+
+def test_thumbnail_transient_transport_failure_is_retryable_not_negative_cached(
+    app_client,
+):
+    client, _store, pool, account, path = use_thumbnail_pool(app_client)
+    login(client)
+
+    def unavailable():
+        raise OSError("disconnected")
+
+    account.before_download = unavailable
+    response = client.get("/api/v1/thumbnail", params={"path": path})
+    assert response.status_code == 503
+    assert response.json()["code"] == "THUMBNAIL_BUSY"
+    assert response.headers["retry-after"] == "5"
+    assert pool.active == 0
+    account.before_download = None
+    assert client.get("/api/v1/thumbnail", params={"path": path}).status_code == 200
+    assert account.reads == 2
+
+
+@pytest.mark.asyncio
+async def test_thumbnail_loader_adapter_without_capability_does_not_read_original():
+    pool = ThumbnailPool(SimpleNamespace())
+    assert await load_thumbnail(pool=pool, channel_id=-100, message_id=1) is None
+    assert pool.active == 0
+
+
+@pytest.mark.asyncio
+async def test_thumbnail_cache_singleflight_lru_bytes_and_negative_ttl():
+    cache = ThumbnailCache(max_bytes=len(PNG) * 2, max_entries=2, missing_ttl=0)
+    entered, release = asyncio.Event(), asyncio.Event()
+    reads = 0
+
+    async def loader():
+        nonlocal reads
+        reads += 1
+        entered.set()
+        await release.wait()
+        return Thumbnail(PNG, "image/png")
+
+    first = asyncio.create_task(cache.get((1,), loader))
+    await entered.wait()
+    second = asyncio.create_task(cache.get((1,), loader))
+    release.set()
+    assert (await first).content == (await second).content == PNG
+    assert reads == 1
+    await cache.get((2,), loader)
+    await cache.get((3,), loader)
+    assert len(cache._entries) == 2
+    assert (1,) not in cache._entries
+    assert cache.bytes == len(PNG) * 2
+    misses = 0
+
+    async def missing():
+        nonlocal misses
+        misses += 1
+        return None
+
+    await cache.get((4,), missing)
+    await cache.get((4,), missing)
+    assert misses == 2
+    await cache.close()
+    assert cache.bytes == 0
+    assert not cache._entries
+
+
+@pytest.mark.asyncio
+async def test_thumbnail_cache_limits_work_and_recovers_after_timeout():
+    cache = ThumbnailCache(max_pending=2, timeout=0.02)
+    entered = asyncio.Event()
+
+    async def blocked():
+        entered.set()
+        await asyncio.Event().wait()
+
+    a = asyncio.create_task(cache.get((1,), blocked))
+    await entered.wait()
+    b = asyncio.create_task(cache.get((2,), blocked))
+    await asyncio.sleep(0)
+    with pytest.raises(ThumbnailBusy):
+        await cache.get((3,), blocked)
+    for task in (a, b):
+        with pytest.raises(ThumbnailBusy):
+            await task
+
+    async def ready():
+        return Thumbnail(PNG, "image/png")
+
+    assert (await cache.get((3,), ready)).content == PNG
+    await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_cancelled_last_waiter_releases_thumbnail_fill_without_poisoning_next():
+    cache = ThumbnailCache()
+    entered, finished = asyncio.Event(), asyncio.Event()
+
+    async def blocked():
+        entered.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            finished.set()
+
+    first = asyncio.create_task(cache.get((1,), blocked))
+    await entered.wait()
+    first.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await first
+    await finished.wait()
+    assert not cache._flights
+
+    async def ready():
+        return Thumbnail(PNG, "image/png")
+
+    assert (await cache.get((1,), ready)).content == PNG
+    await cache.close()
+
+
+@pytest.mark.asyncio
+async def test_thumbnail_fill_concurrency_is_two_and_close_releases_waiters():
+    cache = ThumbnailCache()
+    started = asyncio.Event()
+    active = peak = 0
+
+    async def blocked():
+        nonlocal active, peak
+        active += 1
+        peak = max(peak, active)
+        if active == 2:
+            started.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            active -= 1
+
+    tasks = [asyncio.create_task(cache.get((i,), blocked)) for i in range(4)]
+    await started.wait()
+    assert active == peak == 2
+    await cache.close()
+    results = await asyncio.gather(*tasks, return_exceptions=True)
+    assert all(isinstance(result, asyncio.CancelledError) for result in results)
+    assert active == 0
+    assert not cache._flights
+    with pytest.raises(ThumbnailBusy):
+        await cache.get((1,), blocked)
+
+
+class DownloadIterator:
+    def __init__(self, chunks):
+        self.chunks = iter(chunks)
+        self.closed = False
+        self.reads = 0
+
+    async def __anext__(self):
+        self.reads += 1
+        try:
+            return next(self.chunks)
+        except StopIteration:
+            raise StopAsyncIteration from None
+
+    async def close(self):
+        self.closed = True
+
+
+class NativeDownload:
+    def __init__(self, chunks):
+        self.iterator = DownloadIterator(chunks)
+        self.calls = []
+
+    def iter_download(self, location, **kwargs):
+        self.calls.append((location, kwargs))
+        return self.iterator
+
+
+def transport_message(sizes, *, photo=False):
+    kwargs = dict(
+        id=7, access_hash=8, file_reference=b"ref", date=datetime.now(UTC), dc_id=2
+    )
+    if photo:
+        media = types.Photo(**kwargs, sizes=sizes)
+        return SimpleNamespace(photo=media, document=None)
+    media = types.Document(
+        **kwargs, mime_type="video/mp4", size=2_000_000_000, attributes=[], thumbs=sizes
+    )
+    return SimpleNamespace(photo=None, document=media)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("photo", [False, True])
+async def test_transport_chooses_small_explicit_thumb_and_closes_iterator(photo):
+    native = NativeDownload([PNG])
+    client = Client.__new__(Client)
+    client.native = native
+    message = transport_message(
+        [
+            types.PhotoSize(type="s", w=90, h=90, size=1024),
+            types.PhotoSize(type="m", w=320, h=180, size=32_000),
+            types.PhotoSize(type="x", w=1280, h=720, size=250_000),
+            types.VideoSize(type="v", w=320, h=180, size=1000),
+        ],
+        photo=photo,
+    )
+    assert await client.download_thumbnail(message) == PNG
+    location, args = native.calls[0]
+    assert location.thumb_size == "m"
+    assert isinstance(
+        location,
+        types.InputPhotoFileLocation if photo else types.InputDocumentFileLocation,
+    )
+    assert args == dict(request_size=32768, chunk_size=32768, limit=5, dc_id=2)
+    assert native.iterator.closed
+
+
+@pytest.mark.asyncio
+async def test_transport_refuses_large_missing_or_vector_thumbs_without_download():
+    client = Client.__new__(Client)
+    client.native = NativeDownload([b"never"])
+    for sizes in [
+        [],
+        [types.PhotoSize(type="x", w=320, h=180, size=THUMBNAIL_BYTES + 1)],
+        [types.PhotoSize(type="x", w=1280, h=720, size=1000)],
+        [types.PhotoPathSize(type="j", bytes=b"svg")],
+        [types.PhotoSize(type="", w=320, h=180, size=1000)],
+    ]:
+        assert await client.download_thumbnail(transport_message(sizes)) is None
+    assert client.native.calls == []
+
+
+@pytest.mark.asyncio
+async def test_transport_rejects_oversized_response_and_embedded_thumb_uses_no_rpc():
+    client = Client.__new__(Client)
+    native = NativeDownload([b"x" * 32768] * 10)
+    client.native = native
+    message = transport_message([types.PhotoSize(type="m", w=320, h=180, size=1000)])
+    assert await client.download_thumbnail(message) is None
+    assert native.iterator.reads == 5
+    assert native.iterator.closed
+    native.calls.clear()
+    cached = types.PhotoCachedSize(type="m", w=320, h=180, bytes=PNG)
+    assert await client.download_thumbnail(transport_message([cached])) == PNG
+    assert native.calls == []
+
+
+def test_thumbnail_signature_rejects_svg_and_recognizes_only_small_raster_types():
+    assert image_type(PNG) == "image/png"
+    assert image_type(b"\xff\xd8\xffjpeg") == "image/jpeg"
+    assert image_type(b"RIFF0000WEBPdata") == "image/webp"
+    assert image_type(b"<svg/>") is None
+
+
+def test_own_generated_cover_precedes_provider_and_is_authorized(app_client):
+    from tgdrive.media.generated_thumbnails import save
+
+    client, store, _runtime, settings = app_client
+    cover = b"\xff\xd8\xff" + b"small generated cover"
+    file = store.add_file(
+        "/",
+        "split.mp4",
+        650,
+        2,
+        parts=[
+            {"index": 0, "offset": 0, "size": 1, "message_id": 650, "sha256": "a" * 64},
+            {"index": 1, "offset": 1, "size": 1, "message_id": 651, "sha256": "b" * 64},
+        ],
+    )
+    path = "/" + file["id"]
+    save(
+        settings.resolved_cache_dir / "thumbnails", settings.storage_channel, 650, cover
+    )
+    assert client.get("/api/v1/thumbnail", params={"path": path}).status_code == 403
+    login(client)
+    token = store.create_share(path)
+    client.post("/api/logout")
+    response = client.get("/api/v1/thumbnail", params={"path": path, "auth": token})
+    assert response.status_code == 200 and response.content == cover
+    store.revoke_share(path)
+    assert (
+        client.get(
+            "/api/v1/thumbnail",
+            params={"path": path, "auth": token},
+            headers={"If-None-Match": response.headers["etag"]},
+        ).status_code
+        == 403
+    )
diff --git a/tests/observability/__init__.py b/tests/observability/__init__.py
new file mode 100644
index 00000000..e100c217
--- /dev/null
+++ b/tests/observability/__init__.py
@@ -0,0 +1 @@
+"""TGDrive observability tests."""
diff --git a/tests/observability/test_logging.py b/tests/observability/test_logging.py
new file mode 100644
index 00000000..e7aee0ff
--- /dev/null
+++ b/tests/observability/test_logging.py
@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from tgdrive.core.logging import configure_logging
+
+
+def flush_logs(log_path: Path) -> str:
+    for handler in logging.getLogger().handlers:
+        handler.flush()
+    return log_path.read_text(encoding="utf-8")
+
+
+def test_logging_redacts_credentials_and_appends_records(tmp_path: Path) -> None:
+    log_path = tmp_path / "tgdrive.log"
+    configure_logging("INFO", log_path)
+    logger = logging.getLogger("test")
+
+    logger.info("password=super-secret")
+    logger.info("token 123456:abcdefghijklmnopqrstuvwxyz1234")
+    logger.info("GET /file?path=/abc&auth=share-secret-value HTTP/1.1")
+    logger.info("Cookie: tgdrive_session=session-secret-value")
+    for handler in logging.getLogger().handlers:
+        handler.flush()
+
+    content = log_path.read_text(encoding="utf-8")
+    assert "super-secret" not in content
+    assert "abcdefghijklmnopqrstuvwxyz1234" not in content
+    assert "share-secret-value" not in content
+    assert "session-secret-value" not in content
+    assert "auth=[REDACTED]" in content
+    assert content.count("[REDACTED]") == 4
+    previous = next(
+        handler
+        for handler in logging.getLogger().handlers
+        if isinstance(handler, logging.FileHandler)
+    )
+    configure_logging("INFO")
+    assert previous.stream is None
+    assert logging.getLogger("uvicorn.access").disabled
+
+
+def test_exception_traceback_redacts_secret_values(tmp_path: Path) -> None:
+    log_path = tmp_path / "traceback.log"
+    configure_logging("INFO", log_path)
+    try:
+        raise RuntimeError(
+            "Telegram 123456:abcdefghijklmnopqrstuvwxyz1234 "
+            "failed for /file?auth=private-link"
+        )
+    except RuntimeError:
+        logging.getLogger("test").exception("Transfer failed")
+    for handler in logging.getLogger().handlers:
+        handler.flush()
+    content = log_path.read_text()
+    assert "Traceback" in content
+    assert "RuntimeError" in content
+    assert "abcdefghijklmnopqrstuvwxyz1234" not in content
+    assert "private-link" not in content
+
+
+def test_default_logs_show_app_lifecycle_and_provider_warnings(tmp_path: Path) -> None:
+    log_path = tmp_path / "default.log"
+    configure_logging("INFO", log_path)
+    provider = logging.getLogger("telethon.client.updates")
+    provider.info("Got difference for channel 123 updates")
+    provider.warning("Connection requires attention")
+    logging.getLogger("httpx").info("HTTP Request: GET /private?auth=secret")
+    logging.getLogger("tgdrive.transfers.uploads").info(
+        "Device upload accepted id=example"
+    )
+
+    content = flush_logs(log_path)
+    assert "Got difference" not in content
+    assert "HTTP Request" not in content
+    assert "Connection requires attention" in content
+    assert "Device upload accepted" in content
+
+
+def test_debug_restores_provider_diagnostics_and_info_reconfiguration(tmp_path: Path):
+    log_path = tmp_path / "debug.log"
+    configure_logging("DEBUG", log_path)
+    logging.getLogger("telethon.client.updates").debug("provider diagnostic")
+    assert "provider diagnostic" in flush_logs(log_path)
+    configure_logging("INFO", log_path)
+    logging.getLogger("telethon.client.updates").info("provider chatter")
+    assert "provider chatter" not in flush_logs(log_path)
+
+
+def test_provider_logging_respects_stricter_global_level(tmp_path: Path):
+    log_path = tmp_path / "errors.log"
+    configure_logging("ERROR", log_path)
+    logging.getLogger("telethon.client.updates").warning("provider warning")
+    logging.getLogger("telethon.client.updates").error("provider error")
+    content = flush_logs(log_path)
+    assert "provider warning" not in content
+    assert "provider error" in content
+    configure_logging("INFO")
diff --git a/tests/observability/test_performance_integration.py b/tests/observability/test_performance_integration.py
new file mode 100644
index 00000000..9725ed28
--- /dev/null
+++ b/tests/observability/test_performance_integration.py
@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.core.test_runtime import FakePool
+from tests.observability.test_performance_preferences import (
+    mongo_backend as mongo_backend,
+)
+from tests.observability.test_performance_preferences import (
+    runtime as performance_runtime,
+)
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tgdrive.core.runtime import Runtime
+from tgdrive.observability.performance_api import system_snapshot
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.settings.performance_preferences import PerformanceSettings
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+pytestmark = pytest.mark.usefixtures("mongo_backend")
+
+
+@pytest.mark.asyncio
+async def test_failed_live_policy_apply_restores_saved_policy_and_revision(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    runtime = performance_runtime(mongo_backend)
+    service = PerformanceSettings(settings, runtime)
+    before = await service.snapshot()
+    runtime.pool.set_media_per_bot = AsyncMock(side_effect=[OSError("temporary"), None])
+    try:
+        with pytest.raises(SettingsProblem) as failed:
+            await service.save({"timezone": "UTC", "cache_memory_bytes": 0})
+        assert failed.value.status == 503
+        assert "restored" in str(failed.value).lower()
+        assert (await service.snapshot())["revision"] == before["revision"]
+        assert settings.timezone == before["timezone"]
+        assert settings.cache_memory_bytes == before["cache_memory_bytes"]
+        saved = mongo_backend.db.settings.find_one({"_id": "performance-preferences"})[
+            "document"
+        ]
+        assert saved["timezone"] == before["timezone"]
+        assert (
+            runtime.preloads.cache.policy.memory_max_bytes
+            == before["cache_memory_bytes"]
+        )
+    finally:
+        await runtime.preloads.close()
+
+
+@pytest.mark.asyncio
+async def test_existing_manager_applies_cache_policy_only_once(tmp_path, mongo_backend):
+    runtime = performance_runtime(mongo_backend)
+    service = PerformanceSettings(make_settings(tmp_path), runtime)
+    await service.initialize()
+    cache = runtime.preloads.cache
+    reconfigure = AsyncMock(wraps=cache.reconfigure)
+    cache.reconfigure = reconfigure
+    try:
+        await service.save({"auto_preload": False})
+        assert reconfigure.await_count == 1
+    finally:
+        await runtime.preloads.close()
+
+
+@pytest.mark.asyncio
+async def test_zero_tier_settings_initialize_and_report_disabled_cache(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    settings.cache_memory_bytes = settings.cache_disk_bytes = 0
+    runtime = performance_runtime(mongo_backend)
+    service = PerformanceSettings(settings, runtime)
+    try:
+        await service.initialize()
+        snapshot = await runtime.preloads.snapshot()
+        assert snapshot["cache"]["memory"]["bytes"] == 0
+        assert snapshot["cache"]["memory"]["effective_max_bytes"] == 0
+        assert snapshot["cache"]["disk"]["max_bytes"] == 0
+        assert snapshot["cache"]["files"] == []
+    finally:
+        if hasattr(runtime, "preloads"):
+            await runtime.preloads.close()
+
+
+def test_lazy_resource_api_without_telegram_runtime_is_controlled(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = mongo_backend
+    app = create_app(settings, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            login(client)
+            assert client.get("/api/v1/settings/performance").status_code == 200
+            performance = client.get("/api/v1/performance")
+            assert performance.status_code == 200
+            assert performance.json()["cache"]["disk"]["available"] is False
+            assert performance.json()["cache"]["files"] == []
+            assert client.get("/api/v1/preloads").status_code == 503
+            assert client.post("/api/v1/preloads/clear", json={}).status_code == 503
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
+
+
+def test_resource_snapshot_survives_unavailable_data_directory(tmp_path):
+    settings = make_settings(tmp_path)
+    state = system_snapshot(settings)
+    assert state["disk"]["available"] is False
+    assert state["disk"]["free_bytes"] == 0
+    assert "memory" in state and "load_average" in state
+
+
+@pytest.mark.asyncio
+async def test_media_cleanup_failure_still_stops_pool_and_releases_owner(tmp_path):
+    pool = FakePool()
+    runtime = Runtime(make_settings(tmp_path), pool=pool)
+    runtime.preloads = SimpleNamespace(
+        close=AsyncMock(side_effect=OSError("cache failed"))
+    )
+    owner = SimpleNamespace(close=Mock())
+    runtime._owner_lock = owner
+    await runtime.stop()
+    assert pool.stopped
+    owner.close.assert_called_once()
+    assert runtime._owner_lock is None
+    runtime.preloads.close.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_manager_owns_cache_close_without_double_close(tmp_path):
+    runtime = Runtime(make_settings(tmp_path), pool=FakePool())
+    cache = SimpleNamespace(close=AsyncMock())
+    runtime.pool._media_read_cache = cache
+    runtime.preloads = SimpleNamespace(close=AsyncMock(side_effect=cache.close))
+    await runtime.stop()
+    runtime.preloads.close.assert_awaited_once()
+    cache.close.assert_awaited_once()
+
+
+def test_prepare_rejects_catalog_generation_change_before_origin_work(
+    tmp_path, monkeypatch, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    file_id = store.add_file("/", "movie.mp4", 77, 1024)["id"]
+    runtime = FakeRuntime(store)
+    runtime.mongo = mongo_backend
+    runtime.pool = performance_runtime().pool
+    app = create_app(settings, runtime=runtime)
+    original = store.get_file
+    calls = 0
+
+    def changed(*args, **kwargs):
+        nonlocal calls
+        calls += 1
+        value = original(*args, **kwargs)
+        return value if calls == 1 else value | {"message_id": 88}
+
+    monkeypatch.setattr(store, "get_file", changed)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            login(client)
+            result = client.post("/api/v1/preloads", json={"path": "/" + file_id})
+            assert result.status_code == 409
+            assert "changed" in result.json()["detail"].lower()
+            assert not runtime.preloads._jobs
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/observability/test_performance_preferences.py b/tests/observability/test_performance_preferences.py
new file mode 100644
index 00000000..234e1589
--- /dev/null
+++ b/tests/observability/test_performance_preferences.py
@@ -0,0 +1,271 @@
+import re
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.settings.performance_preferences import (
+    PerformancePreferences,
+    PerformanceSettings,
+)
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+
+def test_operator_default_hints_match_runtime_defaults():
+    """Dashboard hints and typed defaults must describe the same live policy."""
+    root = Path(__file__).resolve().parents[2]
+    defaults = PerformancePreferences().model_dump()
+    definitions = (
+        (root / "website/src/features/performance/performanceApi.ts")
+        .read_text()
+        .split("export type PerformanceDraft", 1)[0]
+    )
+    displayed = dict(
+        re.findall(r'key: "([a-z_]+)"[\s\S]*?appDefault: (\d+)', definitions)
+    )
+    numeric = {key: value for key, value in defaults.items() if type(value) is int}
+    assert displayed.keys() == numeric.keys()
+    units = {
+        "cache_memory_bytes": 1024**2,
+        "cache_disk_bytes": 1024**3,
+        "cache_min_free_bytes": 1024**3,
+        "cache_ttl_seconds": 3600,
+        "max_file_size": 1024**3,
+        "staging_budget_bytes": 1024**3,
+        "min_free_bytes": 1024**3,
+    }
+    for key, expected in defaults.items():
+        if key == "max_file_size":
+            assert Settings.model_fields[key].default is None
+        else:
+            assert Settings.model_fields[key].default == expected
+        if key in numeric:
+            assert int(displayed[key]) * units.get(key, 1) == expected
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path / "data")
+
+
+def runtime(backend=None):
+    return SimpleNamespace(
+        mongo=backend,
+        pool=SimpleNamespace(
+            _slots=[], set_media_per_bot=AsyncMock(), set_media_queue_limit=AsyncMock()
+        ),
+    )
+
+
+async def test_policy_persists_conflicts_and_failed_write_is_not_applied(
+    tmp_path, monkeypatch, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    state = runtime(mongo_backend)
+    service = PerformanceSettings(settings, state)
+    before = await service.snapshot()
+    after = await service.save(
+        {"cache_disk_bytes": 16 * 1024**3, "timezone": "UTC"},
+        expected=before["revision"],
+    )
+    assert after["timezone"] == "UTC"
+    with pytest.raises(SettingsProblem) as conflict:
+        await service.save({"timezone": "Asia/Kolkata"}, expected=before["revision"])
+    assert conflict.value.status == 409
+
+    def failed(value):
+        raise OSError("synthetic")
+
+    monkeypatch.setattr(service, "_write", failed)
+    with pytest.raises(SettingsProblem):
+        await service.save({"cache_disk_bytes": 1})
+    assert (await service.snapshot())["cache_disk_bytes"] == 16 * 1024**3
+    other = runtime(mongo_backend)
+    restarted = PerformanceSettings(settings, other)
+    assert (await restarted.snapshot())["timezone"] == "UTC"
+    await state.preloads.close()
+    await other.preloads.close()
+
+
+def test_owner_api_resource_policy_and_share_capability(tmp_path, mongo_backend):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    item = store.add_file("/", "hello.txt", 123, 12)["id"]
+    app_runtime = FakeRuntime(store)
+    app_runtime.mongo = mongo_backend
+    app_runtime.pool = runtime().pool
+    app = create_app(settings, runtime=app_runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            url = "/api/v1/settings/performance"
+            assert client.get(url).status_code == 401
+            assert client.post("/api/v1/preloads/clear", json={}).status_code == 401
+            login(client)
+            result = client.get(url)
+            assert result.status_code == 200
+            assert result.json()["timezone"] == "Asia/Kolkata"
+            assert result.json()["defaults"] == PerformancePreferences().model_dump()
+            assert result.json()["documentation_url"].endswith("/docs/configuration.md")
+            assert result.headers["cache-control"] == "no-store"
+            for changes in (
+                {"cache_disk_bytes": -1},
+                {"cache_memory_bytes": True},
+                {"unknown": 4},
+                {"timezone": "INVALID"},
+            ):
+                assert client.patch(url, json=changes).status_code == 422
+            assert (
+                client.patch(
+                    url,
+                    json={"auto_preload": False},
+                    headers={"If-Match": result.headers["etag"]},
+                ).status_code
+                == 200
+            )
+            assert (
+                client.patch(
+                    url,
+                    json={"auto_preload": True},
+                    headers={"If-Match": result.headers["etag"]},
+                ).status_code
+                == 409
+            )
+            assert client.get("/api/v1/preloads").json()["cache"]["files"] == []
+            # HEAD has no provider work; revoked links fail even for owner.
+            head = client.head("/file", params={"path": "/" + item})
+            assert head.status_code == 200
+            assert head.headers["content-length"] == "12"
+            assert head.content == b""
+            ranged = client.head(
+                "/file", params={"path": "/" + item}, headers={"Range": "bytes=4-7"}
+            )
+            assert ranged.status_code == 206
+            assert ranged.headers["content-range"] == "bytes 4-7/12"
+            assert (
+                client.head(
+                    "/file", params={"path": "/" + item}, headers={"Range": "bytes=50-"}
+                ).status_code
+                == 416
+            )
+            copied = client.post(
+                "/api/v1/download-links", json={"path": "/" + item}
+            ).json()
+            assert "auth=" in copied["url"]
+            assert len(store.list_shares()) == 1
+            assert (
+                client.post("/api/v1/download-links", json={"path": "/" + item}).json()[
+                    "url"
+                ]
+                == copied["url"]
+            )
+            client.request("DELETE", "/api/v1/shares", json={"path": "/" + item})
+            assert client.head(copied["url"]).status_code == 403
+    finally:
+        app_runtime.transfers.registry.close()
+        store.close()
+
+
+@pytest.mark.parametrize(
+    "method,path,body",
+    [
+        ("GET", "/api/v1/settings/performance", None),
+        ("PATCH", "/api/v1/settings/performance", {"cache_disk_bytes": 0}),
+        ("GET", "/api/v1/preloads", None),
+        ("POST", "/api/v1/preloads", {"path": "/file-placeholder"}),
+        ("POST", "/api/v1/preloads/clear", {}),
+        ("POST", "/api/v1/preloads/job-placeholder/cancel", {}),
+        ("GET", "/api/v1/performance", None),
+    ],
+)
+def test_valid_public_share_cannot_inspect_or_control_operator_resources(
+    tmp_path, method, path, body, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    item = store.add_file("/", "public.txt", 123, 12)["id"]
+    token = store.create_share("/" + item)
+    assert store.authorize_file("/" + item, token)
+    state = FakeRuntime(store)
+    state.mongo = mongo_backend
+    app = create_app(settings, runtime=state)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            response = client.request(method, path, params={"auth": token}, json=body)
+            assert response.status_code == 401
+            assert not hasattr(state, "performance_settings")
+    finally:
+        state.transfers.registry.close()
+        store.close()
+
+
+async def test_defaults_are_built_in_and_invalid_updates_never_change_saved_policy(
+    tmp_path,
+    mongo_backend,
+):
+    settings = make_settings(tmp_path)
+    settings.cache_memory_bytes = 512 * 1024**2
+    state = runtime(mongo_backend)
+    service = PerformanceSettings(settings, state)
+    try:
+        before = await service.snapshot()
+        assert before["cache_memory_bytes"] == 512 * 1024**2
+        assert before["defaults"]["cache_memory_bytes"] == 256 * 1024**2
+        from pydantic import ValidationError
+
+        for changes in [
+            {"cache_memory_bytes": 9 * 1024**3, "timezone": "UTC"},
+            {"telegram_upload_pipeline": 17},
+            {"telegram_request_limit": 33},
+            {"telegram_parts_per_second": 129},
+            {"telegram_media_per_bot": 17},
+            {"telegram_max_queue": 4097},
+            {"preload_max_jobs": 0},
+            {"upload_split_mib": 2001},
+            {"cache_ttl_seconds": 0},
+            {"cache_memory_bytes": 1.5},
+            {"auto_preload": "false"},
+            {"defaults": {"cache_memory_bytes": 1}},
+        ]:
+            with pytest.raises(ValidationError):
+                await service.save(changes, expected=before["revision"])
+            assert await service.snapshot() == before
+        with pytest.raises(SettingsProblem) as too_low:
+            await service.save({"cache_min_free_bytes": 0}, expected=before["revision"])
+        assert too_low.value.status == 422
+        assert await service.snapshot() == before
+        disabled = await service.save(
+            {"cache_disk_bytes": 0, "cache_min_free_bytes": 0}
+        )
+        assert disabled["cache_disk_bytes"] == 0
+        restored = await service.save(before["defaults"], expected=disabled["revision"])
+        assert all(restored[key] == value for key, value in before["defaults"].items())
+    finally:
+        await state.preloads.close()
+
+
+async def test_url_concurrency_applies_live_and_persists(tmp_path, mongo_backend):
+    from tgdrive.transfers.remote_scheduler import URLDownloadScheduler
+
+    settings = make_settings(tmp_path)
+    state = runtime(mongo_backend)
+    state.remote = SimpleNamespace(scheduler=URLDownloadScheduler())
+    service = PerformanceSettings(settings, state)
+    before = await service.snapshot()
+    assert before["remote_download_concurrency"] == 2
+    for invalid in (0, 9, True, 2.5):
+        with pytest.raises(ValueError):
+            await service.save({"remote_download_concurrency": invalid})
+    await service.save({"remote_download_concurrency": 8})
+    assert state.remote.scheduler.full_speed_limit == 8
+    other = runtime(mongo_backend)
+    restarted = PerformanceSettings(settings, other)
+    assert (await restarted.snapshot())["remote_download_concurrency"] == 8
+    await state.preloads.close()
+    await other.preloads.close()
diff --git a/tests/observability/test_request_ids.py b/tests/observability/test_request_ids.py
new file mode 100644
index 00000000..f109c480
--- /dev/null
+++ b/tests/observability/test_request_ids.py
@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import pytest
+
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+from tgdrive.web.request_ids import (
+    RequestIdCancelled,
+    RequestIdConflict,
+    RequestIdNotFound,
+    TransferStarts,
+)
+
+
+def test_repeated_start_is_idempotent_but_different_payload_conflicts() -> None:
+    starts = TransferStarts()
+    entry, created = starts.claim("a" * 24, ("local", "/", "file.txt", "12"))
+    again, created_again = starts.claim("a" * 24, ("local", "/", "file.txt", "12"))
+    assert created
+    assert not created_again
+    assert entry is again
+    with pytest.raises(RequestIdConflict):
+        starts.claim("a" * 24, ("local", "/", "other.txt", "12"))
+
+
+def test_cancel_before_start_prevents_late_transfer() -> None:
+    starts = TransferStarts()
+    entry = starts.cancel("cancel-before-start")
+    assert entry.snapshot()["status"] == "cancelled"
+    assert entry.snapshot()["id"] == ""
+    with pytest.raises(RequestIdCancelled):
+        starts.claim("cancel-before-start", ("remote", "/", "https://example.com"))
+
+
+async def test_bound_record_is_visible_during_save_and_after_completion() -> None:
+    starts = TransferStarts()
+    registry = TransferRegistry()
+    record = await registry.create("saving", total=12)
+    entry, _ = starts.claim("b" * 24, ("local", "/", "file.txt", "12"))
+    assert not starts.bind(entry, record)
+    assert starts.get("b" * 24).snapshot()["id"] == record.id
+    await registry.update(record.id, status=TransferStatus.COMPLETED, phase="completed")
+    starts.cancel("b" * 24)
+    assert not entry.cancelled
+    assert entry.snapshot()["status"] == "completed"
+    assert starts.claim("b" * 24, entry.fingerprint)[1] is False
+
+
+async def test_cancel_intent_reaches_record_bound_later() -> None:
+    starts = TransferStarts()
+    entry, _ = starts.claim("c" * 24, ("local", "/", "file.txt", "12"))
+    starts.cancel("c" * 24)
+    record = await TransferRegistry().create("saving")
+    assert starts.bind(entry, record)
+
+
+def test_failed_start_has_an_authoritative_recovery_result() -> None:
+    starts = TransferStarts()
+    entry, _ = starts.claim("d" * 24, ("local", "/", "file.txt", "12"))
+    starts.fail(entry, "Destination no longer exists")
+    assert entry.snapshot()["status"] == "error"
+    assert entry.snapshot()["error"] == "Destination no longer exists"
+
+
+def test_unknown_start_is_not_found() -> None:
+    with pytest.raises(RequestIdNotFound):
+        TransferStarts().get("missing-request-id")
+
+
+async def test_request_capacity_is_bounded_without_evicting_active_work() -> None:
+    starts = TransferStarts(max_entries=1)
+    entry, _ = starts.claim("e" * 24, ("local",))
+    starts.bind(entry, await TransferRegistry().create("saving"))
+    with pytest.raises(RuntimeError, match="Too many transfer requests"):
+        starts.cancel("f" * 24)
+    assert starts.get("e" * 24) is entry
diff --git a/tests/observability/test_resource_metrics.py b/tests/observability/test_resource_metrics.py
new file mode 100644
index 00000000..7dc5265e
--- /dev/null
+++ b/tests/observability/test_resource_metrics.py
@@ -0,0 +1,146 @@
+import pytest
+
+from tgdrive.observability.resource_metrics import ResourceMetrics
+
+
+def setup_counters(tmp_path, monkeypatch, *, quota="200000 100000"):
+    proc, cgroup = tmp_path / "proc", tmp_path / "cgroup"
+    (proc / "net").mkdir(parents=True)
+    cgroup.mkdir()
+    (cgroup / "cpu.max").write_text(quota)
+    (cgroup / "cpu.stat").write_text("usage_usec 1000000\n")
+    (proc / "stat").write_text("cpu 100 0 0 100 0 0 0 0 0 0\n")
+    (proc / "net/route").write_text(
+        "Iface Destination Gateway Flags RefCnt Use Metric Mask\n"
+        "eth0 00000000 0100000A 0003 0 0 100 00000000\n"
+    )
+    network(proc, 1000, 2000)
+    monkeypatch.setattr(
+        "tgdrive.observability.resource_metrics.os.cpu_count", lambda: 8
+    )
+    monkeypatch.setattr(
+        "tgdrive.observability.resource_metrics.os.sched_getaffinity",
+        lambda _: set(range(8)),
+    )
+    now = [100.0]
+    monkeypatch.setattr(
+        "tgdrive.observability.resource_metrics.time.monotonic", lambda: now[0]
+    )
+    return ResourceMetrics(proc=proc, cgroup=cgroup), proc, cgroup, now
+
+
+def network(proc, received, sent):
+    (proc / "net/dev").write_text(
+        f"eth0: {received} 0 0 0 0 0 0 0 {sent} 0 0 0 0 0 0 0\n"
+        "lo: 999999999 0 0 0 0 0 0 0 999999999 0 0 0 0 0 0 0\n"
+        "docker0: 999999999 0 0 0 0 0 0 0 999999999 0 0 0 0 0 0 0\n"
+    )
+
+
+def test_current_cpu_respects_container_quota_and_network_counts_url_like_ingress(
+    tmp_path, monkeypatch
+):
+    metrics, proc, cgroup, now = setup_counters(tmp_path, monkeypatch)
+    first = metrics.sample()
+    assert first["cpu"]["percent"] is None
+    assert first["network"]["received_bytes"] == 0
+    now[0] += 2
+    (cgroup / "cpu.stat").write_text("usage_usec 3000000\n")
+    network(proc, 1000 + 1024**3, 6000)
+    sample = metrics.sample()
+    assert sample["cpu"] == {"percent": 50, "scope": "cgroup", "capacity_cores": 2}
+    assert sample["network"]["received_bytes"] == 1024**3
+    assert sample["network"]["received_bytes_per_second"] == 1024**3 / 2
+    assert sample["network"]["sent_bytes_per_second"] == 2000
+    assert sample["network"]["interface"] == "eth0"
+    # Finished URL import: current rate is zero; the observed total remains.
+    now[0] += 3
+    idle = metrics.sample()["network"]
+    assert idle["received_bytes_per_second"] == 0
+    assert idle["received_bytes"] == 1024**3
+
+
+def test_missing_cgroup_uses_host_busy_cpu_not_load_average(tmp_path, monkeypatch):
+    metrics, proc, cgroup, now = setup_counters(tmp_path, monkeypatch)
+    (cgroup / "cpu.stat").unlink()
+    metrics.sample()
+    now[0] += 3
+    (proc / "stat").write_text("cpu 150 0 0 150 0 0 0 0 0 0\n")
+    assert metrics.sample()["cpu"] == {"percent": 50, "scope": "host"}
+
+
+@pytest.mark.parametrize("elapsed", [-3, 40])
+def test_gap_clock_jump_and_reset_do_not_fabricate_resource_rates(
+    tmp_path, monkeypatch, elapsed
+):
+    metrics, proc, _cgroup, now = setup_counters(tmp_path, monkeypatch)
+    metrics.sample()
+    now[0] += elapsed
+    network(proc, 1500, 3000)
+    value = metrics.sample()
+    assert value["cpu"]["percent"] is None
+    assert value["network"]["received_bytes_per_second"] is None
+    now[0] += 3
+    network(proc, 10, 20)
+    assert metrics.sample()["network"]["sent_bytes_per_second"] is None
+    network(proc, 100, 200)
+    now[0] += 3
+    assert metrics.sample()["network"]["received_bytes_per_second"] == 30
+
+
+def test_unavailable_metrics_are_unknown_not_zero(tmp_path):
+    value = ResourceMetrics(proc=tmp_path, cgroup=tmp_path).sample()
+    assert value["cpu"]["percent"] is None
+    assert not value["network"]["available"]
+    assert value["network"]["received_bytes_per_second"] is None
+
+
+def test_history_retains_measured_resources_without_dashboard_and_expires(
+    tmp_path, monkeypatch
+):
+    metrics, proc, cgroup, now = setup_counters(tmp_path, monkeypatch)
+    monkeypatch.setattr(
+        "tgdrive.observability.resource_metrics.time.time", lambda: now[0] + 1000
+    )
+    (cgroup / "memory.current").write_text("1073741824")
+    (cgroup / "memory.max").write_text("2147483648")
+    initial = metrics.sample()
+    assert initial["history"][0]["cpu_percent"] is None
+    assert initial["history"][0]["received_bytes_per_second"] is None
+    for index in range(1, 106):
+        now[0] += 3
+        (cgroup / "cpu.stat").write_text(f"usage_usec {1000000 + index * 3000000}")
+        network(proc, 1000 + index * 3000, 2000 + index * 6000)
+        value = metrics.sample()
+    assert len(initial["history"]) == 1
+    assert len(value["history"]) == 101
+    assert value["history"][-1]["at"] - value["history"][0]["at"] == 300
+    assert value["history"][-1] == {
+        "at": now[0] + 1000,
+        "cpu_percent": 50,
+        "cpu_scope": "cgroup",
+        "memory_bytes": 1024**3,
+        "memory_limit_bytes": 2 * 1024**3,
+        "received_bytes_per_second": 1000,
+        "sent_bytes_per_second": 2000,
+        "network_interface": "eth0",
+    }
+    now[0] += 60
+    assert len(metrics.sample()["history"]) == 1
+    now[0] -= 10
+    assert len(metrics.sample()["history"]) == 1
+
+
+def test_history_missing_container_memory_is_unknown_and_unlimited_is_not_zero(
+    tmp_path, monkeypatch
+):
+    metrics, _proc, cgroup, now = setup_counters(tmp_path, monkeypatch)
+    sample = metrics.sample()["history"][-1]
+    assert sample["memory_bytes"] is None
+    assert sample["memory_limit_bytes"] is None
+    (cgroup / "memory.current").write_text("0")
+    (cgroup / "memory.max").write_text("max")
+    now[0] += 3
+    sample = metrics.sample()["history"][-1]
+    assert sample["memory_bytes"] == 0
+    assert sample["memory_limit_bytes"] is None
diff --git a/tests/observability/test_resource_telemetry.py b/tests/observability/test_resource_telemetry.py
new file mode 100644
index 00000000..5473d3aa
--- /dev/null
+++ b/tests/observability/test_resource_telemetry.py
@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from tgdrive.observability.traffic import (
+    TrafficCounters,
+    TrafficMiddleware,
+    sample_performance,
+)
+
+
+@pytest.mark.asyncio
+async def test_traffic_counts_received_bytes_and_only_successful_sends():
+    counters = TrafficCounters()
+
+    async def app(scope, receive, send):
+        await receive()
+        await send({"type": "http.response.start", "status": 200})
+        await send({"type": "http.response.body", "body": b"ready", "more_body": True})
+        await send(
+            {"type": "http.response.body", "body": b"not delivered", "more_body": False}
+        )
+
+    async def receive():
+        return {"type": "http.request", "body": b"received"}
+
+    async def send(message):
+        if message.get("body") == b"not delivered":
+            raise OSError("disconnected client")
+
+    middleware = TrafficMiddleware(app, counters)
+    with pytest.raises(OSError, match="disconnected client"):
+        await middleware(
+            {"type": "http", "path": "/api/v1/uploads/example"}, receive, send
+        )
+    assert counters.requests == counters.errors == 1
+    assert counters.active == 0
+    assert counters.upload_bytes == len(b"received")
+    assert counters.download_bytes == len(b"ready")
+
+
+def test_traffic_history_is_bounded_and_restarts_without_fabricated_rates(
+    monkeypatch,
+):
+    now = [1000.0]
+    monkeypatch.setattr("tgdrive.observability.traffic.time.time", lambda: now[0])
+    counters = TrafficCounters()
+    for _index in range(180):
+        now[0] += 1
+        counters.download_bytes += 100
+        counters.snapshot()
+    snapshot = counters.snapshot()
+    assert len(snapshot["history"]) == 120
+    assert snapshot["history"][0]["download_bytes"] == 6100
+    assert snapshot["history"][-1]["download_bytes"] == 18000
+    assert len(counters.snapshot()["history"]) == 120
+    restarted = TrafficCounters().snapshot()
+    assert restarted["download_bytes"] == restarted["requests"] == 0
+    assert len(restarted["history"]) == 1
+    assert restarted["download_bytes_per_second"] is None
+
+
+def test_rates_reject_old_samples_and_clock_jumps(monkeypatch):
+    now = [1000.0]
+    monkeypatch.setattr("tgdrive.observability.traffic.time.time", lambda: now[0])
+    counters = TrafficCounters()
+    counters.snapshot()
+    now[0] += 3
+    counters.download_bytes += 3000
+    counters.upload_bytes += 600
+    current = counters.snapshot()
+    assert current["download_bytes_per_second"] == 1000
+    assert current["upload_bytes_per_second"] == 200
+    now[0] += 44683
+    stale = counters.snapshot()
+    assert len(stale["history"]) == 1
+    assert stale["download_bytes_per_second"] is None
+    now[0] -= 100
+    assert len(counters.snapshot()["history"]) == 1
+
+
+@pytest.mark.asyncio
+async def test_sampler_records_without_dashboard_and_cancels_cleanly():
+    counters = TrafficCounters()
+    sampled = asyncio.Event()
+
+    class Pool:
+        def performance_snapshot(self):
+            sampled.set()
+
+    task = asyncio.create_task(sample_performance(counters, Pool(), interval=60))
+    await asyncio.wait_for(sampled.wait(), 1)
+    assert len(counters.history) == 1
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+
+def test_system_snapshot_distinguishes_current_and_peak_memory(tmp_path, monkeypatch):
+    from types import SimpleNamespace
+
+    from tgdrive.observability.performance_api import system_snapshot
+
+    original = Path.read_text
+
+    def read(path, *args, **kwargs):
+        if str(path) == "/proc/self/status":
+            return "Name:\ttgdrive\nVmRSS:\t12345 kB\n"
+        return original(path, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "read_text", read)
+    current = system_snapshot(
+        SimpleNamespace(resolved_data_dir=tmp_path, staging_budget_bytes=1024)
+    )
+    assert current["process_rss_bytes"] == 12345 * 1024
+    assert current["process_peak_rss_bytes"] > 0
+    assert current["cpu_count"] is None or current["cpu_count"] > 0
diff --git a/tests/observability/test_telemetry_history.py b/tests/observability/test_telemetry_history.py
new file mode 100644
index 00000000..9185a40e
--- /dev/null
+++ b/tests/observability/test_telemetry_history.py
@@ -0,0 +1,344 @@
+"""Persistent telemetry must remain measured, bounded and separate from file state."""
+
+from __future__ import annotations
+
+import math
+import time
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.observability.telemetry_history import (
+    RETENTION_SECONDS,
+    HistoryStorage,
+    TelemetryHistory,
+    validate_range,
+)
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+pytestmark = pytest.mark.usefixtures("mongo_backend")
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    backend = register_test_backend(monkeypatch, tmp_path)
+    register_test_backend(monkeypatch, tmp_path / "data", backend)
+    return backend
+
+
+def sample(
+    at,
+    *,
+    cpu=20,
+    memory=1024,
+    incoming=100,
+    outgoing=50,
+    interface="eth0",
+    scope="cgroup",
+    limit=8192,
+):
+    return dict(
+        at=at,
+        cpu_percent=cpu,
+        cpu_scope=scope,
+        memory_bytes=memory,
+        memory_limit_bytes=limit,
+        received_bytes_per_second=incoming,
+        sent_bytes_per_second=outgoing,
+        network_interface=interface,
+    )
+
+
+def counters(value=0):
+    return dict(
+        network=dict(received_bytes=value * 10, sent_bytes=value * 2),
+        upload_bytes=value * 3,
+        download_bytes=value * 4,
+        requests=value,
+        errors=value // 2,
+    )
+
+
+def test_weighted_minute_averages_use_actual_seconds_and_preserve_null_gaps(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    history.observe(sample(960), counters())
+    history.observe(sample(963, cpu=20, incoming=100), counters(1))
+    history.observe(sample(972, cpu=40, incoming=300), counters(2))
+    result = history.query(900, 1200, now=1200)
+    measured = result["samples"][1]
+    assert measured["at"] == 960
+    assert measured["cpu_percent"] == 35
+    assert measured["received_bytes_per_second"] == 250
+    assert measured["coverage_seconds"]["cpu_percent"] == 12
+    assert result["samples"][0]["cpu_percent"] is None
+    assert result["samples"][2]["received_bytes_per_second"] is None
+    assert result["totals"]["http_download_bytes"] == 8
+    assert result["totals"]["telegram_download_bytes"] is None
+
+
+def test_cross_minute_interval_is_split_without_losing_weight(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    history.observe(sample(1019), counters())
+    history.observe(sample(1022), counters())
+    result = history.query(960, 1080, now=1100)
+    assert [s["coverage_seconds"]["memory_bytes"] for s in result["samples"]] == [1, 2]
+    assert all(s["memory_bytes"] == 1024 for s in result["samples"])
+
+
+def test_downsampling_weights_covered_seconds_instead_of_averaging_minutes(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    start = 60000
+    for at, cpu, incoming in (
+        (start, 0, 0),
+        (start + 3, 20, 100),
+        (start + 60, 0, 0),
+        (start + 69, 40, 400),
+    ):
+        history.observe(sample(at, cpu=cpu, incoming=incoming), counters())
+    result = history.query(start, start + 86400, now=start + 86400)
+    assert result["bucket_seconds"] == 240
+    assert len(result["samples"]) == 360
+    assert result["samples"][0]["cpu_percent"] == 35
+    assert result["samples"][0]["received_bytes_per_second"] == 325
+    assert result["samples"][0]["coverage_seconds"]["cpu_percent"] == 12
+    assert result["samples"][1]["cpu_percent"] is None
+
+
+def test_unavailable_network_is_unknown_in_lifetime_totals(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    history.observe(
+        sample(960, incoming=None, outgoing=None, interface=None),
+        counters()
+        | {"network": {"available": False, "received_bytes": 0, "sent_bytes": 0}},
+    )
+    result = history.query(900, 1020, now=1100)
+    assert result["totals"]["network_received_bytes"] is None
+    assert result["totals"]["http_requests"] == 0
+
+
+def test_source_changes_do_not_mix_cpu_or_interface_measurements(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    for at, interface, scope in (
+        (960, "eth0", "cgroup"),
+        (963, "eth0", "cgroup"),
+        (966, "eth1", "host"),
+        (969, "eth1", "host"),
+    ):
+        history.observe(sample(at, interface=interface, scope=scope), counters())
+    point = history.query(960, 1020, now=1100)["samples"][0]
+    assert point["cpu_percent"] is point["received_bytes_per_second"] is None
+    assert point["cpu_scope"] is point["network_interface"] is None
+    assert point["memory_bytes"] == 1024
+
+
+def test_suspend_and_clock_reversal_do_not_backfill_or_double_count_coverage(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    for at in (960, 963, 900, 903, 962, 965, 968, 1100):
+        history.observe(sample(at), counters())
+    result = history.query(900, 1140, now=1200)
+    assert result["samples"][0]["memory_bytes"] is None
+    assert result["samples"][1]["coverage_seconds"]["memory_bytes"] == 6
+    assert result["samples"][2]["memory_bytes"] is None
+    assert result["samples"][3]["memory_bytes"] is None
+
+
+def test_restart_retains_minutes_and_lifetime_counters_without_replay(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    history.observe(sample(960), counters(10))
+    history.observe(sample(963), counters(20))
+    history.flush(force=True, now=964)
+    history.flush(force=True, now=964)  # Unknown write outcome/retry is idempotent.
+    restarted = TelemetryHistory(tmp_path)
+    restarted.observe(sample(966), counters(2))
+    restarted.observe(sample(969), counters(3))
+    restarted.flush(force=True, now=970)
+    result = TelemetryHistory(tmp_path).query(960, 1020, now=1100)
+    assert result["totals"]["network_received_bytes"] == 230
+    assert result["totals"]["http_requests"] == 23
+    assert result["samples"][0]["coverage_seconds"]["memory_bytes"] == 6
+    assert result["tracked_since"] == 960
+    assert result["last_updated"] == 969
+
+
+def test_telegram_account_replacement_and_counter_resets_are_not_negative(tmp_path):
+    history = TelemetryHistory(tmp_path)
+
+    def observe(at, value, identity):
+        history.observe(
+            sample(at),
+            counters(),
+            {
+                "accounts": [
+                    {
+                        "name": "bot",
+                        "requests": {
+                            "upload_bytes": value,
+                            "download_bytes": value * 2,
+                        },
+                    }
+                ]
+            },
+            sources={"bot": identity},
+        )
+
+    observe(960, 100, "first")
+    observe(963, 150, "first")
+    observe(966, 200, "replacement")
+    observe(969, 10, "replacement")
+    result = history.query(960, 1020, now=1100)
+    assert result["totals"]["telegram_upload_bytes"] == 360
+    assert result["totals"]["telegram_download_bytes"] == 720
+    assert "bot" not in repr(history.storage.read(960, 1020))
+
+
+def test_connection_churn_does_not_evict_active_counter_baselines(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    for index in range(600):
+        history.observe(
+            sample(960 + index * 3),
+            counters(),
+            {
+                "accounts": [
+                    {"name": "stable", "requests": {"upload_bytes": 100 + index}},
+                    {"name": "replacement", "requests": {"upload_bytes": 1}},
+                ]
+            },
+            sources={"stable": "stable", "replacement": index},
+        )
+    assert history._totals["telegram_upload_bytes"] == 699 + 600
+    assert len(history._baselines) <= 512
+
+
+def test_retention_prunes_minutes_without_erasing_lifetime_stats(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    history.observe(sample(960), counters(100))
+    history.observe(sample(963), counters(200))
+    history.flush(force=True, now=964)
+    now = 964 + RETENTION_SECONDS + 120
+    history.observe(sample(now), counters(300))
+    history.flush(force=True, now=now)
+    assert history.storage.read(0, now - RETENTION_SECONDS) == []
+    result = history.query(now - 3600, now, now=now)
+    assert result["totals"]["network_received_bytes"] == 3000
+    assert result["tracked_since"] == 960
+
+
+def test_month_query_is_bounded_and_boundary_minutes_are_explicit(tmp_path):
+    history = TelemetryHistory(tmp_path)
+    now = 4_000_000
+    result = history.query(now - 30 * 86400 + 17, now - 7, now=now)
+    assert len(result["samples"]) <= 360
+    assert result["bucket_seconds"] >= 60
+    assert result["start"] % 60 == 0
+    assert result["end"] <= now
+    assert all(point["cpu_percent"] is None for point in result["samples"])
+    assert result["tracked_since"] is None
+
+
+@pytest.mark.parametrize(
+    "start,end",
+    [
+        (math.nan, 100),
+        (0, math.inf),
+        (1000, 900),
+        (1001, 1010),
+        (999, 1061),
+        (-1, 1000),
+        (1000 - RETENTION_SECONDS - 61, 1000),
+    ],
+)
+def test_invalid_or_future_ranges_are_rejected(start, end):
+    with pytest.raises(ValueError):
+        validate_range(start, end, now=1000)
+
+
+def test_flush_backoff_and_pending_memory_are_bounded_during_failure(
+    tmp_path, monkeypatch
+):
+    history = TelemetryHistory(tmp_path)
+    history.observe(sample(960), counters())
+    writes = []
+
+    def fail(*args):
+        writes.append(args)
+        raise OSError("temporarily unavailable")
+
+    monkeypatch.setattr(history.storage, "write", fail)
+    monkeypatch.setattr(
+        "tgdrive.observability.telemetry_history.time.monotonic", lambda: 1000
+    )
+    with pytest.raises(OSError):
+        history.flush(now=960)
+    history.flush(now=963)
+    assert len(writes) == 1
+    for at in range(1020, 1020 + 180 * 60, 60):
+        history.observe(sample(at), counters())
+        history.observe(sample(at + 3), counters())
+    assert len(history._minutes) == 120
+
+
+def test_history_uses_mongodb_without_creating_a_local_database(
+    tmp_path, mongo_backend
+):
+    storage = HistoryStorage(tmp_path)
+    storage.load(960)
+    assert storage.mongo is mongo_backend
+    assert not (tmp_path / "telemetry.sqlite3").exists()
+    assert mongo_backend.db.telemetry_minutes.count_documents({}) == 0
+
+
+def test_history_api_requires_owner_bounds_results_and_hides_storage_errors(
+    tmp_path, monkeypatch, mongo_backend
+):
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = mongo_backend
+    app = create_app(make_settings(tmp_path), runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            now = time.time()
+            params = {"start": now - 3600, "end": now}
+            assert (
+                client.get("/api/v1/performance/history", params=params).status_code
+                == 401
+            )
+            item = store.add_file("/", "public.txt", 123, 12)["id"]
+            token = store.create_share("/" + item)
+            assert (
+                client.get(
+                    "/api/v1/performance/history", params=params | {"auth": token}
+                ).status_code
+                == 401
+            )
+            login(client)
+            response = client.get("/api/v1/performance/history", params=params)
+            assert response.status_code == 200
+            assert response.headers["cache-control"] == "no-store"
+            assert len(response.json()["samples"]) <= 360
+            assert (
+                client.get(
+                    "/api/v1/performance/history", params={"start": "nan", "end": now}
+                ).status_code
+                == 422
+            )
+            assert (
+                client.get(
+                    "/api/v1/performance/history",
+                    params={"start": now + 1, "end": now + 10},
+                ).status_code
+                == 422
+            )
+
+            def fail(*args):
+                raise OSError("mongodb://private-secret")
+
+            monkeypatch.setattr(app.state.telemetry_history, "query", fail)
+            failed = client.get("/api/v1/performance/history", params=params)
+            assert failed.status_code == 503
+            assert "private-secret" not in failed.text
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/observability/test_transfer_metrics.py b/tests/observability/test_transfer_metrics.py
new file mode 100644
index 00000000..5c06c65a
--- /dev/null
+++ b/tests/observability/test_transfer_metrics.py
@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+import tgdrive.transfers.tasks as tasks
+from tests.support.mongo_fixtures import FakeMongoBackend
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+
+@pytest.fixture
+def clock(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace:
+    value = SimpleNamespace(now=1000.0)
+    monkeypatch.setattr(tasks.time, "time", lambda: value.now)
+    monkeypatch.setattr(tasks.time, "monotonic", lambda: value.now)
+    return value
+
+
+async def running(registry: TransferRegistry):
+    record = await registry.create("queued", total=100)
+    record.created_at = 1000.0
+    await registry.update(
+        record.id, status=TransferStatus.RUNNING, phase="uploading", current=0
+    )
+    return record
+
+
+async def test_metrics_are_stage_specific_stale_bounded_and_terminal_frozen(clock):
+    registry = TransferRegistry()
+    record = await running(registry)
+    clock.now += 2
+    await registry.update(record.id, current=50)
+    snapshot = record.as_dict()
+    assert snapshot["speed_bytes_per_second"] == 25
+    assert snapshot["eta_seconds"] == 2
+    assert snapshot["elapsed_seconds"] == 2
+    assert snapshot["started_at"] == 1000
+    assert snapshot["progress_updated_at"] == 1002
+    clock.now += 16
+    assert record.as_dict()["speed_bytes_per_second"] is None
+    await registry.update(record.id, phase="finalizing", current=100)
+    assert record.as_dict()["eta_seconds"] is None
+    await registry.update(record.id, status=TransferStatus.COMPLETED, phase="completed")
+    finished = record.as_dict()
+    clock.now += 60
+    assert record.as_dict() == finished
+    assert finished["finished_at"] == 1018
+
+
+async def test_metrics_restart_when_phase_total_or_counter_changes(clock):
+    registry = TransferRegistry()
+    record = await running(registry)
+    clock.now += 1
+    await registry.update(record.id, current=50)
+    assert record.as_dict()["speed_bytes_per_second"] == 50
+    await registry.update(record.id, phase="downloading", current=0)
+    assert record.as_dict()["speed_bytes_per_second"] is None
+    clock.now += 1
+    await registry.update(record.id, current=25)
+    assert record.as_dict()["speed_bytes_per_second"] == 25
+    await registry.update(record.id, total=200)
+    assert record.as_dict()["speed_bytes_per_second"] is None
+    clock.now += 1
+    await registry.update(record.id, current=100)
+    await registry.update(record.id, current=50)
+    assert record.as_dict()["speed_bytes_per_second"] is None
+    record.context["kind"] = "delete"
+    clock.now += 1
+    await registry.update(record.id, current=75)
+    assert record.as_dict()["speed_bytes_per_second"] is None
+
+
+async def test_progress_is_visible_without_per_chunk_commits_and_context_flushes(clock):
+    backend = FakeMongoBackend()
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = await running(registry)
+    backend.write = Mock(wraps=backend.write)
+    for current in range(1, 50):
+        await registry.update(record.id, current=current)
+    assert record.as_dict()["current"] == 49
+    assert backend.write.call_count == 0
+    assert backend.db.jobs.find_one({"_id": record.id})["data"]["current"] == 0
+    record.context.update(sender="stable-sender", random_id=123, send_started=True)
+    await registry.update(record.id, current=50)
+    assert backend.write.call_count == 1
+    clock.now += 0.51
+    await registry.update(record.id, current=75)
+    assert record.current == 75
+    assert backend.write.call_count == 1
+    assert backend.db.jobs.find_one({"_id": record.id})["data"]["current"] == 50
+    await registry.update(
+        record.id, status=TransferStatus.COMPLETED, phase="completed", current=100
+    )
+    assert backend.write.call_count == 2
+    finished = record.finished_at
+    registry.close()
+    reopened = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    restored = reopened.get(record.id)
+    assert restored.current == 100
+    assert restored.started_at == 1000 and restored.finished_at == finished
+    assert restored.as_dict()["speed_bytes_per_second"] is None
+    assert restored.context["random_id"] == 123
+    reopened.close()
+
+
+async def test_terminal_job_without_known_start_does_not_invent_elapsed(clock):
+    backend = FakeMongoBackend()
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = await registry.create("failed")
+    clock.now = 1010
+    await registry.update(
+        record.id,
+        phase="failed",
+        status=TransferStatus.ERROR,
+        error="offline",
+    )
+    registry.close()
+    reopened = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    assert reopened.get(record.id).as_dict()["elapsed_seconds"] == 0
+    reopened.close()
+
+
+async def test_url_byte_progress_avoids_commits_but_keeps_recovery_changes_durable(
+    clock, monkeypatch
+):
+    backend = FakeMongoBackend()
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = await registry.create("downloading", total=100)
+    record.context.update(kind="remote", staging_size=100, staging_written=0)
+    await registry.update(record.id, status=TransferStatus.RUNNING, current=0)
+    persist = Mock(wraps=backend.write)
+    monkeypatch.setattr(backend, "write", persist)
+
+    for current in range(1, 50):
+        clock.now += 1  # Beyond the normal progress checkpoint interval.
+        record.context["staging_written"] = current
+        await registry.update(record.id, current=current, checkpoint_progress=False)
+    assert persist.call_count == 0
+    assert record.as_dict()["current"] == 49
+    assert record.as_dict()["speed_bytes_per_second"] == 1
+    assert registry._durable[record.id]["context"]["staging_written"] == 0
+
+    # Reservation and dispatch identities still commit immediately, even when
+    # advisory byte checkpoints are disabled by the URL pipeline.
+    record.context.update(staging_size=200, sender="bot", random_id=123)
+    await registry.update(record.id, current=50, checkpoint_progress=False)
+    assert persist.call_count == 1
+    assert registry._durable[record.id]["context"]["random_id"] == 123
+    await registry.update(
+        record.id,
+        status=TransferStatus.ERROR,
+        error="connection interrupted",
+        checkpoint_progress=False,
+    )
+    assert persist.call_count == 2
+    assert registry._durable[record.id]["current"] == 50
+    assert registry._durable[record.id]["context"]["staging_written"] == 49
+    registry.close()
+
+
+async def test_unknown_length_reports_rate_without_inventing_an_eta(clock):
+    registry = TransferRegistry()
+    record = await registry.create("queued")
+    await registry.update(
+        record.id,
+        status=TransferStatus.RUNNING,
+        phase="downloading",
+        current=0,
+        total=0,
+    )
+    clock.now += 2
+    await registry.update(record.id, current=50, total=0)
+    snapshot = record.as_dict()
+    assert snapshot["speed_bytes_per_second"] == 25
+    assert snapshot["eta_seconds"] is None
+
+
+async def test_waiting_for_capacity_does_not_start_elapsed_and_completion_freezes_it(
+    clock,
+):
+    backend = FakeMongoBackend()
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = await registry.create("queued", total=100)
+    clock.now += 60
+    assert record.as_dict()["elapsed_seconds"] == 0
+    assert record.as_dict()["started_at"] is None
+    registry.close()
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = registry.get(record.id)
+    assert record.as_dict()["elapsed_seconds"] == 0
+    await registry.update(
+        record.id, status=TransferStatus.RUNNING, phase="uploading", current=0
+    )
+    clock.now += 2
+    await registry.update(record.id, current=50)
+    assert record.as_dict()["elapsed_seconds"] == 2
+    await registry.update(
+        record.id, status=TransferStatus.COMPLETED, phase="completed", current=100
+    )
+    clock.now += 120
+    assert record.as_dict()["elapsed_seconds"] == 2
+    registry.close()
+
+
+async def test_cancel_before_start_has_no_elapsed_transfer_time(clock):
+    registry = TransferRegistry()
+    record = await registry.create("queued", total=100)
+    clock.now += 60
+    await registry.cancel(record.id)
+    assert record.as_dict()["elapsed_seconds"] == 0
+    assert record.as_dict()["speed_bytes_per_second"] is None
+    assert record.as_dict()["eta_seconds"] is None
+
+
+@pytest.mark.parametrize(
+    "context",
+    [
+        {"retry_at": 1100.0},
+        {"channel_retry_at": 1100.0},
+        {"multipart_plan": {"parts": [{"sender": "bot-one", "retry_at": 1100.0}]}},
+    ],
+)
+async def test_terminal_jobs_retain_provider_deadlines_until_they_expire(
+    clock, context
+):
+    registry = TransferRegistry(ttl_seconds=1, max_entries=1)
+    record = await registry.create("queued")
+    record.context.update(context)
+    await registry.cancel(record.id)
+    clock.now = 1010.0
+    await registry.prune()
+    assert registry.get(record.id) is record
+    with pytest.raises(RuntimeError, match="too many active"):
+        await registry.create("queued")
+    clock.now = 1101.0
+    await registry.prune()
+    assert registry.list() == []
+    assert await registry.create("queued")
+
+
+@pytest.mark.parametrize("mode", ["warm", "queued", "waiting_storage"])
+async def test_waiting_url_does_not_extrapolate_a_completion_eta(clock, mode):
+    registry = TransferRegistry()
+    record = await running(registry)
+    record.context.update(source_kind="remote", download_mode=mode)
+    await registry.update(record.id, phase="downloading", current=0)
+    clock.now += 2
+    await registry.update(record.id, current=50)
+    snapshot = record.as_dict()
+    assert snapshot["download_mode"] == mode
+    assert snapshot["speed_bytes_per_second"] == 25
+    assert snapshot["eta_seconds"] is None
+    record.context["download_mode"] = "full"
+    assert record.as_dict()["eta_seconds"] == 2
+    # Intake pacing must not suppress the subsequent Telegram-stage ETA.
+    record.context["download_mode"] = mode
+    await registry.update(record.id, phase="uploading", current=0)
+    clock.now += 2
+    await registry.update(record.id, current=50)
+    assert record.as_dict()["eta_seconds"] == 2
+    assert "download_mode" not in record.as_dict()
+
+
+async def test_source_retry_status_exposes_its_deadline_without_telegram_eta(clock):
+    registry = TransferRegistry()
+    record = await running(registry)
+    record.context.update(source_attempt=2, source_retry_at=clock.now + 4)
+    await registry.update(record.id, phase="source_retry_wait", current=0)
+    snapshot = record.as_dict()
+    assert snapshot["source_attempt"] == 2
+    assert snapshot["source_max_attempts"] == 4
+    assert snapshot["retry_at"] == clock.now + 4
+    assert snapshot["speed_bytes_per_second"] is None
+    assert snapshot["eta_seconds"] is None
+    await registry.update(record.id, phase="uploading")
+    assert record.as_dict()["retry_at"] is None
+    assert "source_attempt" not in record.as_dict()
diff --git a/tests/recovery/__init__.py b/tests/recovery/__init__.py
new file mode 100644
index 00000000..9a39f52a
--- /dev/null
+++ b/tests/recovery/__init__.py
@@ -0,0 +1 @@
+"""TGDrive recovery tests."""
diff --git a/tests/recovery/test_backup.py b/tests/recovery/test_backup.py
new file mode 100644
index 00000000..633aeb1c
--- /dev/null
+++ b/tests/recovery/test_backup.py
@@ -0,0 +1,38 @@
+"""Portable recovery JSON remains bounded, strict and independent of a backend."""
+
+import json
+
+import pytest
+
+import tgdrive.recovery.backup as backup
+from tgdrive.recovery.backup import BackupError, decode_catalog_snapshot
+
+
+def test_portable_recovery_json_decodes_utf8_without_database_access():
+    payload = {"name": chr(233), "revision": 2}
+    assert (
+        decode_catalog_snapshot(json.dumps(payload, ensure_ascii=False).encode())
+        == payload
+    )
+
+
+@pytest.mark.parametrize(
+    "content",
+    [
+        bytes([128, 4]),
+        bytes([255]),
+        b"{",
+        b'{"revision":1,"revision":2}',
+        b'{"root":{"id":1,"id":2}}',
+    ],
+)
+def test_portable_recovery_json_rejects_invalid_input_and_duplicate_keys(content):
+    with pytest.raises(BackupError):
+        decode_catalog_snapshot(content)
+
+
+def test_portable_recovery_json_enforces_the_shared_size_bound(monkeypatch):
+    monkeypatch.setattr(backup, "MAX_STORE_BYTES", 2)
+    assert decode_catalog_snapshot(b"{}") == {}
+    with pytest.raises(BackupError, match="safe size limit"):
+        decode_catalog_snapshot(b"{} ")
diff --git a/tests/recovery/test_backup_api.py b/tests/recovery/test_backup_api.py
new file mode 100644
index 00000000..6ccd2e75
--- /dev/null
+++ b/tests/recovery/test_backup_api.py
@@ -0,0 +1,247 @@
+"""Owner backup status/actions and cancellation boundaries through real routes."""
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.recovery.backup import RecoveryConflict
+from tgdrive.storage.store import DriveStore
+from tgdrive.transfers.manager import BackupPending
+from tgdrive.web.app import create_app
+
+
+class Backup:
+    def __init__(self):
+        self.calls = []
+        self.history_limits = []
+        self.confirmed = 0
+        self.fail = False
+
+    def history(self, *, limit=None):
+        self.history_limits.append(limit)
+        return []
+
+    def protection_status(self, store):
+        return {
+            "state": "protected" if self.confirmed >= store.revision else "pending",
+            "metadata_revision": store.revision,
+            "protected_revision": self.confirmed,
+        }
+
+    async def ensure_revision(self, store, revision):
+        self.calls.append(revision)
+        if self.fail:
+            raise RuntimeError("private-provider-token-must-never-be-returned")
+        self.confirmed = revision
+        return revision
+
+    async def snapshot_now(self, store):
+        return await self.ensure_revision(store, store.revision)
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path / "data")
+
+
+@pytest.fixture
+def owner(tmp_path, mongo_backend):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = mongo_backend
+    runtime.pool = None
+    runtime.backup = Backup()
+    with TestClient(
+        create_app(settings, runtime=runtime), base_url="https://testserver"
+    ) as client:
+        yield client, store, runtime, settings
+    store.close()
+
+
+def test_backup_actions_require_owner_and_same_origin(owner):
+    client, _, runtime, _ = owner
+    assert client.get("/api/v1/status").status_code == 401
+    assert client.post("/api/v1/backup", json={}).status_code == 401
+    login(client)
+    response = client.post(
+        "/api/v1/backup", json={}, headers={"Origin": "https://other.example"}
+    )
+    assert response.status_code == 403
+    assert runtime.backup.calls == []
+
+
+def test_manual_backup_confirms_current_revision_and_limits_status_history(owner):
+    client, store, runtime, _ = owner
+    login(client)
+    store.create_folder("/", "Recoverable")
+    pending = client.get("/api/v1/status")
+    assert pending.status_code == 200
+    assert pending.json()["recovery"]["state"] == "pending"
+    assert runtime.backup.history_limits == [1]
+    protected = client.post("/api/v1/backup", json={})
+    assert protected.status_code == 200
+    assert runtime.backup.calls == [store.revision]
+    assert protected.json()["recovery"] == {
+        "state": "protected",
+        "metadata_revision": store.revision,
+        "protected_revision": store.revision,
+    }
+    store.create_folder("/", "New changes")
+    assert client.get("/api/v1/status").json()["recovery"]["state"] == "pending"
+
+
+def test_manual_backup_failure_never_claims_confirmation_or_exposes_provider_error(
+    owner,
+):
+    client, _, runtime, _ = owner
+    login(client)
+    runtime.backup.fail = True
+    response = client.post("/api/v1/backup", json={})
+    assert response.status_code == 503
+    assert "not confirmed" in response.json()["detail"]
+    assert "private-provider" not in response.text
+    assert client.get("/api/v1/status").json()["recovery"]["state"] == "pending"
+
+
+def test_backup_unavailable_is_explicit(owner):
+    client, _, runtime, _ = owner
+    login(client)
+    runtime.backup = None
+    assert client.post("/api/v1/backup", json={}).status_code == 503
+    assert client.get("/api/v1/status").json()["recovery"] is None
+
+
+@pytest.mark.parametrize("route", ["job", "legacy-id", "legacy-request"])
+def test_no_cancellation_route_bypasses_checkpoint_guard(owner, route):
+    client, _, runtime, _ = owner
+    login(client)
+    manager = runtime.transfers
+    record = client.portal.call(
+        lambda: manager.registry.create("backup_pending", total=10)
+    )
+    request_id = "checkpoint-cancel-request"
+    starts = client.app.state.transfer_starts
+    entry, _ = starts.claim(request_id, ("test",))
+    starts.bind(entry, record)
+
+    async def protected(_job_id):
+        raise BackupPending("File stored; recovery checkpoint is pending")
+
+    manager.cancel_job = protected
+    if route == "job":
+        response = client.post(f"/api/v1/jobs/{record.id}/cancel", json={})
+    else:
+        payload = (
+            {"id": record.id}
+            if route == "legacy-id"
+            else {"client_request_id": request_id}
+        )
+        response = client.post("/api/cancelUpload", json=payload)
+    assert response.status_code == 409
+    assert response.json()["code"] == "BACKUP_PENDING"
+    assert not record.cancel_event.is_set()
+    assert not record.context.get("cancel_requested")
+    assert not entry.cancelled
+
+
+async def test_receipt_cancellation_checks_manager_before_mutating_job_or_receipt(
+    tmp_path,
+    mongo_backend,
+):
+    from tests.transfers.test_resumable_uploads import make
+
+    uploads, manager = make(tmp_path)
+    try:
+        receipt = uploads.create("one.txt", "/", 4)
+        await uploads.append(receipt["id"], 0, b"safe")
+        record = await uploads.complete(receipt["id"])
+        before = uploads.get_unchecked(receipt["id"]).copy()
+
+        async def protected(_job_id):
+            raise BackupPending("File stored; recovery checkpoint is pending")
+
+        manager.cancel_job = protected
+        with pytest.raises(BackupPending):
+            await uploads.cancel(receipt["id"])
+        assert uploads.get_unchecked(receipt["id"]) == before
+        assert not record.cancel_event.is_set()
+    finally:
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+@pytest.mark.parametrize(
+    ("route", "payload"),
+    [
+        ("/api/createNewFolder", {"path": "/", "name": "Unsafe"}),
+        ("/api/v1/uploads", {"name": "new.txt", "parent_id": "/", "total_size": 4}),
+        ("/api/v1/nodes/bulk", {"paths": ["/anything"], "action": "delete"}),
+        (
+            "/api/v1/folders/tree",
+            {
+                "destination": "/",
+                "root_name": "Unsafe",
+                "folders": [],
+                "client_request_id": "root-should-not-be-created",
+            },
+        ),
+        ("/api/v1/backup", {}),
+    ],
+)
+def test_recovery_conflict_blocks_writes_but_preserves_owner_catalog(
+    owner,
+    route,
+    payload,
+):
+    client, store, runtime, _ = owner
+    original = store.create_folder("/", "Preserved")
+    runtime.backup.recovery_required = True
+    login(client)
+    response = client.post(route, json=payload)
+    assert response.status_code == 409
+    assert response.json()["code"] == "RECOVERY_REQUIRED"
+    assert list(store.list_directory("/")) == [original["id"]]
+    catalog = client.post("/api/getDirectory", json={"path": "/"})
+    assert catalog.status_code == 200
+    assert client.get("/api/v1/status").status_code == 200
+    assert client.post("/api/logout", json={}).status_code == 200
+
+
+def test_recovery_conflict_blocks_media_before_using_wrong_channel(owner):
+    client, store, runtime, _ = owner
+    item = store.add_file("/", "private.txt", 123, 4)
+    runtime.backup.recovery_required = True
+    login(client)
+    for path in ("/file", "/api/v1/preview", "/api/v1/media"):
+        response = client.get(path, params={"path": "/" + item["id"]})
+        assert response.status_code == 409
+        assert response.json()["code"] == "RECOVERY_REQUIRED"
+
+
+def test_manual_backup_discovery_returns_structured_recovery_conflict(owner):
+    client, _, runtime, _ = owner
+    login(client)
+
+    async def conflict(_store):
+        raise RecoveryConflict("A newer Telegram catalog needs explicit recovery")
+
+    runtime.backup.snapshot_now = conflict
+    response = client.post("/api/v1/backup", json={})
+    assert response.status_code == 409
+    assert response.json()["code"] == "RECOVERY_REQUIRED"
+
+
+def test_recovery_conflict_also_pauses_previously_issued_public_links(owner):
+    client, store, runtime, _ = owner
+    folder = store.create_folder("/", "Shared before conflict")
+    path = "/" + folder["id"]
+    token = store.create_share(path)
+    runtime.backup.recovery_required = True
+    response = client.post(
+        "/api/getDirectory", json={"path": "/share_" + folder["id"], "auth": token}
+    )
+    assert response.status_code == 409
+    assert response.json()["code"] == "RECOVERY_REQUIRED"
diff --git a/tests/recovery/test_backup_recovery_key_api.py b/tests/recovery/test_backup_recovery_key_api.py
new file mode 100644
index 00000000..aca1ce65
--- /dev/null
+++ b/tests/recovery/test_backup_recovery_key_api.py
@@ -0,0 +1,38 @@
+"""Recovery-kit key downloads stay private and are never browser-cacheable."""
+
+from pydantic import SecretStr
+
+from tests.recovery.test_backup_api import mongo_backend as mongo_backend
+from tests.recovery.test_backup_api import owner as owner_fixture
+from tests.support.app_fixtures import login
+
+owner = owner_fixture
+
+
+def test_recovery_key_download_requires_owner_and_marks_secret_no_store(owner):
+    client, _, runtime, settings = owner
+    settings.mongodb_backup_key = SecretStr("b" * 64)
+    runtime.mongo = object()
+    response = client.get("/api/v1/backup/recovery-key")
+    assert response.status_code == 401
+    assert "b" * 64 not in response.text
+    login(client)
+    response = client.get("/api/v1/backup/recovery-key")
+    assert response.status_code == 200
+    assert response.text == "MONGODB_BACKUP_KEY=" + "b" * 64 + "\n"
+    assert response.headers["cache-control"] == "no-store"
+    assert response.headers["x-content-type-options"] == "nosniff"
+    assert response.headers["content-disposition"] == (
+        'attachment; filename="tgdrive-recovery-key.env"'
+    )
+
+
+def test_recovery_key_is_unavailable_without_matching_backend_or_key(owner):
+    client, _, runtime, settings = owner
+    login(client)
+    settings.mongodb_backup_key = SecretStr("b" * 64)
+    runtime.mongo = None
+    assert client.get("/api/v1/backup/recovery-key").status_code == 404
+    runtime.mongo = object()
+    settings.mongodb_backup_key = None
+    assert client.get("/api/v1/backup/recovery-key").status_code == 404
diff --git a/tests/recovery/test_channel_state.py b/tests/recovery/test_channel_state.py
new file mode 100644
index 00000000..383bffa5
--- /dev/null
+++ b/tests/recovery/test_channel_state.py
@@ -0,0 +1,153 @@
+"""Telegram configuration changes are checked again after initial setup."""
+
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon import functions, types
+
+from tests.core.test_runtime import FakeBackup, FakePool, FakeRemote, settings
+from tests.core.test_runtime import mongo_backend as mongo_backend_fixture
+from tgdrive.core.runtime import Runtime
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.channel_state import storage_bot_rights_problem
+from tgdrive.telegram.clients import Client
+
+mongo_backend = mongo_backend_fixture
+
+CHANNEL = -1001234567890
+
+
+@pytest.mark.parametrize("require_pin", [False, True])
+async def test_live_adapter_checks_channel_privacy_retention_and_required_rights(
+    require_pin,
+):
+    chat = types.Channel(
+        id=1234567890,
+        title="Storage",
+        photo=types.ChatPhotoEmpty(),
+        date=None,
+        broadcast=True,
+        admin_rights=types.ChatAdminRights(
+            post_messages=True, delete_messages=True, edit_messages=require_pin
+        ),
+    )
+    full_chat = SimpleNamespace(ttl_period=None)
+
+    class Native:
+        def __init__(self):
+            self.requests = []
+
+        async def get_input_entity(self, channel):
+            assert channel == CHANNEL
+            return types.InputPeerChannel(channel_id=chat.id, access_hash=123)
+
+        async def __call__(self, request):
+            self.requests.append(request)
+            assert isinstance(request, functions.channels.GetFullChannelRequest)
+            return SimpleNamespace(chats=[chat], full_chat=full_chat)
+
+    client = Client.__new__(Client)
+    client.native = Native()
+    assert (
+        await client.storage_channel_problem(CHANNEL, require_pin=require_pin)
+    ) is None
+    full_chat.ttl_period = 86400
+    problem = await client.storage_channel_problem(CHANNEL, require_pin=require_pin)
+    assert problem[0] == "CHANNEL_AUTO_DELETE"
+    full_chat.ttl_period = None
+    chat.username = "public_storage"
+    problem = await client.storage_channel_problem(CHANNEL, require_pin=require_pin)
+    assert problem[0] == "CHANNEL_PUBLIC"
+    chat.username = None
+    chat.admin_rights.delete_messages = False
+    problem = await client.storage_channel_problem(CHANNEL, require_pin=require_pin)
+    assert problem[0] == "CHANNEL_RIGHTS"
+    assert len(client.native.requests) == 4
+
+
+@pytest.mark.parametrize("right", ["post_messages", "delete_messages", "edit_messages"])
+def test_bot_rights_match_checkpoint_mode(right):
+    rights = SimpleNamespace(
+        post_messages=True, delete_messages=True, edit_messages=True
+    )
+    setattr(rights, right, False)
+    chat = SimpleNamespace(admin_rights=rights)
+    assert storage_bot_rights_problem(chat, require_pin=True)[0] == "CHANNEL_RIGHTS"
+    assert bool(storage_bot_rights_problem(chat, require_pin=False)) == (
+        right != "edit_messages"
+    )
+
+
+class ChannelPool(FakePool):
+    def __init__(self, *problems):
+        super().__init__()
+        self.clients = {
+            f"storage-{index}": SimpleNamespace(
+                storage_channel_problem=AsyncMock(return_value=problem)
+            )
+            for index, problem in enumerate(problems)
+        }
+
+    async def status(self):
+        return [
+            SimpleNamespace(name=name, kind="bot", healthy=True)
+            for name in self.clients
+        ]
+
+    @asynccontextmanager
+    async def lease(self, *, client_name):
+        yield self.clients[client_name]
+
+
+async def test_runtime_rechecks_every_bot_and_failed_checks_allow_immediate_retry(
+    tmp_path,
+):
+    pool = ChannelPool(None, ("CHANNEL_RIGHTS", "Restore Delete Messages permission."))
+    runtime = Runtime(settings(tmp_path), pool=pool)
+    with pytest.raises(SettingsProblem, match="Delete Messages"):
+        await runtime._verify_storage_channel()
+    assert runtime.storage_channel_error == "Restore Delete Messages permission."
+    pool.clients["storage-1"].storage_channel_problem.return_value = None
+    await runtime._verify_storage_channel()
+    assert runtime.storage_channel_error is None
+    for client in pool.clients.values():
+        assert client.storage_channel_problem.await_count == 2
+        client.storage_channel_problem.assert_awaited_with(CHANNEL, require_pin=False)
+    await runtime._verify_storage_channel()
+    assert pool.clients["storage-0"].storage_channel_problem.await_count == 2
+
+
+async def test_channel_probe_network_error_is_safe_and_retryable(tmp_path):
+    pool = ChannelPool(None)
+    probe = pool.clients["storage-0"].storage_channel_problem
+    probe.side_effect = TimeoutError("sensitive request details")
+    runtime = Runtime(settings(tmp_path), pool=pool)
+    with pytest.raises(ConnectionError, match="could not be verified") as error:
+        await runtime._verify_storage_channel()
+    assert "sensitive" not in str(error.value)
+    probe.side_effect = None
+    await runtime._verify_storage_channel()
+    assert runtime.storage_channel_error is None
+
+
+async def test_unsafe_channel_preserves_metadata_and_pauses_startup_recovery(
+    tmp_path, monkeypatch
+):
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    store.create_folder("/", "Preserve")
+    pool = ChannelPool(("CHANNEL_AUTO_DELETE", "Turn auto-delete off."))
+    runtime = Runtime(settings(tmp_path), pool=pool)
+    runtime.backup = FakeBackup(store)
+    runtime.remote = FakeRemote()
+    monkeypatch.setattr("tgdrive.core.runtime.build_bot_mode_client", lambda _: None)
+    try:
+        await runtime.start()
+        assert runtime.ready
+        assert runtime.store.list_directory("/")
+        assert runtime.backup.backups == 0
+        assert runtime.storage_channel_error == "Turn auto-delete off."
+    finally:
+        await runtime.stop()
diff --git a/tests/recovery/test_recovery.py b/tests/recovery/test_recovery.py
new file mode 100644
index 00000000..9bf154f8
--- /dev/null
+++ b/tests/recovery/test_recovery.py
@@ -0,0 +1,31 @@
+"""Portable catalog identities and operation tombstones survive recovery."""
+
+import pytest
+
+from tgdrive.core.errors import ValidationError
+from tgdrive.storage.store import DriveStore
+
+
+def test_drive_identity_and_file_operation_tombstones_roundtrip(tmp_path):
+    database = tmp_path / "drive.sqlite3"
+    store = DriveStore.create(database)
+    identity = store.drive_id
+    file = store.add_file("/", "finished.bin", 7, 8, operation_id="finished-operation")
+    assert store.has_file_operation("finished-operation")
+    assert not store.has_file_operation("unknown-operation")
+    path = "/" + file["id"]
+    store.set_trashed(path, True)
+    intent = store.begin_deletion(path, channel_id=-1001)
+    store.confirm_deletion_messages(intent["id"], [7])
+    store.finish_deletion(intent["id"])
+    assert store.has_file_operation("finished-operation")
+    with pytest.raises(ValidationError):
+        store.has_file_operation("../unsafe")
+    restored = DriveStore._from_payload(store.export())
+    assert restored.drive_id == identity
+    assert restored.has_file_operation("finished-operation")
+    restored.close()
+    store.close()
+    loaded = DriveStore.load(database)
+    assert loaded.drive_id == identity
+    loaded.close()
diff --git a/tests/recovery/test_recovery_conflicts.py b/tests/recovery/test_recovery_conflicts.py
new file mode 100644
index 00000000..2a572d63
--- /dev/null
+++ b/tests/recovery/test_recovery_conflicts.py
@@ -0,0 +1,133 @@
+"""Channel binding and transfer lineage guards preserve catalog references."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tests.transfers.test_transfers import FakeTelegramClient
+from tgdrive.core.errors import CorruptStoreError, ValidationError
+from tgdrive.recovery.backup import RecoveryConflict
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.manager import TransferManager
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+
+def manager_for(tmp_path, pool, store, guard):
+    return TransferManager(
+        settings=SimpleNamespace(
+            resolved_cache_dir=tmp_path / "cache",
+            max_concurrent_transfers=1,
+            storage_channel=-1001234567890,
+            bot_upload_limit=2_000_000_000,
+        ),
+        pool=pool,
+        store=store,
+        remote=SimpleNamespace(close=AsyncMock()),
+        registry=TransferRegistry(),
+        ensure_lineage=guard,
+    )
+
+
+def test_channel_binding_is_durable_idempotent_and_never_rebound(tmp_path):
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    before = store.revision
+    assert store.storage_channel_id is None
+    store.bind_storage_channel(-100123)
+    assert store.revision == before + 1
+    store.bind_storage_channel(-100123)
+    assert store.revision == before + 1
+    with pytest.raises(ValidationError, match="another storage channel"):
+        store.bind_storage_channel(-100999)
+    payload = store.export()
+    assert payload["storage_channel_id"] == -100123
+    restored = DriveStore._from_payload(payload)
+    assert restored.storage_channel_id == -100123
+    restored.close()
+    store.close()
+    reopened = DriveStore.load(tmp_path / "drive.sqlite3")
+    assert reopened.storage_channel_id == -100123
+    reopened.close()
+
+
+@pytest.mark.parametrize("channel", [0, True, 1.2, "-1001", 2**63, -(2**63) - 1])
+def test_portable_binding_rejects_ambiguous_or_out_of_range_channels(channel):
+    store = DriveStore.create()
+    payload = store.export()
+    payload["storage_channel_id"] = channel
+    with pytest.raises(CorruptStoreError, match="storage_channel_id"):
+        DriveStore._from_payload(payload)
+    assert store.storage_channel_id is None
+    store.close()
+
+
+async def test_catalog_deletion_rechecks_lineage_before_removing_refs(
+    tmp_path,
+):
+    client = FakeTelegramClient()
+    pool = ClientPool([client])
+    await pool.start()
+    store = DriveStore.create()
+    folder = store.create_folder("/", "Bulk")
+    path = "/" + folder["id"]
+    for identity in range(1, 102):
+        store.add_file(path, str(identity), identity, 1)
+    store.set_trashed(path, True)
+    calls = 0
+
+    async def guard():
+        nonlocal calls
+        calls += 1
+        if calls == 2:
+            raise RecoveryConflict("A newer remote catalog appeared")
+
+    manager = manager_for(tmp_path, pool, store, guard)
+    record = await manager.start_deletion(path)
+    await record.task
+    assert record.status is TransferStatus.ERROR
+    assert client.deleted == []
+    assert store.pending_deletions()[0]["pending_message_ids"] == list(range(1, 102))
+    assert len(store.list_directory(path, include_trashed=True)) == 101
+    await manager.close()
+    manager.registry.close()
+    store.close()
+    await pool.stop()
+
+
+async def test_cancel_cleanup_does_not_delete_media_after_late_conflict(
+    tmp_path, monkeypatch
+):
+    client = FakeTelegramClient()
+    pool = ClientPool([client])
+    await pool.start()
+    store = DriveStore.create()
+    calls = 0
+
+    async def guard():
+        nonlocal calls
+        calls += 1
+        if calls == 2:
+            raise RecoveryConflict("A newer remote catalog appeared")
+
+    manager = manager_for(tmp_path, pool, store, guard)
+    record = await manager.registry.create("uploading", total=6)
+    source = tmp_path / "retained.part"
+    source.write_bytes(b"source")
+    original = client.send_staged
+
+    async def cancel_after_acceptance(*args, **kwargs):
+        message = await original(*args, **kwargs)
+        record.cancel_event.set()
+        return message
+
+    monkeypatch.setattr(client, "send_staged", cancel_after_acceptance)
+    with pytest.raises(RecoveryConflict):
+        await manager._upload_path(record, source, "/", "source.bin", 6)
+    assert client.deleted == []
+    assert source.read_bytes() == b"source"
+    assert record.context["remote_message_id"] == 99
+    await manager.close()
+    manager.registry.close()
+    store.close()
+    await pool.stop()
diff --git a/tests/recovery/test_restore_api.py b/tests/recovery/test_restore_api.py
new file mode 100644
index 00000000..dc05ce2b
--- /dev/null
+++ b/tests/recovery/test_restore_api.py
@@ -0,0 +1,435 @@
+"""Archive restore guards and owner HTTP contract with isolated Mongo doubles."""
+
+import asyncio
+import copy
+import zlib
+from threading import Event, RLock
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from bson import json_util
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.testclient import TestClient
+
+import tgdrive.recovery.mongo_backup as archive
+import tgdrive.recovery.restore_api as api
+from tgdrive.core.errors import CorruptStoreError
+from tgdrive.core.security import SESSION_COOKIE, InvalidSession, SessionManager
+from tgdrive.recovery.backup import BackupError
+from tgdrive.storage.store import ROOT_ID, SCHEMA_VERSION, DriveStore
+from tgdrive.web.http_guard import ApiBodyGuardMiddleware
+
+
+class Collection:
+    def __init__(self):
+        self.rows = []
+        self.fail_insert = False
+
+    def find(self, query, **_kwargs):
+        if "expires" in query:
+            return [
+                dict(row)
+                for row in self.rows
+                if row["expires"] > query["expires"]["$gt"]
+            ]
+        return copy.deepcopy(self.rows)
+
+    def find_one(self, _query, **_kwargs):
+        return copy.deepcopy(self.rows[0]) if self.rows else None
+
+    def delete_many(self, query, **_kwargs):
+        if "expires" in query:
+            self.rows = [
+                row for row in self.rows if row["expires"] > query["expires"]["$lte"]
+            ]
+        else:
+            self.rows.clear()
+
+    def insert_one(self, row, **_kwargs):
+        self.rows.append(copy.deepcopy(row))
+
+    def insert_many(self, rows, **_kwargs):
+        if self.fail_insert:
+            raise RuntimeError("Synthetic transaction failure")
+        self.rows.extend(copy.deepcopy(rows))
+
+
+class Collections(dict):
+    def __getattr__(self, name):
+        return self[name]
+
+
+class Backend:
+    def __init__(self):
+        self.db = Collections({name: Collection() for name in archive.COLLECTIONS})
+        self.ping, self.fence = Mock(), Mock()
+        self.pause_writes = Mock()
+        self.acquire, self.release = Mock(), Mock()
+        self._settings_lock = RLock()
+        self._settings_cached = True
+        self._settings_document = object()
+
+    def transaction(self, operation, *, allow_paused=False):
+        before = {name: copy.deepcopy(value.rows) for name, value in self.db.items()}
+        try:
+            return operation(object())
+        except BaseException:
+            for name, rows in before.items():
+                self.db[name].rows = rows
+            raise
+
+    def write(self, collection, method, *args, **kwargs):
+        return getattr(collection, method)(*args, **kwargs)
+
+
+def pristine(backend):
+    backend.db.catalog.rows = [
+        {
+            "_id": "catalog",
+            "schema_version": SCHEMA_VERSION,
+            "drive_id": "new-drive",
+            "revision": 2,
+            "generation": 1,
+        }
+    ]
+    backend.db.nodes.rows = [
+        {
+            "_id": ROOT_ID,
+            "parent_id": None,
+            "kind": "folder",
+            "name": "/",
+            "trashed": False,
+        }
+    ]
+    backend.db.settings.rows = [
+        {"_id": "bootstrap", "document": {}},
+        {"_id": "telegram", "revision": 1, "document": {}},
+    ]
+
+
+def recovered_data():
+    result = {name: [] for name in archive.COLLECTIONS}
+    result["catalog"] = [
+        {
+            "_id": "catalog",
+            "schema_version": SCHEMA_VERSION,
+            "drive_id": "recovered-drive",
+            "revision": 7,
+            "backed_up_revision": 7,
+            "generation": 6,
+        }
+    ]
+    result["nodes"] = [archive.MongoStore._node(ROOT_ID, None, "/", "folder")]
+    result["sessions"] = [{"_id": "old-session", "expires": 9999999999}]
+    return result
+
+
+def current_archive_records():
+    store = DriveStore.create()
+    try:
+        folder = store.create_folder("/", "Folder")
+        file = store.add_file("/", "Shared.bin", 41, 3, operation_id="saved-operation")
+        store.create_share("/" + file["id"])
+        trash = store.add_file("/", "Removed.bin", 42, 4)
+        store.set_trashed("/" + trash["id"], True)
+        store.begin_deletion("/" + trash["id"], channel_id=-1001234567890)
+        store.prepare_folder_tree("/", "Prepared", [["Child"]], "prepared-request-1")
+        payload = store.export()
+    finally:
+        store.close()
+    data = recovered_data()
+    data["catalog"][0].update(
+        drive_id=payload["drive_id"],
+        revision=payload["revision"],
+        backed_up_revision=payload["backed_up_revision"],
+    )
+    data["nodes"] = []
+    stack = [(payload["root"], None)]
+    while stack:
+        node, parent = stack.pop()
+        values = {
+            key: value
+            for key, value in node.items()
+            if key not in {"id", "name", "type", "children", "share_hashes"}
+        }
+        values["part_count"] = len(node.get("parts") or [None])
+        data["nodes"].append(
+            archive.MongoStore._node(
+                node["id"], parent, node["name"], node["type"], **values
+            )
+        )
+        if node["type"] == "folder":
+            stack.extend((child, node["id"]) for child in node["children"].values())
+    for name, portable, identity in (
+        ("shares", "shares", "id"),
+        ("operations", "operations", "operation_id"),
+        ("deletions", "deletions", "id"),
+        ("preparations", "folder_preparations", "request_id"),
+    ):
+        data[name] = [dict(row, _id=row[identity]) for row in payload[portable]]
+    return data, folder["id"]
+
+
+def test_current_archive_records_validate_without_sqlite(monkeypatch):
+    import sqlite3
+
+    data, _folder = current_archive_records()
+    connect = Mock(side_effect=AssertionError("Archive validation opened SQLite"))
+    monkeypatch.setattr(sqlite3, "connect", connect)
+    archive.MongoStore.validate_snapshot_records(data)
+    connect.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "fault",
+    [
+        "share_expiry",
+        "share_created",
+        "share_label",
+        "share_identity",
+        "operation_kind",
+        "operation_identity",
+        "deletion_state",
+        "deletion_messages",
+        "deletion_path",
+        "preparation_fingerprint",
+        "preparation_mapping",
+        "name_key",
+        "part_count",
+        "starred",
+    ],
+)
+def test_invalid_archive_records_fail_before_database_work(fault):
+    data, folder = current_archive_records()
+    if fault.startswith("share_"):
+        field = fault.removeprefix("share_")
+        field = {"expiry": "expires_at", "created": "created_at", "identity": "id"}.get(
+            field, field
+        )
+        data["shares"][0][field] = "invalid" if field in {"created_at", "id"} else 123
+    elif fault == "operation_kind":
+        data["operations"][0]["node_id"] = folder
+    elif fault == "operation_identity":
+        data["operations"][0]["operation_id"] = "different-operation"
+    elif fault == "deletion_state":
+        data["deletions"][0]["state"] = "invalid"
+    elif fault == "deletion_messages":
+        data["deletions"][0]["pending_message_ids"] = [999]
+    elif fault == "deletion_path":
+        data["deletions"][0]["path"] = "/" + folder
+    elif fault == "preparation_fingerprint":
+        data["preparations"][0]["fingerprint"] = "0" * 64
+    elif fault == "preparation_mapping":
+        data["preparations"][0]["result"]["folders"]["Child"] = "/" + folder
+    else:
+        data["nodes"][0][fault] = "incorrect"
+    backend = Backend()
+    with pytest.raises(CorruptStoreError):
+        archive.restore_decoded_snapshot(backend, data)
+    backend.ping.assert_not_called()
+    backend.fence.assert_not_called()
+    assert all(not collection.rows for collection in backend.db.values())
+
+
+def test_pristine_guard_refuses_saved_work_and_settings_changes():
+    backend = Backend()
+    pristine(backend)
+    archive.check_restore_destination(backend, allow_pristine=True)
+    backend.db.jobs.rows = [{"_id": "unfinished-job"}]
+    with pytest.raises(FileExistsError):
+        archive.check_restore_destination(backend, allow_pristine=True)
+    backend.db.jobs.rows.clear()
+    backend.db.settings.rows[1]["revision"] = 2
+    with pytest.raises(FileExistsError):
+        archive.check_restore_destination(backend, allow_pristine=True)
+
+
+def test_import_rolls_back_placeholder_and_revokes_archived_sessions(monkeypatch):
+    backend = Backend()
+    pristine(backend)
+    before = copy.deepcopy(backend.db.catalog.rows)
+    backend.db.nodes.fail_insert = True
+    with pytest.raises(RuntimeError, match="Synthetic transaction"):
+        archive.restore_decoded_snapshot(backend, recovered_data(), allow_pristine=True)
+    assert backend.db.catalog.rows == before
+    backend.db.nodes.fail_insert = False
+    monkeypatch.setattr(archive.MongoStore, "_indexes", Mock())
+    archive.restore_decoded_snapshot(backend, recovered_data(), allow_pristine=True)
+    assert backend.db.catalog.rows[0]["drive_id"] == "recovered-drive"
+    assert backend.db.sessions.rows == []
+    assert backend._settings_cached is False
+
+
+@pytest.mark.parametrize("fault", ["missing_parent", "share_expiry", "name_key"])
+def test_authenticated_archive_with_invalid_catalog_is_rejected_before_database_work(
+    tmp_path, fault
+):
+    data, _folder = current_archive_records()
+    if fault == "missing_parent":
+        data["nodes"][0]["parent_id"] = "missing-parent"
+    elif fault == "share_expiry":
+        data["shares"][0]["expires_at"] = 123
+    else:
+        data["nodes"][0]["name_key"] = "incorrect"
+    records = [{"format": "tgdrive-mongodb", "version": 1}]
+    records.extend(
+        {"collection": name, "document": row}
+        for name, rows in data.items()
+        for row in rows
+    )
+    records.append(
+        {"complete": True, "counts": {name: len(rows) for name, rows in data.items()}}
+    )
+    content = "\n".join(json_util.dumps(row) for row in records).encode()
+    key, nonce = b"k" * 32, b"n" * 12
+    encrypted = AESGCM(key).encrypt(nonce, zlib.compress(content), archive.MAGIC)
+    path = tmp_path / "invalid.tgdb"
+    path.write_bytes(archive.MAGIC + nonce + encrypted)
+    with pytest.raises(BackupError, match="authentication or validation"):
+        archive.decode_snapshot(path, key)
+
+
+@pytest.fixture
+def owner_api(tmp_path, monkeypatch):
+    backend = Backend()
+    pristine(backend)
+    runtime = SimpleNamespace(
+        mongo=backend,
+        stop=AsyncMock(return_value=[]),
+        replica=SimpleNamespace(blocked=False, status=lambda: {"configured": False}),
+    )
+    app = FastAPI()
+    app.state.sessions = SessionManager(b"s" * 32, 3600, mongo_backend=backend)
+
+    async def require_admin(request: Request):
+        try:
+            app.state.sessions.verify(request.cookies.get(SESSION_COOKIE, ""))
+        except InvalidSession:
+            raise HTTPException(401, "Not authenticated") from None
+
+    api.register_restore_routes(
+        app,
+        SimpleNamespace(
+            demo_mode=False,
+            resolved_cache_dir=tmp_path / "cache",
+            resolved_data_dir=tmp_path / "data",
+        ),
+        require_admin=require_admin,
+        get_runtime=lambda _request: runtime,
+    )
+    app.add_middleware(ApiBodyGuardMiddleware, sessions=app.state.sessions)
+    monkeypatch.setattr(api, "decode_snapshot", Mock(return_value=recovered_data()))
+    monkeypatch.setattr(archive.MongoStore, "_indexes", Mock())
+    with TestClient(app) as client:
+        yield client, app, runtime, backend
+
+
+def sign_in(client, app):
+    token = app.state.sessions.create()
+    client.cookies.set(SESSION_COOKIE, token)
+    return token
+
+
+def headers():
+    return {
+        "Content-Type": "application/octet-stream",
+        "X-TGDrive-Recovery-Key": "a" * 64,
+        "X-TGDrive-Confirm": "RESTORE",
+    }
+
+
+def test_restore_authenticates_before_reading_oversized_body(owner_api):
+    client, _app, runtime, _backend = owner_api
+    response = client.post(
+        api.RESTORE_PATH,
+        content=b"unused",
+        headers=headers() | {"Content-Length": str(archive.MAX_EXPANDED + 1)},
+    )
+    assert response.status_code == 401
+    runtime.stop.assert_not_awaited()
+
+
+def test_restore_rejects_oversized_archive_before_stopping_runtime(owner_api):
+    client, app, runtime, _backend = owner_api
+    sign_in(client, app)
+    response = client.post(
+        api.RESTORE_PATH,
+        content=b"unused",
+        headers=headers() | {"Content-Length": str(archive.MAX_EXPANDED + 1)},
+    )
+    assert response.status_code == 413
+    runtime.stop.assert_not_awaited()
+
+
+def test_invalid_archive_preserves_running_drive(owner_api, monkeypatch):
+    client, app, runtime, backend = owner_api
+    sign_in(client, app)
+    monkeypatch.setattr(
+        api, "decode_snapshot", Mock(side_effect=BackupError("Wrong key"))
+    )
+    response = client.post(api.RESTORE_PATH, content=b"encrypted", headers=headers())
+    assert response.status_code == 422
+    assert response.json()["code"] == "ARCHIVE_INVALID"
+    runtime.stop.assert_not_awaited()
+    assert backend.db.catalog.rows[0]["drive_id"] == "new-drive"
+
+
+def test_owner_restore_imports_archive_and_requires_restart(owner_api):
+    client, app, runtime, backend = owner_api
+    token = sign_in(client, app)
+    response = client.post(api.RESTORE_PATH, content=b"encrypted", headers=headers())
+    assert response.status_code == 200
+    assert response.json()["restart_required"] is True
+    assert runtime.recovery_only is True
+    runtime.stop.assert_awaited_once()
+    assert backend.db.catalog.rows[0]["drive_id"] == "recovered-drive"
+    assert backend.db.sessions.rows == []
+    with pytest.raises(InvalidSession):
+        app.state.sessions.verify(token)
+
+
+def test_failed_commit_reports_uncertain_result_and_restart(owner_api):
+    client, app, _runtime, backend = owner_api
+    sign_in(client, app)
+    backend.db.nodes.fail_insert = True
+    response = client.post(api.RESTORE_PATH, content=b"encrypted", headers=headers())
+    assert response.status_code == 503
+    assert response.json()["code"] == "DATABASE_RESTORE_UNCONFIRMED"
+    assert response.json()["restart_required"] is True
+    assert backend.db.catalog.rows[0]["drive_id"] == "new-drive"
+    backend.release.assert_called_once()
+
+
+def test_failed_shutdown_never_starts_database_import(owner_api):
+    client, app, runtime, backend = owner_api
+    sign_in(client, app)
+    runtime.stop.return_value = [RuntimeError("Synthetic worker drain failure")]
+    response = client.post(api.RESTORE_PATH, content=b"encrypted", headers=headers())
+    assert response.status_code == 503
+    assert response.json()["restart_required"] is True
+    backend.acquire.assert_not_called()
+    assert backend.db.catalog.rows[0]["drive_id"] == "new-drive"
+
+
+async def test_repeated_disconnect_cancellation_drains_file_or_database_worker():
+    entered, release = Event(), Event()
+
+    def write():
+        entered.set()
+        assert release.wait(3)
+
+    operation = asyncio.create_task(api._finish(write))
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        operation.cancel()
+        await asyncio.sleep(0)
+        operation.cancel()
+        await asyncio.sleep(0)
+        assert not operation.done()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await operation
+    finally:
+        release.set()
diff --git a/tests/recovery/test_runtime_backup_barrier.py b/tests/recovery/test_runtime_backup_barrier.py
new file mode 100644
index 00000000..14f1f44c
--- /dev/null
+++ b/tests/recovery/test_runtime_backup_barrier.py
@@ -0,0 +1,128 @@
+"""Production lifecycle wiring for mandatory completed-upload protection."""
+
+from pathlib import Path
+from unittest.mock import AsyncMock, Mock
+
+import tgdrive.core.runtime as runtime_module
+from tests.core.test_runtime import mongo_backend as mongo_backend_fixture
+from tgdrive.core.config import Settings
+from tgdrive.core.errors import CorruptStoreError
+from tgdrive.core.runtime import Runtime
+from tgdrive.storage.store import DriveStore
+
+mongo_backend = mongo_backend_fixture
+
+
+def configuration(tmp_path: Path, **overrides) -> Settings:
+    values = {
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "API_ID": 12345,
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30,
+        "STORAGE_CHANNEL": -1001234567890,
+        "ADMIN_PASSWORD": "correct horse battery staple",
+        "SESSION_SECRET": "s" * 48,
+        "DATA_DIR": tmp_path / "data",
+        "CACHE_DIR": tmp_path / "cache",
+        "COOKIE_SECURE": False,
+    }
+    values.update(overrides)
+    return Settings(_env_file=None, **values)
+
+
+class RuntimePool:
+    def __init__(self, *, unavailable=False):
+        self.unavailable = unavailable
+        self.stopped = False
+
+    async def set_uploads_per_bot(self, value):
+        self.uploads_per_bot = value
+
+    async def start(self):
+        if self.unavailable:
+            raise RuntimeError("synthetic Telegram outage")
+
+    async def stop(self, *, drain_timeout=None):
+        self.stopped = True
+        return ()
+
+
+async def test_runtime_upload_barrier_always_calls_its_store_backup(
+    tmp_path, monkeypatch
+):
+    settings = configuration(tmp_path)
+    settings.resolved_data_dir.mkdir(parents=True)
+    store = DriveStore.create()
+    store.mark_backed_up(store.revision)
+    runtime = Runtime(settings, pool=RuntimePool())
+    runtime.backup.restore = AsyncMock(return_value=store)
+    runtime.backup.ensure_revision = AsyncMock(
+        side_effect=lambda _store, required_revision: required_revision
+    )
+    runtime.backup.start = Mock()
+    runtime.backup.stop = AsyncMock()
+    monkeypatch.setattr(runtime_module, "build_bot_mode_client", lambda _: None)
+    try:
+        await runtime.start()
+        assert runtime.transfers is not None
+        assert runtime.transfers._ensure_backup is not None
+        protected = await runtime.transfers._ensure_backup(store.revision)
+        assert protected == store.revision
+        runtime.backup.ensure_revision.assert_awaited_once_with(store, store.revision)
+    finally:
+        await runtime.stop()
+
+
+async def test_missing_catalog_requires_explicit_recovery(tmp_path):
+    pool = RuntimePool()
+    runtime = Runtime(configuration(tmp_path), pool=pool)
+    runtime.backup.restore = AsyncMock(
+        side_effect=CorruptStoreError(
+            "Saved MongoDB catalog requires explicit recovery"
+        )
+    )
+
+    try:
+        await runtime.start()
+        assert runtime.recovery_only
+        assert not runtime.ready
+        assert runtime.store is None
+        assert runtime.transfers is None
+        assert runtime.bot_mode is None
+        assert not runtime._reconnector
+        assert runtime._owner_lock is not None
+        assert runtime.replica.status()["recovery_only"]
+        assert not runtime.settings.resolved_data_dir.joinpath("drive.sqlite3").exists()
+        assert not runtime.settings.resolved_data_dir.joinpath("jobs.sqlite3").exists()
+        # Recovery may inspect Telegram metadata without creating a replacement.
+        assert any(
+            "explicit recovery" in row["message"]
+            for row in runtime.replica.status()["report"]
+        )
+    finally:
+        await runtime.stop()
+    assert runtime._owner_lock is None
+    assert pool.stopped
+    assert not runtime.settings.resolved_data_dir.joinpath("drive.sqlite3").exists()
+
+
+async def test_existing_catalog_remains_available_during_telegram_outage(tmp_path):
+    settings = configuration(tmp_path)
+    settings.resolved_data_dir.mkdir(parents=True)
+    store = DriveStore.create()
+    store.create_folder("/", "Offline catalog")
+    pool = RuntimePool(unavailable=True)
+    runtime = Runtime(settings, pool=pool)
+    runtime.backup.restore = AsyncMock(return_value=store)
+    runtime.backup.start = Mock()
+    runtime.backup.stop = AsyncMock()
+    try:
+        await runtime.start()
+        assert runtime.ready
+        assert [
+            item["name"] for item in runtime.store.list_directory("/").values()
+        ] == ["Offline catalog"]
+        assert runtime.transfers._ensure_backup is not None
+    finally:
+        await runtime.stop()
+    assert pool.stopped
diff --git a/tests/recovery/test_upload_backup_barrier.py b/tests/recovery/test_upload_backup_barrier.py
new file mode 100644
index 00000000..eecbf6d5
--- /dev/null
+++ b/tests/recovery/test_upload_backup_barrier.py
@@ -0,0 +1,374 @@
+"""Uploads finish only after their catalog revision has a confirmed checkpoint."""
+
+import asyncio
+import hashlib
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.recovery.backup import BackupError
+from tgdrive.storage.mongo import for_directory
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.manager import BackupPending, TransferManager
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path)
+
+
+def registry_for(directory):
+    backend = for_directory(directory)
+    return TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+
+
+class MediaClient:
+    name = "barrier-test-bot"
+
+    def __init__(self):
+        self.is_connected = False
+        self.messages = {}
+        self.sent = []
+        self.deleted = []
+
+    async def start(self):
+        self.is_connected = True
+
+    async def stop(self):
+        self.is_connected = False
+
+    async def send_staged(
+        self,
+        channel,
+        path,
+        *,
+        random_id,
+        file_name,
+        progress,
+        offset=0,
+        size=None,
+        expected_sha256=None,
+        before_dispatch=None,
+    ):
+        end = offset + size if size is not None else None
+        content = path.read_bytes()[offset:end]
+        if expected_sha256 is not None:
+            assert hashlib.sha256(content).hexdigest() == expected_sha256
+        if before_dispatch is not None:
+            await before_dispatch()
+        self.sent.append(random_id)
+        message = SimpleNamespace(
+            id=101 + len(self.messages),
+            document=SimpleNamespace(file_size=len(content)),
+        )
+        self.messages[message.id] = message
+        return message
+
+    async def get_messages(self, channel, *, message_ids):
+        return self.messages.get(message_ids)
+
+    async def delete_messages(self, channel, message_ids):
+        self.deleted.append(message_ids)
+
+
+def manager_for(tmp_path, pool, callback, *, store=None, registry=None):
+    return TransferManager(
+        settings=SimpleNamespace(
+            resolved_cache_dir=tmp_path / "cache",
+            max_concurrent_transfers=1,
+            storage_channel=-100123,
+            bot_upload_limit=2_000_000_000,
+            upload_limit=4_000_000_000,
+        ),
+        pool=pool,
+        store=store or DriveStore.create(tmp_path / "drive.sqlite3"),
+        registry=registry or registry_for(tmp_path),
+        remote=SimpleNamespace(close=AsyncMock()),
+        ensure_backup=callback,
+    )
+
+
+def staged_file(tmp_path, name="receipt.part"):
+    path = tmp_path / name
+    path.write_bytes(b"immutable bytes")
+    return path
+
+
+async def test_checkpoint_wait_releases_upload_slot_and_protects_committed_media(
+    tmp_path,
+):
+    client = MediaClient()
+    pool = ClientPool([client])
+    await pool.start()
+    entered = asyncio.Event()
+    release = asyncio.Event()
+    revisions = []
+    both_entered = asyncio.Event()
+
+    async def protect(required):
+        revisions.append(required)
+        if len(revisions) == 2:
+            both_entered.set()
+        entered.set()
+        await release.wait()
+        return required
+
+    manager = manager_for(tmp_path, pool, protect)
+    first = staged_file(tmp_path, "first.part")
+    second = staged_file(tmp_path, "second.part")
+    one = await manager.enqueue_upload(first, "/", "one.bin", first.stat().st_size)
+    try:
+        await asyncio.wait_for(entered.wait(), 2)
+        assert one.phase == "backup_pending"
+        assert one.status == TransferStatus.RUNNING
+        assert one.context["metadata_committed"]
+        assert one.context["catalog_revision"] == manager.store.revision
+        assert first.exists()
+        assert (await pool.health()).active_leases == 0
+        with pytest.raises(BackupPending) as exc:
+            await manager.cancel_job(one.id)
+        assert exc.value.code == "BACKUP_PENDING"
+        assert not one.cancel_event.is_set()
+
+        two = await manager.enqueue_upload(
+            second, "/", "two.bin", second.stat().st_size
+        )
+        await asyncio.wait_for(both_entered.wait(), 2)
+        assert len(client.sent) == 2
+        assert two.phase == "backup_pending"
+        assert first.exists() and second.exists()
+        assert client.deleted == []
+        release.set()
+        await asyncio.gather(one.task, two.task)
+        assert one.status == two.status == TransferStatus.COMPLETED
+        assert not first.exists() and not second.exists()
+        assert one.context["protected_revision"] >= one.context["catalog_revision"]
+    finally:
+        release.set()
+        await manager.registry.shutdown()
+        manager.registry.close()
+        manager.store.close()
+        await pool.stop()
+
+
+async def test_backup_error_restarts_without_staged_bytes_or_second_media_send(
+    tmp_path,
+):
+    client = MediaClient()
+    pool = ClientPool([client])
+    await pool.start()
+    failed = AsyncMock(side_effect=BackupError("checkpoint unavailable"))
+    manager = manager_for(tmp_path, pool, failed)
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    await record.task
+    assert record.status == TransferStatus.ERROR
+    assert record.phase == "backup_pending"
+    assert source.exists()
+    assert len(client.sent) == 1
+    required = record.context["catalog_revision"]
+    manager.registry.close()
+    manager.store.close()
+    source.unlink()
+
+    callback = AsyncMock(return_value=required)
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        callback,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path),
+    )
+    try:
+        with pytest.raises(BackupPending):
+            await recovered.cancel_job(record.id)
+        retry = await recovered.retry_job(record.id)
+        await retry.task
+        assert retry.status == TransferStatus.COMPLETED
+        callback.assert_awaited_once_with(required)
+        assert len(client.sent) == 1
+        assert client.deleted == []
+        assert len(recovered.store.list_directory("/")) == 1
+    finally:
+        await recovered.registry.shutdown()
+        recovered.registry.close()
+        recovered.store.close()
+        await pool.stop()
+
+
+async def test_store_commit_journal_gap_is_detected_before_cancel_or_resend(
+    tmp_path, monkeypatch
+):
+    client = MediaClient()
+    pool = ClientPool([client])
+    await pool.start()
+    callback = AsyncMock(side_effect=BackupError("not reached before crash"))
+    manager = manager_for(tmp_path, pool, callback)
+    source = staged_file(tmp_path)
+    original = manager.store.add_file
+
+    def commit_then_crash(*args, **kwargs):
+        original(*args, **kwargs)
+        raise RuntimeError("process lost response after catalog commit")
+
+    monkeypatch.setattr(manager.store, "add_file", commit_then_crash)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    await record.task
+    assert record.status == TransferStatus.ERROR
+    assert not record.context.get("metadata_committed")
+    assert manager.store.has_file_operation(record.id)
+    with pytest.raises(BackupPending):
+        await manager.cancel_job(record.id)
+    callback.assert_not_awaited()
+    required = manager.store.revision
+    manager.registry.close()
+    manager.store.close()
+
+    confirmed = AsyncMock(return_value=required)
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        confirmed,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path),
+    )
+    try:
+        retry = await recovered.retry_job(record.id)
+        await retry.task
+        assert retry.status == TransferStatus.COMPLETED
+        confirmed.assert_awaited_once_with(required)
+        assert len(client.sent) == 1
+        assert client.deleted == []
+        assert not source.exists()
+    finally:
+        await recovered.registry.shutdown()
+        recovered.registry.close()
+        recovered.store.close()
+        await pool.stop()
+
+
+async def test_checkpoint_flood_wait_retries_only_backup_and_persists_deadline(
+    tmp_path,
+):
+    client = MediaClient()
+    pool = ClientPool([client])
+    await pool.start()
+    entered = asyncio.Event()
+    release = asyncio.Event()
+    count = 0
+
+    async def protect(required):
+        nonlocal count
+        count += 1
+        if count == 1:
+            raise BackupError("checkpoint rate limited", retry_after=0.01)
+        entered.set()
+        await release.wait()
+        return required
+
+    manager = manager_for(tmp_path, pool, protect)
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    try:
+        await asyncio.wait_for(entered.wait(), 2)
+        assert record.phase == "backup_pending"
+        assert record.context["backup_retry_at"] > 0
+        journal = registry_for(tmp_path)
+        assert journal.get(record.id).context["backup_retry_at"] > 0
+        journal.close()
+        assert len(client.sent) == 1
+        release.set()
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        assert "backup_retry_at" not in record.context
+        assert len(client.sent) == 1
+    finally:
+        release.set()
+        await manager.registry.shutdown()
+        manager.registry.close()
+        manager.store.close()
+        await pool.stop()
+
+
+@pytest.mark.parametrize("protected", [0, True, None])
+async def test_insufficient_checkpoint_keeps_staging_and_retryable_phase(
+    tmp_path, protected
+):
+    client = MediaClient()
+    pool = ClientPool([client])
+    await pool.start()
+    manager = manager_for(tmp_path, pool, AsyncMock(return_value=protected))
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    try:
+        await record.task
+        assert record.status == TransferStatus.ERROR
+        assert record.phase == "backup_pending"
+        assert record.context["metadata_committed"]
+        assert source.exists()
+        assert len(client.sent) == 1
+        assert client.deleted == []
+        retried = await manager.retry_job(record.id)
+        await retried.task
+        assert retried.status == TransferStatus.ERROR
+        assert retried.phase == "backup_pending"
+        assert source.exists()
+        assert len(client.sent) == 1
+        assert client.deleted == []
+    finally:
+        await manager.registry.shutdown()
+        manager.registry.close()
+        manager.store.close()
+        await pool.stop()
+
+
+async def test_shutdown_during_checkpoint_recovers_protection_without_media_resend(
+    tmp_path,
+):
+    client = MediaClient()
+    pool = ClientPool([client])
+    await pool.start()
+    entered = asyncio.Event()
+
+    async def interrupted_checkpoint(required):
+        entered.set()
+        await asyncio.Event().wait()
+
+    manager = manager_for(tmp_path, pool, interrupted_checkpoint)
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    await asyncio.wait_for(entered.wait(), 2)
+    required = record.context["catalog_revision"]
+    await manager.registry.shutdown()
+    assert record.status == TransferStatus.QUEUED
+    assert record.context["metadata_committed"]
+    assert source.exists()
+    manager.registry.close()
+    manager.store.close()
+
+    confirmed = AsyncMock(return_value=required)
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        confirmed,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path),
+    )
+    try:
+        await recovered.recover()
+        resumed = recovered.registry.get(record.id)
+        await resumed.task
+        assert resumed.status == TransferStatus.COMPLETED
+        confirmed.assert_awaited_once_with(required)
+        assert len(client.sent) == 1
+        assert client.deleted == []
+        assert not source.exists()
+    finally:
+        await recovered.registry.shutdown()
+        recovered.registry.close()
+        recovered.store.close()
+        await pool.stop()
diff --git a/tests/replication/__init__.py b/tests/replication/__init__.py
new file mode 100644
index 00000000..40efb767
--- /dev/null
+++ b/tests/replication/__init__.py
@@ -0,0 +1 @@
+"""TGDrive replication tests."""
diff --git a/tests/replication/test_replica.py b/tests/replication/test_replica.py
new file mode 100644
index 00000000..a3ee6469
--- /dev/null
+++ b/tests/replication/test_replica.py
@@ -0,0 +1,1557 @@
+"""Coordinator fault injection against isolated synthetic Telegram channels."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from pydantic import SecretStr
+
+from tests.support.mongo_fixtures import register_test_backend
+from tests.support.recovery_fixtures import settings
+from tgdrive.replication.replica import ChannelReplica
+from tgdrive.replication.replica_state import decode_bundle, files_in, parts_in
+from tgdrive.replication.replica_transport import ReplicaTransportError
+from tgdrive.storage.mongo import for_directory
+from tgdrive.storage.store import DriveStore
+
+BACKUP = -1002234567890
+REPLACEMENT = -1003234567890
+TOKEN = "234567:" + "b" * 24
+
+pytestmark = pytest.mark.usefixtures("replica_backend")
+
+
+@pytest.fixture
+def replica_backend(tmp_path, monkeypatch):
+    backend = register_test_backend(monkeypatch, settings(tmp_path))
+    # Coordinator tests isolate archive transport, covered in test_replica_mongo.
+    monkeypatch.setattr(
+        "tgdrive.replication.replica_mongo.mirror_mongodb", AsyncMock(return_value=None)
+    )
+    return backend
+
+
+class Telegram:
+    """Independent message names, with provider-side operation-ID deduplication."""
+
+    def __init__(self):
+        self.messages = {}
+        self.pins = {}
+        self.receipts = {}
+        self.calls = []
+        self.instances = []
+        self.next_id = 1001
+        self.lose_response = False
+        self.copy_error = None
+        self.publish_error_channel = None
+        self.lose_publish_response_channel = None
+        self.after_copy = None
+        self.unavailable = set()
+
+    def factory(self, configured, token):
+        result = Transport(self, configured, token)
+        self.instances.append(result)
+        return result
+
+    def new_message(self, channel, body):
+        identity = self.next_id
+        self.next_id += 1
+        self.messages[channel, identity] = body
+        return identity
+
+
+class Transport:
+    def __init__(self, remote, configured, token):
+        self.remote, self.settings, self.token = remote, configured, token
+        self.closed = False
+
+    async def start(self):
+        # Exercise the same Settings property used by real transport startup.
+        assert self.token.split(":")[0] not in {
+            token.split(":")[0] for token in self.settings.bot_tokens
+        }
+
+    async def close(self):
+        self.closed = True
+
+    async def inspect(self, channel, *, writable=True):
+        if channel in self.remote.unavailable:
+            raise ReplicaTransportError("Channel access was lost.", "REPLICA_ACCESS")
+        return {"id": channel, "title": "Dedicated private channel", "private": True}
+
+    async def copy(self, source, message, destination, *, random_id, expected_size):
+        self.remote.calls.append(("copy", source, message, destination, random_id))
+        if self.remote.copy_error:
+            raise self.remote.copy_error
+        await self.inspect(source)
+        await self.inspect(destination)
+        content = self.remote.messages.get((source, message))
+        if content is None:
+            raise ReplicaTransportError(
+                "Source part is missing.", "REPLICA_MESSAGE_MISSING"
+            )
+        assert len(content) == expected_size
+        identity = (self.token.split(":")[0], destination, random_id)
+        if identity not in self.remote.receipts:
+            self.remote.receipts[identity] = self.remote.new_message(
+                destination, content
+            )
+        result = self.remote.receipts[identity]
+        if self.remote.after_copy:
+            hook, self.remote.after_copy = self.remote.after_copy, None
+            value = hook()
+            if inspect.isawaitable(value):
+                await value
+        if self.remote.lose_response:
+            self.remote.lose_response = False
+            raise ReplicaTransportError(
+                "Response lost.", "REPLICA_UNAVAILABLE", retryable=True
+            )
+        return result
+
+    async def publish(self, channel, path, *, random_id, caption, pin):
+        self.remote.calls.append(("publish", channel, random_id))
+        if channel == self.remote.publish_error_channel:
+            raise ReplicaTransportError("Primary unavailable.", "REPLICA_ACCESS")
+        await self.inspect(channel)
+        identity = (self.token.split(":")[0], channel, random_id)
+        if identity not in self.remote.receipts:
+            self.remote.receipts[identity] = self.remote.new_message(
+                channel, path.read_bytes()
+            )
+        result = self.remote.receipts[identity]
+        if pin:
+            self.remote.pins[channel] = result
+        if self.remote.lose_publish_response_channel == channel:
+            self.remote.lose_publish_response_channel = None
+            raise ReplicaTransportError(
+                "Publication response lost.", "REPLICA_UNAVAILABLE", retryable=True
+            )
+        return result
+
+    async def pinned_message(self, channel):
+        await self.inspect(channel, writable=False)
+        return self.remote.pins.get(channel)
+
+    async def verify(self, channel, message_id, expected_size):
+        await self.inspect(channel)
+        self.remote.calls.append(("verify", channel, message_id))
+        content = self.remote.messages.get((channel, message_id))
+        if content is None or len(content) != expected_size:
+            raise ReplicaTransportError(
+                "Remote verification failed.", "REPLICA_VERIFY_FAILED"
+            )
+
+    async def publish_catalog(self, channel, path, *, random_id, caption, pin=True):
+        assert caption.startswith("TGDrive checkpoint v1\nDrive: ")
+        return await self.publish(
+            channel, path, random_id=random_id, caption=caption, pin=pin
+        )
+
+    async def download(self, channel, message_id, destination):
+        identity = message_id or self.remote.pins[channel]
+        content = self.remote.messages[channel, identity]
+        if content.startswith(b"{"):
+            raise ReplicaTransportError("Different filename.", "REPLICA_DOCUMENT_TYPE")
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(content)
+        destination.chmod(0o600)
+        return identity
+
+    async def download_catalog(self, channel, destination, message_id=None):
+        identity = message_id or self.remote.pins[channel]
+        content = self.remote.messages[channel, identity]
+        if not content.startswith(b"{"):
+            raise ReplicaTransportError("Different filename.", "REPLICA_DOCUMENT_TYPE")
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(content)
+        destination.chmod(0o600)
+        return identity
+
+
+def setup(tmp_path, *, multipart=False, empty=False):
+    configured = settings(tmp_path)
+    configured.resolved_data_dir.mkdir(parents=True, exist_ok=True)
+    store = DriveStore.create(configured.resolved_data_dir / "catalog.sqlite3")
+    store.bind_storage_channel(configured.storage_channel)
+    remote = Telegram()
+    if not empty:
+        folder = store.create_folder("/", "Important")
+        folder_path = "/" + folder["id"]
+        store.set_starred(folder_path, True)
+        if multipart:
+            parts = [
+                {
+                    "index": 0,
+                    "offset": 0,
+                    "size": 3,
+                    "message_id": 77,
+                    "sha256": "a" * 64,
+                    "document_id": 7001,
+                },
+                {
+                    "index": 1,
+                    "offset": 3,
+                    "size": 4,
+                    "message_id": 78,
+                    "sha256": "b" * 64,
+                    "document_id": 7002,
+                },
+            ]
+            node = store.add_file(
+                folder_path,
+                "split.bin",
+                77,
+                7,
+                parts=parts,
+                sha256="c" * 64,
+                operation_id="old-upload",
+            )
+            remote.messages[configured.storage_channel, 77] = b"abc"
+            remote.messages[configured.storage_channel, 78] = b"defg"
+        else:
+            node = store.add_file(folder_path, "record.bin", 77, 3)
+            remote.messages[configured.storage_channel, 77] = b"abc"
+        path = folder_path + "/" + node["id"]
+        store.set_starred(path, True)
+        store.create_share(path, label="Research team")
+    runtime = SimpleNamespace(
+        store=store, mongo=for_directory(configured.resolved_data_dir)
+    )
+    replica = ChannelReplica(configured, runtime, transport_factory=remote.factory)
+    config = {"channel": BACKUP, "token": TOKEN, "enabled": True}
+    replica.journal.set("config", config)
+    return configured, store, remote, replica, config
+
+
+async def dispose(replica, store):
+    await replica.close()
+    store.close()
+
+
+def remote_bundle(remote, replica, channel=BACKUP):
+    return decode_bundle(remote.messages[channel, remote.pins[channel]], replica.key())
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "empty,multipart", [(True, False), (False, False), (False, True)]
+)
+async def test_existing_or_empty_catalog_gets_independent_complete_recovery_bundle(
+    tmp_path, empty, multipart
+):
+    configured, store, remote, replica, config = setup(
+        tmp_path, empty=empty, multipart=multipart
+    )
+    before = store.export()
+    try:
+        await replica._sync(config)
+        assert replica.status()["protected_revision"] == store.revision
+        bundle = remote_bundle(remote, replica)
+        assert bundle["catalog"] == before
+        restored = bundle["replica_catalog"]
+        assert restored["storage_channel_id"] == BACKUP
+        assert restored["drive_id"] == store.drive_id
+        assert restored["shares"] == before["shares"]
+        assert restored["operations"] == restored["deletions"] == []
+        old_files, new_files = list(files_in(before)), list(files_in(restored))
+        assert len(old_files) == len(new_files)
+        for old, new in zip(old_files, new_files, strict=True):
+            assert old["id"] == new["id"] and old["starred"] == new["starred"]
+            for original, copied in zip(parts_in(old), parts_in(new), strict=True):
+                assert original["message_id"] != copied["message_id"]
+                assert (
+                    remote.messages[configured.storage_channel, original["message_id"]]
+                    == remote.messages[BACKUP, copied["message_id"]]
+                )
+        assert store.export() == before, (
+            "Replication cannot mutate live source metadata"
+        )
+        assert all(instance.closed for instance in remote.instances)
+        assert configured.storage_channel not in remote.pins, (
+            "Primary catalog pin must be preserved"
+        )
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_response_loss_preserves_intent_and_reuses_operation_after_restart(
+    tmp_path,
+):
+    configured, store, remote, replica, config = setup(tmp_path)
+    try:
+        remote.lose_response = True
+        with pytest.raises(ReplicaTransportError):
+            await replica._sync(config)
+        original = next(call for call in remote.calls if call[0] == "copy")
+        assert replica.journal.get("job")
+        assert not remote.pins
+        await replica.close()
+        replica = ChannelReplica(
+            configured,
+            SimpleNamespace(
+                store=store, mongo=for_directory(configured.resolved_data_dir)
+            ),
+            transport_factory=remote.factory,
+        )
+        await replica._sync(config)
+        attempts = [call for call in remote.calls if call[0] == "copy"]
+        assert attempts == [original, original]
+        assert (
+            len([key for key in remote.messages if key[0] == BACKUP]) == 2
+        )  # payload + capsule
+        assert replica.status()["protected_revision"] == store.revision
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_pause_mid_copy_resumes_confirmed_parts_without_resending(tmp_path):
+    configured, store, remote, replica, config = setup(tmp_path, multipart=True)
+    try:
+        remote.after_copy = lambda: replica.update(phase="paused")
+        await replica._sync(config)
+        assert replica.status()["phase"] == "paused"
+        assert replica.status()["done_parts"] == 1 and not remote.pins
+        await replica.close()
+        replica = ChannelReplica(
+            configured,
+            SimpleNamespace(
+                store=store, mongo=for_directory(configured.resolved_data_dir)
+            ),
+            transport_factory=remote.factory,
+        )
+        assert replica.status()["phase"] == "paused"
+        replica.update(phase="idle")  # Explicitly resume the saved paused job.
+        await replica._sync(config)
+        assert [call[2] for call in remote.calls if call[0] == "copy"] == [77, 78]
+        assert replica.status()["done_parts"] == 2
+        assert remote_bundle(remote, replica)["complete"]
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_missing_source_part_does_not_advertise_restore_point(tmp_path):
+    _, store, remote, replica, config = setup(tmp_path, multipart=True)
+    try:
+        remote.messages.pop((replica.settings.storage_channel, 78))
+        with pytest.raises(ReplicaTransportError):
+            await replica._sync(config)
+        assert replica.status()["protected_revision"] == 0
+        assert replica.journal.get("restore_point") is None
+        assert not remote.pins
+        assert replica.journal.get("job")
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("missing_confirmed_part", [False, True])
+async def test_retry_batches_confirmed_parts_before_copying_remaining_files(
+    tmp_path, monkeypatch, missing_confirmed_part
+):
+    _, store, remote, replica, config = setup(tmp_path, empty=True)
+    for index in range(35):
+        identity = 77 + index
+        store.add_file("/", f"file-{index}.bin", identity, 1)
+        remote.messages[replica.settings.storage_channel, identity] = b"x"
+
+    async def stop_after_29():
+        if len(remote.receipts) == 29:
+            remote.copy_error = ReplicaTransportError(
+                "Wait for Telegram.",
+                "REPLICA_FLOOD_WAIT",
+                retry_after=20,
+                retryable=True,
+            )
+        else:
+            remote.after_copy = stop_after_29
+
+    remote.after_copy = stop_after_29
+    verify_one = Transport.verify
+
+    async def verify_many(self, channel, documents):
+        self.remote.calls.append(("verify_batch", channel, list(documents)))
+        for message, size in documents:
+            await verify_one(self, channel, message, size)
+
+    async def unexpected_single_verification(self, *_args):
+        raise AssertionError("The retry must use bounded batch verification")
+
+    monkeypatch.setattr(Transport, "verify_many", verify_many, raising=False)
+    monkeypatch.setattr(Transport, "verify", unexpected_single_verification)
+    try:
+        with pytest.raises(ReplicaTransportError):
+            await replica._sync(config)
+        assert replica.status()["done_parts"] == 29
+        assert not remote.pins
+        if missing_confirmed_part:
+            message = next(iter(remote.receipts.values()))
+            remote.messages.pop((BACKUP, message))
+        remote.copy_error = None
+        remote.calls.clear()
+        if missing_confirmed_part:
+            with pytest.raises(ReplicaTransportError):
+                await replica._sync(config)
+            assert not remote.pins
+            assert not [call for call in remote.calls if call[0] == "copy"]
+        else:
+            await replica._sync(config)
+            copies = [call for call in remote.calls if call[0] == "copy"]
+            assert len(copies) == 6
+            assert replica.status()["phase"] == "protected"
+            assert replica.status()["done_files"] == 35
+        batches = [call for call in remote.calls if call[0] == "verify_batch"]
+        assert len(batches) == 1
+        assert len(batches[0][2]) == 29
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_reverification_splits_large_catalog_into_bounded_batches(
+    tmp_path, monkeypatch
+):
+    from tgdrive.replication.replica_transport import MAX_VERIFY_BATCH
+
+    _, store, remote, replica, config = setup(tmp_path, empty=True)
+    for index in range(MAX_VERIFY_BATCH + 3):
+        identity = 77 + index
+        store.add_file("/", f"file-{index}.bin", identity, 1)
+        remote.messages[replica.settings.storage_channel, identity] = b"x"
+    batches = []
+
+    async def verify_many(self, channel, documents):
+        batches.append(list(documents))
+        for message, size in documents:
+            await self.verify(channel, message, size)
+
+    monkeypatch.setattr(Transport, "verify_many", verify_many, raising=False)
+    try:
+        await replica._sync(config)
+        store.create_folder("/", "Next snapshot")
+        remote.calls.clear()
+        await replica._sync(config)
+        assert [len(batch) for batch in batches] == [MAX_VERIFY_BATCH, 3]
+        assert not [call for call in remote.calls if call[0] == "copy"]
+        assert replica.status()["phase"] == "protected"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_catalog_change_during_copy_reports_pending_revision_and_catches_up(
+    tmp_path,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        revision = store.revision
+        remote.after_copy = lambda: store.create_folder("/", "Created during backup")
+        await replica._sync(config)
+        assert replica.status()["protected_revision"] == revision
+        assert replica.status()["pending_revision"] == 1
+        first = remote_bundle(remote, replica)
+        assert first["catalog"]["revision"] == revision
+        await replica._sync(config)
+        assert replica.status()["protected_revision"] == store.revision
+        assert replica.status()["pending_revision"] == 0
+        assert len([call for call in remote.calls if call[0] == "copy"]) == 1
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_primary_lost_at_second_publish_retains_recoverable_backup_and_old_status(
+    tmp_path,
+):
+    configured, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        old = replica.journal.get("restore_point")
+        store.create_folder("/", "After previous restore point")
+        remote.publish_error_channel = configured.storage_channel
+        with pytest.raises(ReplicaTransportError):
+            await replica._sync(config)
+        assert replica.journal.get("restore_point") == old
+        assert replica.status()["protected_revision"] == old["revision"]
+        assert remote_bundle(remote, replica)["catalog"]["revision"] == store.revision
+        assert remote_bundle(remote, replica)["complete"]
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_replacement_target_uses_new_intent_and_retains_old_backup(tmp_path):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        old_pin = remote.pins[BACKUP]
+        config = dict(config, channel=REPLACEMENT)
+        replica.journal.set("config", config)
+        replica.journal.set("job", None)
+        replica.update(protected_revision=0)
+        await replica._sync(config)
+        assert remote.pins[BACKUP] == old_pin
+        assert REPLACEMENT in remote.pins
+        attempts = [call for call in remote.calls if call[0] == "copy"]
+        assert [call[3] for call in attempts] == [BACKUP, REPLACEMENT]
+        assert attempts[0][4] != attempts[1][4]
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_flood_wait_error_and_retry_deadline_survive_service_restart(tmp_path):
+    configured, store, remote, replica, _config = setup(tmp_path)
+    try:
+        remote.copy_error = ReplicaTransportError(
+            "Telegram requested a wait.",
+            "REPLICA_FLOOD_WAIT",
+            retry_after=120,
+            retryable=True,
+        )
+        remote.copy_error.operation = "messages.sendMedia"
+        replica.start()
+        for _ in range(100):
+            if replica.status().get("error"):
+                break
+            await asyncio.sleep(0.01)
+        result = replica.status()
+        assert result["phase"] == "waiting"
+        assert result["error"]["retry_at"] > 0
+        assert "messages.sendMedia" in result["error"]["detail"]
+        assert "Retry in 120 seconds" in result["report"][-1]["message"]
+        assert "channel permissions do not need changing" in result["error"]["action"]
+        deadline = result["error"]["retry_at"]
+        await replica.close()
+        replica = ChannelReplica(
+            configured,
+            SimpleNamespace(
+                store=store, mongo=for_directory(configured.resolved_data_dir)
+            ),
+            transport_factory=remote.factory,
+        )
+        assert replica.status()["error"]["retry_at"] == deadline
+        count = len(remote.calls)
+        replica.start()
+        await asyncio.sleep(0.05)
+        assert len(remote.calls) == count, "Restart must honor Telegram's wait"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_expired_health_check_detects_lost_channel_even_without_catalog_changes(
+    tmp_path,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        replica.update(checked_at=0)
+        remote.unavailable.add(BACKUP)
+        with pytest.raises(ReplicaTransportError):
+            await replica._sync(config)
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_unchanged_backup_stays_idle_between_hourly_health_checks(tmp_path):
+    from tgdrive.replication.replica import HEALTH_CHECK_INTERVAL_SECONDS
+
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        point = replica.journal.get("restore_point")
+        remote.calls.clear()
+        connections = len(remote.instances)
+        replica.update(checked_at=time.time() - HEALTH_CHECK_INTERVAL_SECONDS + 60)
+        await replica._sync(config)
+        await replica._sync(config)
+        assert len(remote.instances) == connections
+        assert remote.calls == []
+        assert replica.status()["phase"] == "protected"
+        assert replica.journal.get("job") is None
+        assert replica.journal.get("restore_point") == point
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_hourly_health_check_does_not_start_a_copy_job_or_republish(
+    tmp_path,
+    monkeypatch,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        point = replica.journal.get("restore_point")
+        success = replica.status()["last_success_at"]
+        remote.calls.clear()
+        phases = []
+        start = Transport.start
+
+        async def record_start(self):
+            phases.append(replica.status()["phase"])
+            assert replica.journal.get("job") is None
+            await start(self)
+
+        monkeypatch.setattr(Transport, "start", record_start)
+        replica.update(checked_at=0)
+        await replica._sync(config)
+        assert phases == ["protected"]
+        assert [call[0] for call in remote.calls] == ["verify"]
+        assert replica.journal.get("restore_point") == point
+        assert replica.status()["last_success_at"] == success
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_new_catalog_revision_is_not_delayed_until_the_next_health_check(
+    tmp_path,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        previous = replica.status()["protected_revision"]
+        connections = len(remote.instances)
+        store.create_folder("/", "New metadata")
+        await replica._sync(config)
+        assert len(remote.instances) == connections + 1
+        assert replica.status()["protected_revision"] > previous
+        assert replica.status()["protected_revision"] == store.revision
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_manual_sync_forces_health_check_but_resume_reuses_recent_confirmation(
+    tmp_path,
+    monkeypatch,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    monkeypatch.setattr(replica, "start", lambda: None)
+    try:
+        await replica._sync(config)
+        connections = len(remote.instances)
+        await replica.action("pause")
+        await replica.action("resume")
+        await replica._sync(config)
+        assert len(remote.instances) == connections
+        assert replica.status()["phase"] == "protected"
+        await replica.action("sync")
+        await replica._sync(config)
+        assert len(remote.instances) == connections + 1
+        assert replica.status()["phase"] == "protected"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_idle_health_wait_reports_context_and_retries_after_saved_deadline(
+    tmp_path,
+    monkeypatch,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    original_start = Transport.start
+
+    async def limited_start(self):
+        error = ReplicaTransportError(
+            "Telegram requested a pause. Backup will resume after the wait.",
+            "REPLICA_FLOOD_WAIT",
+            retry_after=120,
+            retryable=True,
+        )
+        error.operation = "sign_in"
+        raise error
+
+    try:
+        await replica._sync(config)
+        replica.update(checked_at=0)
+        monkeypatch.setattr(Transport, "start", limited_start)
+        replica.start()
+        for _ in range(100):
+            if replica.status().get("error"):
+                break
+            await asyncio.sleep(0.01)
+        failure = replica.status()["error"]
+        assert "Routine backup health check delayed" in failure["detail"]
+        assert "sign_in" in failure["detail"]
+        assert "Retry in 120 seconds" in failure["detail"]
+        assert replica.journal.get("job") is None
+        assert replica.journal.get("restore_point") is not None
+        replica._task.cancel()
+        await asyncio.gather(replica._task, return_exceptions=True)
+        monkeypatch.setattr(Transport, "start", original_start)
+        connections = len(remote.instances)
+        await replica.action("sync")
+        replica._task.cancel()
+        await asyncio.gather(replica._task, return_exceptions=True)
+        assert replica.status()["error"]["retry_at"] == failure["retry_at"]
+        assert len(remote.instances) == connections
+        replica.update(error=failure | {"retry_at": 0}, checked_at=time.time())
+        await replica._sync(config)
+        assert len(remote.instances) == connections + 1
+        assert replica.status()["phase"] == "protected"
+        assert replica.status()["error"] is None
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("action", ["retry", "resume"])
+async def test_expired_health_wait_is_checked_on_manual_retry(
+    tmp_path, monkeypatch, action
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    monkeypatch.setattr(replica, "start", lambda: None)
+    try:
+        await replica._sync(config)
+        connections = len(remote.instances)
+        replica.update(
+            phase="waiting",
+            checked_at=time.time(),
+            error={"code": "REPLICA_FLOOD_WAIT", "retry_at": time.time() - 1},
+        )
+        await replica.action(action)
+        await replica._sync(config)
+        assert len(remote.instances) == connections + 1
+        assert replica.status()["phase"] == "protected"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["access", "pin", "document"])
+async def test_deletion_barrier_rechecks_recent_checkpoint_before_mutation(
+    tmp_path, failure
+):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        point = replica.journal.get("restore_point")
+        if failure == "access":
+            remote.unavailable.add(BACKUP)
+        elif failure == "pin":
+            remote.pins[BACKUP] += 1
+        else:
+            remote.messages.pop((BACKUP, point["backup_message_id"]))
+        connections = len(remote.instances)
+        with pytest.raises((SettingsProblem, ReplicaTransportError)):
+            await replica.before_mutation()
+        assert len(remote.instances) == connections + 1
+        assert replica.journal.get("restore_point") == point
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_pause_during_health_check_stays_paused(tmp_path, monkeypatch):
+    _, store, _remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        replica.update(checked_at=0)
+        original_pin = Transport.pinned_message
+
+        async def pause_after_pin(self, channel):
+            result = await original_pin(self, channel)
+            replica.update(phase="paused")
+            return result
+
+        monkeypatch.setattr(Transport, "pinned_message", pause_after_pin)
+        await replica._sync(config)
+        assert replica.status()["phase"] == "paused"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("caller", ["worker", "mutation"])
+@pytest.mark.parametrize("action", ["pause", "disable"])
+@pytest.mark.parametrize("code", ["REPLICA_FLOOD_WAIT", "REPLICA_UNAVAILABLE"])
+async def test_stop_during_failed_request_preserves_control_and_saved_wait(
+    tmp_path,
+    monkeypatch,
+    caller,
+    action,
+    code,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    entered, release, recorded = asyncio.Event(), asyncio.Event(), asyncio.Event()
+    mutation = None
+    report = replica.report
+
+    async def failed_start(self):
+        entered.set()
+        await release.wait()
+        error = ReplicaTransportError(
+            "Provider requested a wait.",
+            code,
+            retry_after=120 if code == "REPLICA_FLOOD_WAIT" else None,
+            retryable=True,
+        )
+        error.operation = "sign_in"
+        raise error
+
+    def record_error(level, message):
+        report(level, message)
+        if level == "error":
+            recorded.set()
+
+    try:
+        await replica._sync(config)
+        replica.update(checked_at=0)
+        monkeypatch.setattr(Transport, "start", failed_start)
+        monkeypatch.setattr(replica, "report", record_error)
+        if caller == "worker":
+            replica.start()
+        else:
+            mutation = asyncio.create_task(replica.before_mutation())
+        await asyncio.wait_for(entered.wait(), 1)
+        await replica.action(action)
+        release.set()
+        if mutation is not None:
+            with pytest.raises(ReplicaTransportError):
+                await mutation
+        else:
+            await asyncio.wait_for(recorded.wait(), 1)
+        expected_phase = "paused" if action == "pause" else "disabled"
+        state = replica.status()
+        assert state["phase"] == expected_phase
+        assert state["error"]["retry_at"] > time.time()
+        assert state["enabled"] is (action == "pause")
+        deadline = state["error"]["retry_at"]
+        connections = len(remote.instances)
+        await replica.action("resume")
+        await asyncio.sleep(0)
+        assert replica.status()["phase"] == "waiting"
+        assert replica.status()["error"]["retry_at"] == deadline
+        assert len(remote.instances) == connections
+    finally:
+        release.set()
+        if mutation is not None and not mutation.done():
+            mutation.cancel()
+            await asyncio.gather(mutation, return_exceptions=True)
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("action", ["pause", "disable"])
+async def test_deletion_barrier_rechecks_control_after_waiting_for_operation_lock(
+    tmp_path,
+    action,
+):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    _, store, remote, replica, config = setup(tmp_path)
+    mutation = None
+    try:
+        await replica._sync(config)
+        connections = len(remote.instances)
+        async with replica._operation:
+            mutation = asyncio.create_task(replica.before_mutation())
+            await asyncio.sleep(0)
+            assert not mutation.done()
+            await replica.action(action)
+        if action == "pause":
+            with pytest.raises(SettingsProblem, match="Resume independent backup"):
+                await mutation
+        else:
+            await mutation  # Explicitly disabling protection permits the mutation.
+        assert len(remote.instances) == connections
+        assert replica.status()["phase"] == (
+            "paused" if action == "pause" else "disabled"
+        )
+    finally:
+        if mutation is not None and not mutation.done():
+            mutation.cancel()
+            await asyncio.gather(mutation, return_exceptions=True)
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_deletion_barrier_rechecks_pause_after_successful_remote_check(
+    tmp_path,
+    monkeypatch,
+):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    _, store, _remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        original_pin = Transport.pinned_message
+
+        async def pause_after_pin(self, channel):
+            result = await original_pin(self, channel)
+            await replica.action("pause")
+            return result
+
+        monkeypatch.setattr(Transport, "pinned_message", pause_after_pin)
+        with pytest.raises(SettingsProblem, match="Resume independent backup"):
+            await replica.before_mutation()
+        assert replica.status()["phase"] == "paused"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stage", ["credentials", "catalog"])
+async def test_pause_during_local_snapshot_does_not_restart_telegram_work(
+    tmp_path,
+    monkeypatch,
+    stage,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    entered, release = asyncio.Event(), asyncio.Event()
+    original_thread = asyncio.to_thread
+    selected = replica._credentials if stage == "credentials" else store.export
+
+    async def blocked_snapshot(function, *args, **kwargs):
+        if function == selected:
+            entered.set()
+            await release.wait()
+        return await original_thread(function, *args, **kwargs)
+
+    monkeypatch.setattr(
+        "tgdrive.replication.replica.asyncio.to_thread", blocked_snapshot
+    )
+    operation = asyncio.create_task(replica._sync(config))
+    try:
+        await asyncio.wait_for(entered.wait(), 1)
+        await replica.action("pause")
+        release.set()
+        await operation
+        assert replica.status()["phase"] == "paused"
+        assert replica.journal.get("job") is None
+        assert not remote.instances
+    finally:
+        release.set()
+        if not operation.done():
+            operation.cancel()
+            await asyncio.gather(operation, return_exceptions=True)
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_worker_rechecks_pause_after_waiting_for_operation_lock(tmp_path):
+    _, store, remote, replica, _config = setup(tmp_path)
+    try:
+        async with replica._operation:
+            replica.start()
+            await asyncio.sleep(0)
+            await replica.action("pause")
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        assert replica.status()["phase"] == "paused"
+        assert not remote.instances
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("action", ["pause", "disable"])
+@pytest.mark.parametrize("stage", ["start", "inspect", "close"])
+async def test_recovery_probe_does_not_undo_pause_or_disable(
+    tmp_path,
+    monkeypatch,
+    action,
+    stage,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    target_token = "345678:" + "z" * 30
+    entered, release = asyncio.Event(), asyncio.Event()
+    original = getattr(Transport, stage)
+    operation = None
+
+    async def blocked_probe(self, *args, **kwargs):
+        if self.token == target_token:
+            entered.set()
+            await release.wait()
+        return await original(self, *args, **kwargs)
+
+    try:
+        await replica._sync(config)
+        await replica.inspect_recovery(BACKUP, TOKEN, replica.key())
+        recovery = {"target": REPLACEMENT, "target_token": target_token}
+        replica.journal.set("recovery", recovery)
+        replica.update(phase="recovering")
+        remote.calls.clear()
+        monkeypatch.setattr(Transport, stage, blocked_probe)
+        operation = asyncio.create_task(replica._recover_copy(recovery))
+        await asyncio.wait_for(entered.wait(), 1)
+        await replica.action(action)
+        release.set()
+        await operation
+        assert replica.status()["phase"] == (
+            "paused" if action == "pause" else "disabled"
+        )
+        assert not [call for call in remote.calls if call[0] in {"copy", "publish"}]
+        if action == "disable":
+            assert replica.journal.get("recovery") is None
+            assert replica.journal.get("candidate") is None
+        else:
+            assert not replica.journal.get("candidate")["complete"]
+    finally:
+        release.set()
+        if operation is not None and not operation.done():
+            operation.cancel()
+            await asyncio.gather(operation, return_exceptions=True)
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_deletion_poll_does_not_extend_a_short_saved_telegram_wait(
+    tmp_path,
+    monkeypatch,
+):
+    from tgdrive.recovery.backup import BackupError
+
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        timestamp = [1000.0]
+        monkeypatch.setattr(
+            "tgdrive.replication.replica.time.time", lambda: timestamp[0]
+        )
+        error = {
+            "code": "REPLICA_FLOOD_WAIT",
+            "detail": "Saved provider cooldown",
+            "retry_at": 1003.0,
+        }
+        replica.update(phase="waiting", error=error)
+        connections = len(remote.instances)
+        for current in (1000.0, 1001.0, 1002.9):
+            timestamp[0] = current
+            with pytest.raises(BackupError):
+                await replica.before_mutation()
+            assert replica.status()["error"] == error
+            assert len(remote.instances) == connections
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_deletion_barrier_rejects_saved_wait_at_expiry_boundary(
+    tmp_path,
+    monkeypatch,
+):
+    from tgdrive.recovery.backup import BackupError
+
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        error = {"code": "REPLICA_FLOOD_WAIT", "retry_at": 1003.0}
+        replica.update(phase="waiting", error=error)
+        connections = len(remote.instances)
+        timestamps = iter([1002.999999])
+        monkeypatch.setattr(
+            "tgdrive.replication.replica.time.time", lambda: next(timestamps, 1003.0)
+        )
+        with pytest.raises(BackupError):
+            await replica.before_mutation()
+        assert replica.status()["error"] == error
+        assert len(remote.instances) == connections
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_inspected_backup_rebuilds_replacement_main_when_original_main_is_lost(
+    tmp_path,
+):
+    configured, store, remote, replica, config = setup(tmp_path, multipart=True)
+    try:
+        before = store.export()
+        await replica._sync(config)
+        key = replica.key()
+        remote.unavailable.add(configured.storage_channel)
+        await replica.inspect_recovery(BACKUP, TOKEN, key)
+        candidate = replica.journal.get("candidate")
+        assert candidate["catalog"]["storage_channel_id"] == BACKUP
+        assert not candidate["complete"]
+        recovery = {
+            "target": REPLACEMENT,
+            "target_token": "345678:" + "z" * 30,
+        }
+        replica.journal.set("recovery", recovery)
+        replica.update(phase="recovering")
+        await replica._recover_copy(recovery)
+        restored = replica.journal.get("candidate")
+        assert restored["complete"]
+        assert restored["catalog"]["storage_channel_id"] == REPLACEMENT
+        assert replica.status()["phase"] == "ready_to_activate"
+        assert restored["credentials"]["bot_tokens"] == ["345678:" + "z" * 30]
+        for node in files_in(restored["catalog"]):
+            for part in parts_in(node):
+                assert (REPLACEMENT, part["message_id"]) in remote.messages
+        assert remote.messages[REPLACEMENT, remote.pins[REPLACEMENT]].startswith(b"{")
+        assert store.export() == before, "Recovery must not activate partial metadata"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_database_only_restore_checks_existing_parts_without_payload_copies(
+    tmp_path,
+):
+    configured, store, remote, replica, config = setup(tmp_path, multipart=True)
+    try:
+        await replica._sync(config)
+        await replica.inspect_recovery(
+            configured.storage_channel,
+            TOKEN,
+            replica.key(),
+            message_id=replica.journal.get("restore_point")["source_message_id"],
+        )
+        before = len([call for call in remote.calls if call[0] == "copy"])
+        recovery = {
+            "target": configured.storage_channel,
+            "target_token": "345678:" + "z" * 30,
+            "catalog_only": True,
+        }
+        replica.journal.set("recovery", recovery)
+        replica.update(phase="recovering")
+        await replica._recover_copy(recovery)
+        assert replica.journal.get("candidate")["complete"]
+        assert len([call for call in remote.calls if call[0] == "copy"]) == before
+        verified = [call[2] for call in remote.calls if call[0] == "verify"]
+        assert verified == [77, 78]
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_wrong_key_or_foreign_channel_does_not_replace_live_metadata(tmp_path):
+    configured, store, remote, replica, config = setup(tmp_path)
+    try:
+        before = store.export()
+        await replica._sync(config)
+        with pytest.raises(ValueError, match="nothing changed"):
+            await replica.inspect_recovery(BACKUP, TOKEN, "c2" * 32)
+        assert replica.journal.get("candidate") is None
+        assert store.export() == before
+        encrypted = remote.messages[BACKUP, remote.pins[BACKUP]]
+        remote.messages[REPLACEMENT, 9000] = encrypted
+        remote.pins[REPLACEMENT] = 9000
+        with pytest.raises(ValueError, match="selected channel"):
+            await replica.inspect_recovery(REPLACEMENT, TOKEN, replica.key())
+        assert replica.journal.get("candidate") is None
+        assert store.export() == before
+        assert configured.storage_channel == store.storage_channel_id
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_manual_retry_and_mutations_do_not_bypass_persisted_provider_wait(
+    tmp_path,
+):
+    from tgdrive.recovery.backup import BackupError
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    _, store, remote, replica, _config = setup(tmp_path)
+    try:
+        deadline = time.time() + 120
+        replica.update(
+            phase="waiting",
+            error={
+                "code": "REPLICA_FLOOD_WAIT",
+                "detail": "Wait for Telegram",
+                "retry_at": deadline,
+            },
+        )
+        await replica.action("retry")
+        assert replica.status()["error"]["retry_at"] == deadline
+        with pytest.raises((BackupError, SettingsProblem, ReplicaTransportError)):
+            await replica.before_mutation()
+        assert not [call for call in remote.calls if call[0] == "copy"]
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_pause_during_final_part_does_not_publish_or_claim_protection(tmp_path):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        remote.after_copy = lambda: replica.update(phase="paused")
+        await replica._sync(config)
+        assert replica.status()["phase"] == "paused"
+        assert not remote.pins
+        assert replica.status()["protected_revision"] == 0
+        replica.update(phase="idle")
+        await replica._sync(config)
+        assert replica.status()["protected_revision"] == store.revision
+        assert len([call for call in remote.calls if call[0] == "copy"]) == 1
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_configure_refuses_destination_with_foreign_pinned_checkpoint(tmp_path):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    _, store, remote, replica, _config = setup(tmp_path)
+    try:
+        remote.pins[BACKUP] = 700
+        before = replica.journal.get("config")
+        with pytest.raises(SettingsProblem):
+            await replica.configure(BACKUP, TOKEN, True)
+        assert replica.journal.get("config") == before
+        assert remote.pins[BACKUP] == 700
+        assert not [call for call in remote.calls if call[0] in {"copy", "publish"}]
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("phase", ["paused", "disabled"])
+async def test_pause_during_database_archive_stops_metadata_publication(
+    tmp_path, monkeypatch, phase
+):
+    _, store, remote, replica, config = setup(tmp_path)
+
+    async def stopped_archive(*_args, **_kwargs):
+        replica.update(phase=phase)
+        return None
+
+    monkeypatch.setattr(
+        "tgdrive.replication.replica_mongo.mirror_mongodb", stopped_archive
+    )
+    try:
+        await replica._sync(config)
+        assert replica.status()["phase"] == phase
+        assert replica.status()["protected_revision"] == 0
+        assert not remote.pins
+        assert not [call for call in remote.calls if call[0] == "publish"]
+        assert replica.journal.get("job"), "Interrupted catalog must remain resumable"
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("lost_stage", [False, True])
+async def test_capsule_publication_response_loss_recovers_after_process_restart(
+    tmp_path, lost_stage
+):
+    configured, store, remote, replica, config = setup(tmp_path)
+    try:
+        remote.lose_publish_response_channel = BACKUP
+        with pytest.raises(ReplicaTransportError):
+            await replica._sync(config)
+        original_pin = remote.pins[BACKUP]
+        assert replica.status()["protected_revision"] == 0
+        assert replica.journal.get("restore_point") is None
+        first_random_id = next(call[2] for call in remote.calls if call[0] == "publish")
+        if lost_stage:
+            # Disk loss after Telegram accepted a capsule must get a fresh
+            # ciphertext intent, never reuse an ID for different AES-GCM bytes.
+            for path in (configured.resolved_data_dir / "replica-bundles").glob(
+                "*.tgdb"
+            ):
+                path.unlink()
+        await replica.close()
+        replica = ChannelReplica(
+            configured,
+            SimpleNamespace(
+                store=store, mongo=for_directory(configured.resolved_data_dir)
+            ),
+            transport_factory=remote.factory,
+        )
+        await replica._sync(config)
+        second_random_id = [
+            call[2] for call in remote.calls if call[:2] == ("publish", BACKUP)
+        ][-1]
+        assert (second_random_id == first_random_id) is not lost_stage
+        assert (remote.pins[BACKUP] == original_pin) is not lost_stage
+        assert replica.status()["protected_revision"] == store.revision
+        assert (
+            replica.journal.get("restore_point")["backup_message_id"]
+            == remote.pins[BACKUP]
+        )
+        assert remote_bundle(remote, replica)["catalog"] == store.export()
+        assert len([call for call in remote.calls if call[0] == "copy"]) == 1
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("replacement", [None, 9000])
+async def test_health_check_detects_changed_pin_without_overwriting_it(
+    tmp_path, replacement
+):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        point = replica.journal.get("restore_point")
+        count = len([call for call in remote.calls if call[0] == "publish"])
+        replica.update(checked_at=0)
+        if replacement is None:
+            remote.pins.pop(BACKUP)
+        else:
+            remote.pins[BACKUP] = replacement
+        with pytest.raises(SettingsProblem) as error:
+            await replica._sync(config)
+        assert error.value.code == "REPLICA_PIN_CHANGED"
+        assert replica.journal.get("restore_point") == point
+        assert remote.pins.get(BACKUP) == replacement
+        assert len([call for call in remote.calls if call[0] == "publish"]) == count
+        assert remote.messages[BACKUP, point["backup_message_id"]]
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_key_kit_pairs_confirmed_point_with_its_original_keys_after_rotation(
+    tmp_path,
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        replica.settings.mongodb_backup_key = SecretStr("a1" * 32)
+        await replica._sync(config)
+        point = replica.journal.get("restore_point")
+        original_key = replica.key()
+        replica.journal.set("key", "c3" * 32)
+        replica.settings.mongodb_backup_key = SecretStr("b2" * 32)
+        kit = replica.recovery_kit()
+        assert kit["restore_point"] == point
+        assert kit["key"] == original_key
+        assert kit["next_backup_key"] == "c3" * 32
+        assert kit["mongodb_backup_key"] == "a1" * 32
+        assert kit["next_mongodb_backup_key"] == "b2" * 32
+        bundle = decode_bundle(
+            remote.messages[BACKUP, point["backup_message_id"]], kit["key"]
+        )
+        assert bundle["credentials"]["mongodb_backup_key"] == kit["mongodb_backup_key"]
+        # A failed next generation must not pair its new keys with the old point.
+        store.create_folder("/", "Next generation")
+        remote.copy_error = ReplicaTransportError("Offline.", "REPLICA_ACCESS")
+        # Force a new missing receipt through an added file, preserving original.
+        folder = next(iter(store.export()["root"]["children"].values()))
+        store.add_file("/" + folder["id"], "new.bin", 79, 1)
+        with pytest.raises(ReplicaTransportError):
+            await replica._sync(config)
+        assert replica.recovery_kit() == kit
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_inspected_recovery_key_kit_uses_candidate_keys_and_checkpoint(tmp_path):
+    from tgdrive.replication.replica_state import encode_bundle
+
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        inspected = remote_bundle(remote, replica)
+        inspected_key = "d4" * 32
+        inspected["credentials"]["mongodb_backup_key"] = "e5" * 32
+        message = remote.new_message(BACKUP, encode_bundle(inspected, inspected_key))
+        await replica.inspect_recovery(BACKUP, TOKEN, inspected_key, message_id=message)
+        kit = replica.recovery_kit()
+        assert kit["key"] == inspected_key
+        assert kit["mongodb_backup_key"] == "e5" * 32
+        assert kit["restore_point"]["source_channel"] == BACKUP
+        assert kit["restore_point"]["source_message_id"] == message
+        assert decode_bundle(remote.messages[BACKUP, message], kit["key"]) == inspected
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("lost_at", ["capsule", "primary-catalog"])
+async def test_recovery_resumes_its_accepted_pin_after_lost_publication_response(
+    tmp_path, monkeypatch, lost_at
+):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        await replica.inspect_recovery(BACKUP, TOKEN, replica.key())
+        recovery = {"target": REPLACEMENT, "target_token": "345678:" + "z" * 30}
+        replica.journal.set("recovery", recovery)
+        replica.update(phase="recovering")
+        if lost_at == "capsule":
+            remote.lose_publish_response_channel = REPLACEMENT
+        else:
+            publish_catalog = Transport.publish_catalog
+            lose_response = True
+
+            async def lose_catalog_response(self, *_args, **_kwargs):
+                nonlocal lose_response
+                result = await publish_catalog(self, *_args, **_kwargs)
+                if lose_response:
+                    lose_response = False
+                    raise ReplicaTransportError(
+                        "Catalog response lost.", "REPLICA_UNAVAILABLE", retryable=True
+                    )
+                return result
+
+            monkeypatch.setattr(Transport, "publish_catalog", lose_catalog_response)
+        with pytest.raises(ReplicaTransportError):
+            await replica._recover_copy(recovery)
+        assert remote.pins[REPLACEMENT]
+        assert not replica.journal.get("candidate")["complete"]
+        count = len([call for call in remote.calls if call[0] == "copy"])
+        await replica._recover_copy(recovery)
+        assert replica.journal.get("candidate")["complete"]
+        assert replica.status()["phase"] == "ready_to_activate"
+        assert remote.messages[REPLACEMENT, remote.pins[REPLACEMENT]].startswith(b"{")
+        assert len([call for call in remote.calls if call[0] == "copy"]) == count
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("kind", ["capsule", "catalog"])
+async def test_recovery_refuses_unrelated_pin_introduced_during_pause(tmp_path, kind):
+    _, store, remote, replica, config = setup(tmp_path)
+    try:
+        await replica._sync(config)
+        unrelated = (
+            remote.messages[BACKUP, remote.pins[BACKUP]]
+            if kind == "capsule"
+            else DriveStore._json_bytes(store.export())
+        )
+        await replica.inspect_recovery(BACKUP, TOKEN, replica.key())
+        recovery = {"target": REPLACEMENT, "target_token": "345678:" + "z" * 30}
+        replica.journal.set("recovery", recovery)
+        replica.update(phase="recovering")
+        remote.after_copy = lambda: replica.update(phase="paused")
+        await replica._recover_copy(recovery)
+        assert not replica.journal.get("candidate")["complete"]
+        foreign_pin = remote.new_message(REPLACEMENT, unrelated)
+        remote.pins[REPLACEMENT] = foreign_pin
+        publications = len([call for call in remote.calls if call[0] == "publish"])
+        replica.update(phase="recovering")
+        with pytest.raises(ValueError, match="pin changed"):
+            await replica._recover_copy(recovery)
+        assert not replica.journal.get("candidate")["complete"]
+        assert remote.pins[REPLACEMENT] == foreign_pin
+        assert (
+            len([call for call in remote.calls if call[0] == "publish"]) == publications
+        )
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_pending_mongo_job_rejects_changed_key_before_any_remote_side_effect(
+    tmp_path, monkeypatch
+):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    configured, store, remote, replica, config = setup(tmp_path)
+    original_mongo_key, replacement_mongo_key = "a1" * 32, "b2" * 32
+    configured.mongodb_backup_key = SecretStr(original_mongo_key)
+    try:
+        await replica._sync(config)
+        point = replica.journal.get("restore_point")
+        original_capsule = remote.messages[BACKUP, point["backup_message_id"]]
+        captured = replica._credentials()
+        store.create_folder("/", "A later catalog generation")
+        pending = {"catalog": store.export(), "credentials": captured}
+        replica.journal.set("job", pending)
+        replica.runtime.mongo = object()
+        configured.mongodb_backup_key = SecretStr(replacement_mongo_key)
+
+        def current_credentials():
+            current_key = configured.mongodb_backup_key.get_secret_value()
+            return captured | {"mongodb_backup_key": current_key}
+
+        monkeypatch.setattr(replica, "_credentials", current_credentials)
+        archive = {
+            "format": "mongodb-encrypted-v1",
+            "id": "captured-full-mongo",
+            "revision": store.revision,
+            "source_channel": configured.storage_channel,
+            "source_message_id": 900,
+            "replica_channel": BACKUP,
+            "replica_message_id": 901,
+            "size": 128,
+            "sha256": "c" * 64,
+            "created_at": "2026-10-22T10:00:00Z",
+        }
+        mirror = AsyncMock(return_value=archive)
+        monkeypatch.setattr("tgdrive.replication.replica_mongo.mirror_mongodb", mirror)
+        calls, connections = list(remote.calls), len(remote.instances)
+        with pytest.raises(SettingsProblem) as error:
+            await replica._sync(config)
+        assert error.value.code == "REPLICA_MONGODB_KEY_CHANGED"
+        assert original_mongo_key not in str(error.value)
+        assert replacement_mongo_key not in str(error.value)
+        mirror.assert_not_awaited()
+        assert remote.calls == calls and len(remote.instances) == connections
+        assert replica.journal.get("job") == pending
+        assert replica.journal.get("restore_point") == point
+        assert remote.pins[BACKUP] == point["backup_message_id"]
+        assert replica.recovery_kit()["mongodb_backup_key"] == original_mongo_key
+        # Reinstating the captured key resumes this exact generation safely.
+        configured.mongodb_backup_key = SecretStr(original_mongo_key)
+        await replica._sync(config)
+        mirror.assert_awaited_once()
+        bundle = remote_bundle(remote, replica)
+        assert bundle["credentials"]["mongodb_backup_key"] == original_mongo_key
+        assert bundle["credentials"]["mongodb_archive"] == archive
+        assert replica.status()["protected_revision"] == pending["catalog"]["revision"]
+        assert replica.journal.get("job") is None
+        assert remote.messages[BACKUP, point["backup_message_id"]] == original_capsule
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_provider_inflight_reply_preserves_deadline_and_identity_after_restart(
+    tmp_path,
+):
+    from telethon.errors import RandomIdDuplicateError
+
+    from tgdrive.recovery.backup import BackupError
+    from tgdrive.replication.replica_transport import _provider_error
+
+    configured, store, remote, replica, config = setup(tmp_path)
+
+    def still_inflight():
+        raise _provider_error(RandomIdDuplicateError(request=TOKEN))
+
+    try:
+        remote.after_copy = still_inflight
+        with pytest.raises(ReplicaTransportError) as error:
+            await replica.before_mutation()
+        assert error.value.code == "REPLICA_IN_FLIGHT"
+        state = replica.status()
+        assert state["phase"] == "waiting"
+        assert state["error"]["retry_at"] > time.time()
+        assert TOKEN not in state["error"]["detail"]
+        assert len(remote.receipts) == 1
+        first_id = next(call[-1] for call in remote.calls if call[0] == "copy")
+        await replica.close()
+        replica = ChannelReplica(
+            configured,
+            SimpleNamespace(
+                store=store, mongo=for_directory(configured.resolved_data_dir)
+            ),
+            transport_factory=remote.factory,
+        )
+        calls = list(remote.calls)
+        with pytest.raises(BackupError):
+            await replica._sync(config)
+        assert remote.calls == calls, "Restart cannot bypass the durable wait"
+        replica.update(error=state["error"] | {"retry_at": 0})
+        await replica._sync(config)
+        ids = [call[-1] for call in remote.calls if call[0] == "copy"]
+        assert ids == [first_id, first_id]
+        assert replica.status()["protected_revision"] == store.revision
+        assert len([row for row in remote.messages if row[0] == BACKUP]) == 2
+    finally:
+        await dispose(replica, store)
diff --git a/tests/replication/test_replica_activation.py b/tests/replication/test_replica_activation.py
new file mode 100644
index 00000000..6b153240
--- /dev/null
+++ b/tests/replication/test_replica_activation.py
@@ -0,0 +1,834 @@
+"""Crash boundaries for explicit catalog/channel activation, never live overwrite."""
+
+from __future__ import annotations
+
+import copy
+import json
+import threading
+from types import SimpleNamespace
+
+import pytest
+from pydantic import SecretStr
+
+from tests.support.mongo_fixtures import Collection as MongoCollection
+from tgdrive.core.config import Settings
+from tgdrive.replication.replica_activation import (
+    MANIFEST,
+    ActivationError,
+    apply_activation,
+    effective_settings,
+    prepare_activation,
+)
+from tgdrive.replication.replica_settings import POLICIES
+from tgdrive.replication.replica_state import read_private
+from tgdrive.settings.managed_settings import (
+    ManagedClient,
+    ManagedDocument,
+    SettingsProblem,
+    credential_id,
+    read_document,
+    save_document,
+)
+from tgdrive.storage.mongo import DatabaseUnavailable, for_settings
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.storage.store import DriveStore
+
+OLD = -100111222
+NEW = -100333444
+OLD_BOT = "12345:" + "a" * 24
+NEW_BOT = "54321:" + "b" * 24
+BACKUP_BOT = "67890:" + "c" * 24
+
+
+@pytest.fixture
+def settings(tmp_path, monkeypatch):
+    configured = Settings(
+        _env_file=None,
+        MONGODB_URI="mongodb://synthetic.invalid",
+        API_ID=12345,
+        API_HASH="a" * 32,
+        BOT_TOKENS=OLD_BOT,
+        STORAGE_CHANNEL=OLD,
+        ADMIN_PASSWORD="test activation password",
+        SESSION_SECRET="s" * 40,
+        DATA_DIR=tmp_path / "data",
+        CACHE_DIR=tmp_path / "cache",
+    )
+
+    backend = Backend(_seed_catalog())
+    import tgdrive.storage.mongo as mongo
+
+    monkeypatch.setattr(mongo, "configure", lambda *_args, **_kwargs: backend)
+    monkeypatch.setattr(mongo, "for_settings", lambda _settings: backend)
+    monkeypatch.setattr(mongo, "for_directory", lambda _directory: backend)
+    return configured
+
+
+def _seed_catalog():
+    store = DriveStore.create()
+    store.bind_storage_channel(OLD)
+    item = store.add_file("/", "original.bin", 123, 42)
+    store.set_starred("/" + item["id"], True)
+    store.create_share("/" + item["id"], label="Review")
+    payload = store.export()
+    store.close()
+    return payload
+
+
+def catalog(settings):
+    return installed(settings)
+
+
+def _apply(settings):
+    return apply_activation(settings, for_settings(settings))
+
+
+def candidate(payload):
+    value = copy.deepcopy(payload)
+    value["storage_channel_id"] = NEW
+    for node in value["root"]["children"].values():
+        if node["type"] == "file":
+            node["message_id"] += 1000
+    return {
+        "catalog": value,
+        "complete": True,
+        "credentials": {
+            "api_id": 9876,
+            "api_hash": "b" * 32,
+            "session_secret": "r" * 40,
+            "bot_tokens": [NEW_BOT],
+            "managed_document": json.loads(
+                ManagedDocument(
+                    revision=1,
+                    api_id=9876,
+                    api_hash=SecretStr("b" * 32),
+                    clients=[
+                        ManagedClient(
+                            id="recovery-bot",
+                            label="Recovery bot",
+                            kind="bot",
+                            credential=SecretStr(NEW_BOT),
+                        )
+                    ],
+                ).private_bytes()
+            ),
+            "preferences": {
+                filename: model.model_validate(
+                    {"uploads_per_bot": 1}
+                    if filename == "transfer-preferences.json"
+                    else {}
+                ).model_dump()
+                for filename, model in POLICIES.items()
+            },
+        },
+        "token": BACKUP_BOT,
+        "key": "d" * 64,
+    }
+
+
+def installed(settings):
+    store = MongoStore(for_settings(settings))
+    try:
+        return store.export()
+    finally:
+        store.close()
+
+
+def test_prepare_preserves_live_mongo_catalog_and_archives_replaced_state(settings):
+    before = catalog(settings)
+    backend = for_settings(settings)
+    original_jobs = copy.deepcopy(backend.data["jobs"])
+    source = candidate(before)
+    identity = prepare_activation(settings, source)
+    assert installed(settings) == before
+    assert (settings.resolved_data_dir / MANIFEST).stat().st_mode & 0o777 == 0o600
+    next_settings = effective_settings(settings)
+    assert next_settings.storage_channel == NEW
+    assert next_settings.bot_tokens == (NEW_BOT,)
+    assert next_settings.string_sessions == ()
+    assert _apply(next_settings)
+    result = installed(settings)
+    node = next(iter(result["root"]["children"].values()))
+    assert result["storage_channel_id"] == NEW
+    assert result["drive_id"] == before["drive_id"]
+    assert node["message_id"] == 1123 and node["starred"] is True
+    assert result["shares"] == before["shares"]
+    archive = settings.resolved_data_dir / "recovery-archive" / identity
+    saved = json.loads(read_private(archive / "mongodb-before.json"))
+    assert saved["jobs"] == original_jobs
+    assert saved["catalog"][0]["storage_channel_id"] == OLD
+    assert backend.data["jobs"] == [] and backend.data["receipts"] == []
+    assert (
+        read_document(settings.resolved_data_dir)
+        .clients[0]
+        .credential.get_secret_value()
+        == NEW_BOT
+    )
+    assert not _apply(next_settings)
+
+
+def test_apply_replays_after_catalog_swap_before_manifest_update(settings, monkeypatch):
+    before = catalog(settings)
+    prepare_activation(settings, candidate(before))
+    import tgdrive.replication.replica_activation as module
+
+    original = module._write
+    once = True
+
+    def crash(config, value):
+        nonlocal once
+        if once and value["phase"] == "catalog":
+            once = False
+            raise OSError("synthetic power loss")
+        return original(config, value)
+
+    monkeypatch.setattr(module, "_write", crash)
+    with pytest.raises(OSError, match="synthetic"):
+        _apply(settings)
+    assert installed(settings)["storage_channel_id"] == NEW
+    assert (
+        json.loads(read_private(settings.resolved_data_dir / MANIFEST))["phase"]
+        == "installing"
+    )
+    assert _apply(settings)
+    assert not _apply(settings)
+
+
+def test_changed_catalog_and_foreign_nonempty_drive_are_never_overwritten(settings):
+    before = catalog(settings)
+    other = copy.deepcopy(before)
+    other["drive_id"] = "another-drive"
+    with pytest.raises(ActivationError, match="different drive"):
+        prepare_activation(settings, candidate(other))
+    assert not (settings.resolved_data_dir / MANIFEST).exists()
+    prepare_activation(settings, candidate(before))
+    store = MongoStore(for_settings(settings))
+    store.create_folder("/", "Added after inspection")
+    store.close()
+    with pytest.raises(ActivationError, match="metadata changed"):
+        _apply(settings)
+    assert installed(settings)["storage_channel_id"] == OLD
+    assert not (settings.resolved_data_dir / "recovery-archive").exists()
+
+
+def test_applied_settings_keep_newer_connections_and_never_reinstall_catalog(settings):
+    before = catalog(settings)
+    prepare_activation(settings, candidate(before))
+    _apply(settings)
+    current = read_document(settings.resolved_data_dir)
+    newer = ManagedDocument(
+        revision=current.revision + 1,
+        api_id=55555,
+        api_hash=SecretStr("e" * 32),
+        clients=[
+            ManagedClient(
+                id="updated-bot",
+                label="Updated",
+                kind="bot",
+                credential=SecretStr("22222:" + "f" * 24),
+            )
+        ],
+    )
+    save_document(settings.resolved_data_dir, newer, current.revision)
+    active = effective_settings(settings)
+    assert active.api_id == 55555
+    assert active.api_hash.get_secret_value() == "e" * 32
+    assert active.bot_tokens == ("22222:" + "f" * 24,)
+    assert active.session_secret.get_secret_value() == "r" * 40
+    assert active.storage_channel == NEW
+    store = MongoStore(for_settings(settings))
+    store.create_folder("/", "After activation")
+    revision = store.revision
+    store.close()
+    assert not _apply(active)
+    assert installed(settings)["revision"] == revision
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        {"complete": "true"},
+        {"key": "bad"},
+        {"token": "bad"},
+        {
+            "credentials": {
+                "api_id": True,
+                "api_hash": "b" * 32,
+                "session_secret": "r" * 40,
+                "bot_tokens": [NEW_BOT],
+            }
+        },
+        {
+            "credentials": {
+                "api_id": 123,
+                "api_hash": "bad",
+                "session_secret": "short",
+                "bot_tokens": [NEW_BOT],
+            }
+        },
+    ],
+)
+def test_invalid_activation_never_writes_or_leaks_credentials(settings, change):
+    before = catalog(settings)
+    value = candidate(before)
+    for field, replacement in change.items():
+        if field == "credentials":
+            value[field].update(replacement)
+        else:
+            value[field] = replacement
+    with pytest.raises(ActivationError) as error:
+        prepare_activation(settings, value)
+    assert NEW_BOT not in str(error.value)
+    assert "r" * 40 not in str(error.value)
+    assert installed(settings) == before
+    assert not (settings.resolved_data_dir / MANIFEST).exists()
+
+
+def test_pending_conflict_and_corrupt_manifest_preserve_original_intent(settings):
+    before = catalog(settings)
+    value = candidate(before)
+    prepare_activation(settings, value)
+    path = settings.resolved_data_dir / MANIFEST
+    original = path.read_bytes()
+    different = copy.deepcopy(value)
+    different["catalog"]["storage_channel_id"] -= 1
+    with pytest.raises(ActivationError, match="pending"):
+        prepare_activation(settings, different)
+    assert path.read_bytes() == original
+    assert prepare_activation(settings, value)
+    damaged = json.loads(original)
+    damaged["candidate"]["credentials"]["api_id"] += 1
+    path.write_text(json.dumps(damaged))
+    with pytest.raises(ActivationError, match="private activation record"):
+        effective_settings(settings)
+    assert installed(settings) == before
+
+
+class Collection(MongoCollection):
+    def __init__(self, backend, name):
+        self.backend, self.name = backend, name
+
+    @property
+    def rows(self):
+        return self.backend.data.setdefault(self.name, [])
+
+    def find(self, _query, **_kwargs):
+        return copy.deepcopy(self.rows)
+
+    def find_one(self, query, **_kwargs):
+        return next(
+            (
+                copy.deepcopy(row)
+                for row in self.rows
+                if all(row.get(key) == value for key, value in query.items())
+            ),
+            None,
+        )
+
+    def count_documents(self, _query, **_kwargs):
+        return len(self.rows)
+
+    def delete_many(self, _query, **_kwargs):
+        self.backend.data[self.name] = []
+
+    def insert_many(self, rows, **_kwargs):
+        if self.backend.fail_insert and self.name == "nodes":
+            self.backend.fail_insert = False
+            raise RuntimeError("synthetic transaction interruption")
+        self.rows.extend(copy.deepcopy(rows))
+
+    def replace_one(self, query, row, *, upsert=False, **_kwargs):
+        for i, existing in enumerate(self.rows):
+            if all(existing.get(key) == value for key, value in query.items()):
+                self.rows[i] = copy.deepcopy(row)
+                return SimpleNamespace(matched_count=1)
+        if upsert:
+            self.rows.append(copy.deepcopy(row))
+        return SimpleNamespace(matched_count=0)
+
+
+class Database(SimpleNamespace):
+    def __getitem__(self, name):
+        return getattr(self, name)
+
+
+class Backend:
+    def __init__(self, payload):
+        from tgdrive.replication.replica_activation import _mongo_nodes
+
+        self.data = {
+            "nodes": _mongo_nodes(payload),
+            "shares": [dict(row, _id=row["id"]) for row in payload.get("shares", [])],
+            "catalog": [
+                {
+                    "_id": "catalog",
+                    "schema_version": 4,
+                    "drive_id": payload["drive_id"],
+                    "generation": 2,
+                    "revision": payload["revision"],
+                    "backed_up_revision": payload["revision"],
+                    "storage_channel_id": OLD,
+                }
+            ],
+            "jobs": [{"_id": "old-job", "message_id": 123}],
+            "receipts": [{"_id": "old-receipt"}],
+            "settings": [{"_id": "bootstrap", "document": {"STORAGE_CHANNEL": OLD}}],
+        }
+        self.db = Database(
+            **{
+                name: Collection(self, name)
+                for name in (
+                    "nodes",
+                    "shares",
+                    "catalog",
+                    "operations",
+                    "deletions",
+                    "preparations",
+                    "settings",
+                    "jobs",
+                    "receipts",
+                    "bot_folders",
+                    "backups",
+                )
+            }
+        )
+        for name in vars(self.db):
+            self.data.setdefault(name, [])
+        self._settings_lock = threading.RLock()
+        self._settings_cached = False
+        self._settings_document = None
+        self.fail_insert = False
+        self.lose_reply = False
+        self.fences = 0
+
+    def fence(self, _session):
+        self.fences += 1
+
+    def check_owner(self):
+        pass
+
+    def write(self, collection, method, *args, **kwargs):
+        return getattr(collection, method)(*args, **kwargs)
+
+    def transaction(self, operation):
+        before = copy.deepcopy(self.data)
+        try:
+            result = operation(object())
+        except BaseException:
+            self.data = before
+            raise
+        if self.lose_reply and self.data["catalog"][0].get("replica_activation_id"):
+            self.lose_reply = False
+            raise RuntimeError("synthetic lost commit reply")
+        return result
+
+
+def mongo_settings(settings, monkeypatch):
+    payload = catalog(settings)
+    backend = Backend(payload)
+    import tgdrive.storage.mongo as mongo
+
+    monkeypatch.setattr(mongo, "configure", lambda *_args, **_kwargs: backend)
+    monkeypatch.setattr(mongo, "for_settings", lambda _settings: backend)
+    monkeypatch.setattr(mongo, "for_directory", lambda _directory: backend)
+    return (
+        settings.model_copy(
+            update={"mongodb_uri": SecretStr("mongodb://synthetic.invalid")}
+        ),
+        backend,
+        candidate(payload),
+    )
+
+
+def test_mongo_activation_is_fenced_atomic_and_has_no_sqlite_fallback(
+    settings, monkeypatch
+):
+    settings, backend, source = mongo_settings(settings, monkeypatch)
+    identity = prepare_activation(settings, source)
+    before = copy.deepcopy(backend.data)
+    backend.fail_insert = True
+    with pytest.raises(RuntimeError, match="transaction interruption"):
+        apply_activation(settings, backend)
+    assert backend.data == before
+    assert (
+        json.loads(read_private(settings.resolved_data_dir / MANIFEST))["phase"]
+        == "installing"
+    )
+    assert apply_activation(settings, backend)
+    metadata = backend.data["catalog"][0]
+    assert metadata["storage_channel_id"] == NEW
+    assert metadata["replica_activation_id"] == identity
+    assert backend.data["jobs"] == [] and backend.data["receipts"] == []
+    assert backend.data["settings"][0]["document"]["STORAGE_CHANNEL"] == NEW
+    assert backend.fences >= 3
+    saved = json.loads(
+        read_private(
+            settings.resolved_data_dir
+            / "recovery-archive"
+            / identity
+            / "mongodb-before.json"
+        )
+    )
+    assert saved["jobs"][0]["_id"] == "old-job"
+    assert not apply_activation(settings, backend)
+
+
+def test_mongo_commit_response_loss_replays_without_replacing_committed_state(
+    settings, monkeypatch
+):
+    settings, backend, source = mongo_settings(settings, monkeypatch)
+    prepare_activation(settings, source)
+    backend.lose_reply = True
+    with pytest.raises(RuntimeError, match="lost commit reply"):
+        apply_activation(settings, backend)
+    assert backend.data["catalog"][0]["storage_channel_id"] == NEW
+    generation = backend.data["catalog"][0]["generation"]
+    assert apply_activation(settings, backend)
+    assert backend.data["catalog"][0]["generation"] == generation
+    assert effective_settings(settings).storage_channel == NEW
+
+
+def test_mongo_pending_activation_never_uses_local_sqlite(settings, monkeypatch):
+    settings, _backend, source = mongo_settings(settings, monkeypatch)
+    local = settings.resolved_data_dir / "drive.sqlite3"
+    local.parent.mkdir(parents=True, exist_ok=True)
+    local.write_bytes(b"legacy local catalog")
+    before = local.read_bytes()
+    prepare_activation(settings, source)
+    with pytest.raises(ActivationError, match="no fallback"):
+        apply_activation(settings)
+    assert (settings.resolved_data_dir / "drive.sqlite3").read_bytes() == before
+
+
+def with_saved_settings(value):
+    from tgdrive.settings.performance_preferences import PerformancePreferences
+
+    old = ManagedDocument(
+        revision=7,
+        api_id=12345,
+        api_hash=SecretStr("a" * 32),
+        clients=[
+            ManagedClient(
+                id="old-bot",
+                label="Former bot",
+                kind="bot",
+                credential=SecretStr(OLD_BOT),
+            ),
+            ManagedClient(
+                id="old-premium",
+                label="Former Premium",
+                kind="user",
+                credential=SecretStr("synthetic-premium-session"),
+            ),
+        ],
+    )
+    value["credentials"].update(
+        {
+            "managed_document": json.loads(old.private_bytes()),
+            "preferences": value["credentials"]["preferences"]
+            | {
+                "performance-preferences.json": PerformancePreferences(
+                    timezone="UTC", cache_memory_bytes=0
+                ).model_dump(),
+                "transfer-preferences.json": {"uploads_per_bot": 3},
+            },
+            "mongodb_backup_key": "e" * 64,
+        }
+    )
+    return value
+
+
+def test_recovery_restores_mongo_policies_and_keeps_previous_connections_disabled(
+    settings,
+):
+    backend = for_settings(settings)
+    backend.db.settings.replace_one(
+        {"_id": "performance-preferences"},
+        {"_id": "performance-preferences", "document": {"timezone": "Asia/Tokyo"}},
+        upsert=True,
+    )
+    value = with_saved_settings(candidate(catalog(settings)))
+    identity = prepare_activation(settings, value)
+    pending = effective_settings(settings)
+    assert pending.timezone == "UTC"
+    assert pending.cache_memory_bytes == 0
+    assert pending.telegram_uploads_per_bot == 3
+    assert pending.string_sessions == ()
+    assert pending.mongodb_backup_key.get_secret_value() == "e" * 64
+    assert _apply(pending)
+    document = read_document(settings.resolved_data_dir)
+    assert [row.id for row in document.clients if row.enabled] == [
+        credential_id("bot", NEW_BOT)
+    ]
+    assert {row.label for row in document.clients if not row.enabled} == {
+        "Former bot",
+        "Former Premium",
+    }
+    saved = backend.db.settings.find_one({"_id": "performance-preferences"})
+    assert saved["document"]["timezone"] == "UTC"
+    archived = json.loads(
+        read_private(
+            settings.resolved_data_dir
+            / "recovery-archive"
+            / identity
+            / "mongodb-before.json"
+        )
+    )
+    old_policy = next(
+        row for row in archived["settings"] if row["_id"] == "performance-preferences"
+    )
+    assert old_policy["document"]["timezone"] == "Asia/Tokyo"
+    backend.db.settings.replace_one(
+        {"_id": "transfer-preferences"},
+        {"_id": "transfer-preferences", "document": {"uploads_per_bot": 2}},
+    )
+    assert not _apply(settings)
+    assert backend.db.settings.find_one({"_id": "transfer-preferences"})[
+        "document"
+    ] == {"uploads_per_bot": 2}
+
+
+def test_mongo_activation_restores_only_saved_domain_preferences(settings, monkeypatch):
+    settings, backend, value = mongo_settings(settings, monkeypatch)
+    with_saved_settings(value)
+    value["credentials"]["mongodb_archive"] = {
+        "format": "mongodb-encrypted-v1",
+        "id": "archive-id",
+        "revision": 42,
+        "source_channel": OLD,
+        "source_message_id": 800,
+        "replica_channel": NEW,
+        "replica_message_id": 900,
+        "size": 1200,
+        "sha256": "a" * 64,
+        "created_at": "2026-10-22T00:00:00Z",
+    }
+    prepare_activation(settings, value)
+    assert apply_activation(settings, backend)
+    assert backend.db.settings.find_one({"_id": "transfer-preferences"})[
+        "document"
+    ] == {"uploads_per_bot": 3}
+    assert (
+        backend.db.settings.find_one({"_id": "performance-preferences"})["document"][
+            "timezone"
+        ]
+        == "UTC"
+    )
+    assert backend.data["jobs"] == [] and backend.data["receipts"] == []
+    retained = json.loads(read_private(settings.resolved_data_dir / MANIFEST))
+    assert (
+        retained["candidate"]["credentials"]["mongodb_archive"]
+        == value["credentials"]["mongodb_archive"]
+    )
+    assert (
+        effective_settings(settings).mongodb_backup_key.get_secret_value() == "e" * 64
+    )
+
+
+@pytest.mark.parametrize(
+    "current,expected",
+    [
+        ("a" * 64, "e" * 64),
+        ("e" * 64, "e" * 64),
+        ("f" * 64, "f" * 64),
+        (None, "e" * 64),
+    ],
+)
+def test_applied_mongo_key_accepts_rotation_but_retains_recovery_for_stale_key(
+    settings, monkeypatch, current, expected
+):
+    settings, backend, value = mongo_settings(settings, monkeypatch)
+    settings.mongodb_backup_key = SecretStr("a" * 64)
+    with_saved_settings(value)
+    prepare_activation(settings, value)
+    pending = effective_settings(settings)
+    assert pending.mongodb_backup_key.get_secret_value() == "e" * 64
+    assert apply_activation(pending, backend)
+    deployment = settings.model_copy(
+        update={"mongodb_backup_key": SecretStr(current) if current else None}
+    )
+    active = effective_settings(deployment)
+    assert active.mongodb_backup_key.get_secret_value() == expected
+    assert active.storage_channel == NEW
+
+
+def test_applied_manifest_rejects_missing_baseline_without_changes(
+    settings, monkeypatch
+):
+    import tgdrive.replication.replica_activation as module
+
+    settings, backend, value = mongo_settings(settings, monkeypatch)
+    with_saved_settings(value)
+    prepare_activation(settings, value)
+    assert apply_activation(settings, backend)
+    path = settings.resolved_data_dir / MANIFEST
+    manifest = json.loads(read_private(path))
+    manifest.pop("mongodb_key_before_sha256")
+    module.atomic_private(path, module._raw(manifest))
+    settings.mongodb_backup_key = SecretStr("f" * 64)
+    before = copy.deepcopy(backend.data)
+    private_files = {
+        file.relative_to(settings.resolved_data_dir): file.read_bytes()
+        for file in settings.resolved_data_dir.rglob("*")
+        if file.is_file()
+    }
+    with pytest.raises(ActivationError, match="record is invalid"):
+        effective_settings(settings)
+    with pytest.raises(ActivationError, match="record is invalid"):
+        apply_activation(settings, backend)
+    assert settings.mongodb_backup_key.get_secret_value() == "f" * 64
+    assert backend.data == before
+    assert {
+        file.relative_to(settings.resolved_data_dir): file.read_bytes()
+        for file in settings.resolved_data_dir.rglob("*")
+        if file.is_file()
+    } == private_files
+
+
+def test_applied_key_baseline_is_bound_to_activation_identity(settings):
+    import tgdrive.replication.replica_activation as module
+
+    value = with_saved_settings(candidate(catalog(settings)))
+    prepare_activation(settings, value)
+    path = settings.resolved_data_dir / MANIFEST
+    manifest = json.loads(read_private(path))
+    manifest["mongodb_key_before_sha256"] = "f" * 64
+    module.atomic_private(path, module._raw(manifest))
+    with pytest.raises(ActivationError, match="record is invalid"):
+        effective_settings(settings)
+
+
+def test_applied_mongo_settings_outage_rejects_startup_without_writes(
+    settings, monkeypatch
+):
+    import tgdrive.replication.replica_activation as module
+
+    settings, backend, value = mongo_settings(settings, monkeypatch)
+    with_saved_settings(value)
+    prepare_activation(settings, value)
+    assert apply_activation(settings, backend)
+    before = copy.deepcopy(backend.data)
+
+    def unavailable(_directory):
+        raise DatabaseUnavailable("MongoDB is unavailable")
+
+    monkeypatch.setattr(module, "read_document", unavailable)
+    with pytest.raises(DatabaseUnavailable, match="MongoDB is unavailable"):
+        effective_settings(settings)
+    assert backend.data == before
+
+
+def test_applied_mongo_invalid_connection_document_still_fails_closed(
+    settings, monkeypatch
+):
+    import tgdrive.replication.replica_activation as module
+
+    prepare_activation(settings, candidate(catalog(settings)))
+    assert _apply(settings)
+
+    def invalid(_directory):
+        raise SettingsProblem("Private Telegram settings are invalid.", status=503)
+
+    monkeypatch.setattr(module, "read_document", invalid)
+    with pytest.raises(ActivationError, match="connection settings are invalid"):
+        effective_settings(settings)
+
+
+def test_recovery_policy_path_injection_is_rejected_before_preparation(settings):
+    value = candidate(catalog(settings))
+    value["credentials"]["preferences"] = {"../escaped.json": {"uploads_per_bot": 2}}
+    with pytest.raises(ActivationError):
+        prepare_activation(settings, value)
+    assert not (settings.resolved_data_dir / MANIFEST).exists()
+
+
+@pytest.mark.parametrize("missing", ["managed_document", "preferences", "bot-policy"])
+def test_incomplete_recovery_settings_are_rejected_before_preparation(
+    settings, missing
+):
+    before = catalog(settings)
+    value = candidate(before)
+    if missing == "bot-policy":
+        value["credentials"]["preferences"].pop("bot-preferences.json")
+    else:
+        value["credentials"].pop(missing)
+    with pytest.raises(ActivationError):
+        prepare_activation(settings, value)
+    assert installed(settings) == before
+    assert not (settings.resolved_data_dir / MANIFEST).exists()
+
+
+def test_archive_symlink_and_manifest_size_limit_leave_catalog_untouched(
+    settings, monkeypatch
+):
+    before = catalog(settings)
+    value = candidate(before)
+    import tgdrive.replication.replica_activation as module
+
+    original_limit = module.MAX_BUNDLE
+    monkeypatch.setattr(module, "MAX_BUNDLE", 100)
+    with pytest.raises(ActivationError, match="64 MiB"):
+        prepare_activation(settings, value)
+    assert not (settings.resolved_data_dir / MANIFEST).exists()
+    monkeypatch.setattr(module, "MAX_BUNDLE", original_limit)
+    prepare_activation(settings, value)
+    outside = settings.resolved_data_dir.parent / "outside"
+    outside.mkdir()
+    (settings.resolved_data_dir / "recovery-archive").symlink_to(
+        outside, target_is_directory=True
+    )
+    with pytest.raises(ActivationError, match="archive path is unsafe"):
+        _apply(settings)
+    assert list(outside.iterdir()) == []
+    assert installed(settings) == before
+
+
+def test_connection_edit_after_confirmation_stops_before_catalog_replacement(settings):
+    before = catalog(settings)
+    prepare_activation(settings, candidate(before))
+    changed = ManagedDocument(
+        revision=1,
+        api_id=44444,
+        api_hash=SecretStr("e" * 32),
+        clients=[
+            ManagedClient(
+                id="changed-bot",
+                label="Changed",
+                kind="bot",
+                credential=SecretStr(OLD_BOT),
+            )
+        ],
+    )
+    save_document(settings.resolved_data_dir, changed, 0)
+    with pytest.raises(ActivationError, match="Connection settings changed"):
+        _apply(settings)
+    assert installed(settings) == before
+    assert not (settings.resolved_data_dir / "recovery-archive").exists()
+
+
+def test_full_historical_connection_list_is_archived_without_auto_enabling_it(settings):
+    value = candidate(catalog(settings))
+    historical = ManagedDocument(
+        revision=1,
+        api_id=12345,
+        api_hash=SecretStr("a" * 32),
+        clients=[
+            ManagedClient(
+                id=f"old-bot-{i}",
+                label=f"Former bot {i}",
+                kind="bot",
+                credential=SecretStr(str(100000 + i) + ":" + "a" * 24),
+            )
+            for i in range(50)
+        ],
+    )
+    value["credentials"]["managed_document"] = json.loads(historical.private_bytes())
+    prepare_activation(settings, value)
+    assert _apply(settings)
+    saved = read_document(settings.resolved_data_dir)
+    assert len(saved.clients) == 50
+    assert sum(row.enabled for row in saved.clients) == 1
+    manifest = json.loads(read_private(settings.resolved_data_dir / MANIFEST))
+    assert (
+        len(manifest["candidate"]["credentials"]["managed_document"]["clients"]) == 50
+    )
diff --git a/tests/replication/test_replica_activation_mongodb.py b/tests/replication/test_replica_activation_mongodb.py
new file mode 100644
index 00000000..c32a5abd
--- /dev/null
+++ b/tests/replication/test_replica_activation_mongodb.py
@@ -0,0 +1,358 @@
+"""Activation checks on an opt-in, disposable real MongoDB replica set."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+import secrets
+from types import SimpleNamespace
+
+import pytest
+from pydantic import SecretStr
+
+from tgdrive.core.config import Settings
+from tgdrive.replication.replica_activation import (
+    MANIFEST,
+    ActivationError,
+    apply_activation,
+    effective_settings,
+    prepare_activation,
+)
+from tgdrive.replication.replica_settings import collect_credentials
+from tgdrive.replication.replica_state import read_private, remap_catalog
+from tgdrive.settings.managed_settings import (
+    ManagedClient,
+    ManagedDocument,
+    read_document,
+    save_document,
+)
+from tgdrive.settings.performance_preferences import PerformancePreferences
+from tgdrive.storage.mongo import configure
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.web.share_links import token_factory
+
+pytestmark = pytest.mark.skipif(
+    os.environ.get("TGDRIVE_MONGO_TESTS") != "1",
+    reason="Set TGDRIVE_MONGO_TESTS=1 for isolated live MongoDB checks",
+)
+
+OLD = -100111222
+NEW = -100333444
+OLD_BOT = "12345:" + "a" * 24
+NEW_BOT = "54321:" + "b" * 24
+BACKUP_BOT = "67890:" + "c" * 24
+
+
+def node_path(row):
+    return row["path"].rstrip("/") + "/" + row["id"]
+
+
+@pytest.fixture
+def deployment(tmp_path):
+    uri = os.environ.get("TGDRIVE_TEST_MONGODB_URI")
+    if not uri:
+        raise pytest.UsageError(
+            "Set TGDRIVE_TEST_MONGODB_URI to an isolated replica set"
+        )
+    name = "tgdrive_test_activation_" + secrets.token_hex(6)
+    directory = tmp_path / "private-data"
+    backend = configure(directory, uri, name)
+    backend.acquire()
+    try:
+        settings = Settings(
+            _env_file=None,
+            MONGODB_URI=uri,
+            MONGODB_DATABASE=name,
+            DATA_DIR=directory,
+            CACHE_DIR=tmp_path / "cache",
+            API_ID=12345,
+            API_HASH="a" * 32,
+            BOT_TOKENS=OLD_BOT,
+            STORAGE_CHANNEL=OLD,
+            ADMIN_PASSWORD="synthetic recovery owner password",
+            SESSION_SECRET="s" * 40,
+            MONGODB_BACKUP_KEY="e" * 64,
+        )
+        store = MongoStore.create(backend)
+        store.bind_storage_channel(OLD)
+        folder = store.create_folder("/", "Projects")
+        parts = [
+            {
+                "index": 0,
+                "offset": 0,
+                "size": 3,
+                "message_id": 101,
+                "sha256": hashlib.sha256(b"abc").hexdigest(),
+            },
+            {
+                "index": 1,
+                "offset": 3,
+                "size": 3,
+                "message_id": 102,
+                "sha256": hashlib.sha256(b"def").hexdigest(),
+            },
+        ]
+        item = store.add_file(
+            node_path(folder),
+            "split.bin",
+            101,
+            6,
+            parts=parts,
+            sha256=hashlib.sha256(b"abcdef").hexdigest(),
+            operation_id="source-receipt",
+        )
+        store.set_starred(node_path(item), True)
+        store.set_starred(node_path(folder), True)
+        tokens = [
+            store.create_share(
+                node_path(item), label=label, token_factory=token_factory(settings)
+            )
+            for label in ("Review", "External")
+        ]
+        old = store.export()
+        store.close()
+        document = ManagedDocument(
+            revision=1,
+            api_id=12345,
+            api_hash=SecretStr("a" * 32),
+            clients=[
+                ManagedClient(
+                    id="original-bot",
+                    label="Original bot",
+                    kind="bot",
+                    credential=SecretStr(OLD_BOT),
+                )
+            ],
+        )
+        save_document(directory, document, 0)
+        backend.write(
+            backend.db.settings,
+            "replace_one",
+            {"_id": "bootstrap"},
+            {
+                "_id": "bootstrap",
+                "document": {"STORAGE_CHANNEL": OLD, "SESSION_SECRET": "s" * 40},
+            },
+            upsert=True,
+        )
+        for identity, value in (
+            (
+                "performance-preferences",
+                PerformancePreferences(timezone="UTC").model_dump(),
+            ),
+            ("transfer-preferences", {"uploads_per_bot": 2}),
+        ):
+            backend.write(
+                backend.db.settings,
+                "replace_one",
+                {"_id": identity},
+                {"_id": identity, "document": value},
+                upsert=True,
+            )
+        backend.write(
+            backend.db.jobs,
+            "insert_one",
+            {"_id": "old-running-job", "status": "running", "message_id": 101},
+        )
+        backend.write(
+            backend.db.receipts,
+            "insert_one",
+            {"_id": "old-receipt", "message_ids": [101, 102]},
+        )
+        backend.write(
+            backend.db.backups,
+            "insert_one",
+            {"_id": "old-checkpoint", "channel_id": OLD, "revision": old["revision"]},
+        )
+        credentials = collect_credentials(settings, SimpleNamespace(mongo=backend))
+        credentials["bot_tokens"] = [NEW_BOT]
+        recovered = remap_catalog(old, NEW, {"101": 1101, "102": 1102})
+        candidate = {
+            "catalog": recovered,
+            "credentials": credentials,
+            "complete": True,
+            "token": BACKUP_BOT,
+            "key": "f" * 64,
+        }
+        yield SimpleNamespace(
+            settings=settings,
+            backend=backend,
+            original=old,
+            candidate=candidate,
+            item=item,
+            tokens=tokens,
+        )
+    finally:
+        backend.release()
+        assert backend.db.name == name and name.startswith("tgdrive_test_activation_")
+        backend.client.drop_database(name)
+        backend.client.close()
+
+
+def test_live_mongo_catalog_preferences_and_credentials_commit_together(deployment):
+    row = deployment
+    identity = prepare_activation(row.settings, row.candidate)
+    pending = effective_settings(row.settings)
+    assert pending.storage_channel == NEW and pending.bot_tokens == (NEW_BOT,)
+    assert apply_activation(pending, row.backend)
+    store = MongoStore(row.backend)
+    payload = store.export()
+    assert payload == row.candidate["catalog"]
+    file = store.get_file(node_path(row.item))
+    assert file["message_id"] == 1101
+    assert [part["message_id"] for part in file["parts"]] == [1101, 1102]
+    assert file["sha256"] == hashlib.sha256(b"abcdef").hexdigest()
+    assert file["starred"] is True
+    assert all(store.authorize_file(node_path(row.item), token) for token in row.tokens)
+    assert {link["label"] for link in store.list_shares()} == {"Review", "External"}
+    store.close()
+    assert row.backend.db.jobs.count_documents({}) == 0
+    assert row.backend.db.receipts.count_documents({}) == 0
+    assert row.backend.db.operations.count_documents({}) == 0
+    assert row.backend.db.backups.count_documents({}) == 0
+    document = read_document(row.settings.resolved_data_dir)
+    assert [
+        client.credential.get_secret_value()
+        for client in document.clients
+        if client.enabled
+    ] == [NEW_BOT]
+    assert (
+        next(
+            client for client in document.clients if client.id == "original-bot"
+        ).enabled
+        is False
+    )
+    assert (
+        row.backend.db.settings.find_one({"_id": "performance-preferences"})[
+            "document"
+        ]["timezone"]
+        == "UTC"
+    )
+    assert row.backend.db.settings.find_one({"_id": "transfer-preferences"})[
+        "document"
+    ] == {"uploads_per_bot": 2}
+    archive = (
+        row.settings.resolved_data_dir
+        / "recovery-archive"
+        / identity
+        / "mongodb-before.json"
+    )
+    saved = json.loads(read_private(archive))
+    assert saved["jobs"][0]["_id"] == "old-running-job"
+    assert saved["catalog"][0]["storage_channel_id"] == OLD
+    assert archive.stat().st_mode & 0o777 == 0o600
+    assert not list(row.settings.resolved_data_dir.glob("*.sqlite3"))
+    assert not (row.settings.resolved_data_dir / "telegram-settings.json").exists()
+    assert not apply_activation(pending, row.backend)
+
+
+def test_live_mongo_aborted_catalog_write_rolls_back_files_settings_and_jobs(
+    deployment, monkeypatch
+):
+    row = deployment
+    prepare_activation(row.settings, row.candidate)
+    before = MongoStore(row.backend).export()
+    settings_before = list(row.backend.db.settings.find({}))
+    from pymongo.synchronous.collection import Collection
+
+    original = Collection.replace_one
+    once = True
+
+    def interrupt(collection, query, replacement, **kwargs):
+        nonlocal once
+        result = original(collection, query, replacement, **kwargs)
+        if (
+            once
+            and collection.database.name == row.backend.db.name
+            and collection.name == "catalog"
+            and replacement.get("replica_activation_id")
+        ):
+            once = False
+            raise RuntimeError("synthetic transaction interruption")
+        return result
+
+    monkeypatch.setattr(Collection, "replace_one", interrupt)
+    with pytest.raises(RuntimeError, match="transaction interruption"):
+        apply_activation(row.settings, row.backend)
+    assert MongoStore(row.backend).export() == before
+    assert list(row.backend.db.settings.find({})) == settings_before
+    assert row.backend.db.jobs.find_one({"_id": "old-running-job"})
+    assert row.backend.db.receipts.find_one({"_id": "old-receipt"})
+    assert (
+        json.loads(read_private(row.settings.resolved_data_dir / MANIFEST))["phase"]
+        == "installing"
+    )
+    assert apply_activation(row.settings, row.backend)
+    assert MongoStore(row.backend).storage_channel_id == NEW
+
+
+def test_live_mongo_lost_commit_reply_reuses_marker_and_preserves_later_revision(
+    deployment, monkeypatch
+):
+    row = deployment
+    prepare_activation(row.settings, row.candidate)
+    transaction = row.backend.transaction
+    once = True
+
+    def lose_reply(operation):
+        nonlocal once
+        result = transaction(operation)
+        if once and operation.__name__ == "replace":
+            once = False
+            raise RuntimeError("synthetic lost commit reply")
+        return result
+
+    monkeypatch.setattr(row.backend, "transaction", lose_reply)
+    with pytest.raises(RuntimeError, match="lost commit reply"):
+        apply_activation(row.settings, row.backend)
+    metadata = row.backend.db.catalog.find_one({"_id": "catalog"})
+    assert metadata["storage_channel_id"] == NEW
+    assert metadata["replica_activation_id"]
+    assert row.backend.db.settings.find_one({"_id": "telegram"})["revision"] == 2
+    assert apply_activation(row.settings, row.backend)
+    assert (
+        row.backend.db.catalog.find_one({"_id": "catalog"})["generation"]
+        == metadata["generation"]
+    )
+    active = MongoStore(row.backend)
+    active.create_folder("/", "Created after recovery")
+    revision = active.revision
+    active.close()
+    assert not apply_activation(row.settings, row.backend)
+    assert MongoStore(row.backend).revision == revision
+
+
+def test_live_mongo_foreign_or_changed_catalog_cannot_be_overwritten(deployment):
+    row = deployment
+    foreign = copy.deepcopy(row.candidate)
+    foreign["catalog"]["drive_id"] = "different-drive"
+    with pytest.raises(ActivationError, match="different drive"):
+        prepare_activation(row.settings, foreign)
+    prepare_activation(row.settings, row.candidate)
+    current = MongoStore(row.backend)
+    current.create_folder("/", "Newer owner work")
+    revision = current.revision
+    current.close()
+    with pytest.raises(ActivationError, match="metadata changed"):
+        apply_activation(row.settings, row.backend)
+    assert MongoStore(row.backend).revision == revision
+    assert row.backend.db.jobs.find_one({"_id": "old-running-job"})
+
+
+def test_live_mongo_same_channel_database_recovery_preserves_share_secret(deployment):
+    row = deployment
+    original = copy.deepcopy(row.candidate)
+    original["catalog"] = copy.deepcopy(row.original)
+    prepare_activation(row.settings, original)
+    active = effective_settings(row.settings)
+    assert active.storage_channel == OLD
+    assert active.session_key == row.settings.session_key
+    assert apply_activation(active, row.backend)
+    reopened = MongoStore(row.backend)
+    assert reopened.get_file(node_path(row.item))["message_id"] == 101
+    assert all(
+        reopened.authorize_file(node_path(row.item), token) for token in row.tokens
+    )
+    reopened.close()
diff --git a/tests/replication/test_replica_api.py b/tests/replication/test_replica_api.py
new file mode 100644
index 00000000..0f7d040b
--- /dev/null
+++ b/tests/replication/test_replica_api.py
@@ -0,0 +1,239 @@
+"""Recovery remains owner-only and reachable when the live catalog is missing."""
+
+import json
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.core.test_runtime import mongo_backend as mongo_backend
+from tests.replication.test_replica import TOKEN, Telegram
+from tests.replication.test_replica_activation import NEW, candidate
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.errors import CorruptStoreError
+from tgdrive.core.runtime import Runtime
+from tgdrive.replication.replica import ChannelReplica
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+
+@pytest.fixture
+def owner(tmp_path, monkeypatch):
+    settings = make_settings(tmp_path)
+    backend = register_test_backend(monkeypatch, settings)
+    monkeypatch.setattr("tgdrive.storage.mongo.for_settings", lambda _: backend)
+    store = DriveStore.create(tmp_path / "catalog.sqlite3")
+    store.bind_storage_channel(settings.storage_channel)
+    runtime = FakeRuntime(store)
+    runtime.mongo = backend
+    remote = Telegram()
+    replica = ChannelReplica(settings, runtime, transport_factory=remote.factory)
+    runtime.replica = replica
+    original_stop = runtime.stop
+
+    async def stop():
+        await replica.close()
+        await original_stop()
+
+    runtime.stop = stop
+    with TestClient(
+        create_app(settings, runtime=runtime), base_url="https://testserver"
+    ) as client:
+        yield client, runtime, replica
+    store.close()
+
+
+def test_replica_is_owner_only_and_cross_origin_mutations_are_rejected(owner):
+    client, _, _ = owner
+    for path in ("", "/key", "/report"):
+        assert client.get("/api/v1/replica" + path).status_code == 401
+    login(client)
+    response = client.post(
+        "/api/v1/replica/configure",
+        json={
+            "channel_id": -100222333444,
+            "bot_token": TOKEN,
+            "independent_accounts": True,
+        },
+        headers={"Origin": "https://foreign.example"},
+    )
+    assert response.status_code == 403
+
+
+def test_status_and_reports_never_expose_private_replica_credentials(owner):
+    client, _, replica = owner
+    replica.journal.set(
+        "config", {"channel": -100222333444, "token": TOKEN, "enabled": False}
+    )
+    replica.journal.set("candidate", None)
+    login(client)
+    for path in ("", "/report"):
+        response = client.get("/api/v1/replica" + path)
+        assert response.status_code == 200
+        assert TOKEN not in response.text
+        assert replica.key() not in response.text
+    response = client.get("/api/v1/replica/key")
+    assert response.status_code == 200
+    assert response.json()["key"] == replica.key()
+    assert response.headers["cache-control"] == "no-store"
+
+
+def test_recovery_blocks_file_mutations_but_keeps_owner_controls_available(owner):
+    client, _, replica = owner
+    replica.journal.set("recovery", {"target": -100222333444})
+    login(client)
+    assert (
+        client.post(
+            "/api/createNewFolder", json={"path": "/", "name": "unsafe"}
+        ).status_code
+        == 409
+    )
+    assert client.post("/api/v1/backup", json={}).status_code == 409
+    assert client.get("/api/v1/replica").status_code == 200
+    assert client.post("/api/logout", json={}).status_code == 200
+
+
+def test_request_validation_hides_rejected_secrets_and_no_unverified_activation(owner):
+    client, _, _ = owner
+    login(client)
+    response = client.post(
+        "/api/v1/replica/configure",
+        json={
+            "channel_id": "private-token-that-must-not-echo",
+            "bot_token": TOKEN,
+            "independent_accounts": True,
+        },
+    )
+    assert response.status_code == 422
+    assert TOKEN not in response.text
+    assert "private-token" not in response.text
+    assert (
+        client.post("/api/v1/replica/recover", json={"activate": True}).status_code
+        == 409
+    )
+
+
+@pytest.mark.parametrize("confirmation", [None, "", "-100999888777"])
+def test_activation_requires_pending_destination_and_preserves_plan_on_failure(
+    owner, confirmation
+):
+    client, runtime, replica = owner
+    runtime.store.add_file("/", "preserved.bin", 123, 42)
+    pending = candidate(runtime.store.export())
+    replica.journal.set("candidate", pending)
+    recovery = {"target": NEW, "phase": "ready_to_activate"}
+    replica.journal.set("recovery", recovery)
+    manifest = replica.settings.resolved_data_dir / "channel-activation.json"
+    original_catalog = runtime.store.export()
+    login(client)
+
+    payload = {"activate": True, "target_channel": -100999888777}
+    if confirmation is not None:
+        payload["confirm_channel"] = confirmation
+    rejected = client.post("/api/v1/replica/recover", json=payload)
+    assert rejected.status_code == 422
+    assert "confirm activation" in rejected.json()["detail"]
+    assert replica.journal.get("candidate") == pending
+    assert replica.journal.get("recovery") == recovery
+    assert not replica.journal.get("activation")
+    assert not manifest.exists()
+    assert runtime.store.export() == original_catalog
+
+    accepted = client.post(
+        "/api/v1/replica/recover",
+        json={"activate": True, "confirm_channel": str(NEW)},
+    )
+    assert accepted.status_code == 200
+    assert accepted.json()["phase"] == "restart_required"
+    assert replica.journal.get("activation") is True
+    assert replica.journal.get("candidate") == pending
+    assert replica.journal.get("recovery") == recovery
+    assert (
+        json.loads(manifest.read_text())["candidate"]["catalog"]["storage_channel_id"]
+        == NEW
+    )
+    assert runtime.store.export() == original_catalog
+
+
+def test_matching_destination_cannot_activate_incomplete_recovery(owner):
+    client, runtime, replica = owner
+    pending = candidate(runtime.store.export())
+    pending["complete"] = False
+    replica.journal.set("candidate", pending)
+    login(client)
+    response = client.post(
+        "/api/v1/replica/recover",
+        json={"activate": True, "confirm_channel": str(NEW)},
+    )
+    assert response.status_code == 409
+    assert replica.journal.get("candidate") == pending
+    assert not replica.journal.get("activation")
+    assert not (replica.settings.resolved_data_dir / "channel-activation.json").exists()
+
+
+def test_missing_catalog_starts_authenticated_recovery_shell_without_telegram_writes(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    runtime = Runtime(settings)
+    runtime.backup.restore = AsyncMock(
+        side_effect=CorruptStoreError(
+            "Saved MongoDB catalog requires explicit recovery"
+        )
+    )
+    with TestClient(
+        create_app(settings, runtime=runtime), base_url="https://testserver"
+    ) as client:
+        assert not runtime.ready
+        assert runtime.recovery_only
+        assert runtime.store is None
+        assert runtime.transfers is None
+        assert client.get("/").status_code == 200
+        assert client.get("/api/config").json()["recovery_only"] is True
+        assert client.get("/api/v1/replica").status_code == 401
+        login(client)
+        assert client.get("/api/v1/status").json()["recovery_only"] is True
+        assert client.get("/api/v1/replica").json()["recovery_only"] is True
+        assert client.post("/api/getDirectory", json={"path": "/"}).status_code == 409
+
+
+def test_mongo_ownership_unavailable_rejects_startup_without_local_fallback(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    runtime = Runtime(settings)
+
+    mongo_backend.acquire.side_effect = DatabaseUnavailable(
+        "synthetic offline database"
+    )
+    with (
+        pytest.raises(DatabaseUnavailable, match="synthetic offline database"),
+        TestClient(
+            create_app(settings, runtime=runtime), base_url="https://testserver"
+        ),
+    ):
+        pytest.fail("An unavailable database must reject application startup")
+    assert not runtime.ready
+    assert runtime.store is None and runtime.transfers is None
+    assert not runtime._mongo_acquired
+    assert runtime._owner_lock is None
+    assert not (settings.resolved_data_dir / "drive.sqlite3").exists()
+    mongo_backend.release.assert_not_called()
+
+
+def test_corrupt_activation_manifest_preserves_owner_recovery_shell(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    from tgdrive.replication.replica_state import atomic_private
+
+    atomic_private(settings.resolved_data_dir / "channel-activation.json", b"{}")
+    runtime = Runtime(settings)
+    with TestClient(
+        create_app(settings, runtime=runtime), base_url="https://testserver"
+    ) as client:
+        assert runtime.recovery_only and runtime.store is None
+        login(client)
+        assert client.get("/api/v1/replica").status_code == 200
diff --git a/tests/replication/test_replica_bootstrap.py b/tests/replication/test_replica_bootstrap.py
new file mode 100644
index 00000000..e236aebc
--- /dev/null
+++ b/tests/replication/test_replica_bootstrap.py
@@ -0,0 +1,70 @@
+"""Portable recovery credentials cannot bypass mandatory MongoDB access."""
+
+import json
+from types import SimpleNamespace
+
+import pytest
+from argon2 import PasswordHasher
+
+from tests.support.app_fixtures import make_settings
+from tgdrive.core.config import Settings
+from tgdrive.replication.replica_bootstrap import load_bootstrap, save_bootstrap
+from tgdrive.replication.replica_state import atomic_private
+from tgdrive.storage.mongo import DatabaseUnavailable
+
+
+def test_bootstrap_contains_valid_credentials_and_only_a_password_hash(tmp_path):
+    settings = make_settings(tmp_path)
+    save_bootstrap(settings)
+    path = settings.resolved_data_dir / "replica-bootstrap.json"
+    assert path.stat().st_mode & 0o777 == 0o600
+    assert settings.admin_password.get_secret_value() not in path.read_text()
+    values = load_bootstrap(
+        settings.resolved_data_dir,
+        mongodb_uri=settings.mongodb_uri,
+        mongodb_database=settings.mongodb_database,
+    )
+    assert PasswordHasher().verify(
+        values["ADMIN_PASSWORD_HASH"], settings.admin_password.get_secret_value()
+    )
+    assert values["SESSION_SECRET"] == settings.session_secret.get_secret_value()
+    assert "MONGODB_URI" not in values
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [{"version": 2, "settings": {}}, {"version": 1, "settings": {}, "extra": True}],
+)
+def test_bootstrap_rejects_unrecognized_shapes(tmp_path, payload):
+    atomic_private(tmp_path / "replica-bootstrap.json", json.dumps(payload).encode())
+    with pytest.raises(ValueError, match="Invalid private recovery bootstrap"):
+        load_bootstrap(tmp_path, mongodb_uri="mongodb://synthetic.invalid/tgdrive")
+
+
+def test_private_bootstrap_cannot_start_without_mongodb(tmp_path, monkeypatch):
+    settings = make_settings(tmp_path)
+    save_bootstrap(settings)
+
+    def unavailable(_query):
+        raise RuntimeError("database unavailable")
+
+    backend = SimpleNamespace(
+        db=SimpleNamespace(settings=SimpleNamespace(find_one=unavailable))
+    )
+    monkeypatch.setattr("tgdrive.storage.mongo.configure", lambda *_args: backend)
+    for name in (
+        "API_ID",
+        "API_HASH",
+        "BOT_TOKENS",
+        "STORAGE_CHANNEL",
+        "SESSION_SECRET",
+        "ADMIN_PASSWORD_HASH",
+        "ADMIN_PASSWORD",
+    ):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setenv("API_HASH", "")
+    monkeypatch.setenv("DATA_DIR", str(settings.resolved_data_dir))
+    monkeypatch.setenv("CACHE_DIR", str(settings.resolved_cache_dir))
+    monkeypatch.setenv("MONGODB_URI", "mongodb://synthetic.invalid/tgdrive")
+    with pytest.raises(DatabaseUnavailable, match="MongoDB is unavailable"):
+        Settings(_env_file=None)
diff --git a/tests/replication/test_replica_deletion_barrier.py b/tests/replication/test_replica_deletion_barrier.py
new file mode 100644
index 00000000..3d5691ef
--- /dev/null
+++ b/tests/replication/test_replica_deletion_barrier.py
@@ -0,0 +1,152 @@
+"""Catalog removal preserves originals and the independent backup barrier."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tests.replication.test_replica import BACKUP, remote_bundle, setup
+from tests.replication.test_replica import replica_backend as replica_backend
+from tests.transfers.test_durable_jobs import Telegram, manager_for
+from tests.transfers.test_durable_jobs import mongo_backend as mongo_backend
+from tgdrive.replication.replica_state import files_in, parts_in
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.tasks import TransferStatus
+
+pytestmark = pytest.mark.usefixtures("mongo_backend", "replica_backend")
+
+
+async def cleanup(manager, pool, replica=None):
+    await manager.close()
+    manager.registry.close()
+    if replica is not None:
+        await replica.close()
+    manager.store.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_catalog_delete_waits_for_backup_and_retains_original_messages(
+    tmp_path,
+):
+    configured, store, remote, replica, _ = setup(tmp_path)
+    telegram = Telegram()
+    telegram.messages[77] = SimpleNamespace(id=77)
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool, store=store)
+    manager.settings.storage_channel = configured.storage_channel
+    manager._ensure_replica = replica.before_mutation
+    node = next(files_in(store.export()))
+    path = store.resolve_id(node["id"])
+    store.set_trashed(path, True)
+    original_finish = store.finish_deletion
+
+    def checked_finish(intent_id):
+        # The catalog subtree cannot disappear before its restore point exists.
+        assert replica.journal.get("restore_point")
+        copied = next(files_in(remote_bundle(remote, replica)["replica_catalog"]))
+        assert remote.messages[BACKUP, copied["message_id"]] == b"abc"
+        return original_finish(intent_id)
+
+    store.finish_deletion = checked_finish
+    try:
+        job = await manager.start_deletion(path)
+        await job.task
+        assert job.status is TransferStatus.COMPLETED
+        assert telegram.deleted == [] and 77 in telegram.messages
+        assert remote.messages[configured.storage_channel, 77] == b"abc"
+        assert store.list_trash() == {}
+        copied = next(files_in(remote_bundle(remote, replica)["replica_catalog"]))
+        assert copied["trashed"]
+        assert remote.messages[BACKUP, parts_in(copied)[0]["message_id"]] == b"abc"
+        assert store.pending_deletions() == []
+    finally:
+        await cleanup(manager, pool, replica)
+
+
+@pytest.mark.asyncio
+async def test_paused_backup_prevents_permanent_delete_and_retry_preserves_intent(
+    tmp_path,
+):
+    configured, store, remote, replica, _ = setup(tmp_path)
+    telegram = Telegram()
+    telegram.messages[77] = SimpleNamespace(id=77)
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool, store=store)
+    manager.settings.storage_channel = configured.storage_channel
+    manager._ensure_replica = replica.before_mutation
+    path = store.resolve_id(next(files_in(store.export()))["id"])
+    store.set_trashed(path, True)
+    replica.update(phase="paused")
+    try:
+        job = await manager.start_deletion(path)
+        await job.task
+        assert job.status is TransferStatus.ERROR
+        assert telegram.deleted == [] and 77 in telegram.messages
+        assert store.pending_deletions()[0]["pending_message_ids"] == [77]
+        assert not remote.pins
+        replica.update(phase="idle")
+        retry = await manager.retry_job(job.id)
+        await retry.task
+        assert retry.status is TransferStatus.COMPLETED
+        assert telegram.deleted == [] and 77 in telegram.messages
+        assert replica.journal.get("restore_point")
+    finally:
+        await cleanup(manager, pool, replica)
+
+
+@pytest.mark.asyncio
+async def test_unavailable_backup_blocks_delete_without_erasing_main_or_its_refs(
+    tmp_path,
+):
+    _, store, _, replica, _ = setup(tmp_path)
+    telegram = Telegram()
+    telegram.messages[77] = SimpleNamespace(id=77)
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool, store=store)
+    path = store.resolve_id(next(files_in(store.export()))["id"])
+    store.set_trashed(path, True)
+    manager._ensure_replica = AsyncMock(
+        side_effect=SettingsProblem("Independent copy is not confirmed.", status=503)
+    )
+    try:
+        job = await manager.start_deletion(path)
+        await job.task
+        assert job.status is TransferStatus.ERROR
+        manager._ensure_replica.assert_awaited_once()
+        assert job.phase == "checking_backup"
+        assert not telegram.deleted
+        assert store.pending_deletions()[0]["pending_message_ids"] == [77]
+        assert manager.store.message_ids(path, include_trashed=True) == [77]
+    finally:
+        await cleanup(manager, pool, replica)
+
+
+@pytest.mark.asyncio
+async def test_background_backup_does_not_block_normal_upload_completion(tmp_path):
+    telegram = Telegram()
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    manager._ensure_replica = AsyncMock(
+        side_effect=SettingsProblem("Backup is paused.", status=409)
+    )
+    source = tmp_path / "payload.part"
+    source.write_bytes(b"normal foreground upload")
+    try:
+        job = await manager.enqueue_upload(
+            source, "/", "new.bin", source.stat().st_size
+        )
+        await job.task
+        assert job.status is TransferStatus.COMPLETED
+        manager._ensure_replica.assert_not_called()
+        assert len(manager.store.list_directory("/")) == 1
+        assert len(telegram.messages) == 1
+    finally:
+        await cleanup(manager, pool)
diff --git a/tests/replication/test_replica_mongo.py b/tests/replication/test_replica_mongo.py
new file mode 100644
index 00000000..75cd0839
--- /dev/null
+++ b/tests/replication/test_replica_mongo.py
@@ -0,0 +1,273 @@
+"""Independent full MongoDB archive replication; no actual credentials/network."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from pydantic import SecretStr
+
+from tests.replication.test_replica import BACKUP, dispose, setup
+from tests.replication.test_replica import replica_backend as replica_backend
+from tgdrive.replication.replica_mongo import mirror_mongodb
+from tgdrive.replication.replica_transport import ReplicaTransportError
+from tgdrive.settings.managed_settings import SettingsProblem
+
+pytestmark = pytest.mark.usefixtures("replica_backend")
+
+
+class Snapshot:
+    def __init__(self, configured, store, remote):
+        self.count = 0
+        self.rows = []
+        self.configured, self.store, self.remote = configured, store, remote
+
+    async def snapshot_now(self, store):
+        self.count += 1
+        self.remote.messages[self.configured.storage_channel, 900] = (
+            b"encrypted full MongoDB database"
+        )
+        self.rows = [
+            {
+                "id": "full-mongo-snapshot",
+                "status": "confirmed",
+                "channel_id": self.configured.storage_channel,
+                "message_id": 900,
+                "format": "mongodb-encrypted-v1",
+                "revision": store.revision,
+                "sha256": "a" * 64,
+                "created_at": "2026-10-22T10:00:00Z",
+            }
+        ]
+        return True
+
+    def history(self, *, limit=None):
+        return self.rows
+
+
+class Pool:
+    def __init__(self, remote):
+        self.remote = remote
+
+    @asynccontextmanager
+    async def lease(self):
+        async def get(channel, *, message_ids):
+            body = self.remote.messages.get((channel, message_ids))
+            return SimpleNamespace(
+                document=SimpleNamespace(
+                    file_size=len(body) if body is not None else None,
+                    file_name="tgdrive-full-mongo-snapshot.tgdb",
+                )
+            )
+
+        yield SimpleNamespace(get_messages=get)
+
+
+@pytest.mark.asyncio
+async def test_no_mongodb_installation_never_requests_snapshot(tmp_path):
+    _, store, _, replica, _ = setup(tmp_path)
+    replica.runtime.mongo = None
+    try:
+        assert (
+            await mirror_mongodb(
+                replica,
+                None,
+                source_channel=replica.settings.storage_channel,
+                destination_channel=BACKUP,
+            )
+            is None
+        )
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_missing_key_blocks_without_changing_other_backup_settings(tmp_path):
+    _, store, _, replica, _ = setup(tmp_path)
+    replica.runtime.mongo = object()
+    replica.runtime.backup = SimpleNamespace(snapshot_now=AsyncMock())
+    try:
+        with pytest.raises(SettingsProblem) as error:
+            await mirror_mongodb(
+                replica,
+                None,
+                source_channel=replica.settings.storage_channel,
+                destination_channel=BACKUP,
+            )
+        assert error.value.code == "REPLICA_MONGODB_KEY_REQUIRED"
+        replica.runtime.backup.snapshot_now.assert_not_called()
+        assert replica.settings.mongodb_backup_key is None
+    finally:
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_full_archive_retry_keeps_source_ciphertext_and_operation(
+    tmp_path,
+):
+    configured, store, remote, replica, _ = setup(tmp_path)
+    configured.mongodb_backup_key = SecretStr("b2" * 32)
+    replica.runtime.mongo = object()
+    service = Snapshot(configured, store, remote)
+    replica.runtime.backup, replica.runtime.pool = service, Pool(remote)
+    transport = remote.factory(configured, "234567:" + "b" * 24)
+    await transport.start()
+    try:
+        remote.lose_response = True
+        with pytest.raises(ReplicaTransportError):
+            await mirror_mongodb(
+                replica,
+                transport,
+                source_channel=configured.storage_channel,
+                destination_channel=BACKUP,
+                revision=store.revision,
+            )
+        assert service.count == 1
+        result = await mirror_mongodb(
+            replica,
+            transport,
+            source_channel=configured.storage_channel,
+            destination_channel=BACKUP,
+            revision=store.revision,
+        )
+        assert service.count == 1, (
+            "The chosen confirmed ciphertext must survive retries"
+        )
+        assert result["format"] == "mongodb-encrypted-v1"
+        assert result["source_message_id"] == 900
+        assert result["replica_channel"] == BACKUP
+        assert (
+            remote.messages[BACKUP, result["replica_message_id"]]
+            == remote.messages[configured.storage_channel, 900]
+        )
+        attempts = [call for call in remote.calls if call[0] == "copy"]
+        assert len(attempts) == 2 and attempts[0][-1] == attempts[1][-1]
+        await mirror_mongodb(
+            replica,
+            transport,
+            source_channel=configured.storage_channel,
+            destination_channel=BACKUP,
+            revision=store.revision,
+        )
+        assert len([call for call in remote.calls if call[0] == "copy"]) == 2
+        assert any(call[0] == "verify" for call in remote.calls)
+    finally:
+        await transport.close()
+        await dispose(replica, store)
+
+
+@pytest.mark.asyncio
+async def test_same_catalog_with_changed_settings_gets_a_fresh_full_snapshot(tmp_path):
+    configured, store, remote, replica, _ = setup(tmp_path)
+    configured.mongodb_backup_key = SecretStr("b2" * 32)
+    replica.runtime.mongo = object()
+    service = Snapshot(configured, store, remote)
+    replica.runtime.backup, replica.runtime.pool = service, Pool(remote)
+    transport = remote.factory(configured, "234567:" + "b" * 24)
+    await transport.start()
+    revision = store.revision
+    try:
+        for fingerprint, expected in [("a1" * 32, 1), ("a1" * 32, 1), ("b2" * 32, 2)]:
+            await mirror_mongodb(
+                replica,
+                transport,
+                source_channel=configured.storage_channel,
+                destination_channel=BACKUP,
+                revision=revision,
+                settings_fingerprint=fingerprint,
+            )
+            assert service.count == expected
+            assert store.revision == revision
+        # An older generation remains replayable; switching back does not
+        # overwrite either durable snapshot selection or request a third one.
+        await mirror_mongodb(
+            replica,
+            transport,
+            source_channel=configured.storage_channel,
+            destination_channel=BACKUP,
+            revision=revision,
+            settings_fingerprint="a1" * 32,
+        )
+        assert service.count == 2
+        with pytest.raises(SettingsProblem, match="fingerprint"):
+            await mirror_mongodb(
+                replica,
+                transport,
+                source_channel=configured.storage_channel,
+                destination_channel=BACKUP,
+                settings_fingerprint="not-a-digest",
+            )
+        assert service.count == 2
+    finally:
+        await transport.close()
+        await dispose(replica, store)
+
+
+def test_pending_mongo_ciphertext_must_match_current_recovery_key(tmp_path):
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+    from tests.support.recovery_fixtures import settings
+    from tgdrive.recovery.mongo_backup import MAGIC
+    from tgdrive.replication.replica_mongo import _check_pending_key
+
+    configured = settings(tmp_path)
+    root = configured.resolved_cache_dir / "mongo-backups"
+    root.mkdir(parents=True)
+    path = root / "pending.tgdb"
+    nonce = b"n" * 12
+    key = "a1" * 32
+    path.write_bytes(
+        MAGIC
+        + nonce
+        + AESGCM(bytes.fromhex(key)).encrypt(nonce, b"compressed records", MAGIC)
+    )
+    snapshot = path.read_bytes()
+    service = SimpleNamespace(
+        backend=SimpleNamespace(
+            db=SimpleNamespace(
+                backups=SimpleNamespace(
+                    find_one=lambda *args, **kwargs: {"local_path": str(path)}
+                )
+            )
+        )
+    )
+    _check_pending_key(service, configured, key)
+    with pytest.raises(SettingsProblem) as error:
+        _check_pending_key(service, configured, "b2" * 32)
+    assert error.value.code == "REPLICA_MONGODB_KEY_MISMATCH"
+    assert path.read_bytes() == snapshot
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("kind", ["flood", "network"])
+async def test_full_snapshot_errors_are_retryable_and_never_echo_provider_secrets(
+    tmp_path, kind
+):
+    from tgdrive.recovery.backup import BackupError
+
+    configured, store, remote, replica, _ = setup(tmp_path)
+    configured.mongodb_backup_key = SecretStr("a1" * 32)
+    replica.runtime.mongo = object()
+    error = (
+        BackupError("credential=private", retry_after=123)
+        if kind == "flood"
+        else TimeoutError("credential=private")
+    )
+    replica.runtime.backup = SimpleNamespace(snapshot_now=AsyncMock(side_effect=error))
+    transport = remote.factory(configured, "234567:" + "b" * 24)
+    try:
+        with pytest.raises(ReplicaTransportError) as raised:
+            await mirror_mongodb(
+                replica,
+                transport,
+                source_channel=configured.storage_channel,
+                destination_channel=BACKUP,
+            )
+        assert raised.value.retryable
+        assert "credential=private" not in str(raised.value)
+        if kind == "flood":
+            assert raised.value.retry_after == 123
+    finally:
+        await dispose(replica, store)
diff --git a/tests/replication/test_replica_settings.py b/tests/replication/test_replica_settings.py
new file mode 100644
index 00000000..be431ea5
--- /dev/null
+++ b/tests/replication/test_replica_settings.py
@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import copy
+from types import SimpleNamespace
+
+import pytest
+from pydantic import SecretStr
+from pymongo.errors import ConnectionFailure
+
+from tests.support.mongo_fixtures import register_test_backend
+from tests.support.recovery_fixtures import settings
+from tgdrive.replication.replica_settings import (
+    collect_credentials,
+    validate_recovery_settings,
+)
+from tgdrive.settings.managed_settings import (
+    ManagedDocument,
+    initial_clients,
+    save_document,
+)
+from tgdrive.settings.performance_preferences import PerformancePreferences
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, settings(tmp_path))
+
+
+def test_settings_snapshot_keeps_managed_labels_sessions_and_safe_preferences(
+    tmp_path, mongo_backend
+):
+    configured = settings(tmp_path)
+    configured.mongodb_backup_key = SecretStr("a1" * 32)
+    configured.string_sessions_csv = SecretStr("syntheticPremiumSession")
+    document = ManagedDocument(
+        revision=3,
+        api_id=configured.api_id,
+        api_hash=configured.api_hash,
+        clients=initial_clients(configured),
+    )
+    document.clients[0].label = "Primary storage"
+    save_document(configured.resolved_data_dir, document, 0)
+    preferences = PerformancePreferences(
+        timezone="UTC", cache_memory_bytes=0
+    ).model_dump()
+    mongo_backend.db.settings.insert_many(
+        [
+            {"_id": "performance-preferences", "document": preferences},
+            {"_id": "transfer-preferences", "document": {"uploads_per_bot": 2}},
+        ]
+    )
+    credentials = collect_credentials(configured, SimpleNamespace(mongo=mongo_backend))
+    validate_recovery_settings(credentials)
+    assert credentials["managed_document"]["clients"][0]["label"] == "Primary storage"
+    assert (
+        credentials["managed_document"]["clients"][1]["credential"]
+        == "syntheticPremiumSession"
+    )
+    assert (
+        credentials["preferences"]["performance-preferences.json"]["timezone"] == "UTC"
+    )
+    assert credentials["preferences"]["transfer-preferences.json"] == {
+        "uploads_per_bot": 2
+    }
+    assert credentials["mongodb_backup_key"] == "a1" * 32
+    assert "mongodb_uri" not in credentials and "DATA_DIR" not in credentials
+
+
+def test_credentials_collector_bounds_and_validates_private_policy_files(
+    tmp_path, mongo_backend, monkeypatch
+):
+    configured = settings(tmp_path)
+    collection = mongo_backend.db.settings
+    collection.insert_one(
+        {"_id": "transfer-preferences", "document": {"uploads_per_bot": 99}}
+    )
+    runtime = SimpleNamespace(mongo=mongo_backend)
+    with pytest.raises(ValueError):
+        collect_credentials(configured, runtime)
+    collection.replace_one(
+        {"_id": "transfer-preferences"},
+        {"_id": "transfer-preferences", "document": {"oversized": "x" * 65536}},
+    )
+    with pytest.raises(ValueError):
+        collect_credentials(configured, runtime)
+
+    def unavailable(_query):
+        raise ConnectionFailure("synthetic database access failure")
+
+    monkeypatch.setattr(collection, "find_one", unavailable)
+    with pytest.raises(ConnectionFailure):
+        collect_credentials(configured, runtime)
+
+
+@pytest.mark.parametrize(
+    "damage",
+    [
+        "traversal",
+        "unknown-policy",
+        "missing-policy",
+        "invalid-value",
+        "coerced-api",
+        "coerced-enabled",
+    ],
+)
+def test_imported_settings_are_complete_allowlisted_and_strongly_typed(
+    tmp_path, damage, mongo_backend
+):
+    value = collect_credentials(
+        settings(tmp_path), SimpleNamespace(mongo=mongo_backend)
+    )
+    value = copy.deepcopy(value)
+    if damage == "traversal":
+        value["preferences"]["../secrets"] = {}
+    elif damage == "unknown-policy":
+        value["preferences"]["arbitrary.json"] = {}
+    elif damage == "missing-policy":
+        value["preferences"].pop("bot-preferences.json")
+    elif damage == "invalid-value":
+        value["preferences"]["transfer-preferences.json"] = {"uploads_per_bot": True}
+    elif damage == "coerced-api":
+        value["managed_document"]["api_id"] = True
+    else:
+        value["managed_document"]["clients"][0]["enabled"] = "yes"
+    with pytest.raises(ValueError):
+        validate_recovery_settings(value)
diff --git a/tests/replication/test_replica_state.py b/tests/replication/test_replica_state.py
new file mode 100644
index 00000000..ba7e1d0e
--- /dev/null
+++ b/tests/replication/test_replica_state.py
@@ -0,0 +1,456 @@
+"""Recovery envelope integrity and durable replica journal fault contracts."""
+
+from __future__ import annotations
+
+import copy
+import json
+import sqlite3
+import subprocess
+import sys
+import textwrap
+from types import SimpleNamespace
+
+import pytest
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from pydantic import SecretStr
+
+from tgdrive.replication.replica_settings import POLICIES
+from tgdrive.replication.replica_state import (
+    MAGIC,
+    ReplicaJournal,
+    atomic_private,
+    decode_bundle,
+    encode_bundle,
+    files_in,
+    parts_in,
+    read_private,
+    remap_catalog,
+)
+from tgdrive.settings.managed_settings import ManagedClient, ManagedDocument
+from tgdrive.storage.store import DriveStore
+
+MAIN = -1001234567890
+BACKUP = -1002234567890
+KEY = "a1" * 32
+
+
+def payload():
+    store = DriveStore.create()
+    try:
+        store.bind_storage_channel(MAIN)
+        folder = store.create_folder("/", "Records")
+        path = "/" + folder["id"]
+        first = store.add_file(path, "Report.txt", 11, 7)
+        store.add_file(path, "Second.txt", 12, 8)
+        store.set_starred(path + "/" + first["id"], True)
+        store.create_share(path, label="Team", expires_at=None)
+        catalog = store.export()
+    finally:
+        store.close()
+    mapping = {
+        str(part["message_id"]): part["message_id"] + 100
+        for node in files_in(catalog)
+        for part in parts_in(node)
+    }
+    return {
+        "format": "tgdrive-replica",
+        "version": 1,
+        "complete": True,
+        "created_at": "2026-10-22T10:00:00Z",
+        "catalog": catalog,
+        "replica_catalog": remap_catalog(catalog, BACKUP, mapping),
+        "credentials": {
+            "api_id": 12345,
+            "api_hash": "a" * 32,
+            "session_secret": "s" * 48,
+            "bot_tokens": ["123456:" + "x" * 30],
+            "managed_document": json.loads(
+                ManagedDocument(
+                    revision=1,
+                    api_id=12345,
+                    api_hash=SecretStr("a" * 32),
+                    clients=[
+                        ManagedClient(
+                            id="storage-bot",
+                            label="Storage bot",
+                            kind="bot",
+                            credential=SecretStr("123456:" + "x" * 30),
+                        )
+                    ],
+                ).private_bytes()
+            ),
+            "preferences": {
+                filename: model.model_validate(
+                    {"uploads_per_bot": 1}
+                    if filename == "transfer-preferences.json"
+                    else {}
+                ).model_dump()
+                for filename, model in POLICIES.items()
+            },
+        },
+    }
+
+
+def test_authenticated_roundtrip_retains_catalog_identity_shares_and_starred():
+    original = payload()
+    encrypted = encode_bundle(original, KEY)
+    assert encrypted.startswith(MAGIC) and b"session_secret" not in encrypted
+    assert b"Report.txt" not in encrypted
+    assert decode_bundle(encrypted, KEY) == original
+    assert decode_bundle(encrypted, "  " + KEY + "  ") == original
+
+
+@pytest.mark.parametrize("damage", [None, "source", "destination", "old-revision"])
+def test_full_database_archive_reference_binds_to_catalog_pair(damage):
+    value = payload()
+    revision = value["catalog"]["revision"]
+    archive = {
+        "format": "mongodb-encrypted-v1",
+        "id": "full-database-snapshot",
+        "revision": revision + 1,
+        "source_channel": MAIN,
+        "source_message_id": 90,
+        "replica_channel": BACKUP,
+        "replica_message_id": 190,
+        "size": 1024,
+        "sha256": "a" * 64,
+        "created_at": value["created_at"],
+    }
+    value["credentials"].update(mongodb_archive=archive, mongodb_backup_key=KEY)
+    if damage == "source":
+        archive["source_channel"] = -100999
+    elif damage == "destination":
+        archive["replica_channel"] = -100999
+    elif damage == "old-revision":
+        archive["revision"] = revision - 1
+    if damage is None:
+        assert decode_bundle(encode_bundle(value, KEY), KEY) == value
+    else:
+        with pytest.raises(ValueError, match="nothing changed"):
+            decode_bundle(encode_bundle(value, KEY), KEY)
+
+
+@pytest.mark.parametrize("damage", ["wrong-key", "truncated", "tampered", "not-bundle"])
+def test_key_or_archive_corruption_never_yields_a_catalog(damage):
+    encrypted = encode_bundle(payload(), KEY)
+    key = KEY
+    if damage == "wrong-key":
+        key = "b2" * 32
+    elif damage == "truncated":
+        encrypted = encrypted[:-1]
+    elif damage == "tampered":
+        encrypted = encrypted[:-1] + bytes([encrypted[-1] ^ 1])
+    else:
+        encrypted = b"not a backup"
+    with pytest.raises(ValueError, match="nothing changed"):
+        decode_bundle(encrypted, key)
+
+
+@pytest.mark.parametrize(
+    "damage",
+    [
+        "extra-field",
+        "missing-field",
+        "bool-version",
+        "incomplete",
+        "fake-complete",
+        "created-at",
+        "same-channel",
+        "positive-channel",
+        "bool-channel",
+        "revision",
+        "drive-id",
+        "renamed",
+        "starred",
+        "share-label",
+        "missing-file",
+        "duplicate-destination",
+        "credential-extra",
+        "credential-missing",
+        "managed-document-missing",
+        "preferences-missing",
+        "policy-missing",
+        "bool-api-id",
+        "hash",
+        "short-secret",
+        "long-secret",
+        "placeholder-secret",
+        "tokens-empty",
+        "token-malformed",
+        "token-duplicate-identity",
+        "tokens-unbounded",
+    ],
+)
+def test_authenticated_envelope_still_rejects_semantic_forgery(damage):
+    value = payload()
+    if damage == "extra-field":
+        value["unexpected"] = True
+    elif damage == "missing-field":
+        value.pop("credentials")
+    elif damage == "bool-version":
+        value["version"] = True
+    elif damage == "incomplete":
+        value["complete"] = False
+    elif damage == "fake-complete":
+        value["complete"] = "true"
+    elif damage == "created-at":
+        value["created_at"] = "not a time"
+    elif damage in {"same-channel", "positive-channel", "bool-channel"}:
+        value["replica_catalog"]["storage_channel_id"] = {
+            "same-channel": MAIN,
+            "positive-channel": 123,
+            "bool-channel": True,
+        }[damage]
+    elif damage == "revision":
+        value["replica_catalog"]["revision"] += 1
+    elif damage == "drive-id":
+        value["replica_catalog"]["drive_id"] = "different-drive"
+    elif damage in {"renamed", "starred"}:
+        node = next(files_in(value["replica_catalog"]))
+        if damage == "renamed":
+            node["name"] = "Wrong file name"
+        else:
+            node["starred"] = not node.get("starred", False)
+    elif damage == "share-label":
+        value["replica_catalog"]["shares"][0]["label"] = "Different audience"
+    elif damage == "missing-file":
+        root = value["replica_catalog"]["root"]
+        folder = next(iter(root["children"].values()))
+        folder["children"].pop(next(iter(folder["children"])))
+    elif damage == "duplicate-destination":
+        nodes = list(files_in(value["replica_catalog"]))
+        nodes[1]["message_id"] = nodes[0]["message_id"]
+    elif damage == "credential-extra":
+        value["credentials"]["remote_url"] = "https://invalid.example"
+    elif damage == "credential-missing":
+        value["credentials"].pop("session_secret")
+    elif damage == "managed-document-missing":
+        value["credentials"].pop("managed_document")
+    elif damage == "preferences-missing":
+        value["credentials"].pop("preferences")
+    elif damage == "policy-missing":
+        value["credentials"]["preferences"].pop("bot-preferences.json")
+    elif damage == "bool-api-id":
+        value["credentials"]["api_id"] = True
+    elif damage == "hash":
+        value["credentials"]["api_hash"] = "not a hash"
+    elif damage == "short-secret":
+        value["credentials"]["session_secret"] = "short"
+    elif damage == "long-secret":
+        value["credentials"]["session_secret"] = "x" * 4097
+    elif damage == "placeholder-secret":
+        value["credentials"]["session_secret"] = "<replace this example" + "x" * 40
+    elif damage == "tokens-empty":
+        value["credentials"]["bot_tokens"] = []
+    elif damage == "token-malformed":
+        value["credentials"]["bot_tokens"] = ["invalid"]
+    elif damage == "token-duplicate-identity":
+        value["credentials"]["bot_tokens"] += ["123456:" + "y" * 30]
+    else:
+        value["credentials"]["bot_tokens"] = [
+            str(100000 + index) + ":" + "x" * 30 for index in range(257)
+        ]
+    with pytest.raises(ValueError, match="nothing changed"):
+        decode_bundle(encode_bundle(value, KEY), KEY)
+
+
+def test_authenticated_duplicate_json_keys_are_rejected():
+    encoded = json.dumps(payload()).replace(
+        '"version": 1', '"version": 1, "version": 1'
+    )
+    nonce = b"n" * 12
+    content = (
+        MAGIC
+        + nonce
+        + AESGCM(bytes.fromhex(KEY)).encrypt(nonce, encoded.encode(), MAGIC)
+    )
+    with pytest.raises(ValueError, match="nothing changed"):
+        decode_bundle(content, KEY)
+
+
+def test_remap_does_not_mutate_original_and_requires_every_part():
+    original = payload()["catalog"]
+    preserved = copy.deepcopy(original)
+    with pytest.raises(KeyError):
+        remap_catalog(original, BACKUP, {"11": 111})
+    assert original == preserved
+
+
+def test_journal_retains_exact_intent_and_confirmation_across_restarts(tmp_path):
+    journal = ReplicaJournal(tmp_path)
+    identity, receipt = journal.intent("drive:source:target:part", 123)
+    assert type(identity) is int and identity > 0 and receipt is None
+    journal.set("job", {"phase": "copying", "checkpoint": 17})
+    journal.confirm("drive:source:target:part", 901)
+    journal.close()
+    journal = ReplicaJournal(tmp_path)
+    try:
+        assert journal.intent("drive:source:target:part", 123) == (identity, 901)
+        assert journal.get("job") == {"phase": "copying", "checkpoint": 17}
+        with pytest.raises(ValueError, match="size changed"):
+            journal.intent("drive:source:target:part", 124)
+        assert journal.intent("drive:source:different-target:part", 123)[0] != identity
+        assert (tmp_path / "channel-backup.sqlite3").stat().st_mode & 0o777 == 0o600
+    finally:
+        journal.close()
+
+
+def test_atomic_state_rejects_unserializable_value_without_changing_any_key(tmp_path):
+    journal = ReplicaJournal(tmp_path)
+    journal.set_many({"restore_point": {"revision": 17}, "restore_point_key": KEY})
+    try:
+        with pytest.raises(ValueError):
+            journal.set_many(
+                {"restore_point": {"revision": 18}, "restore_point_key": float("nan")}
+            )
+    finally:
+        journal.close()
+    reopened = ReplicaJournal(tmp_path)
+    try:
+        assert reopened.get("restore_point") == {"revision": 17}
+        assert reopened.get("restore_point_key") == KEY
+    finally:
+        reopened.close()
+
+
+def test_process_death_cannot_pair_new_restore_point_with_old_keys(tmp_path):
+    old = {
+        "restore_point": {"revision": 17, "backup_message_id": 901},
+        "restore_point_key": KEY,
+        "restore_point_mongodb_key": "b2" * 32,
+        "credentials_digest": "a" * 64,
+    }
+    new = {
+        "restore_point": {"revision": 18, "backup_message_id": 902},
+        "restore_point_key": "c3" * 32,
+        "restore_point_mongodb_key": None,
+        "credentials_digest": "d" * 64,
+    }
+    journal = ReplicaJournal(tmp_path)
+    journal.set_many(old)
+    journal.close()
+    script = textwrap.dedent(
+        """
+        import json
+        import os
+        import sys
+        from pathlib import Path
+        from tgdrive.replication.replica_state import ReplicaJournal
+
+        journal = ReplicaJournal(Path(sys.argv[1]))
+        journal.db.create_function("crash_before_key", 0, lambda: os._exit(73))
+        journal.db.executescript('''
+            CREATE TRIGGER crash_publication BEFORE INSERT ON state
+            WHEN NEW.key = 'restore_point_key'
+            BEGIN SELECT crash_before_key(); END;
+        ''')
+        journal.set_many(json.loads(sys.argv[2]))
+        raise SystemExit("Crash injection did not execute")
+        """
+    )
+    stopped = subprocess.run(  # noqa: S603 - fixed Python and crash-injection script
+        [sys.executable, "-c", script, str(tmp_path), json.dumps(new)],
+        capture_output=True,
+        text=True,
+        timeout=30,
+        check=False,
+    )
+    assert stopped.returncode == 73, stopped.stderr
+    reopened = ReplicaJournal(tmp_path)
+    try:
+        assert {key: reopened.get(key) for key in old} == old
+        reopened.db.execute("DROP TRIGGER crash_publication")
+        reopened.db.commit()
+        reopened.set_many(new)
+    finally:
+        reopened.close()
+    committed = ReplicaJournal(tmp_path)
+    try:
+        assert {key: committed.get(key) for key in new} == new
+        assert committed.get("restore_point_mongodb_key", "stale") is None
+    finally:
+        committed.close()
+
+
+@pytest.mark.asyncio
+async def test_capsule_publication_rolls_back_point_and_keys_as_one_generation(
+    tmp_path,
+    monkeypatch,
+):
+    from unittest.mock import AsyncMock
+
+    from pydantic import SecretStr
+
+    from tests.replication.test_replica import BACKUP, dispose, setup
+    from tests.support.mongo_fixtures import register_test_backend
+    from tests.support.recovery_fixtures import settings
+    from tgdrive.replication.replica import ChannelReplica
+
+    backend = register_test_backend(monkeypatch, settings(tmp_path))
+    monkeypatch.setattr(
+        "tgdrive.replication.replica_mongo.mirror_mongodb", AsyncMock(return_value=None)
+    )
+    configured, store, remote, replica, config = setup(tmp_path)
+    try:
+        configured.mongodb_backup_key = SecretStr("b2" * 32)
+        await replica._sync(config)
+        replica.journal.set("key", "c3" * 32)
+        configured.mongodb_backup_key = SecretStr("d4" * 32)
+        previous = replica.recovery_kit()
+        store.create_folder("/", "Next generation")
+        replica.journal.db.executescript(
+            """
+            CREATE TRIGGER reject_publication BEFORE INSERT ON state
+            WHEN NEW.key = 'restore_point_key'
+            BEGIN SELECT RAISE(ABORT, 'injected key write failure'); END;
+            """
+        )
+        with pytest.raises(sqlite3.IntegrityError, match="injected key write failure"):
+            await replica._sync(config)
+        await replica.close()
+        replica = ChannelReplica(
+            configured,
+            SimpleNamespace(store=store, mongo=backend),
+            transport_factory=remote.factory,
+        )
+        assert replica.recovery_kit() == previous
+        original = decode_bundle(
+            remote.messages[BACKUP, previous["restore_point"]["backup_message_id"]],
+            previous["key"],
+        )
+        assert (
+            original["credentials"]["mongodb_backup_key"]
+            == previous["mongodb_backup_key"]
+        )
+        replica.journal.db.execute("DROP TRIGGER reject_publication")
+        replica.journal.db.commit()
+        await replica._sync(config)
+        current = replica.recovery_kit()
+        assert current["restore_point"] != previous["restore_point"]
+        assert current["key"] == "c3" * 32
+        assert current["mongodb_backup_key"] == "d4" * 32
+        recovered = decode_bundle(
+            remote.messages[BACKUP, current["restore_point"]["backup_message_id"]],
+            current["key"],
+        )
+        assert (
+            recovered["credentials"]["mongodb_backup_key"]
+            == current["mongodb_backup_key"]
+        )
+    finally:
+        await dispose(replica, store)
+
+
+def test_private_archive_write_and_read_reject_world_readable_or_symlink(tmp_path):
+    target = tmp_path / "checkpoint.tgdb"
+    atomic_private(target, b"encrypted archive")
+    assert read_private(target) == b"encrypted archive"
+    target.chmod(0o644)
+    with pytest.raises(ValueError, match="0600"):
+        read_private(target)
+    target.chmod(0o600)
+    link = tmp_path / "link"
+    link.symlink_to(target)
+    with pytest.raises(OSError):
+        read_private(link)
+    assert target.read_bytes() == b"encrypted archive"
diff --git a/tests/replication/test_replica_transport.py b/tests/replication/test_replica_transport.py
new file mode 100644
index 00000000..56a03ca8
--- /dev/null
+++ b/tests/replication/test_replica_transport.py
@@ -0,0 +1,1110 @@
+"""Offline contracts for the exact Telegram replica transport requests."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import stat
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from pydantic import SecretStr
+from telethon import TelegramClient, functions, types, utils
+from telethon.crypto import AuthKey
+from telethon.errors import (
+    AccessTokenInvalidError,
+    FloodWaitError,
+    NetworkMigrateError,
+    PhoneMigrateError,
+    RandomIdDuplicateError,
+    UserMigrateError,
+)
+from telethon.sessions import SQLiteSession, StringSession
+
+from tgdrive.replication.replica_transport import (
+    CAPSULE_NAME,
+    MAX_CAPSULE_BYTES,
+    MAX_VERIFY_BATCH,
+    ReplicaRequestPacer,
+    ReplicaTransport,
+    ReplicaTransportError,
+    _provider_error,
+)
+
+MAIN = -1001234567890
+BACKUP = -1002234567890
+TOKEN = "234567:" + "b" * 24
+PRIMARY = "123456:" + "a" * 24
+
+
+def channel(identity: int, **kwargs):
+    return types.Channel(
+        id=utils.resolve_id(identity)[0],
+        title="Private storage",
+        photo=types.ChatPhotoEmpty(),
+        date=None,
+        broadcast=True,
+        admin_rights=types.ChatAdminRights(
+            post_messages=True, edit_messages=True, delete_messages=True
+        ),
+        **kwargs,
+    )
+
+
+def document(size=123, name="payload.bin"):
+    return types.Document(
+        id=123456789,
+        access_hash=42,
+        file_reference=b"fresh-reference",
+        date=None,
+        mime_type="application/octet-stream",
+        size=size,
+        dc_id=2,
+        attributes=[types.DocumentAttributeFilename(name)],
+    )
+
+
+def message(identity, channel_id, doc):
+    return SimpleNamespace(
+        id=identity,
+        peer_id=types.PeerChannel(utils.resolve_id(channel_id)[0]),
+        document=doc,
+        media=SimpleNamespace(ttl_seconds=None),
+        noforwards=False,
+        fwd_from=None,
+    )
+
+
+class Native:
+    def __init__(self):
+        self.connect = AsyncMock()
+        self.sign_in = AsyncMock(return_value=SimpleNamespace(id=234567, bot=True))
+        self.get_me = AsyncMock(return_value=None)
+        self.disconnect = AsyncMock()
+        self.chats = {MAIN: channel(MAIN), BACKUP: channel(BACKUP)}
+        self.messages = {(MAIN, 77): message(77, MAIN, document())}
+        self.requests = []
+        self.downloads = []
+        self.uploads = []
+        self.pins = {}
+        self.receipts = {}
+        self.next_message = 901
+        self.response_loss = False
+        self.bad_copy = False
+        self.wrong_destination_peer = False
+        self.response_mode = "updates"
+        self.body = b"encrypted capsule"
+        self.delay_download = False
+
+    async def get_input_entity(self, identity):
+        return types.InputPeerChannel(utils.resolve_id(identity)[0], 1)
+
+    async def get_messages(self, channel_id, *, ids):
+        if isinstance(ids, list):
+            return [self.messages.get((channel_id, identity)) for identity in ids]
+        return self.messages.get((channel_id, ids))
+
+    async def upload_file(self, source, **kwargs):
+        self.body = source.read()
+        self.uploads.append(kwargs)
+        return types.InputFileBig(id=123, parts=1, name=kwargs["file_name"])
+
+    async def __call__(self, request):
+        self.requests.append(request)
+        if isinstance(request, functions.channels.GetFullChannelRequest):
+            identity = utils.get_peer_id(request.channel)
+            return SimpleNamespace(
+                chats=[self.chats[identity]],
+                full_chat=SimpleNamespace(pinned_msg_id=self.pins.get(identity)),
+            )
+        if isinstance(request, functions.messages.UpdatePinnedMessageRequest):
+            self.pins[utils.get_peer_id(request.peer)] = request.id
+            return True
+        assert isinstance(request, functions.messages.SendMediaRequest)
+        identity = utils.get_peer_id(request.peer)
+        key = (identity, request.random_id)
+        if key not in self.receipts:
+            result = self.next_message
+            self.next_message += 1
+            self.receipts[key] = result
+            if isinstance(request.media, types.InputMediaDocument):
+                doc = copy.deepcopy(self.messages[(MAIN, 77)].document)
+                if self.bad_copy:
+                    doc.id += 1
+            else:
+                doc = document(len(self.body), request.media.attributes[0].file_name)
+            self.messages[identity, result] = message(result, identity, doc)
+            if self.wrong_destination_peer:
+                self.messages[identity, result].peer_id = types.PeerChannel(999)
+        result = self.receipts[key]
+        if self.response_loss:
+            self.response_loss = False
+            raise TimeoutError("ambiguous response includes " + TOKEN)
+        if self.response_mode == "short":
+            return types.UpdateShort(
+                update=types.UpdateMessageID(id=result, random_id=request.random_id),
+                date=None,
+            )
+        if self.response_mode == "short-sent":
+            return types.UpdateShortSentMessage(
+                id=result, pts=1, pts_count=1, date=None, out=True
+            )
+        return SimpleNamespace(
+            updates=[types.UpdateMessageID(id=result, random_id=request.random_id)]
+        )
+
+    def iter_download(self, doc, **kwargs):
+        self.downloads.append((doc, kwargs))
+
+        async def read():
+            if self.delay_download:
+                await asyncio.Event().wait()
+            yield self.body[:5]
+            yield self.body[5:]
+
+        return read()
+
+
+class Clock:
+    def __init__(self):
+        self.value = 0.0
+        self.delays = []
+
+    def now(self):
+        return self.value
+
+    async def sleep(self, delay):
+        self.delays.append(delay)
+        self.value += delay
+        await asyncio.sleep(0)
+
+
+async def started(native=None, *, primary=PRIMARY, pacer=None):
+    native = native or Native()
+    transport = ReplicaTransport(
+        SimpleNamespace(bot_tokens=(primary,), api_id=1),
+        TOKEN,
+        client=native,
+        pacer=pacer or ReplicaRequestPacer(interval=0, maximum_interval=0),
+    )
+    await transport.start()
+    return transport, native
+
+
+def session_settings(directory, *, api_id=12345, api_hash="a" * 32):
+    return SimpleNamespace(
+        bot_tokens=(PRIMARY,),
+        api_id=api_id,
+        api_hash=SecretStr(api_hash),
+        resolved_data_dir=directory,
+    )
+
+
+@pytest.fixture
+def persistent_clients(monkeypatch):
+    """Exercise real private SQLite auth storage without connecting to Telegram."""
+    state = SimpleNamespace(
+        instances=[], expired=False, failure=None, account_id=234567
+    )
+
+    def create(session_path, *_args, **_kwargs):
+        native = Native()
+        native.session = SQLiteSession(session_path)
+
+        async def account():
+            key = native.session.auth_key
+            if not state.expired and key is not None and key.key is not None:
+                return SimpleNamespace(id=state.account_id, bot=True)
+            return None
+
+        async def authorize(**_kwargs):
+            if state.failure is not None:
+                raise state.failure
+            native.session.auth_key = AuthKey(bytes(range(256)))
+            native.session.save()
+            return SimpleNamespace(id=state.account_id, bot=True)
+
+        native.sign_in = AsyncMock(side_effect=authorize)
+        native.get_me = AsyncMock(side_effect=account)
+        native.disconnect = AsyncMock(side_effect=native.session.close)
+        state.instances.append(native)
+        return native
+
+    monkeypatch.setattr("tgdrive.replication.replica_transport.TelegramClient", create)
+    return state
+
+
+@pytest.mark.asyncio
+async def test_saved_bot_session_avoids_authorization_on_reconnect_and_replacement(
+    tmp_path,
+    persistent_clients,
+):
+    settings = session_settings(tmp_path)
+    first = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    await first.start()
+    await first.close()
+    await first.start()
+    await first.close()
+    replacement = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    try:
+        await replacement.start()
+        original, restored = persistent_clients.instances
+        original.sign_in.assert_awaited_once_with(bot_token=TOKEN)
+        assert original.get_me.await_count == 2
+        restored.sign_in.assert_not_awaited()
+        restored.get_me.assert_awaited_once()
+        assert original.session.filename == restored.session.filename
+        path = Path(restored.session.filename)
+        assert path.name.startswith("backup-bot-234567-")
+        assert TOKEN not in str(path) and "a" * 32 not in str(path)
+        assert stat.S_IMODE(path.parent.stat().st_mode) == 0o700
+        assert stat.S_IMODE(path.stat().st_mode) == 0o600
+    finally:
+        await replacement.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("change", ["token", "api_id", "api_hash"])
+async def test_session_cache_is_isolated_when_credentials_change(
+    tmp_path,
+    persistent_clients,
+    change,
+):
+    settings = session_settings(tmp_path)
+    first = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    await first.start()
+    await first.close()
+    token = TOKEN
+    if change == "token":
+        token = "234567:" + "c" * 24
+    elif change == "api_id":
+        settings = session_settings(tmp_path, api_id=54321)
+    else:
+        settings = session_settings(tmp_path, api_hash="b" * 32)
+    replacement = ReplicaTransport(
+        settings, token, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    try:
+        await replacement.start()
+        old, new = persistent_clients.instances
+        assert old.session.filename != new.session.filename
+        new.sign_in.assert_awaited_once_with(bot_token=token)
+        assert token not in new.session.filename
+    finally:
+        await replacement.close()
+
+
+@pytest.mark.asyncio
+async def test_expired_saved_auth_preserves_typed_signin_wait_without_erasing_session(
+    tmp_path,
+    persistent_clients,
+):
+    settings = session_settings(tmp_path)
+    first = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    await first.start()
+    await first.close()
+    session_path = Path(persistent_clients.instances[0].session.filename)
+    persistent_clients.expired = True
+    persistent_clients.failure = FloodWaitError(request=TOKEN, capture=2876)
+    replacement = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    with pytest.raises(ReplicaTransportError) as raised:
+        await replacement.start()
+    assert raised.value.code == "REPLICA_FLOOD_WAIT"
+    assert raised.value.operation == "sign_in"
+    assert raised.value.retryable and raised.value.retry_after == 2876
+    assert TOKEN not in str(raised.value)
+    assert session_path.is_file()
+    expired = persistent_clients.instances[-1]
+    expired.sign_in.assert_awaited_once_with(bot_token=TOKEN)
+    expired.get_me.assert_awaited_once()
+    expired.disconnect.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_authorized_saved_session_still_requires_matching_bot_identity(
+    tmp_path,
+    persistent_clients,
+):
+    settings = session_settings(tmp_path)
+    first = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    await first.start()
+    await first.close()
+    persistent_clients.account_id = 999999
+    replacement = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    with pytest.raises(ReplicaTransportError) as raised:
+        await replacement.start()
+    assert raised.value.code == "REPLICA_CREDENTIALS"
+    assert TOKEN not in str(raised.value)
+    restored = persistent_clients.instances[-1]
+    restored.sign_in.assert_not_awaited()
+    restored.get_me.assert_awaited_once()
+    restored.disconnect.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("link", ["directory", "session", "journal", "wal", "shm"])
+async def test_session_storage_rejects_symbolic_links_without_touching_target(
+    tmp_path,
+    persistent_clients,
+    link,
+):
+    settings = session_settings(tmp_path)
+    transport = ReplicaTransport(
+        settings, TOKEN, pacer=ReplicaRequestPacer(interval=0, maximum_interval=0)
+    )
+    outside = tmp_path / "preserve-this-file"
+    outside.write_bytes(b"unchanged")
+    if link == "directory":
+        target = tmp_path / "other-sessions"
+        target.mkdir()
+        (tmp_path / "sessions").symlink_to(target, target_is_directory=True)
+    else:
+        path = transport._persistent_session(234567)
+        if link == "session":
+            path.unlink()
+            path.symlink_to(outside)
+        else:
+            suffix = {"journal": "-journal", "wal": "-wal", "shm": "-shm"}[link]
+            path.with_name(path.name + suffix).symlink_to(outside)
+    with pytest.raises(ReplicaTransportError) as raised:
+        await transport.start()
+    assert raised.value.code == "REPLICA_SESSION"
+    assert TOKEN not in str(raised.value)
+    assert not persistent_clients.instances
+    assert outside.read_bytes() == b"unchanged"
+
+
+@pytest.mark.asyncio
+async def test_pacer_serializes_callers_and_spaces_completion_from_next_start():
+    clock = Clock()
+    pacer = ReplicaRequestPacer(clock=clock.now, sleep=clock.sleep)
+    active = maximum_active = 0
+    starts = []
+
+    async def operation():
+        nonlocal active, maximum_active
+        async with pacer.slot():
+            active += 1
+            maximum_active = max(maximum_active, active)
+            starts.append(clock.value)
+            await asyncio.sleep(0)
+            clock.value += 0.5
+            active -= 1
+
+    await asyncio.gather(operation(), operation(), operation())
+    assert maximum_active == 1
+    assert starts == [0, 1.5, 3]
+    assert clock.delays == [1, 1]
+
+
+@pytest.mark.asyncio
+async def test_floodwait_slows_replacement_transport_and_retains_typed_operation():
+    clock = Clock()
+    pacer = ReplicaRequestPacer(clock=clock.now, sleep=clock.sleep)
+    transport, native = await started(pacer=pacer)
+    native.get_input_entity = AsyncMock(side_effect=FloodWaitError(TOKEN, capture=42))
+    with pytest.raises(ReplicaTransportError) as raised:
+        await transport.inspect(BACKUP)
+    assert raised.value.retry_after == 42
+    assert raised.value.operation == "resolve_peer"
+    assert TOKEN not in str(raised.value)
+    assert pacer.interval == 2
+    await transport.close()
+
+    clock.value += 42
+    replacement, _ = await started(pacer=pacer)
+    try:
+        assert clock.delays[-1] == 2
+        pacer.slow_down()
+        pacer.slow_down()
+        assert pacer.interval == 4
+        async with pacer.slot():
+            pass
+        pacer.reset()
+        async with pacer.slot():
+            pass
+        assert clock.delays[-1] == 4, "Reset cannot discard the already reserved gap"
+        assert pacer.interval == 1
+    finally:
+        await replacement.close()
+
+
+@pytest.mark.asyncio
+async def test_cancelled_pacer_wait_does_not_issue_a_request_or_hold_the_lock():
+    entered = asyncio.Event()
+    blocked = asyncio.Event()
+
+    async def sleep(_delay):
+        entered.set()
+        await blocked.wait()
+
+    pacer = ReplicaRequestPacer(clock=lambda: 0, sleep=sleep)
+    async with pacer.slot():
+        pass
+    called = False
+
+    async def operation():
+        nonlocal called
+        async with pacer.slot():
+            called = True
+
+    task = asyncio.create_task(operation())
+    await entered.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert not called
+    blocked.set()
+    await operation()
+    assert called
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", [None, "missing", "size", "peer", "protected"])
+async def test_batched_verification_checks_every_document_without_payload_io(failure):
+    transport, native = await started()
+    native.messages[BACKUP, 901] = message(901, BACKUP, document(123))
+    native.messages[BACKUP, 902] = message(902, BACKUP, document(456))
+    if failure == "missing":
+        native.messages.pop((BACKUP, 902))
+    elif failure == "size":
+        native.messages[BACKUP, 902].document.size = 455
+    elif failure == "peer":
+        native.messages[BACKUP, 902].peer_id = types.PeerChannel(999)
+    elif failure == "protected":
+        native.messages[BACKUP, 902].noforwards = True
+    native.get_messages = AsyncMock(wraps=native.get_messages)
+    try:
+        if failure:
+            with pytest.raises(ReplicaTransportError):
+                await transport.verify_many(BACKUP, [(901, 123), (902, 456)])
+        else:
+            await transport.verify_many(BACKUP, [(901, 123), (902, 456)])
+        native.get_messages.assert_awaited_once_with(BACKUP, ids=[901, 902])
+        assert len(native.requests) == 1
+        assert isinstance(native.requests[0], functions.channels.GetFullChannelRequest)
+        assert native.uploads == native.downloads == []
+        with pytest.raises(ReplicaTransportError) as raised:
+            await transport.verify_many(BACKUP, [(901, 123)] * (MAX_VERIFY_BATCH + 1))
+        assert raised.value.code == "REPLICA_INPUT"
+    finally:
+        await transport.close()
+
+
+@pytest.mark.asyncio
+async def test_paced_copies_keep_fresh_channel_checks_and_reference_only_media():
+    clock = Clock()
+    pacer = ReplicaRequestPacer(clock=clock.now, sleep=clock.sleep)
+    transport, native = await started(pacer=pacer)
+    native.get_input_entity = AsyncMock(wraps=native.get_input_entity)
+    try:
+        copies = await asyncio.gather(
+            transport.copy(MAIN, 77, BACKUP, random_id=11, expected_size=123),
+            transport.copy(MAIN, 77, BACKUP, random_id=12, expected_size=123),
+        )
+        assert copies == [901, 902]
+        assert all(delay == 1 for delay in clock.delays)
+        assert native.get_input_entity.await_count == 2
+        assert native.uploads == native.downloads == []
+        native.chats[BACKUP].username = "now_public"
+        with pytest.raises(ReplicaTransportError) as raised:
+            await transport.copy(MAIN, 77, BACKUP, random_id=13, expected_size=123)
+        assert raised.value.code == "REPLICA_PUBLIC_CHANNEL"
+        assert len(native.receipts) == 2
+    finally:
+        await transport.close()
+
+
+@pytest.mark.asyncio
+async def test_start_distinguishes_identity_and_does_not_reveal_credentials():
+    native = Native()
+    transport = ReplicaTransport(
+        SimpleNamespace(bot_tokens=(TOKEN,)), TOKEN, client=native
+    )
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.start()
+    assert error.value.code == "REPLICA_SAME_BOT"
+    native.connect.assert_not_called()
+    assert TOKEN not in str(error.value)
+    native.get_me.return_value = SimpleNamespace(id=999999, bot=True)
+    candidate = ReplicaTransport(
+        SimpleNamespace(bot_tokens=(PRIMARY,)), TOKEN, client=native
+    )
+    with pytest.raises(ReplicaTransportError, match="identity"):
+        await candidate.start()
+    native.disconnect.assert_awaited_once()
+
+
+def test_inflight_duplicate_is_retryable_without_echoing_provider_request():
+    error = RandomIdDuplicateError(request=TOKEN)
+    mapped = _provider_error(error)
+    assert mapped.code == "REPLICA_IN_FLIGHT"
+    assert mapped.retryable and mapped.retry_after == 5
+    assert TOKEN not in str(mapped)
+
+
+@pytest.mark.asyncio
+async def test_native_client_preserves_typed_error_for_durable_coordinator_retry(
+    monkeypatch,
+    tmp_path,
+):
+    native = Native()
+    constructor = Mock(return_value=native)
+    monkeypatch.setattr(
+        "tgdrive.replication.replica_transport.TelegramClient", constructor
+    )
+    transport = ReplicaTransport(
+        SimpleNamespace(
+            bot_tokens=(PRIMARY,),
+            api_id=12345,
+            api_hash=SecretStr("a" * 32),
+            resolved_data_dir=tmp_path,
+        ),
+        TOKEN,
+    )
+    try:
+        await transport.start()
+        assert constructor.call_args.kwargs["raise_last_call_error"] is True
+        assert constructor.call_args.kwargs["request_retries"] == 0
+        assert constructor.call_args.kwargs["receive_updates"] is False
+    finally:
+        await transport.close()
+
+
+@pytest.mark.asyncio
+async def test_real_telethon_auth_probe_preserves_floodwait_without_signing_in():
+    native = TelegramClient(
+        StringSession(),
+        12345,
+        "a" * 32,
+        receive_updates=False,
+        request_retries=0,
+        raise_last_call_error=True,
+        flood_sleep_threshold=0,
+    )
+    account = types.User(id=234567, access_hash=1, is_self=True, bot=True)
+    native.connect = AsyncMock()
+    native.disconnect = AsyncMock()
+    native.sign_in = AsyncMock(wraps=native.sign_in)
+    requests = []
+
+    async def respond(request):
+        request = getattr(request, "query", request)
+        requests.append(request)
+        if len(requests) == 1:
+            raise FloodWaitError(request=request, capture=2876)
+        # If the initial wait is swallowed, get_me succeeds and allows the
+        # erroneous startup to continue, reproducing the real SDK behavior.
+        assert isinstance(request, functions.users.GetUsersRequest)
+        return [account]
+
+    native._sender = SimpleNamespace(
+        send=Mock(side_effect=lambda request, **_kwargs: respond(request))
+    )
+    transport = ReplicaTransport(
+        SimpleNamespace(bot_tokens=(PRIMARY,)),
+        TOKEN,
+        client=native,
+        pacer=ReplicaRequestPacer(interval=0, maximum_interval=0),
+    )
+    with pytest.raises(ReplicaTransportError) as raised:
+        await transport.start()
+    assert raised.value.code == "REPLICA_FLOOD_WAIT"
+    assert raised.value.retry_after == 2876
+    assert raised.value.retryable
+    assert raised.value.operation == "get_me"
+    assert TOKEN not in str(raised.value)
+    assert len(requests) == 1
+    assert isinstance(requests[0], functions.users.GetUsersRequest)
+    native.sign_in.assert_not_awaited()
+    native.disconnect.assert_awaited_once()
+    assert not transport._started
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "migration", [UserMigrateError, NetworkMigrateError, PhoneMigrateError]
+)
+async def test_real_telethon_login_replays_auth_once_after_dc_switch(migration):
+    native = TelegramClient(
+        StringSession(),
+        12345,
+        "a" * 32,
+        receive_updates=False,
+        request_retries=0,
+        raise_last_call_error=True,
+        flood_sleep_threshold=0,
+    )
+    account = types.User(id=234567, access_hash=1, is_self=True, bot=True)
+    native.connect = AsyncMock()
+    native.disconnect = AsyncMock()
+    native.get_me = AsyncMock(side_effect=[None, None, None, None])
+    native._on_login = AsyncMock(return_value=account)
+    native._switch_dc = AsyncMock()
+    native._authorized = False
+    requests = []
+
+    async def respond(request):
+        request = getattr(request, "query", request)
+        assert isinstance(request, functions.auth.ImportBotAuthorizationRequest)
+        requests.append(request)
+        if len(requests) == 1:
+            raise migration(request=request, capture=4)
+        return types.auth.Authorization(user=account)
+
+    def send(request, *, ordered=False):
+        return respond(request)
+
+    native._sender = SimpleNamespace(send=Mock(side_effect=send))
+    transport = ReplicaTransport(
+        SimpleNamespace(bot_tokens=(PRIMARY,)), TOKEN, client=native
+    )
+    try:
+        await transport.start()
+        assert transport._started
+        assert native._request_retries == 0
+        assert len(requests) == 2
+        native._switch_dc.assert_awaited_once_with(4)
+        native._on_login.assert_awaited_once_with(account)
+    finally:
+        await transport.close()
+    native.disconnect.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "migration", [UserMigrateError, NetworkMigrateError, PhoneMigrateError]
+)
+async def test_repeated_login_migration_is_bounded_and_sanitized(migration):
+    native = Native()
+    native.sign_in.side_effect = [
+        migration(request=TOKEN, capture=4),
+        migration(request=TOKEN, capture=5),
+    ]
+    transport = ReplicaTransport(
+        SimpleNamespace(bot_tokens=(PRIMARY,)), TOKEN, client=native
+    )
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.start()
+    assert native.sign_in.await_count == 2
+    assert error.value.code == "REPLICA_DC_MIGRATION"
+    assert error.value.retryable
+    assert TOKEN not in str(error.value)
+    assert error.value.__cause__ is None
+    assert not transport._started
+    assert native.get_me.await_count == 2
+    native.disconnect.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "failure,code",
+    [
+        (AccessTokenInvalidError(request=TOKEN), "REPLICA_CREDENTIALS"),
+        (FloodWaitError(request=TOKEN, capture=42), "REPLICA_FLOOD_WAIT"),
+        (TimeoutError(TOKEN), "REPLICA_UNAVAILABLE"),
+    ],
+)
+async def test_nonmigration_login_failures_are_not_retried(failure, code):
+    native = Native()
+    native.sign_in.side_effect = failure
+    transport = ReplicaTransport(
+        SimpleNamespace(bot_tokens=(PRIMARY,)), TOKEN, client=native
+    )
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.start()
+    native.sign_in.assert_awaited_once_with(bot_token=TOKEN)
+    native.disconnect.assert_awaited_once()
+    assert error.value.code == code
+    assert TOKEN not in str(error.value)
+    assert not transport._started
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mode", ["short", "short-sent"])
+@pytest.mark.parametrize("failure", [None, "channel", "document"])
+async def test_typed_short_receipts_require_fresh_matching_destination(mode, failure):
+    transport, native = await started()
+    native.response_mode = mode
+    native.wrong_destination_peer = failure == "channel"
+    native.bad_copy = failure == "document"
+    try:
+        if failure is None:
+            assert (
+                await transport.copy(MAIN, 77, BACKUP, random_id=321, expected_size=123)
+                == 901
+            )
+        else:
+            with pytest.raises(ReplicaTransportError) as error:
+                await transport.copy(MAIN, 77, BACKUP, random_id=321, expected_size=123)
+            assert error.value.code == "REPLICA_VERIFY_FAILED"
+    finally:
+        await transport.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "mode,code",
+    [
+        ("username", "REPLICA_PUBLIC_CHANNEL"),
+        ("usernames", "REPLICA_PUBLIC_CHANNEL"),
+        ("noforwards", "REPLICA_PROTECTED"),
+        ("restricted", "REPLICA_PROTECTED"),
+        ("group", "REPLICA_CHANNEL_TYPE"),
+        ("permissions", "REPLICA_PERMISSIONS"),
+        ("no-admin", "REPLICA_PERMISSIONS"),
+    ],
+)
+async def test_private_channel_preflight_rejects_unsafe_states(mode, code):
+    transport, native = await started()
+    chat = native.chats[BACKUP]
+    if mode == "username":
+        chat.username = "publicchannel"
+    elif mode == "usernames":
+        chat.usernames = [types.Username(username="publicchannel", active=True)]
+    elif mode in {"restricted", "noforwards"}:
+        setattr(chat, mode, True)
+    elif mode == "group":
+        chat.broadcast = False
+    elif mode == "permissions":
+        chat.admin_rights.edit_messages = False
+    else:
+        chat.admin_rights = None
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.inspect(BACKUP)
+    assert error.value.code == code
+    await transport.close()
+
+
+@pytest.mark.asyncio
+async def test_copy_existing_premium_document_uses_reference_not_original_bytes():
+    transport, native = await started()
+    native.messages[MAIN, 77].document.size = 4 * 1024**3
+    result = await transport.copy(
+        MAIN, 77, BACKUP, random_id=123, expected_size=4 * 1024**3
+    )
+    assert result == 901
+    assert native.uploads == native.downloads == []
+    sent = [
+        r for r in native.requests if isinstance(r, functions.messages.SendMediaRequest)
+    ]
+    assert len(sent) == 1 and isinstance(sent[0].media, types.InputMediaDocument)
+    assert sent[0].media.id.id == native.messages[MAIN, 77].document.id
+    assert sent[0].random_id == 123 and sent[0].silent
+    assert not any(
+        isinstance(r, functions.messages.ForwardMessagesRequest)
+        for r in native.requests
+    )
+
+
+@pytest.mark.asyncio
+async def test_ambiguous_send_reuses_persisted_random_id_without_double_copy():
+    transport, native = await started()
+    native.response_loss = True
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.copy(MAIN, 77, BACKUP, random_id=-555, expected_size=123)
+    assert error.value.retryable and TOKEN not in str(error.value)
+    assert (
+        await transport.copy(MAIN, 77, BACKUP, random_id=-555, expected_size=123) == 901
+    )
+    assert len(native.receipts) == 1
+    sent = [
+        r for r in native.requests if isinstance(r, functions.messages.SendMediaRequest)
+    ]
+    assert [r.random_id for r in sent] == [-555, -555]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["missing", "size", "identity", "channel"])
+async def test_copy_never_confirms_wrong_missing_or_changed_documents(failure):
+    transport, native = await started()
+    if failure == "missing":
+        native.messages.clear()
+    elif failure == "size":
+        native.messages[MAIN, 77].document.size = 124
+    elif failure == "identity":
+        native.bad_copy = True
+    else:
+        native.messages[MAIN, 77].peer_id = types.PeerChannel(999)
+    with pytest.raises(ReplicaTransportError):
+        await transport.copy(MAIN, 77, BACKUP, random_id=123, expected_size=123)
+
+
+@pytest.mark.asyncio
+async def test_inspection_is_fresh_and_detects_public_change_before_copy():
+    transport, native = await started()
+    assert (await transport.inspect(BACKUP))["private"]
+    native.chats[BACKUP].username = "became_public"
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.copy(MAIN, 77, BACKUP, random_id=123, expected_size=123)
+    assert error.value.code == "REPLICA_PUBLIC_CHANNEL"
+    assert not native.receipts
+
+
+@pytest.mark.asyncio
+async def test_floodwait_carries_wait_without_provider_message_or_credentials():
+    transport, native = await started()
+    native.get_input_entity = AsyncMock(side_effect=FloodWaitError(None, capture=42))
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.inspect(BACKUP)
+    assert error.value.retryable and error.value.retry_after == 42
+    assert error.value.code == "REPLICA_FLOOD_WAIT"
+    assert TOKEN not in str(error.value)
+
+
+@pytest.mark.asyncio
+async def test_unresolved_numeric_channel_reports_access_without_provider_detail():
+    transport, native = await started()
+    native.get_input_entity = AsyncMock(side_effect=ValueError(TOKEN))
+    try:
+        with pytest.raises(ReplicaTransportError) as error:
+            await transport.inspect(BACKUP)
+        assert error.value.code == "REPLICA_ACCESS"
+        assert str(BACKUP) in str(error.value)
+        assert TOKEN not in str(error.value)
+        assert error.value.__cause__ is None
+        assert not native.requests
+    finally:
+        await transport.close()
+
+
+@pytest.mark.asyncio
+async def test_publish_verifies_remote_capsule_then_pins_backup(tmp_path):
+    transport, native = await started()
+    source = tmp_path / "snapshot.tgdb"
+    source.write_bytes(b"authenticated encrypted bytes")
+    result = await transport.publish(
+        BACKUP, source, random_id=12, caption="TGDrive replica", pin=True
+    )
+    assert result == 901 and native.pins[BACKUP] == 901
+    assert native.uploads[0]["file_name"] == CAPSULE_NAME
+    assert native.downloads[0][1]["file_size"] == source.stat().st_size
+    assert native.messages[BACKUP, 901].document.attributes[0].file_name == CAPSULE_NAME
+    result = await transport.publish(
+        MAIN, source, random_id=13, caption="TGDrive replica", pin=False
+    )
+    assert result == 902 and MAIN not in native.pins
+
+
+@pytest.mark.asyncio
+async def test_publish_does_not_pin_when_remote_size_or_bytes_do_not_match(tmp_path):
+    transport, native = await started()
+    source = tmp_path / "snapshot.tgdb"
+    source.write_bytes(b"snapshot")
+    original_download = native.iter_download
+
+    def corrupt(doc, **options):
+        native.body = b"corrupt!"
+        return original_download(doc, **options)
+
+    native.iter_download = corrupt
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.publish(BACKUP, source, random_id=12, caption="safe", pin=True)
+    assert error.value.code == "REPLICA_VERIFY_FAILED"
+    assert not native.pins
+
+
+@pytest.mark.asyncio
+async def test_publish_rejects_large_capsule_without_upload(tmp_path):
+    transport, native = await started()
+    source = tmp_path / "snapshot.tgdb"
+    with source.open("wb") as handle:
+        handle.truncate(MAX_CAPSULE_BYTES + 1)
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.publish(BACKUP, source, random_id=12, caption="safe", pin=True)
+    assert error.value.code == "REPLICA_ARCHIVE_TOO_LARGE"
+    assert native.uploads == []
+
+
+@pytest.mark.asyncio
+async def test_download_only_pinned_capsule_into_private_exclusive_path(tmp_path):
+    transport, native = await started()
+    native.messages[BACKUP, 901] = message(
+        901, BACKUP, document(len(native.body), CAPSULE_NAME)
+    )
+    native.pins[BACKUP] = 901
+    target = tmp_path / "recovery.tgdb"
+    assert await transport.download(BACKUP, None, target) == 901
+    assert target.read_bytes() == native.body
+    assert target.stat().st_mode & 0o777 == 0o600
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.download(BACKUP, 901, target)
+    assert error.value.code == "REPLICA_LOCAL_EXISTS"
+    assert target.read_bytes() == native.body
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("bad", ["name", "oversize", "truncated", "excess"])
+async def test_download_rejects_wrong_or_unbounded_capsules(tmp_path, bad):
+    transport, native = await started()
+    doc = document(len(native.body), CAPSULE_NAME)
+    if bad == "name":
+        doc.attributes[0].file_name = "../../etc/passwd"
+    elif bad == "oversize":
+        doc.size = MAX_CAPSULE_BYTES + 1
+    elif bad == "truncated":
+        doc.size += 1
+    else:
+        doc.size -= 1
+    native.messages[BACKUP, 901] = message(901, BACKUP, doc)
+    target = tmp_path / "recovery.tgdb"
+    with pytest.raises(ReplicaTransportError):
+        await transport.download(BACKUP, 901, target)
+    assert not target.exists()
+    assert list(tmp_path.iterdir()) == []
+
+
+@pytest.mark.asyncio
+async def test_cancelled_download_removes_partial_file_and_can_resume(tmp_path):
+    transport, native = await started()
+    native.messages[BACKUP, 901] = message(
+        901, BACKUP, document(len(native.body), CAPSULE_NAME)
+    )
+    native.delay_download = True
+    target = tmp_path / "recovery.tgdb"
+    task = asyncio.create_task(transport.download(BACKUP, 901, target))
+    await asyncio.sleep(0.01)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert list(tmp_path.iterdir()) == []
+    native.delay_download = False
+    assert await transport.download(BACKUP, 901, target) == 901
+
+
+@pytest.mark.asyncio
+async def test_missing_pin_does_not_search_history_or_download(tmp_path):
+    transport, native = await started()
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.download(BACKUP, None, tmp_path / "recovery.tgdb")
+    assert error.value.code == "REPLICA_CHECKPOINT_MISSING"
+    assert not native.downloads
+
+
+@pytest.mark.asyncio
+async def test_catalog_download_reads_only_explicit_legacy_name(tmp_path):
+    transport, native = await started()
+    native.messages[MAIN, 78] = message(
+        78, MAIN, document(len(native.body), "drive.json")
+    )
+    native.pins[MAIN] = 78
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.download(MAIN, None, tmp_path / "capsule.tgdb")
+    assert error.value.code == "REPLICA_DOCUMENT_TYPE"
+    assert not native.downloads
+    assert await transport.download_catalog(MAIN, tmp_path / "catalog.json") == 78
+    assert (tmp_path / "catalog.json").read_bytes() == native.body
+    assert MAIN in native.pins and native.pins[MAIN] == 78
+
+
+@pytest.mark.asyncio
+async def test_provider_exceptions_are_sanitized_and_cancellation_propagates():
+    transport, native = await started()
+    native.get_input_entity = AsyncMock(side_effect=RuntimeError(TOKEN))
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.inspect(MAIN)
+    assert TOKEN not in str(error.value)
+    assert error.value.code == "REPLICA_PROVIDER_ERROR"
+    assert error.value.__cause__ is None
+    native.get_input_entity = AsyncMock(side_effect=asyncio.CancelledError())
+    with pytest.raises(asyncio.CancelledError):
+        await transport.inspect(MAIN)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("value", [True, 0, 1, "-1001234567890"])
+async def test_invalid_channel_identifiers_are_rejected_before_network(value):
+    transport, native = await started()
+    with pytest.raises(ReplicaTransportError) as error:
+        await transport.inspect(value)
+    assert error.value.code == "REPLICA_INPUT"
+    assert not native.requests
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("state", ["exists", "missing", "wrong-size"])
+async def test_verify_existing_document_without_payload_download(state):
+    transport, native = await started()
+    if state == "missing":
+        native.messages.clear()
+    elif state == "wrong-size":
+        native.messages[MAIN, 77].document.size = 99
+    if state == "exists":
+        assert await transport.verify(MAIN, 77, 123) is None
+    else:
+        with pytest.raises(ReplicaTransportError):
+            await transport.verify(MAIN, 77, 123)
+    assert native.uploads == native.downloads == []
+    assert not native.receipts
+
+
+@pytest.mark.asyncio
+async def test_publish_catalog_preserves_exact_legacy_filename_and_pin(tmp_path):
+    transport, native = await started()
+    source = tmp_path / "catalog.json"
+    source.write_bytes(b'{"schema_version":4}')
+    result = await transport.publish_catalog(
+        MAIN, source, random_id=99, caption="TGDrive checkpoint v1", pin=True
+    )
+    assert native.pins[MAIN] == result
+    assert native.uploads[0]["file_name"] == "drive.json"
+    assert (
+        native.messages[MAIN, result].document.attributes[0].file_name == "drive.json"
+    )
+    target = tmp_path / "restored.json"
+    assert await transport.download_catalog(MAIN, target) == result
+    assert target.read_bytes() == source.read_bytes()
+
+
+@pytest.mark.asyncio
+async def test_pinned_message_reads_only_current_pin_without_messages_or_history():
+    transport, native = await started()
+    assert await transport.pinned_message(BACKUP) is None
+    native.pins[BACKUP] = 901
+    assert await transport.pinned_message(BACKUP) == 901
+    assert all(
+        isinstance(request, functions.channels.GetFullChannelRequest)
+        for request in native.requests
+    )
+    assert not native.downloads and not native.uploads and not native.receipts
+    native.pins[BACKUP] = True
+    with pytest.raises(ReplicaTransportError):
+        await transport.pinned_message(BACKUP)
+
+
+@pytest.mark.asyncio
+async def test_channel_auto_delete_prevents_backup_copy_before_publishing():
+    transport, native = await started()
+    original = native.__class__.__call__
+
+    async def with_auto_delete(self, request):
+        result = await original(self, request)
+        if isinstance(request, functions.channels.GetFullChannelRequest):
+            result.full_chat.ttl_period = 86400
+        return result
+
+    from unittest.mock import patch
+
+    with (
+        patch.object(native.__class__, "__call__", with_auto_delete),
+        pytest.raises(ReplicaTransportError) as error,
+    ):
+        await transport.copy(MAIN, 77, BACKUP, random_id=123, expected_size=123)
+    assert error.value.code == "REPLICA_AUTO_DELETE"
+    assert not native.receipts
diff --git a/tests/storage/__init__.py b/tests/storage/__init__.py
new file mode 100644
index 00000000..a5bc7be3
--- /dev/null
+++ b/tests/storage/__init__.py
@@ -0,0 +1 @@
+"""TGDrive storage tests."""
diff --git a/tests/storage/test_file_parts.py b/tests/storage/test_file_parts.py
new file mode 100644
index 00000000..6894a204
--- /dev/null
+++ b/tests/storage/test_file_parts.py
@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import sqlite3
+from contextlib import closing
+
+import pytest
+
+from tgdrive.core.errors import (
+    CorruptStoreError,
+    PersistenceError,
+    UnsupportedSchemaError,
+    ValidationError,
+)
+from tgdrive.recovery.backup import decode_catalog_snapshot
+from tgdrive.storage.file_parts import MAX_FILE_PARTS, validate_parts, validate_sha256
+from tgdrive.storage.store import SCHEMA_VERSION, DriveStore
+
+DATA = b"complete logical file"
+SHA = hashlib.sha256(DATA).hexdigest()
+
+
+def manifest():
+    pieces = [DATA[:8], DATA[8:]]
+    return [
+        {
+            "index": index,
+            "offset": 0 if index == 0 else len(pieces[0]),
+            "size": len(content),
+            "message_id": 101 + index,
+            "sha256": hashlib.sha256(content).hexdigest(),
+        }
+        for index, content in enumerate(pieces)
+    ]
+
+
+def full(item):
+    return item["path"].rstrip("/") + "/" + item["id"]
+
+
+@pytest.fixture
+def store():
+    result = DriveStore.create()
+    yield result
+    result.close()
+
+
+def add(store, *, operation_id="logical-upload-operation", parts=None):
+    return store.add_file(
+        "/",
+        "large-video.mp4",
+        101,
+        len(DATA),
+        parts=manifest() if parts is None else parts,
+        sha256=SHA,
+        operation_id=operation_id,
+    )
+
+
+def test_manifest_is_canonical_and_independent():
+    original = manifest()
+    original[0]["sha256"] = original[0]["sha256"].upper()
+    result = validate_parts(original, size=len(DATA), message_id=101)
+    assert result == manifest()
+    result[0]["message_id"] = 999
+    assert original[0]["message_id"] == 101
+    assert validate_sha256(SHA.upper()) == SHA
+    assert validate_sha256(None) is None
+    with pytest.raises(ValidationError):
+        validate_sha256(None, optional=False)
+
+
+@pytest.mark.parametrize(
+    "damage",
+    [
+        "empty",
+        "limit",
+        "not-list",
+        "unknown-field",
+        "missing-sha",
+        "invalid-sha",
+        "null-sha",
+        "bool-index",
+        "index-gap",
+        "offset-gap",
+        "overlap",
+        "zero-size",
+        "negative-size",
+        "overflow",
+        "duplicate-message",
+        "anchor",
+        "sum-short",
+        "sum-long",
+    ],
+)
+def test_invalid_manifests_never_create_partial_catalog_metadata(store, damage):
+    parts = manifest()
+    if damage == "empty":
+        parts = []
+    elif damage == "limit":
+        parts = [parts[0]] * (MAX_FILE_PARTS + 1)
+    elif damage == "not-list":
+        parts = tuple(parts)
+    elif damage == "unknown-field":
+        parts[0]["token"] = "not-allowed"
+    elif damage == "missing-sha":
+        parts[0].pop("sha256")
+    elif damage == "invalid-sha":
+        parts[0]["sha256"] = "not-a-checksum"
+    elif damage == "null-sha":
+        parts[0]["sha256"] = None
+    elif damage == "bool-index":
+        parts[0]["index"] = False
+    elif damage == "index-gap":
+        parts[1]["index"] = 2
+    elif damage == "offset-gap":
+        parts[1]["offset"] += 1
+    elif damage == "overlap":
+        parts[1]["offset"] -= 1
+    elif damage == "zero-size":
+        parts[0]["size"] = 0
+    elif damage == "negative-size":
+        parts[0]["size"] = -1
+    elif damage == "overflow":
+        parts[0]["size"] = 1 << 63
+    elif damage == "duplicate-message":
+        parts[1]["message_id"] = 101
+    elif damage == "anchor":
+        parts[0]["message_id"] = 99
+    elif damage == "sum-short":
+        parts[1]["size"] -= 1
+    elif damage == "sum-long":
+        parts[1]["size"] += 1
+    revision = store.revision
+    with pytest.raises(ValidationError):
+        add(store, parts=parts)
+    assert store.list_directory("/") == {}
+    assert store.revision == revision
+    assert not store.has_file_operation("logical-upload-operation")
+
+
+def test_atomic_commit_idempotency_and_public_records_do_not_expose_provider_parts(
+    store,
+):
+    before = store.revision
+    item = add(store)
+    result = store.get_file(full(item))
+    assert result["parts"] == manifest() and result["sha256"] == SHA
+    assert result["message_id"] == 101 and result["part_count"] == 2
+    assert store.revision == before + 1
+    public = store.list_directory("/")[item["id"]]
+    assert public["part_count"] == 2
+    assert not {"parts", "sha256", "message_id"}.intersection(public)
+    assert store.search_page("large")["items"][0]["part_count"] == 2
+    repeated = store.add_file(
+        "/",
+        "renamed-on-retry.mp4",
+        101,
+        len(DATA),
+        parts=manifest(),
+        sha256=SHA,
+        operation_id="logical-upload-operation",
+        keep_both=True,
+    )
+    assert repeated["id"] == item["id"] and repeated["name"] == "large-video.mp4"
+    assert store.revision == before + 1
+    changed = manifest()
+    changed[1]["message_id"] = 103
+    with pytest.raises(ValidationError):
+        add(store, parts=changed)
+    assert store.revision == before + 1
+    result["parts"][0]["message_id"] = 999
+    assert store.get_file(full(item))["parts"] == manifest()
+
+
+def test_part_insert_failure_rolls_back_node_operation_and_revision(store, monkeypatch):
+    original = store._insert_parts
+    before = store.revision
+
+    def fail(database, identity, parts):
+        original(database, identity, parts[:1])
+        raise PersistenceError("simulated disk failure after first part")
+
+    monkeypatch.setattr(store, "_insert_parts", fail)
+    with pytest.raises(PersistenceError):
+        add(store)
+    assert store.revision == before and not store.list_directory("/")
+    assert not store.has_file_operation("logical-upload-operation")
+    with store._transaction() as database:
+        assert database.execute("SELECT count(*) FROM file_parts").fetchone()[0] == 0
+    monkeypatch.setattr(store, "_insert_parts", original)
+    assert add(store)["part_count"] == 2
+
+
+def test_multipart_move_share_trash_and_recover_keep_one_logical_identity(store):
+    item = add(store)
+    folder = store.create_folder("/", "Movies")
+    token = store.create_share(full(item))
+    moved = store.move(full(item), full(folder))
+    file_path = full(folder) + "/" + item["id"]
+    assert moved["id"] == item["id"]
+    assert store.authorize_file(file_path, token)
+    store.set_trashed(file_path, True)
+    store.set_trashed(file_path, False)
+    restored = DriveStore._from_payload(store.export(), revoke_shares=True)
+    try:
+        result = restored.get_file(file_path)
+        assert result["parts"] == manifest() and result["sha256"] == SHA
+        assert result["id"] == item["id"]
+        assert not restored.authorize_file(file_path, token)
+        assert restored.has_file_operation("logical-upload-operation")
+    finally:
+        restored.close()
+
+
+def test_catalog_deletion_forgets_all_parts_without_remote_confirmations(store):
+    item = add(store)
+    store.set_trashed(full(item), True)
+    intent = store.begin_deletion(full(item), channel_id=-1001234567890)
+    assert intent["message_ids"] == [101, 102]
+    store.confirm_deletion_messages(intent["id"], [101])
+    recovered = DriveStore._from_payload(store.export())
+    try:
+        assert (
+            recovered.get_file(full(item), include_trashed=True)["parts"] == manifest()
+        )
+        pending = recovered.pending_deletions()[0]
+        assert pending["pending_message_ids"] == [102]
+        assert recovered.finish_deletion(intent["id"]) == [101, 102]
+        assert recovered.pending_deletions() == []
+        assert recovered.export()["deletions"][0]["message_ids"] == []
+        with recovered._transaction() as database:
+            assert (
+                database.execute("SELECT count(*) FROM file_parts").fetchone()[0] == 0
+            )
+        assert recovered.has_file_operation("logical-upload-operation")
+        again = DriveStore._from_payload(recovered.export())
+        again.close()
+    finally:
+        recovered.close()
+
+
+def test_portable_v4_rejects_missing_delete_reference_or_changed_manifest(store):
+    item = add(store)
+    store.set_trashed(full(item), True)
+    store.begin_deletion(full(item))
+    payload = store.export()
+    damaged = copy.deepcopy(payload)
+    damaged["deletions"][0]["message_ids"] = [101]
+    damaged["deletions"][0]["pending_message_ids"] = [101]
+    with pytest.raises(CorruptStoreError):
+        DriveStore._from_payload(damaged)
+    damaged = copy.deepcopy(payload)
+    damaged["root"]["children"][item["id"]]["parts"][1]["offset"] += 1
+    with pytest.raises(CorruptStoreError):
+        DriveStore._from_payload(damaged)
+
+
+def test_portable_catalog_recovery_keeps_all_part_ids_and_revokes_shares():
+    source = DriveStore.create()
+    recovered = None
+    try:
+        item = add(source)
+        token = source.create_share(full(item))
+        payload = decode_catalog_snapshot(source.backup_snapshot()[1])
+        assert payload["schema_version"] == SCHEMA_VERSION
+        recovered = DriveStore._from_payload(payload, revoke_shares=True)
+        result = recovered.get_file(full(item))
+        assert result["parts"] == manifest() and result["sha256"] == SHA
+        assert result["message_id"] == 101 and result["id"] == item["id"]
+        assert recovered.drive_id == source.drive_id
+        assert recovered.has_file_operation("logical-upload-operation")
+        assert not recovered.authorize_file(full(item), token)
+    finally:
+        if recovered is not None:
+            recovered.close()
+        source.close()
+
+
+def test_exact_4096_part_boundary_is_supported_atomically(store):
+    checksum = hashlib.sha256(b"x").hexdigest()
+    parts = [
+        {
+            "index": index,
+            "offset": index,
+            "size": 1,
+            "message_id": index + 1,
+            "sha256": checksum,
+        }
+        for index in range(MAX_FILE_PARTS)
+    ]
+    item = store.add_file("/", "many-parts.bin", 1, MAX_FILE_PARTS, parts=parts)
+    result = store.get_file(full(item))
+    assert result["part_count"] == MAX_FILE_PARTS
+    assert result["parts"] == parts
+    assert len(store.message_ids(full(item))) == MAX_FILE_PARTS
+
+
+@pytest.mark.parametrize("document_id", [1, -1, (1 << 63) - 1, -(1 << 63)])
+def test_optional_immutable_document_id_roundtrips_without_public_leak(
+    store, document_id
+):
+    parts = manifest()
+    parts[0]["document_id"] = document_id
+    item = add(store, parts=parts)
+    assert store.get_file(full(item))["parts"] == parts
+    restored = DriveStore._from_payload(store.export())
+    try:
+        assert restored.get_file(full(item))["parts"] == parts
+        assert "document_id" not in json.dumps(restored.list_directory("/"))
+        assert "document_id" not in parts[1]
+        changed = copy.deepcopy(parts)
+        changed[0]["document_id"] = 999
+        with pytest.raises(ValidationError):
+            add(restored, parts=changed)
+    finally:
+        restored.close()
+
+
+@pytest.mark.parametrize("document_id", [None, 0, True, "123", 1 << 63, -(1 << 63) - 1])
+def test_present_document_identity_must_be_a_nonzero_signed_integer(store, document_id):
+    parts = manifest()
+    parts[0]["document_id"] = document_id
+    with pytest.raises(ValidationError):
+        add(store, parts=parts)
+    assert not store.list_directory("/")
+
+
+@pytest.mark.parametrize("version", range(1, DriveStore.DATABASE_VERSION))
+def test_previous_database_schema_is_rejected_without_upgrade(tmp_path, version):
+    database = tmp_path / "drive.sqlite3"
+    source = DriveStore.create(database)
+    source.add_file("/", "current.bin", 333, 13)
+    source.close()
+    with closing(sqlite3.connect(database)) as connection:
+        connection.execute(f"PRAGMA user_version={version}")
+        connection.commit()
+    with pytest.raises(UnsupportedSchemaError, match="database schema"):
+        DriveStore.load(database)
+    with closing(sqlite3.connect(database)) as connection:
+        assert connection.execute("PRAGMA user_version").fetchone()[0] == version
+
+
+@pytest.mark.parametrize("version", range(1, SCHEMA_VERSION))
+def test_previous_portable_schema_is_rejected(store, version):
+    payload = store.export()
+    payload["schema_version"] = version
+    with pytest.raises(UnsupportedSchemaError, match="metadata schema"):
+        DriveStore._from_payload(payload)
diff --git a/tests/storage/test_metadata_transactions.py b/tests/storage/test_metadata_transactions.py
new file mode 100644
index 00000000..b4f9e57f
--- /dev/null
+++ b/tests/storage/test_metadata_transactions.py
@@ -0,0 +1,182 @@
+"""Atomic metadata batches roll back names, ancestry, shares and revisions together."""
+
+import copy
+
+import pytest
+
+from tests.support.mongo_fixtures import FakeMongoBackend
+from tgdrive.core.errors import (
+    NotFoundError,
+    PersistenceError,
+    RootMutationError,
+    TrashedItemError,
+)
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.storage.store import DriveStore
+
+
+def test_later_mutation_failure_restores_every_prior_change_and_revision():
+    store = DriveStore.create()
+    try:
+        first = store.create_folder("/", "First")
+        second = store.create_folder("/", "Second")
+        first_path, second_path = "/" + first["id"], "/" + second["id"]
+        token = store.create_share(first_path)
+        before = store.export()
+        with pytest.raises(NotFoundError), store.metadata_batch():
+            store.move(second_path, first_path)
+            store.set_trashed(first_path, True)
+            store.set_trashed("/missing", True)
+        assert store.export() == before
+        assert store.authorize_directory(first_path, token)
+    finally:
+        store.close()
+
+
+def test_caught_inner_error_rolls_back_savepoint_without_corrupting_outer_batch():
+    store = DriveStore.create()
+    try:
+        original = store.create_folder("/", "Original")
+        path = "/" + original["id"]
+        before = store.revision
+        with store.metadata_batch():
+            store.rename(path, "Committed")
+            with pytest.raises(NotFoundError), store.metadata_batch():
+                store.set_trashed(path, True)
+                store.get_directory("/missing")
+            assert store.get_directory(path)["name"] == "Committed"
+        assert store.get_directory(path)["name"] == "Committed"
+        assert store.revision == before + 1
+    finally:
+        store.close()
+
+
+def test_sqlite_abort_rolls_back_entire_batch_and_connection_remains_usable():
+    store = DriveStore.create()
+    try:
+        node = store.create_folder("/", "Original")
+        path = "/" + node["id"]
+        before = store.export()
+        with pytest.raises(PersistenceError), store.metadata_batch():
+            store.rename(path, "Changed")
+            with store._transaction(write=True) as db:
+                db.execute("INSERT INTO nodes(id) VALUES(?)", ("root",))
+        assert store.export() == before
+        assert store.rename(path, "After rollback")["name"] == "After rollback"
+    finally:
+        store.close()
+
+
+def test_outer_read_cannot_escalate_to_nested_write():
+    store = DriveStore.create()
+    try:
+        before = store.export()
+        with (
+            pytest.raises(PersistenceError, match="cannot become writable"),
+            store._transaction(),
+        ):
+            store.create_folder("/", "Forbidden")
+        assert store.export() == before
+    finally:
+        store.close()
+
+
+def test_deletion_preflight_never_mutates_and_accepts_pending_same_root_retry():
+    store = DriveStore.create()
+    try:
+        node = store.create_folder("/", "Target")
+        path = "/" + node["id"]
+        with pytest.raises(RootMutationError):
+            store.validate_deletion("/")
+        with pytest.raises(TrashedItemError):
+            store.validate_deletion(path)
+        store.set_trashed(path, True)
+        before = store.export()
+        assert store.validate_deletion(path)["id"] == node["id"]
+        assert store.export() == before
+        store.begin_deletion(path)
+        before = store.export()
+        assert store.validate_deletion(path)["id"] == node["id"]
+        assert store.export() == before
+    finally:
+        store.close()
+
+
+@pytest.mark.parametrize("backend", ["sqlite", "mongodb"])
+@pytest.mark.parametrize("action", ["move", "trash", "restore"])
+def test_batch_failure_rolls_back_earlier_items_and_share_access(backend, action):
+    store = (
+        DriveStore.create()
+        if backend == "sqlite"
+        else MongoStore.create(FakeMongoBackend())
+    )
+    try:
+        first = store.create_folder("/", "First")
+        destination = store.create_folder("/", "Destination")
+        first_path = "/" + first["id"]
+        token = store.create_share(first_path)
+        if action == "restore":
+            store.set_trashed(first_path, True)
+        before = store.export()
+        with pytest.raises(NotFoundError):
+            if action == "move":
+                store.move_many([first_path, "/missing"], "/" + destination["id"])
+            elif action == "trash":
+                store.set_trashed_many([first_path, "/missing"], True)
+            else:
+                store.set_trashed_many([first_path, "/missing"], False)
+        assert store.export() == before
+        if action != "restore":
+            assert store.authorize_directory(first_path, token)
+        assert store.create_folder("/", "Still usable")["name"] == "Still usable"
+    finally:
+        store.close()
+
+
+@pytest.mark.parametrize("count", [2, 24])
+@pytest.mark.parametrize("action", ["move", "trash", "restore"])
+def test_mongo_bulk_catalog_copies_do_not_grow_with_selection(
+    monkeypatch, count, action
+):
+    store = MongoStore.create(FakeMongoBackend())
+    try:
+        paths = [
+            "/" + store.create_folder("/", f"Item {index}")["id"]
+            for index in range(count)
+        ]
+        destination = "/" + store.create_folder("/", "Destination")["id"]
+        if action == "restore":
+            store.set_trashed_many(paths, True)
+        before_revision = store.revision
+        deepcopy = copy.deepcopy
+        catalog_copies = []
+
+        def track(value, memo=None):
+            if (
+                isinstance(value, dict)
+                and {"metadata", "nodes", "shares"} <= value.keys()
+            ):
+                catalog_copies.append(value)
+            return deepcopy(value, memo)
+
+        monkeypatch.setattr("tgdrive.storage.mongo_store.copy.deepcopy", track)
+        with store.metadata_batch():
+            if action == "move":
+                results = store.move_many(paths, destination)
+            else:
+                results = store.set_trashed_many(paths, action == "trash")
+        assert len(catalog_copies) <= 2
+        assert len(results) == count
+        assert store.revision == before_revision + count
+        assert {row["id"] for row in results} == {path[1:] for path in paths}
+        if action == "move":
+            assert set(store.list_directory(destination)) == {
+                path[1:] for path in paths
+            }
+        else:
+            actual = (
+                store.list_trash() if action == "trash" else store.list_directory("/")
+            )
+            assert {path[1:] for path in paths} <= actual.keys()
+    finally:
+        store.close()
diff --git a/tests/storage/test_mongo_initialization.py b/tests/storage/test_mongo_initialization.py
new file mode 100644
index 00000000..8f1ef886
--- /dev/null
+++ b/tests/storage/test_mongo_initialization.py
@@ -0,0 +1,150 @@
+"""MongoDB-only startup must not replace saved or partially lost drive state."""
+
+from threading import RLock
+from types import SimpleNamespace
+from unittest.mock import MagicMock, Mock
+
+import pytest
+from pymongo.errors import InvalidURI
+
+from tgdrive.core.errors import CorruptStoreError
+from tgdrive.recovery.mongo_backup import COLLECTIONS
+from tgdrive.storage.mongo import (
+    DatabaseUnavailable,
+    MongoBackend,
+    for_settings,
+    initialize_if_empty,
+)
+
+
+class Collections(dict):
+    __getattr__ = dict.__getitem__
+
+
+@pytest.fixture
+def backend():
+    collections = Collections(
+        {
+            name: SimpleNamespace(find_one=Mock(return_value=None))
+            for name in COLLECTIONS
+        }
+    )
+    return SimpleNamespace(
+        db=collections,
+        fence=Mock(),
+        transaction=lambda callback: callback(None),
+    )
+
+
+def test_missing_mongodb_configuration_has_no_local_backend_fallback():
+    with pytest.raises(DatabaseUnavailable, match="MONGODB_URI is required"):
+        for_settings(SimpleNamespace(mongodb_uri=None))
+
+
+def test_malformed_uri_error_does_not_expose_database_credentials(monkeypatch):
+    secret = "mongodb://private-user:private-password@synthetic.invalid"
+    monkeypatch.setattr(
+        "tgdrive.storage.mongo.MongoClient", Mock(side_effect=InvalidURI(secret))
+    )
+    with pytest.raises(DatabaseUnavailable, match="configuration is invalid") as caught:
+        MongoBackend(secret, "tgdrive")
+    assert "private-user" not in str(caught.value)
+    assert "private-password" not in str(caught.value)
+    assert caught.value.__suppress_context__
+
+
+@pytest.mark.parametrize("collection", ["settings", "jobs", "nodes", "backups"])
+def test_missing_catalog_with_saved_records_is_never_initialized(
+    tmp_path, monkeypatch, backend, collection
+):
+    backend.db[collection].find_one.return_value = {"_id": "saved"}
+    create = Mock()
+    monkeypatch.setattr("tgdrive.storage.mongo_store.MongoStore.create", create)
+    with pytest.raises(CorruptStoreError, match="saved drive state"):
+        initialize_if_empty(SimpleNamespace(resolved_data_dir=tmp_path), backend)
+    create.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "marker",
+    ["mongodb-drive.json", "replica-bootstrap.json", "channel-activation.json"],
+)
+def test_preserved_installation_does_not_recreate_an_empty_database(
+    tmp_path, monkeypatch, backend, marker
+):
+    path = tmp_path / marker
+    path.write_bytes(b"preserved installation state")
+    create = Mock()
+    monkeypatch.setattr("tgdrive.storage.mongo_store.MongoStore.create", create)
+    with pytest.raises(CorruptStoreError, match="existing drive or recovery state"):
+        initialize_if_empty(SimpleNamespace(resolved_data_dir=tmp_path), backend)
+    create.assert_not_called()
+    assert path.read_bytes() == b"preserved installation state"
+
+
+def test_existing_catalog_is_reused_without_initialization(
+    tmp_path, monkeypatch, backend
+):
+    backend.db.catalog.find_one.return_value = {"_id": "catalog"}
+    create = Mock()
+    monkeypatch.setattr("tgdrive.storage.mongo_store.MongoStore.create", create)
+    assert not initialize_if_empty(SimpleNamespace(resolved_data_dir=tmp_path), backend)
+    create.assert_not_called()
+
+
+def test_first_setup_rolls_back_catalog_when_initial_settings_cannot_be_saved(
+    tmp_path, monkeypatch
+):
+    from tests.support.app_fixtures import make_settings
+    from tests.support.mongo_fixtures import register_test_backend
+
+    settings = make_settings(tmp_path)
+    backend = register_test_backend(monkeypatch, settings)
+    backend.db.settings.insert_many = Mock(side_effect=RuntimeError("write failed"))
+
+    with pytest.raises(RuntimeError, match="write failed"):
+        initialize_if_empty(settings, backend)
+
+    assert backend.db.catalog.find_one({}) is None
+    assert backend.db.nodes.find_one({}) is None
+    assert not (settings.resolved_data_dir / "mongodb-drive.json").exists()
+
+
+def test_first_setup_applies_initial_connections_without_a_restart(
+    tmp_path, monkeypatch
+):
+    from tests.support.app_fixtures import make_settings
+    from tests.support.mongo_fixtures import register_test_backend
+    from tgdrive.settings.management import ConnectionManager
+
+    settings = make_settings(tmp_path)
+    backend = register_test_backend(monkeypatch, settings)
+    assert initialize_if_empty(settings, backend)
+
+    manager = ConnectionManager(settings, SimpleNamespace(mongo=backend))
+    assert settings.managed_revision == 1
+    assert tuple(row.id for row in manager.active) == settings.managed_client_ids
+    assert not manager.restart_required
+
+
+def test_archive_restore_pause_blocks_old_writers_but_allows_restore_transaction():
+    backend = object.__new__(MongoBackend)
+    backend._write_lock = RLock()
+    backend._writes_paused = False
+    session = Mock()
+    backend.client = MagicMock()
+    backend.client.start_session.return_value.__enter__.return_value = session
+    backend.pause_writes()
+
+    with pytest.raises(DatabaseUnavailable, match="restore has paused"):
+        backend.transaction(Mock())
+    with pytest.raises(DatabaseUnavailable, match="restore has paused"):
+        backend.write(Mock(), "replace_one", {}, {})
+    backend.client.start_session.assert_not_called()
+
+    restore = Mock()
+    backend.transaction(restore, allow_paused=True)
+    assert session.with_transaction.call_args.args[0] is restore
+
+    with pytest.raises(DatabaseUnavailable, match="restore has paused"):
+        backend.transaction(Mock())
diff --git a/tests/storage/test_mongo_only_persistence.py b/tests/storage/test_mongo_only_persistence.py
new file mode 100644
index 00000000..59edac75
--- /dev/null
+++ b/tests/storage/test_mongo_only_persistence.py
@@ -0,0 +1,54 @@
+"""Application persistence never substitutes a local database or settings file."""
+
+from types import SimpleNamespace
+
+import pytest
+from pymongo.errors import ConnectionFailure
+
+from tgdrive.core.security import SessionManager
+from tgdrive.settings.managed_settings import SettingsProblem, read_document
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.transfers.tasks import TransferRegistry
+from tgdrive.transfers.uploads import ResumableUploads
+
+
+def test_transfer_registry_rejects_local_database_path(tmp_path):
+    path = tmp_path / "jobs.sqlite3"
+    with pytest.raises(ValueError, match="requires MongoDB"):
+        TransferRegistry(database_path=path)
+    assert not path.exists()
+
+
+def test_managed_settings_do_not_read_legacy_local_document(tmp_path):
+    path = tmp_path / "telegram-settings.json"
+    path.write_text('{"local": "obsolete"}')
+    with pytest.raises(SettingsProblem, match="require a configured MongoDB"):
+        read_document(tmp_path)
+    assert path.read_text() == '{"local": "obsolete"}'
+
+
+def test_session_loading_rejects_mongodb_connection_failure():
+    def unavailable(_query):
+        raise ConnectionFailure("synthetic private URI")
+
+    backend = SimpleNamespace(
+        db=SimpleNamespace(sessions=SimpleNamespace(find=unavailable))
+    )
+    with pytest.raises(DatabaseUnavailable, match="Owner sign-in requires") as error:
+        SessionManager(b"x" * 32, 3600, mongo_backend=backend)
+    assert "synthetic private URI" not in str(error.value)
+
+
+def test_upload_receipts_cannot_fall_back_to_sqlite(tmp_path, monkeypatch):
+    settings = SimpleNamespace(
+        resolved_data_dir=tmp_path / "data",
+        resolved_cache_dir=tmp_path / "cache",
+    )
+
+    def unavailable(_settings):
+        raise DatabaseUnavailable("MongoDB is unavailable")
+
+    monkeypatch.setattr("tgdrive.storage.mongo.for_settings", unavailable)
+    with pytest.raises(DatabaseUnavailable, match="MongoDB is unavailable"):
+        ResumableUploads(settings, object())
+    assert not (settings.resolved_data_dir / "uploads.sqlite3").exists()
diff --git a/tests/storage/test_mongo_receipt_ingress.py b/tests/storage/test_mongo_receipt_ingress.py
new file mode 100644
index 00000000..81f5dcc2
--- /dev/null
+++ b/tests/storage/test_mongo_receipt_ingress.py
@@ -0,0 +1,133 @@
+"""Slow receipt commits must not freeze streaming or acknowledge early."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import threading
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+from tests.storage.test_mongodb import backend as backend_fixture
+from tests.transfers.test_resumable_uploads import Manager
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.transfers.uploads import ResumableUploads
+
+backend = backend_fixture
+pytestmark = pytest.mark.skipif(
+    os.environ.get("TGDRIVE_MONGO_TESTS") != "1",
+    reason="Set TGDRIVE_MONGO_TESTS=1 for isolated MongoDB receipt checks",
+)
+
+
+def receipt_for(backend, tmp_path):
+    settings = SimpleNamespace(
+        resolved_cache_dir=tmp_path / "cache",
+        resolved_data_dir=tmp_path / "data",
+        max_concurrent_transfers=2,
+        upload_limit=16 * 1024**2,
+        staging_budget_bytes=32 * 1024**2,
+        min_free_bytes=0,
+        upload_session_ttl_seconds=3600,
+    )
+    manager = Manager(tmp_path, backend=backend)
+    with patch("tgdrive.storage.mongo.for_settings", return_value=backend):
+        uploads = ResumableUploads(settings, manager)
+    return uploads, manager
+
+
+@pytest.mark.asyncio
+async def test_receipt_commit_allows_event_loop_to_run_and_drains_on_disconnect(
+    backend, tmp_path, monkeypatch
+):
+    uploads, manager = receipt_for(backend, tmp_path)
+    payload = b"receipt data" * 10000
+    item = uploads.create("receipt.bin", "/", len(payload))
+    entered, release = threading.Event(), threading.Event()
+    original = backend.write
+    loop_thread = threading.get_ident()
+
+    def slow_commit(*args, **kwargs):
+        entered.set()
+        assert threading.get_ident() != loop_thread, (
+            "A synchronous MongoDB receipt commit must not block the HTTP event loop"
+        )
+        assert release.wait(3), "The event loop could not release the slow commit"
+        return original(*args, **kwargs)
+
+    monkeypatch.setattr(backend, "write", slow_commit)
+    task = asyncio.create_task(uploads.append(item["id"], 0, payload))
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        if task.done():
+            task.result()
+        # This coroutine runs while the actual MongoDB commit is deliberately
+        # held. Existing committed state remains readable, and ACK is pending.
+        assert not task.done()
+        assert uploads.get_unchecked(item["id"])["offset"] == 0
+        assert backend.db.receipts.find_one({"_id": item["id"]})["data"]["offset"] == 0
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        await asyncio.sleep(0)
+        assert not task.done()  # Disconnect cannot abandon a commit in progress.
+        assert uploads.locks[item["id"]].locked()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        committed = uploads.get_unchecked(item["id"])
+        assert committed["offset"] == len(payload)
+        assert committed["checksums"] == [
+            {
+                "offset": 0,
+                "size": len(payload),
+                "sha256": hashlib.sha256(payload).hexdigest(),
+            }
+        ]
+        assert backend.db.receipts.find_one({"_id": item["id"]})["data"] == committed
+        assert uploads.path(item["id"]).read_bytes() == payload
+        idle = uploads.locks.get(item["id"])
+        assert idle is None or not idle.locked()
+    finally:
+        release.set()
+        task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+        uploads.close()
+        manager.registry.close()
+
+
+@pytest.mark.asyncio
+async def test_failed_cloud_receipt_commit_keeps_old_offset_and_retries_exactly_once(
+    backend, tmp_path, monkeypatch
+):
+    uploads, manager = receipt_for(backend, tmp_path)
+    payload = b"durable retry" * 20000
+    item = uploads.create("retry.bin", "/", len(payload))
+    original = backend.write
+
+    def unavailable(*_args, **_kwargs):
+        raise DatabaseUnavailable("Synthetic receipt transaction failure")
+
+    try:
+        monkeypatch.setattr(backend, "write", unavailable)
+        with pytest.raises(DatabaseUnavailable):
+            await uploads.append(item["id"], 0, payload)
+        assert uploads.get_unchecked(item["id"])["offset"] == 0
+        assert backend.db.receipts.find_one({"_id": item["id"]})["data"]["offset"] == 0
+        idle = uploads.locks.get(item["id"])
+        assert idle is None or not idle.locked()
+        monkeypatch.setattr(backend, "write", original)
+        committed = await uploads.append(item["id"], 0, payload)
+        assert committed["offset"] == len(payload)
+        assert len(committed["checksums"]) == 1
+        assert (
+            committed["checksums"][0]["sha256"] == hashlib.sha256(payload).hexdigest()
+        )
+        assert uploads.path(item["id"]).read_bytes() == payload
+        assert backend.db.receipts.find_one({"_id": item["id"]})["data"] == committed
+    finally:
+        uploads.close()
+        manager.registry.close()
diff --git a/tests/storage/test_mongodb.py b/tests/storage/test_mongodb.py
new file mode 100644
index 00000000..0a2f20a5
--- /dev/null
+++ b/tests/storage/test_mongodb.py
@@ -0,0 +1,709 @@
+"""Focused live MongoDB persistence checks using disposable, isolated databases.
+
+Opt in with TGDRIVE_MONGO_TESTS=1. The configured TGDrive database is never used.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import secrets
+from types import SimpleNamespace
+
+import pytest
+
+from tgdrive.core.errors import DuplicateNameError, NotFoundError, ValidationError
+from tgdrive.core.security import InvalidSession, SessionManager
+from tgdrive.recovery.mongo_backup import (
+    decode_snapshot,
+    restore_snapshot,
+    write_snapshot,
+)
+from tgdrive.storage.mongo import DatabaseUnavailable, MongoBackend, configure
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.telegram.client_identity import IdentityCache
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+pytestmark = pytest.mark.skipif(
+    os.environ.get("TGDRIVE_MONGO_TESTS") != "1",
+    reason="Set TGDRIVE_MONGO_TESTS=1 for isolated live MongoDB checks",
+)
+
+
+def mongo_uri():
+    uri = os.environ.get("TGDRIVE_TEST_MONGODB_URI")
+    if not uri:
+        raise pytest.UsageError(
+            "Set TGDRIVE_TEST_MONGODB_URI to an isolated MongoDB replica set"
+        )
+    return uri
+
+
+@pytest.fixture
+def backend(tmp_path):
+    uri = mongo_uri()
+    name = "tgdrive_test_" + secrets.token_hex(8)
+    instance = configure(tmp_path, uri, name)
+    instance.acquire()
+    try:
+        yield instance
+    finally:
+        instance.release()
+        assert instance.db.name == name and name.startswith("tgdrive_test_")
+        instance.client.drop_database(name)
+        instance.client.close()
+
+
+@pytest.fixture
+def store(backend):
+    instance = MongoStore.create(backend)
+    try:
+        yield instance
+    finally:
+        instance.close()
+
+
+def path(row):
+    return row["path"].rstrip("/") + "/" + row["id"]
+
+
+def test_performance_history_survives_restart_without_local_sqlite(
+    backend, tmp_path, monkeypatch
+):
+    import sqlite3
+
+    from tgdrive.observability.telemetry_history import (
+        RETENTION_SECONDS,
+        TelemetryHistory,
+    )
+
+    monkeypatch.setattr(
+        sqlite3,
+        "connect",
+        lambda *_a, **_k: pytest.fail("SQLite used for Mongo telemetry"),
+    )
+
+    def sample(at):
+        return dict(
+            at=at,
+            cpu_percent=25,
+            cpu_scope="cgroup",
+            memory_bytes=1024,
+            memory_limit_bytes=8192,
+            received_bytes_per_second=100,
+            sent_bytes_per_second=50,
+            network_interface="eth0",
+        )
+
+    def counters(value):
+        return dict(
+            network=dict(available=True, received_bytes=value, sent_bytes=value * 2),
+            upload_bytes=value * 3,
+            download_bytes=value * 4,
+            requests=value,
+            errors=0,
+        )
+
+    history = TelemetryHistory(tmp_path)
+    history.observe(sample(960), counters(100))
+    history.observe(sample(963), counters(200))
+    history.flush(force=True, now=964)
+    history.flush(force=True, now=964)
+    restarted = TelemetryHistory(tmp_path)
+    restarted.observe(sample(966), counters(5))
+    restarted.observe(sample(969), counters(10))
+    restarted.flush(force=True, now=970)
+    result = TelemetryHistory(tmp_path).query(960, 1020, now=1100)
+    assert result["samples"][0]["memory_bytes"] == 1024
+    assert result["samples"][0]["coverage_seconds"]["cpu_percent"] == 6
+    assert result["totals"]["network_received_bytes"] == 210
+    assert result["tracked_since"] == 960
+    assert backend.db.telemetry_minutes.count_documents({}) == 1
+    assert not (tmp_path / "telemetry.sqlite3").exists()
+    now = 970 + RETENTION_SECONDS + 120
+    restarted.observe(sample(now), counters(20))
+    restarted.flush(force=True, now=now)
+    assert backend.db.telemetry_minutes.count_documents({}) == 0
+    assert (
+        backend.db.telemetry_state.find_one({"_id": "lifetime"})["totals"][
+            "network_received_bytes"
+        ]
+        == 220
+    )
+
+
+def test_container_keys_and_owner_survive_move_without_local_volume(
+    backend, tmp_path, monkeypatch
+):
+    from argon2 import PasswordHasher
+
+    from tgdrive.core.config import Settings
+    from tgdrive.storage.mongo import bootstrap_values
+
+    fixture = {
+        "TGDRIVE_AUTO_SECRETS": "true",
+        "MONGODB_URI": mongo_uri(),
+        "MONGODB_DATABASE": backend.db.name,
+        "DATA_DIR": str(tmp_path / "first-server"),
+        "API_ID": "12345",
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30,
+        "STORAGE_CHANNEL": "-1001234567890",
+        "ADMIN_PASSWORD": "synthetic deployment owner password",
+    }
+    for key, value in fixture.items():
+        monkeypatch.setenv(key, value)
+    for key in ("SESSION_SECRET", "MONGODB_BACKUP_KEY", "ADMIN_PASSWORD_HASH"):
+        monkeypatch.delenv(key, raising=False)
+    first = Settings(_env_file=None)
+    catalog = MongoStore.create(backend)
+    catalog.bind_storage_channel(first.storage_channel)
+    drive_id = catalog.drive_id
+    backend.write(
+        backend.db.settings,
+        "replace_one",
+        {"_id": "bootstrap"},
+        {"_id": "bootstrap", "document": bootstrap_values(first)},
+        upsert=True,
+    )
+    browser_session = SessionManager(
+        first.session_key, 3600, mongo_backend=backend
+    ).create()
+    for key in ("API_ID", "API_HASH", "BOT_TOKENS", "STORAGE_CHANNEL"):
+        monkeypatch.delenv(key)
+    monkeypatch.setenv("ADMIN_PASSWORD", "")
+    monkeypatch.setenv("DATA_DIR", str(tmp_path / "second-server"))
+    reopened = Settings(_env_file=None)
+    assert reopened.session_secret == first.session_secret
+    assert reopened.mongodb_backup_key == first.mongodb_backup_key
+    assert PasswordHasher().verify(
+        reopened.admin_password_hash.get_secret_value(), fixture["ADMIN_PASSWORD"]
+    )
+    assert MongoStore(backend).drive_id == drive_id
+    assert SessionManager(reopened.session_key, 3600, mongo_backend=backend).verify(
+        browser_session
+    )
+    assert not (tmp_path / "second-server" / "deployment-secrets.json").exists()
+
+
+def test_catalog_roundtrip_without_local_sqlite(store, backend, monkeypatch):
+    import sqlite3
+
+    monkeypatch.setattr(
+        sqlite3, "connect", lambda *_a, **_k: pytest.fail("SQLite used")
+    )
+    store.bind_storage_channel(-1001234567890)
+    folder = store.create_folder("/", "Résumé")
+    item = store.add_file(
+        path(folder), "notes.txt", 42, 128, operation_id="operation123"
+    )
+    reopened = MongoStore(backend)
+    assert reopened.export() == store.export()
+    assert reopened.get_file(path(item))["message_id"] == 42
+    assert reopened.upload_destination("/", directory_id=folder["id"])["path"] == path(
+        folder
+    )
+
+
+def test_atomic_batch_rollback_and_savepoint(store, backend):
+    first = store.create_folder("/", "First")
+    before = store.export()
+    with pytest.raises(NotFoundError), store.metadata_batch():
+        store.rename(path(first), "Changed")
+        store.rename("/missing", "Fail")
+    assert store.export() == before
+    assert MongoStore(backend).export() == before
+    with store.metadata_batch():
+        store.rename(path(first), "Final")
+        with pytest.raises(DuplicateNameError):
+            store.create_folder("/", "FINAL")
+        second = store.create_folder("/", "Second")
+    assert (
+        MongoStore(backend).get_directory("/")["contents"][second["id"]]["name"]
+        == "Second"
+    )
+    with store.metadata_batch():
+        store.rename(path(first), "Temporary")
+        store.rename(path(second), "Final")
+        store.rename(path(first), "Second")
+    loaded = MongoStore(backend).get_directory("/")["contents"]
+    assert loaded[first["id"]]["name"] == "Second"
+    assert loaded[second["id"]]["name"] == "Final"
+
+
+def test_folder_manifest_retry_move_search_and_uniqueness(store):
+    result = store.prepare_folder_tree(
+        "/", "Root", [["Inner"]], "folder-request-id-12345"
+    )
+    assert (
+        store.prepare_folder_tree("/", "Root", [["Inner"]], "folder-request-id-12345")
+        == result
+    )
+    inner = result["folders"]["Inner"]
+    item = store.add_file(inner, "100%_notes.txt", 43, 7)
+    destination = store.create_folder("/", "Destination")
+    store.move(path(result["root"]), path(destination))
+    current = store.upload_destination(inner, directory_id=inner.rsplit("/", 1)[-1])
+    assert current["path"].startswith(path(destination))
+    matches = store.search_page("%_")
+    assert len(matches["items"]) == 1 and matches["items"][0]["id"] == item["id"]
+    assert matches["items"][0]["parent_names"] == ["Destination", "Root", "Inner"]
+    with pytest.raises(DuplicateNameError):
+        store.create_folder("/", "destination")
+
+
+def test_parts_idempotency_shares_and_catalog_deletion(store, backend):
+    parts = [
+        {
+            "index": 0,
+            "offset": 0,
+            "size": 3,
+            "message_id": 101,
+            "sha256": hashlib.sha256(b"abc").hexdigest(),
+        },
+        {
+            "index": 1,
+            "offset": 3,
+            "size": 3,
+            "message_id": 102,
+            "sha256": hashlib.sha256(b"def").hexdigest(),
+        },
+    ]
+    kwargs = dict(
+        operation_id="multipart-op",
+        parts=parts,
+        sha256=hashlib.sha256(b"abcdef").hexdigest(),
+    )
+    item = store.add_file("/", "large.bin", 101, 6, **kwargs)
+    assert store.add_file("/", "large.bin", 101, 6, **kwargs) == item
+    token = store.create_share(path(item))
+    assert store.authorize_file(path(item), token)
+    store.set_trashed(path(item), True)
+    assert not store.authorize_file(path(item), token)
+    intent = store.begin_deletion(path(item), channel_id=-100123)
+    assert intent["message_ids"] == [101, 102]
+    with pytest.raises(ValidationError):
+        store.confirm_deletion_messages(intent["id"], [103])
+    store.confirm_deletion_messages(intent["id"], [101])
+    reopened = MongoStore(backend)
+    assert reopened.pending_deletions()[0]["pending_message_ids"] == [102]
+    assert store.finish_deletion(intent["id"]) == [101, 102]
+    assert store.finish_deletion(intent["id"]) == []
+    assert store.pending_deletions() == []
+    completed = backend.db.deletions.find_one({"_id": intent["id"]})
+    assert completed["message_ids"] == completed["pending_message_ids"] == []
+    assert backend.db.nodes.find_one({"_id": item["id"]}) is None
+    assert store.has_file_operation("multipart-op")
+    with pytest.raises(ValidationError):
+        store.add_file("/", "large.bin", 101, 6, **kwargs)
+
+
+def test_ownership_excludes_second_process_and_fences_expired_writer(store, backend):
+    other = MongoBackend(mongo_uri(), backend.db.name)
+    try:
+        with pytest.raises(DatabaseUnavailable):
+            other.acquire()
+        backend.db.runtime.update_one(
+            {"_id": "owner"}, {"$set": {"token": "different-owner"}}
+        )
+        before = store.export()
+        with pytest.raises(DatabaseUnavailable):
+            store.create_folder("/", "Must not commit")
+        assert store.export() == before
+        assert backend.db.nodes.count_documents({"name": "Must not commit"}) == 0
+    finally:
+        other.client.close()
+
+
+async def test_jobs_sessions_names_and_connection_settings_use_mongodb(
+    backend, tmp_path
+):
+    from pydantic import SecretStr
+
+    from tgdrive.settings.managed_settings import (
+        ManagedClient,
+        ManagedDocument,
+        read_document,
+        save_document,
+    )
+
+    registry = TransferRegistry(mongo=backend.db.jobs)
+    job = await registry.create("queued", total=9)
+    job.context.update(kind="upload", name="file.txt", retry_at=123.0)
+    await registry.persist(job)
+    reopened = TransferRegistry(mongo=backend.db.jobs)
+    assert reopened.get(job.id).context == job.context
+    await reopened.update(job.id, status=TransferStatus.COMPLETED)
+    assert TransferRegistry(mongo=backend.db.jobs).get(job.id).terminal
+    sessions = SessionManager(b"x" * 32, 3600, mongo_backend=backend)
+    token = sessions.create()
+    assert sessions.verify(token)
+    assert SessionManager(b"x" * 32, 3600, mongo_backend=backend).verify(token)
+    sessions.revoke(token)
+    with pytest.raises(InvalidSession):
+        sessions.verify(token)
+    cache = IdentityCache(tmp_path)
+    cache.write("bot-123", {"display_name": "Example", "username": "example_bot"})
+    cache.defer("bot-123", 12345.0)
+    assert cache.read("bot-123")["display_name"] == "Example"
+    assert cache.retry_at("bot-123") == 12345.0
+    document = ManagedDocument(
+        revision=1,
+        api_id=12345,
+        api_hash=SecretStr("a" * 32),
+        clients=[
+            ManagedClient(
+                id="bot-test",
+                label="Bot",
+                kind="bot",
+                credential=SecretStr("123456:AA" + "x" * 24),
+            )
+        ],
+    )
+    save_document(tmp_path, document, 0)
+    assert read_document(tmp_path).revision == 1
+    assert not list(tmp_path.glob("*.sqlite3"))
+    assert not (tmp_path / "telegram-settings.json").exists()
+
+
+def test_encrypted_complete_snapshot_roundtrip_and_tamper_rejection(
+    store, backend, tmp_path
+):
+    from tgdrive.recovery.backup import BackupError
+
+    item = store.add_file("/", "safe.txt", 51, 10)
+    backend.db.settings.insert_one({"_id": "private", "token": "fixture-private-token"})
+    backup = tmp_path / "snapshot.tgdb"
+    key = secrets.token_bytes(32)
+    revision, counts, digest = write_snapshot(backend, backup, key)
+    assert revision == store.revision
+    assert counts["settings"] == 1
+    assert digest == hashlib.sha256(backup.read_bytes()).hexdigest()
+    assert b"fixture-private-token" not in backup.read_bytes()
+    decoded = decode_snapshot(backup, key)
+    assert decoded["settings"][0]["token"] == "fixture-private-token"
+    with pytest.raises(BackupError):
+        decode_snapshot(backup, secrets.token_bytes(32))
+    name = "tgdrive_test_" + secrets.token_hex(8)
+    target = MongoBackend(mongo_uri(), name)
+    try:
+        target.acquire()
+        restore_snapshot(target, backup, key)
+        restored = MongoStore(target)
+        assert restored.get_file(path(item))["message_id"] == 51
+        assert (
+            target.db.settings.find_one({"_id": "private"})["token"]
+            == "fixture-private-token"
+        )
+        with pytest.raises(FileExistsError):
+            restore_snapshot(target, backup, key)
+    finally:
+        assert name.startswith("tgdrive_test_")
+        target.release()
+        target.client.drop_database(name)
+        target.client.close()
+    content = bytearray(backup.read_bytes())
+    content[-20] ^= 1
+    backup.write_bytes(content)
+    with pytest.raises(BackupError):
+        decode_snapshot(backup, key)
+
+
+def test_receipts_survive_new_instance_without_sqlite(backend, store, tmp_path):
+    from tgdrive.transfers.uploads import ResumableUploads
+
+    settings = SimpleNamespace(
+        resolved_data_dir=tmp_path,
+        resolved_cache_dir=tmp_path / "cache",
+        max_concurrent_transfers=2,
+        upload_limit=1024**3,
+        staging_budget_bytes=1024**3,
+        min_free_bytes=0,
+        upload_session_ttl_seconds=3600,
+    )
+    manager = SimpleNamespace(
+        store=store, registry=TransferRegistry(mongo=backend.db.jobs)
+    )
+    # Explicit backend already bound to this private directory.
+    from unittest.mock import patch
+
+    with patch("tgdrive.storage.mongo.for_settings", return_value=backend):
+        receipt = ResumableUploads(settings, manager)
+        item = receipt.create("file.txt", "/", 12)
+        reopened = ResumableUploads(settings, manager)
+        assert reopened.get_unchecked(item["id"])["total_size"] == 12
+        receipt.close()
+        reopened.close()
+    assert not list(tmp_path.glob("*.sqlite3"))
+
+
+def test_readers_see_last_committed_snapshot_without_waiting_for_cloud(
+    store, backend, monkeypatch
+):
+    import threading
+    from concurrent.futures import ThreadPoolExecutor
+
+    entered = threading.Event()
+    proceed = threading.Event()
+    original = backend.transaction
+
+    def delayed(callback):
+        entered.set()
+        assert proceed.wait(5)
+        return original(callback)
+
+    monkeypatch.setattr(backend, "transaction", delayed)
+    with ThreadPoolExecutor(max_workers=1) as executor:
+        task = executor.submit(store.create_folder, "/", "Pending")
+        assert entered.wait(5)
+        try:
+            assert store.get_directory("/")["contents"] == {}
+        finally:
+            proceed.set()
+        node = task.result(timeout=10)
+    assert node["id"] in store.get_directory("/")["contents"]
+
+
+def test_lost_commit_acknowledgement_reloads_authoritative_catalog(
+    store, backend, monkeypatch
+):
+    original = backend.transaction
+    failed = False
+
+    def lost(callback):
+        nonlocal failed
+        result = original(callback)
+        if not failed:
+            failed = True
+            raise DatabaseUnavailable("Synthetic lost acknowledgement")
+        return result
+
+    monkeypatch.setattr(backend, "transaction", lost)
+    with pytest.raises(DatabaseUnavailable):
+        store.add_file("/", "safe.txt", 77, 2**32, operation_id="lost-ack-operation")
+    row = store.add_file("/", "safe.txt", 77, 2**32, operation_id="lost-ack-operation")
+    assert row["size"] == 2**32
+    assert backend.db.nodes.count_documents({"name": "safe.txt"}) == 1
+    assert MongoStore(backend).get_file(path(row))["size"] == 2**32
+
+
+def test_primary_database_commits_do_not_wait_for_telegram_backups(
+    store, backend, tmp_path
+):
+    import asyncio
+
+    from tgdrive.recovery.mongo_backup import MongoProtection
+
+    settings = SimpleNamespace(
+        storage_channel=-1001234567890,
+        mongodb_backup_key=None,
+        resolved_cache_dir=tmp_path,
+        mongodb_backup_seconds=3600,
+    )
+    service = MongoProtection(settings, object(), backend)
+    store.bind_storage_channel(settings.storage_channel)
+    item = store.add_file("/", "saved.txt", 81, 1)
+    assert asyncio.run(service.ensure_revision(store, store.revision)) == store.revision
+    assert backend.db.nodes.find_one({"_id": item["id"]}) is not None
+    assert service.protection_status(store)["state"] == "protected"
+    assert backend.db.backups.count_documents({}) == 0
+
+
+async def test_transfer_journal_cannot_write_after_owner_takeover(backend):
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = await registry.create("queued", total=10)
+    backend.db.runtime.update_one({"_id": "owner"}, {"$set": {"token": "new-owner"}})
+    with pytest.raises(DatabaseUnavailable):
+        await registry.update(record.id, status=TransferStatus.COMPLETED)
+    assert record.status is TransferStatus.QUEUED
+    assert backend.db.jobs.find_one({"_id": record.id})["data"]["status"] == "queued"
+
+
+@pytest.mark.asyncio
+async def test_transfer_history_archive_survives_pruning_and_reopen(backend):
+    import json
+    import time
+
+    registry = TransferRegistry(
+        mongo=backend.db.jobs, mongo_backend=backend, ttl_seconds=1
+    )
+    record = await registry.create("uploading", total=100)
+    record.context.update(
+        name="history.bin",
+        kind="upload",
+        destination="/",
+        source_url="https://private/?token=secret",
+        local_path="/private/staging",
+    )
+    await registry.update(record.id, status=TransferStatus.COMPLETED, current=100)
+    await registry.prune(now=time.time() + 2)
+    assert registry.list() == []
+    row = backend.db.jobs.find_one({"_id": record.id})
+    assert row["archived"] is True
+    assert "data" not in row
+    assert "context" not in row["summary"]
+    assert "secret" not in json.dumps(row)
+    reopened = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    assert reopened.list() == []
+    page = await reopened.history(status="completed", limit=1)
+    assert page["jobs"][0]["name"] == "history.bin"
+    assert (await reopened.history(query="HISTORY.BIN"))["jobs"][0]["id"] == record.id
+    assert (await reopened.history(query=".*"))["jobs"] == []
+    assert page["jobs"][0]["retained"] is False
+    registry.close()
+    reopened.close()
+
+
+@pytest.mark.asyncio
+async def test_archived_search_casefold_and_cursor_are_literal(backend):
+    import time
+
+    registry = TransferRegistry(
+        mongo=backend.db.jobs, mongo_backend=backend, ttl_seconds=1
+    )
+    names = [
+        "Straße [.*] 0.bin",
+        "STRASSE [.*] 1.bin",
+        "strasse [.*] 2.bin",
+        "ΟΣ.txt",
+        "unrelated.bin",
+    ]
+    for index, name in enumerate(names):
+        record = await registry.create("uploading", total=10)
+        record.context.update(name=name, kind="upload", destination="/")
+        record.created_at = 1000 + index
+        await registry.update(record.id, status=TransferStatus.COMPLETED, current=10)
+    await registry.prune(now=time.time() + 2)
+    first = await registry.history(query="STRASSE [.*]", limit=2)
+    assert [row["name"] for row in first["jobs"]] == names[1:3][::-1]
+    assert first["has_more"]
+    second = await registry.history(
+        query="strasse [.*]",
+        limit=2,
+        before=(first["next_before"], first["next_before_id"]),
+    )
+    assert [row["name"] for row in second["jobs"]] == [names[0]]
+    assert not second["has_more"]
+    assert (await registry.history(query="\u03bf\u03c3"))["jobs"][0]["name"] == "ΟΣ.txt"
+    assert (await registry.history(query=".*"))["jobs"][0]["name"] == names[2]
+    assert backend.db.jobs.count_documents({"search_name": {"$exists": False}}) == 0
+    registry.close()
+
+
+def test_transfer_locations_follow_exact_moved_and_deleted_item(store):
+    from tests.transfers.test_transfer_locations import check_locations
+
+    check_locations(store)
+
+
+def test_share_listing_copyability_expiry_and_move(store, backend, monkeypatch):
+    from pydantic import SecretStr
+
+    from tgdrive.web.share_links import token_factory
+
+    factory = token_factory(SimpleNamespace(session_secret=SecretStr("s" * 48)))
+    parent = store.create_folder("/", "Destination")
+    item = store.add_file("/", "report.txt", 42, 4)
+    original = path(item)
+    token = store.create_share(original, token_factory=factory)
+    record = store.list_shares(include_expired=True, token_factory=factory)[0]
+    assert record["copyable"] and factory(record["id"]) == token
+    assert token not in str(store.export())
+    store.move(original, path(parent))
+    store.rename(store.resolve_id(item["id"]), "renamed.txt")
+    reopened = MongoStore(backend)
+    record = reopened.list_shares(token_factory=factory)[0]
+    assert record["folder_label"] == "My Files / Destination"
+    assert record["name"] == "renamed.txt" and record["copyable"]
+    assert reopened.authorize_file(record["path"], token)
+    monkeypatch.setattr(
+        "tgdrive.storage.mongo_store._utc_now", lambda: "9999-01-01T00:00:00Z"
+    )
+    assert reopened.list_shares() == []
+    assert len(reopened.list_shares(include_expired=True)) == 1
+    assert not reopened.authorize_file(record["path"], token)
+    reopened.close()
+
+
+async def test_operator_performance_policy_survives_new_service_with_mongodb(
+    backend, tmp_path
+):
+    from unittest.mock import AsyncMock
+
+    from tgdrive.settings.performance_preferences import PerformanceSettings
+
+    def state():
+        return SimpleNamespace(
+            mongo=backend,
+            pool=SimpleNamespace(
+                _slots=[],
+                set_media_per_bot=AsyncMock(),
+                set_media_queue_limit=AsyncMock(),
+            ),
+        )
+
+    settings = SimpleNamespace(
+        resolved_data_dir=tmp_path / "policy-data",
+        max_file_size=0,
+        staging_budget_bytes=16 * 1024**3,
+    )
+    first, second = state(), state()
+    service = PerformanceSettings(settings, first)
+    try:
+        before = await service.snapshot()
+        saved = await service.save(
+            {"timezone": "UTC", "telegram_media_per_bot": 4},
+            expected=before["revision"],
+        )
+        restarted = PerformanceSettings(settings, second)
+        observed = await restarted.snapshot()
+        assert observed["revision"] == saved["revision"]
+        assert observed["timezone"] == "UTC"
+        assert observed["telegram_media_per_bot"] == 4
+        assert not (
+            settings.resolved_data_dir / "performance-preferences.json"
+        ).exists()
+    finally:
+        for runtime in (first, second):
+            manager = getattr(runtime, "preloads", None)
+            if manager is not None:
+                await manager.close()
+
+
+def test_multiple_independent_share_links_survive_mongo_reopen_and_snapshot(
+    store, backend
+):
+    from datetime import UTC, datetime, timedelta
+
+    from tgdrive.storage.store import DriveStore
+
+    folder = store.create_folder("/", "Reading")
+    target = path(folder)
+    first = store.create_share(target, label="Alex", expires_at=None)
+    second = store.create_share(target, label="Team")
+    rows = store.list_shares(target)
+    store.update_share(
+        rows[0]["id"],
+        label="Alex review",
+        expires_at=(datetime.now(UTC) + timedelta(days=30)).isoformat(),
+    )
+    reopened = MongoStore(backend)
+    assert reopened.authorize_directory(target, first) == target
+    assert reopened.authorize_directory(target, second) == target
+    assert reopened.list_shares(target)[0]["label"] == "Alex review"
+    portable = DriveStore._from_payload(reopened.export())
+    try:
+        assert portable.authorize_directory(target, first) == target
+        assert portable.authorize_directory(target, second) == target
+    finally:
+        portable.close()
+    reopened.revoke_share(rows[0]["id"])
+    assert not reopened.authorize_directory(target, first)
+    assert reopened.authorize_directory(target, second) == target
+
+
+def test_starred_mongo_paths_snapshot_and_restart(store, backend):
+    from tests.web.test_starred import check_starred
+
+    check_starred(store)
+    assert len(MongoStore(backend).list_starred()) == 1
diff --git a/tests/storage/test_mongodb_test_config.py b/tests/storage/test_mongodb_test_config.py
new file mode 100644
index 00000000..aa68b228
--- /dev/null
+++ b/tests/storage/test_mongodb_test_config.py
@@ -0,0 +1,19 @@
+"""Integration tests must never discover the deployment database implicitly."""
+
+import pytest
+
+from tests.storage.test_mongodb import mongo_uri
+
+
+def test_opt_in_mongo_requires_explicit_test_uri(monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv("TGDRIVE_TEST_MONGODB_URI", raising=False)
+    monkeypatch.setenv("MONGODB_URI", "mongodb://deployment.example/")
+    (tmp_path / ".env").write_text("MONGODB_URI=mongodb://deployment.example/\n")
+    with pytest.raises(pytest.UsageError, match="TGDRIVE_TEST_MONGODB_URI"):
+        mongo_uri()
+
+
+def test_explicit_test_uri_is_used(monkeypatch):
+    monkeypatch.setenv("TGDRIVE_TEST_MONGODB_URI", "mongodb://127.0.0.1:27017/")
+    assert mongo_uri() == "mongodb://127.0.0.1:27017/"
diff --git a/tests/storage/test_mongodb_unit.py b/tests/storage/test_mongodb_unit.py
new file mode 100644
index 00000000..6b051e99
--- /dev/null
+++ b/tests/storage/test_mongodb_unit.py
@@ -0,0 +1,288 @@
+"""Small MongoDB failure/scheduling checks without network access."""
+
+import asyncio
+import hashlib
+import threading
+from contextlib import nullcontext
+from datetime import UTC, datetime
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from pydantic import SecretStr
+from pymongo.errors import ConnectionFailure
+
+from tests.support.mongo_fixtures import FakeMongoBackend
+from tgdrive.core.logging import _redact
+from tgdrive.recovery.backup import BackupError
+from tgdrive.recovery.mongo_backup import (
+    MongoProtection,
+    decode_snapshot,
+    write_snapshot,
+)
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.transfers.tasks import TransferRegistry
+
+
+async def test_recent_snapshot_survives_restart_without_immediate_duplicate(
+    monkeypatch,
+):
+    latest = {"confirmed_at": datetime.now(UTC).isoformat()}
+    backend = SimpleNamespace(
+        db=SimpleNamespace(
+            backups=SimpleNamespace(
+                find_one=lambda query, **_kwargs: (
+                    latest if query["status"] == "confirmed" else None
+                )
+            )
+        )
+    )
+    service = MongoProtection(
+        SimpleNamespace(mongodb_backup_seconds=3600), object(), backend
+    )
+    service.snapshot_now = AsyncMock()
+    intervals = []
+
+    async def stop_wait(awaitable, timeout):
+        intervals.append(timeout)
+        awaitable.close()
+        return True
+
+    monkeypatch.setattr("tgdrive.recovery.mongo_backup.asyncio.wait_for", stop_wait)
+    await service._loop(object())
+    assert len(intervals) == 1 and 3590 < intervals[0] <= 3600
+    service.snapshot_now.assert_not_called()
+
+
+async def test_failed_cloud_journal_does_not_admit_an_unrecorded_job():
+    def fail(*_args, **_kwargs):
+        raise ConnectionFailure("Synthetic database outage")
+
+    registry = TransferRegistry(
+        mongo=SimpleNamespace(find=lambda _query: [], replace_one=fail)
+    )
+    with pytest.raises(DatabaseUnavailable):
+        await registry.create("queued")
+    assert registry.list() == []
+
+
+def test_mongodb_connection_credentials_are_redacted():
+    uri = "mongodb+srv://fixture_user:fixture_password@cluster.invalid/?appName=test"
+    result = _redact("Database failed: " + uri)
+    assert "fixture_user" not in result and "fixture_password" not in result
+    assert "[REDACTED_MONGODB_URI]" in result
+
+
+@pytest.mark.parametrize("forced", [False, True])
+async def test_encrypted_snapshot_checks_live_channel_before_staging_or_send(
+    tmp_path, monkeypatch, forced
+):
+    cache = tmp_path / "cache"
+    backend = SimpleNamespace(
+        check_owner=Mock(),
+        db=SimpleNamespace(backups=SimpleNamespace(find_one=Mock())),
+    )
+    pool = SimpleNamespace(lease=Mock())
+    service = MongoProtection(
+        SimpleNamespace(storage_channel=-1001234567890, resolved_cache_dir=cache),
+        pool,
+        backend,
+    )
+    store = SimpleNamespace(storage_channel_id=-1001234567890, revision=1)
+    service.verify_lineage = AsyncMock(
+        side_effect=SettingsProblem("The storage channel is public.")
+    )
+    write = Mock()
+    monkeypatch.setattr("tgdrive.recovery.mongo_backup.write_snapshot", write)
+    with pytest.raises(SettingsProblem, match="channel is public"):
+        if forced:
+            await service.backup(store, force=True)
+        else:
+            await service.snapshot_now(store)
+    service.verify_lineage.assert_awaited_once_with(store)
+    backend.db.backups.find_one.assert_not_called()
+    pool.lease.assert_not_called()
+    write.assert_not_called()
+    assert not cache.exists()
+
+
+@pytest.fixture
+def snapshot_source(tmp_path):
+    backend = FakeMongoBackend()
+    backend.client = SimpleNamespace(
+        start_session=Mock(side_effect=lambda **_kwargs: nullcontext(object()))
+    )
+    store = MongoStore.create(backend, storage_channel=-1001234567890)
+    settings = SimpleNamespace(
+        storage_channel=store.storage_channel_id,
+        resolved_cache_dir=tmp_path,
+        mongodb_backup_key=SecretStr("a1" * 32),
+    )
+    pool = SimpleNamespace(lease=Mock(side_effect=RuntimeError("Publication paused")))
+    yield MongoProtection(settings, pool, backend), store, backend
+    store.close()
+
+
+async def test_snapshot_record_uses_exported_revision_when_catalog_advances(
+    snapshot_source, monkeypatch
+):
+    service, store, backend = snapshot_source
+    exported_revision = store.revision
+
+    def export_then_advance(*args):
+        result = write_snapshot(*args)
+        store.create_folder("/", "Arrived after the snapshot")
+        return result
+
+    monkeypatch.setattr(
+        "tgdrive.recovery.mongo_backup.write_snapshot", export_then_advance
+    )
+    with pytest.raises(RuntimeError, match="Publication paused"):
+        await service.snapshot_now(store)
+    record = backend.db.backups.find_one({"status": "pending"})
+    decoded = decode_snapshot(
+        service.settings.resolved_cache_dir
+        / "mongo-backups"
+        / (record["id"] + ".tgdb"),
+        bytes.fromhex("a1" * 32),
+    )
+    assert record["revision"] == decoded["catalog"][0]["revision"] == exported_revision
+    assert store.revision == exported_revision + 1
+    assert len(decoded["nodes"]) == 1
+    assert len(backend.db.nodes.find({})) == 2
+
+
+@pytest.mark.parametrize(
+    "failure,expected,detail",
+    [
+        ("cursor", ConnectionFailure, "Interrupted snapshot"),
+        ("limit", BackupError, "1 GiB expanded limit"),
+        ("fsync", OSError, "Snapshot fsync failed"),
+    ],
+)
+def test_failed_snapshot_export_removes_only_its_file_and_allows_retry(
+    snapshot_source, tmp_path, monkeypatch, failure, expected, detail
+):
+    _, store, backend = snapshot_source
+    path = tmp_path / "snapshot.tgdb"
+    preserved = tmp_path / "existing.tgdb"
+    preserved.write_bytes(b"Preserve another pending archive")
+    key = bytes.fromhex("a1" * 32)
+    with monkeypatch.context() as patch:
+        if failure == "cursor":
+            find = backend.db.nodes.find
+
+            def interrupted(*args, **kwargs):
+                yield from find(*args, **kwargs)
+                raise ConnectionFailure("Interrupted snapshot")
+
+            patch.setattr(backend.db.nodes, "find", interrupted)
+        elif failure == "limit":
+            patch.setattr("tgdrive.recovery.mongo_backup.MAX_EXPANDED", 1)
+        else:
+
+            def failed_fsync(_descriptor):
+                raise OSError("Snapshot fsync failed")
+
+            patch.setattr("tgdrive.recovery.mongo_backup.os.fsync", failed_fsync)
+        with pytest.raises(expected, match=detail):
+            write_snapshot(backend, path, key)
+    assert not path.exists()
+    assert preserved.read_bytes() == b"Preserve another pending archive"
+    revision, counts, digest = write_snapshot(backend, path, key)
+    assert revision == store.revision
+    assert counts["catalog"] == 1
+    assert digest == hashlib.sha256(path.read_bytes()).hexdigest()
+    assert decode_snapshot(path, key)["catalog"][0]["revision"] == revision
+
+
+def test_snapshot_export_never_removes_an_existing_destination(
+    snapshot_source, tmp_path
+):
+    _, _, backend = snapshot_source
+    path = tmp_path / "existing.tgdb"
+    path.write_bytes(b"Preserve this archive")
+    with pytest.raises(FileExistsError):
+        write_snapshot(backend, path, bytes.fromhex("a1" * 32))
+    assert path.read_bytes() == b"Preserve this archive"
+
+
+@pytest.mark.parametrize("revision", [True, 0])
+def test_snapshot_export_rejects_invalid_catalog_revision(
+    snapshot_source, tmp_path, revision
+):
+    _, _, backend = snapshot_source
+    backend.db.catalog.update_one({"_id": "catalog"}, {"$set": {"revision": revision}})
+    path = tmp_path / "invalid.tgdb"
+    with pytest.raises(BackupError, match="catalog revision is invalid"):
+        write_snapshot(backend, path, bytes.fromhex("a1" * 32))
+    assert not path.exists()
+
+
+async def test_cancelled_snapshot_drains_export_before_removing_unadmitted_file(
+    snapshot_source, monkeypatch
+):
+    service, store, backend = snapshot_source
+    entered, release = threading.Event(), threading.Event()
+
+    def held_export(*args):
+        result = write_snapshot(*args)
+        entered.set()
+        assert release.wait(3), "The event loop could not release the export"
+        return result
+
+    monkeypatch.setattr("tgdrive.recovery.mongo_backup.write_snapshot", held_export)
+    task = asyncio.create_task(service.snapshot_now(store))
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        path = next((service.settings.resolved_cache_dir / "mongo-backups").iterdir())
+        task.cancel()
+        await asyncio.sleep(0)
+        task.cancel()
+        await asyncio.sleep(0)
+        assert not task.done()
+        assert service._lock.locked()
+        assert path.is_file()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert not path.exists()
+        assert backend.db.backups.find({}) == []
+        service.pool.lease.assert_not_called()
+    finally:
+        release.set()
+        task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+
+
+async def test_unknown_pending_snapshot_commit_preserves_ciphertext_for_retry(
+    snapshot_source, monkeypatch
+):
+    service, store, backend = snapshot_source
+    insert = backend.db.backups.insert_one
+
+    def committed_without_acknowledgement(*args, **kwargs):
+        insert(*args, **kwargs)
+        raise ConnectionFailure("Pending snapshot acknowledgement lost")
+
+    with monkeypatch.context() as patch:
+        patch.setattr(
+            backend.db.backups, "insert_one", committed_without_acknowledgement
+        )
+        with pytest.raises(ConnectionFailure, match="acknowledgement lost"):
+            await service.snapshot_now(store)
+    record = backend.db.backups.find_one({"status": "pending"})
+    path = (
+        service.settings.resolved_cache_dir / "mongo-backups" / (record["id"] + ".tgdb")
+    )
+    ciphertext = path.read_bytes()
+    assert hashlib.sha256(ciphertext).hexdigest() == record["sha256"]
+    export = Mock(side_effect=AssertionError("A pending snapshot must be reused"))
+    monkeypatch.setattr("tgdrive.recovery.mongo_backup.write_snapshot", export)
+    with pytest.raises(RuntimeError, match="Publication paused"):
+        await service.snapshot_now(store)
+    export.assert_not_called()
+    assert path.read_bytes() == ciphertext
+    assert backend.db.backups.find_one({"status": "pending"}) == record
diff --git a/tests/storage/test_store.py b/tests/storage/test_store.py
new file mode 100644
index 00000000..02775d8f
--- /dev/null
+++ b/tests/storage/test_store.py
@@ -0,0 +1,567 @@
+from __future__ import annotations
+
+import gc
+import hashlib
+import json
+import re
+import sqlite3
+import subprocess
+import sys
+import weakref
+from concurrent.futures import ThreadPoolExecutor
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+import tgdrive.storage.store as store_module
+from tgdrive.core.errors import (
+    CorruptStoreError,
+    DuplicateNameError,
+    InvalidNameError,
+    InvalidPathError,
+    InvalidRevisionError,
+    NotFoundError,
+    PersistenceError,
+    RootMutationError,
+    TrashedItemError,
+    UnsupportedSchemaError,
+    ValidationError,
+)
+from tgdrive.storage.store import SCHEMA_VERSION, DriveStore
+
+
+def _full_path(record: dict[str, object]) -> str:
+    parent = record["path"]
+    item_id = record["id"]
+    return f"/{item_id}" if parent == "/" else f"{parent}/{item_id}"
+
+
+def test_create_persist_load_and_frontend_shape(tmp_path) -> None:
+    database = tmp_path / "drive.sqlite3"
+    store = DriveStore.create(database)
+
+    assert store.revision == 1
+    assert store.dirty is True
+    folder = store.create_folder("/", "Résumé")
+    folder_path = _full_path(folder)
+    uploaded = store.add_file(folder_path, "notes+100%.txt", 41, 123)
+    file_path = _full_path(uploaded)
+
+    assert re.fullmatch(r"[A-Za-z0-9_-]{22}", str(folder["id"]))
+    assert set(folder) == {"id", "name", "path", "size", "type", "upload_date"}
+    assert folder["path"] == "/"
+    assert folder["size"] == 0
+    assert uploaded["path"] == folder_path
+    assert uploaded["name"] == "notes+100%.txt"
+    assert uploaded["message_id"] == 41
+
+    loaded = DriveStore.load(database)
+    assert loaded.export() == store.export()
+    assert loaded.get_file(file_path)["message_id"] == 41
+    directory = loaded.get_directory(folder_path)
+    assert directory["contents"][uploaded["id"]]["name"] == "notes+100%.txt"
+    assert database.read_bytes().startswith(b"SQLite format 3\x00")
+    assert store.export()["schema_version"] == SCHEMA_VERSION
+
+
+def test_corrupt_and_unsupported_metadata_fail_closed(tmp_path) -> None:
+    database = tmp_path / "drive.sqlite3"
+    database.write_bytes(b"{definitely not json")
+    with pytest.raises(CorruptStoreError):
+        DriveStore.load(database)
+
+    unsupported = DriveStore.create()
+    payload = unsupported.export()
+    unsupported.close()
+    payload["schema_version"] = SCHEMA_VERSION + 1
+    with pytest.raises(UnsupportedSchemaError):
+        DriveStore._from_payload(payload)
+
+    valid = DriveStore.create().export()
+    valid["root"]["children"] = {
+        "first": {
+            "children": {},
+            "id": "first",
+            "name": "Same",
+            "share_hashes": [],
+            "trashed": False,
+            "type": "folder",
+            "upload_date": valid["root"]["upload_date"],
+        },
+        "second": {
+            "children": {},
+            "id": "second",
+            "name": "same",
+            "share_hashes": [],
+            "trashed": False,
+            "type": "folder",
+            "upload_date": valid["root"]["upload_date"],
+        },
+    }
+    with pytest.raises(CorruptStoreError, match="duplicate"):
+        DriveStore._from_payload(valid)
+
+
+@pytest.mark.parametrize(
+    "bad_path",
+    ["relative", "/../escape", "/./child", "/child//file", "/child\\file"],
+)
+def test_paths_reject_traversal_and_ambiguous_forms(bad_path) -> None:
+    store = DriveStore.create()
+    with pytest.raises(InvalidPathError):
+        store.get_directory(bad_path)
+
+
+def test_root_mutations_are_rejected_and_trailing_slash_is_normalized() -> None:
+    store = DriveStore.create()
+    folder = store.create_folder("/", "Folder")
+    folder_path = _full_path(folder)
+
+    assert store.get_directory(f"{folder_path}/")["id"] == folder["id"]
+    with pytest.raises(RootMutationError):
+        store.rename("/", "new root")
+    with pytest.raises(RootMutationError):
+        store.set_trashed("/", True)
+    with pytest.raises(RootMutationError):
+        store.delete("/")
+
+
+def test_unicode_names_and_casefolded_sibling_duplicates() -> None:
+    store = DriveStore.create()
+    store.create_folder("/", "Résumé")
+
+    with pytest.raises(DuplicateNameError):
+        store.add_file("/", "RÉSUMÉ", 1, 0)
+    with pytest.raises(InvalidNameError):
+        store.create_folder("/", " leading")
+    with pytest.raises(InvalidNameError):
+        store.create_folder("/", "bad/name")
+    with pytest.raises(InvalidNameError):
+        store.create_folder("/", "bad\nname")
+
+
+def test_sqlite_failure_rolls_back_rows_and_revision(tmp_path) -> None:
+    database = tmp_path / "drive.sqlite3"
+    store = DriveStore.create(database)
+    folder = store.create_folder("/", "Before")
+    folder_path = _full_path(folder)
+    previous_revision = store.revision
+    connection = sqlite3.connect(database)
+    connection.execute("""CREATE TRIGGER fail_update BEFORE UPDATE ON nodes
+        BEGIN SELECT RAISE(ABORT,'simulated storage failure'); END""")
+    connection.commit()
+    connection.close()
+    with pytest.raises(PersistenceError, match="simulated storage failure"):
+        store.rename(folder_path, "After")
+    assert store.revision == previous_revision
+    assert DriveStore.load(database).get_directory(folder_path)["name"] == "Before"
+
+
+def test_backup_revision_race_cannot_clear_newer_mutation() -> None:
+    store = DriveStore.create()
+    snapshot_revision, snapshot = store.snapshot()
+    assert json.loads(snapshot)["revision"] == snapshot_revision
+
+    store.create_folder("/", "arrived during upload")
+    newest_revision = store.revision
+    assert newest_revision > snapshot_revision
+    assert store.mark_backed_up(snapshot_revision) is True
+    assert store.dirty is True
+    assert store.mark_backed_up(newest_revision) is False
+    assert store.dirty is False
+
+    with pytest.raises(InvalidRevisionError):
+        store.mark_backed_up(newest_revision + 1)
+
+
+def test_trash_listing_and_search_hide_entire_trashed_subtrees() -> None:
+    store = DriveStore.create()
+    folder = store.create_folder("/", "Archive")
+    folder_path = _full_path(folder)
+    secret = store.add_file(folder_path, "Secret Plan.txt", 50, 5)
+    secret_path = _full_path(secret)
+    visible = store.add_file("/", "Secret Public.txt", 51, 6)
+
+    store.set_trashed(folder_path, True)
+    assert set(store.search("secret")) == {visible["id"]}
+    assert set(store.search("secret", include_trashed=True)) == {
+        secret["id"],
+        visible["id"],
+    }
+    assert set(store.list_trash()) == {folder["id"]}
+    assert folder["id"] not in store.list_directory("/")
+    with pytest.raises(TrashedItemError):
+        store.get_file(secret_path)
+
+    store.set_trashed(folder_path, False)
+    store.set_trashed(secret_path, True)
+    assert set(store.list_trash()) == {secret["id"]}
+    assert store.get_file(secret_path, include_trashed=True)["id"] == secret["id"]
+
+
+def test_recursive_delete_returns_all_telegram_message_ids() -> None:
+    store = DriveStore.create()
+    outer = store.create_folder("/", "Outer")
+    outer_path = _full_path(outer)
+    first = store.add_file(outer_path, "one.bin", 101, 1)
+    inner = store.create_folder(outer_path, "Inner")
+    inner_path = _full_path(inner)
+    second = store.add_file(inner_path, "two.bin", 102, 2)
+
+    with pytest.raises(ValidationError, match="permanent deletion intent"):
+        store.delete(outer_path)
+    store.set_trashed(outer_path, True)
+    intent = store.begin_deletion(outer_path, channel_id=-100123)
+    assert set(intent["message_ids"]) == {101, 102}
+    assert set(store.finish_deletion(intent["id"])) == {101, 102}
+    assert store.export()["deletions"][0]["message_ids"] == []
+    assert store.list_directory("/") == {}
+    assert first["id"] != second["id"]
+
+
+def test_message_ids_reads_file_and_nested_folder_without_mutation() -> None:
+    store = DriveStore.create()
+    outer = store.create_folder("/", "Outer")
+    outer_path = _full_path(outer)
+    first = store.add_file(outer_path, "one.bin", 301, 1)
+    inner = store.create_folder(outer_path, "Inner")
+    inner_path = _full_path(inner)
+    store.add_file(inner_path, "two.bin", 302, 2)
+    revision = store.revision
+    dirty = store.dirty
+
+    assert store.message_ids(_full_path(first)) == [301]
+    assert set(store.message_ids(outer_path)) == {301, 302}
+    assert store.revision == revision
+    assert store.dirty is dirty
+
+
+def test_message_ids_rejects_invalid_and_hidden_targets() -> None:
+    store = DriveStore.create()
+    folder = store.create_folder("/", "Trash me")
+    folder_path = _full_path(folder)
+    store.add_file(folder_path, "inside.bin", 401, 1)
+    store.set_trashed(folder_path, True)
+
+    with pytest.raises(TrashedItemError):
+        store.message_ids(folder_path)
+    assert store.message_ids(folder_path, include_trashed=True) == [401]
+    with pytest.raises(NotFoundError):
+        store.message_ids("/missing")
+    with pytest.raises(InvalidPathError):
+        store.message_ids("/../escape")
+
+
+def test_share_tokens_are_hashed_and_strictly_scoped() -> None:
+    store = DriveStore.create()
+    shared = store.create_folder("/", "Shared")
+    shared_path = _full_path(shared)
+    nested = store.create_folder(shared_path, "Nested")
+    nested_path = _full_path(nested)
+    shared_file = store.add_file(nested_path, "inside.bin", 201, 1)
+    shared_file_path = _full_path(shared_file)
+    sibling = store.add_file("/", "outside.bin", 202, 1)
+    sibling_path = _full_path(sibling)
+
+    folder_token = store.create_share(shared_path)
+    file_token = store.create_share(sibling_path)
+
+    assert store.authorize_directory(shared_path, folder_token) == shared_path
+    assert store.authorize_directory(nested_path, folder_token) == shared_path
+    assert store.authorize_file(shared_file_path, folder_token) is True
+    assert store.authorize_file(sibling_path, folder_token) is False
+    assert store.authorize_file(sibling_path, file_token) is True
+    assert store.authorize_directory(shared_path, file_token) is None
+    assert store.authorize_file(shared_file_path, "wrong") is False
+
+    exported = json.dumps(store.export(), sort_keys=True)
+    assert folder_token not in exported
+    assert file_token not in exported
+    assert hashlib.sha256(folder_token.encode()).hexdigest() in exported
+    assert hashlib.sha256(file_token.encode()).hexdigest() in exported
+
+    store.set_trashed(shared_path, True)
+    assert store.authorize_file(shared_file_path, folder_token) is False
+
+
+def test_share_token_history_is_bounded() -> None:
+    store = DriveStore.create()
+    folder = store.create_folder("/", "Shared")
+    folder_path = _full_path(folder)
+    tokens = [
+        store.create_share(folder_path)
+        for _ in range(store_module.MAX_SHARE_TOKENS_PER_ITEM)
+    ]
+    with pytest.raises(store_module.ValidationError, match="100 links"):
+        store.create_share(folder_path)
+    assert store.authorize_directory(folder_path, tokens[0]) == folder_path
+    assert store.authorize_directory(folder_path, tokens[-1]) == folder_path
+
+    exported = store.export()
+    child = next(iter(exported["root"]["children"].values()))
+    assert len(child["share_hashes"]) == store_module.MAX_SHARE_TOKENS_PER_ITEM
+
+
+def test_committed_metadata_survives_process_exit_without_close(tmp_path) -> None:
+    database = tmp_path / "crash.sqlite3"
+    subprocess.run(  # noqa: S603 - fixed interpreter and trusted test script
+        [
+            sys.executable,
+            "-c",
+            "import os,sys; from tgdrive.storage.store import DriveStore; "
+            "s=DriveStore.create(sys.argv[1]); "
+            "s.add_file('/', 'survives.bin', 123, 4, operation_id='crash-operation'); "
+            "os._exit(0)",
+            str(database),
+        ],
+        check=True,
+    )
+    recovered = DriveStore.load(database)
+    row = next(iter(recovered.list_directory("/").values()))
+    assert recovered.get_file(_full_path(row))["message_id"] == 123
+    again = recovered.add_file(
+        "/", "survives.bin", 123, 4, operation_id="crash-operation"
+    )
+    assert again["id"] == row["id"]
+    assert len(recovered.list_directory("/")) == 1
+
+
+def test_independent_connections_serialize_writers_without_lost_updates(
+    tmp_path,
+) -> None:
+    database = tmp_path / "concurrent.sqlite3"
+    first = DriveStore.create(database)
+    second = DriveStore.load(database)
+    with ThreadPoolExecutor(max_workers=2) as workers:
+        left = workers.submit(
+            lambda: [first.create_folder("/", f"left-{n}") for n in range(20)]
+        )
+        right = workers.submit(
+            lambda: [second.create_folder("/", f"right-{n}") for n in range(20)]
+        )
+        left.result()
+        right.result()
+    assert first.revision == second.revision == 41
+    assert len(DriveStore.load(database).list_directory("/")) == 40
+
+
+def test_deletion_intent_survives_restart_with_partial_confirmations(tmp_path) -> None:
+    database = tmp_path / "deletion.sqlite3"
+    store = DriveStore.create(database)
+    folder = store.create_folder("/", "Removal")
+    path = _full_path(folder)
+    store.add_file(path, "one.bin", 101, 1)
+    store.add_file(path, "two.bin", 102, 2)
+    store.set_trashed(path, True)
+    intent = store.begin_deletion(path, channel_id=-100123)
+    store.confirm_deletion_messages(intent["id"], [101])
+    store.fail_deletion(intent["id"], "transport lost")
+    store.close()
+    recovered = DriveStore.load(database)
+    resumed = recovered.pending_deletions()[0]
+    assert resumed["channel_id"] == -100123
+    assert resumed["message_ids"] == [101, 102]
+    assert resumed["pending_message_ids"] == [102]
+    assert recovered.message_ids(path, include_trashed=True) == [101, 102]
+    assert recovered.begin_deletion(path)["id"] == intent["id"]
+    with pytest.raises(ValidationError, match="pending permanent deletion"):
+        recovered.set_trashed(path, False)
+    with pytest.raises(ValidationError, match="outside"):
+        recovered.confirm_deletion_messages(intent["id"], [999])
+    assert recovered.finish_deletion(intent["id"]) == [101, 102]
+    assert recovered.finish_deletion(intent["id"]) == []
+    assert recovered.pending_deletions() == []
+    assert recovered.export()["deletions"][0]["message_ids"] == []
+    assert recovered.export()["deletions"][0]["pending_message_ids"] == []
+
+
+def test_deletion_backups_preserve_refs_and_reject_forged_confirmation() -> None:
+    store = DriveStore.create()
+    file = store.add_file("/", "delete.bin", 99, 1)
+    path = _full_path(file)
+    store.set_trashed(path, True)
+    intent = store.begin_deletion(path)
+    payload = store.export()
+    restored = DriveStore._from_payload(payload)
+    assert restored.pending_deletions() == store.pending_deletions()
+    payload["deletions"][0]["message_ids"] = [1000]
+    payload["deletions"][0]["pending_message_ids"] = [1000]
+    with pytest.raises(CorruptStoreError, match="retained subtree"):
+        DriveStore._from_payload(payload)
+    assert intent["pending_message_ids"] == [99]
+
+
+def test_move_updates_ancestry_without_changing_ids_and_rejects_cycles() -> None:
+    store = DriveStore.create()
+    source = store.create_folder("/", "Source")
+    target = store.create_folder("/", "Target")
+    nested = store.create_folder(_full_path(source), "Nested")
+    file = store.add_file(_full_path(nested), "document.txt", 10, 7)
+    token = store.create_share(_full_path(nested))
+    moved = store.move(_full_path(nested), _full_path(target))
+    assert moved["id"] == nested["id"]
+    new_path = store.resolve_id(file["id"])
+    assert new_path == _full_path(moved) + "/" + file["id"]
+    assert store.authorize_file(new_path, token)
+    assert store.list_shares()[0]["path"] == _full_path(moved)
+    with pytest.raises(InvalidPathError, match="own subtree"):
+        store.move(_full_path(target), _full_path(moved))
+    with pytest.raises(NotFoundError):
+        store.get_directory(_full_path(nested))
+
+
+def test_move_conflicts_skip_or_keep_both_preserving_extension() -> None:
+    store = DriveStore.create()
+    target = store.create_folder("/", "Destination")
+    file = store.add_file("/", "résumé.txt", 1, 1)
+    store.add_file(_full_path(target), "RÉSUMÉ.txt", 2, 1)
+    revision = store.revision
+    assert store.move(_full_path(file), _full_path(target), conflict="skip") is None
+    assert store.revision == revision
+    moved = store.move(_full_path(file), _full_path(target))
+    assert moved["name"] == "résumé (1).txt"
+    assert moved["id"] == file["id"]
+
+
+def test_share_expiry_rotation_revocation_and_trash_are_durable(
+    tmp_path, monkeypatch
+) -> None:
+    import tgdrive.storage.store as module
+
+    store = DriveStore.create(tmp_path / "shares.sqlite3")
+    folder = store.create_folder("/", "Shared")
+    file = store.add_file(_full_path(folder), "secret.bin", 5, 6)
+    folder_path, file_path = _full_path(folder), _full_path(file)
+    token = store.create_share(folder_path)
+    expiry = store.list_shares()[0]["expires_at"]
+    assert datetime.fromisoformat(expiry.replace("Z", "+00:00")) > datetime.now(
+        UTC
+    ) + timedelta(days=6)
+    monkeypatch.setattr(module, "_utc_now", lambda: "9999-01-01T00:00:00Z")
+    assert not store.authorize_file(file_path, token)
+    monkeypatch.undo()
+    token = store.create_share(file_path, expires_at=None)
+    assert store.list_shares(file_path)[0]["expires_at"] is None
+    restored = DriveStore.load(store.storage_path)
+    assert restored.authorize_file(file_path, token)
+    share_id = restored.list_shares(file_path)[0]["id"]
+    assert restored.revoke_share(share_id)
+    assert not store.authorize_file(file_path, token)
+    token = store.create_share(file_path)
+    store.set_trashed(folder_path, True)
+    store.set_trashed(folder_path, False)
+    assert not store.authorize_file(file_path, token)
+    assert store.list_shares() == []
+
+
+def test_operation_id_is_idempotent_across_restart_and_permanent_deletion(
+    tmp_path,
+) -> None:
+    database = tmp_path / "idempotent.sqlite3"
+    store = DriveStore.create(database)
+    file = store.add_file("/", "one.bin", 21, 1, operation_id="one-operation")
+    assert store.add_file("/", "one.bin", 21, 1, operation_id="one-operation") == file
+    revision = store.revision
+    with pytest.raises(ValidationError, match="different media"):
+        store.add_file("/", "other.bin", 22, 1, operation_id="one-operation")
+    assert store.revision == revision
+    path = _full_path(file)
+    store.set_trashed(path, True)
+    intent = store.begin_deletion(path)
+    store.confirm_deletion_messages(intent["id"], [21])
+    store.finish_deletion(intent["id"])
+    recovered = DriveStore.load(database)
+    with pytest.raises(ValidationError, match="file was deleted"):
+        recovered.add_file("/", "one.bin", 21, 1, operation_id="one-operation")
+    assert recovered.list_directory("/") == {}
+
+
+def test_upload_collision_and_trash_restore_keep_both_without_losing_ids() -> None:
+    store = DriveStore.create()
+    first = store.add_file("/", "report.txt", 1, 1)
+    second = store.add_file(
+        "/", "REPORT.txt", 2, 2, keep_both=True, operation_id="duplicate-upload"
+    )
+    assert second["name"] == "REPORT (1).txt"
+    assert (
+        store.add_file(
+            "/", "REPORT.txt", 2, 2, keep_both=True, operation_id="duplicate-upload"
+        )
+        == second
+    )
+    store.set_trashed(_full_path(first), True)
+    replacement = store.add_file("/", "report.txt", 3, 3)
+    restored = store.set_trashed(_full_path(first), False)
+    assert restored["id"] == first["id"]
+    assert restored["name"] == "report (2).txt"
+    assert store.get_file(_full_path(replacement))["message_id"] == 3
+    assert len(store.list_directory("/")) == 3
+    assert DriveStore._from_payload(store.export()).export() == store.export()
+
+
+def test_interrupted_snapshot_import_never_publishes_an_empty_database(
+    tmp_path,
+) -> None:
+    source = tmp_path / "checkpoint.json"
+    original = DriveStore.create()
+    original.create_folder("/", "Must survive")
+    source.write_bytes(original.snapshot()[1])
+    destination = tmp_path / "restore.sqlite3"
+    completed = subprocess.run(  # noqa: S603 - trusted fixed test code
+        [
+            sys.executable,
+            "-c",
+            "import json,os,sys; from tgdrive.storage.store import DriveStore; "
+            "DriveStore._import_shares=lambda *args: os._exit(9); "
+            "DriveStore._from_payload(json.load(open(sys.argv[1])),storage_path=sys.argv[2],persist=True)",
+            str(source),
+            str(destination),
+        ],
+        check=False,
+    )
+    assert completed.returncode == 9
+    assert not destination.exists()
+    assert len(list(tmp_path.glob(".restore-*.sqlite3"))) == 1
+
+
+def test_database_load_rejects_inconsistent_indexes_and_overlapping_deletions(
+    tmp_path,
+) -> None:
+    database = tmp_path / "index.sqlite3"
+    store = DriveStore.create(database)
+    folder = store.create_folder("/", "Folder")
+    connection = sqlite3.connect(database)
+    connection.execute("UPDATE nodes SET name_key='wrong' WHERE id=?", (folder["id"],))
+    connection.commit()
+    connection.close()
+    with pytest.raises(CorruptStoreError, match="name index"):
+        DriveStore.load(database)
+
+
+def test_store_finalizer_closes_abandoned_connection_without_changing_committed_data(
+    tmp_path,
+):
+    database = tmp_path / "finalized.sqlite3"
+    store = DriveStore.create(database)
+    item = store.add_file("/", "committed.bin", 71, 3)
+    connection = store._db
+    reference = weakref.ref(store)
+    del store
+    gc.collect()
+    assert reference() is None
+    with pytest.raises(sqlite3.ProgrammingError, match="closed"):
+        connection.execute("SELECT 1")
+    restored = DriveStore.load(database)
+    assert restored.get_file(_full_path(item))["message_id"] == 71
+    restored.close()
+    restored.close()
+
+
+@pytest.mark.parametrize("field", ["drive_id", "shares"])
+def test_portable_catalog_requires_current_identity_and_share_records(field):
+    source = DriveStore.create()
+    payload = source.export()
+    source.close()
+    del payload[field]
+    with pytest.raises(CorruptStoreError, match="missing or unknown fields"):
+        DriveStore._from_payload(payload)
diff --git a/tests/support/__init__.py b/tests/support/__init__.py
new file mode 100644
index 00000000..20d44b97
--- /dev/null
+++ b/tests/support/__init__.py
@@ -0,0 +1 @@
+"""Shared fixtures and synthetic resources for the TGDrive test suite."""
diff --git a/tests/support/app_fixtures.py b/tests/support/app_fixtures.py
new file mode 100644
index 00000000..520162b9
--- /dev/null
+++ b/tests/support/app_fixtures.py
@@ -0,0 +1,133 @@
+"""Shared synthetic application resources and authenticated HTTP fixtures."""
+
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.mongo_fixtures import FakeMongoBackend, register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.storage.store import DriveStore
+from tgdrive.transfers.tasks import TransferRegistry
+from tgdrive.web.app import create_app
+
+
+def make_settings(tmp_path: Path) -> Settings:
+    return Settings(
+        _env_file=None,
+        MONGODB_URI="mongodb://synthetic.invalid",
+        API_ID=12345,
+        API_HASH="a" * 32,
+        BOT_TOKENS="123456:" + "x" * 30,
+        STORAGE_CHANNEL=-1001234567890,
+        ADMIN_PASSWORD="correct horse battery staple",
+        SESSION_SECRET="s" * 48,
+        DATA_DIR=tmp_path / "data",
+        CACHE_DIR=tmp_path / "cache",
+        COOKIE_SECURE=True,
+    )
+
+
+class FakeTransfers:
+    def __init__(self) -> None:
+        self.registry = TransferRegistry()
+        self.deleted_messages: list[int] = []
+        self.remote_requests: list[tuple[str, str, str | None]] = []
+        self.remote_modes: list[bool] = []
+
+    async def start_deletion(self, path: str):
+        intent = self.store.begin_deletion(path, channel_id=-1001234567890)
+        record = await self.registry.create(
+            "deleting", total=len(intent["message_ids"])
+        )
+
+        async def complete(item):
+            self.store.finish_deletion(intent["id"])
+
+        self.registry.spawn(record.id, complete)
+        return record
+
+    async def delete_telegram_messages(self, message_ids: list[int]) -> None:
+        self.deleted_messages.extend(message_ids)
+
+    async def receive_browser_upload(
+        self,
+        upload: Any,
+        destination: str,
+        **_kwargs: Any,
+    ):
+        assert destination == "/"
+        record = await self.registry.create("uploading", total=3)
+        on_created = _kwargs.get("on_created")
+        if on_created:
+            created = on_created(record)
+            if inspect.isawaitable(created):
+                await created
+        await upload.close()
+        return record
+
+    async def inspect_remote(self, url: str):
+        return SimpleNamespace(
+            filename="remote.bin",
+            size=12,
+            content_type="application/octet-stream",
+            url=url,
+        )
+
+    async def start_remote(
+        self,
+        *,
+        url: str,
+        destination: str,
+        filename: str | None,
+        single_threaded: bool = False,
+    ):
+        self.remote_requests.append((url, destination, filename))
+        self.remote_modes.append(single_threaded)
+        return await self.registry.create("checking_source")
+
+
+class FakeRuntime:
+    def __init__(self, store: DriveStore) -> None:
+        self.store = store
+        self.mongo = FakeMongoBackend()
+        self.transfers = FakeTransfers()
+        self.transfers.store = store
+        self.pool = object()
+        self.ready = False
+        self.stopped = False
+
+    async def start(self) -> None:
+        self.ready = True
+
+    async def stop(self) -> None:
+        uploads = getattr(self.transfers, "uploads", None)
+        if uploads is not None:
+            uploads.close()
+        self.ready = False
+        self.stopped = True
+
+
+@pytest.fixture
+def app_client(tmp_path: Path, monkeypatch):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    runtime = FakeRuntime(store)
+    register_test_backend(monkeypatch, settings, runtime.mongo)
+    app = create_app(settings, runtime=runtime)
+    with TestClient(app, base_url="https://testserver") as client:
+        yield client, store, runtime, settings
+    assert runtime.stopped
+
+
+def login(client: TestClient) -> None:
+    response = client.post(
+        "/api/checkPassword", json={"pass": "correct horse battery staple"}
+    )
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
diff --git a/tests/support/book_samples.py b/tests/support/book_samples.py
new file mode 100644
index 00000000..71f4b287
--- /dev/null
+++ b/tests/support/book_samples.py
@@ -0,0 +1,329 @@
+"""Self-generated book fixtures; no third-party pages or copyrighted media."""
+
+import hashlib
+import io
+import struct
+import zlib
+from zipfile import ZIP_STORED, ZipFile
+
+PDF_SAMPLE_PASSWORD = "fixture-pdf-unlock"
+
+
+def _pdf_objects(objects, *, trailer=b""):
+    """Serialize small authored PDF fixtures with exact byte offsets."""
+    output = bytearray(b"%PDF-1.4\n")
+    offsets = [0]
+    for number, body in enumerate(objects, 1):
+        offsets.append(len(output))
+        output += f"{number} 0 obj\n".encode() + body + b"\nendobj\n"
+    start = len(output)
+    count = len(objects) + 1
+    output += f"xref\n0 {count}\n0000000000 65535 f \n".encode()
+    output += b"".join(f"{offset:010d} 00000 n \n".encode() for offset in offsets[1:])
+    output += (
+        f"trailer\n<< /Size {count} /Root 1 0 R ".encode()
+        + trailer
+        + f">>\nstartxref\n{start}\n%%EOF".encode()
+    )
+    return bytes(output)
+
+
+def _pdf_stream(content):
+    return f"<< /Length {len(content)} >>\nstream\n".encode() + content + b"\nendstream"
+
+
+def encrypted_pdf(password=PDF_SAMPLE_PASSWORD):
+    """Deterministic PDF Standard Security R2 fixture, never application crypto."""
+    padding = bytes.fromhex(
+        "28bf4e5e4e758a4164004e56fffa01082e2e00b6d0683e802f0ca9fe6453697a"
+    )
+
+    def padded(value):
+        return (value.encode("latin-1") + padding)[:32]
+
+    def md5(value):
+        # MD5 and RC4 are required by this deliberately old PDF test format.
+        return hashlib.md5(value, usedforsecurity=False).digest()
+
+    def rc4(key, value):
+        state = list(range(256))
+        position = 0
+        for index in range(256):
+            position = (position + state[index] + key[index % len(key)]) % 256
+            state[index], state[position] = state[position], state[index]
+        first = second = 0
+        output = bytearray()
+        for byte in value:
+            first = (first + 1) % 256
+            second = (second + state[first]) % 256
+            state[first], state[second] = state[second], state[first]
+            output.append(byte ^ state[(state[first] + state[second]) % 256])
+        return bytes(output)
+
+    identity = hashlib.sha256(b"TGDrive encrypted PDF fixture").digest()[:16]
+    owner = rc4(md5(padded("fixture-owner-password"))[:5], padded(password))
+    permissions = -4
+    key = md5(padded(password) + owner + struct.pack("<i", permissions) + identity)[:5]
+    user = rc4(key, padding)
+    content = b"BT /F1 22 Tf 24 540 Td (Encrypted PDF fixture opened) Tj ET"
+    stream_key = md5(key + (5).to_bytes(3, "little") + b"\x00\x00")[:10]
+    return _pdf_objects(
+        [
+            b"<< /Type /Catalog /Pages 2 0 R >>",
+            b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+            b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 420 594] "
+            b"/Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>",
+            b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+            _pdf_stream(rc4(stream_key, content)),
+            b"<< /Filter /Standard /V 1 /R 2 /Length 40 /P -4 /O <"
+            + owner.hex().encode()
+            + b"> /U <"
+            + user.hex().encode()
+            + b"> >>",
+        ],
+        trailer=b"/Encrypt 6 0 R /ID [<"
+        + identity.hex().encode()
+        + b"><"
+        + identity.hex().encode()
+        + b">] ",
+    )
+
+
+def resource_pdf(font_data):
+    """Exercise local fonts, a packed CMap, and CMYK ICC/WASM conversion."""
+    # The named Shift-JIS CMap maps ASCII A to CID 264. Embed the shipped font
+    # and its actual glyph index so a system substitution cannot mask a broken
+    # resource request with a different visible character.
+    cmap_offset = None
+    for index in range(struct.unpack_from(">H", font_data, 4)[0]):
+        offset = 12 + index * 16
+        if font_data[offset : offset + 4] == b"cmap":
+            cmap_offset = struct.unpack_from(">I", font_data, offset + 8)[0]
+            break
+    if cmap_offset is None:
+        raise ValueError("The fixture font has no Unicode character map")
+    glyph = None
+    for index in range(struct.unpack_from(">H", font_data, cmap_offset + 2)[0]):
+        relative = struct.unpack_from(">I", font_data, cmap_offset + 8 + index * 8)[0]
+        table = cmap_offset + relative
+        if struct.unpack_from(">H", font_data, table)[0] != 4:
+            continue
+        segments = struct.unpack_from(">H", font_data, table + 6)[0] // 2
+        ends = table + 14
+        starts = ends + segments * 2 + 2
+        deltas = starts + segments * 2
+        ranges = deltas + segments * 2
+        for segment in range(segments):
+            start = struct.unpack_from(">H", font_data, starts + segment * 2)[0]
+            end = struct.unpack_from(">H", font_data, ends + segment * 2)[0]
+            if not start <= 65 <= end:
+                continue
+            delta = struct.unpack_from(">h", font_data, deltas + segment * 2)[0]
+            range_offset = struct.unpack_from(">H", font_data, ranges + segment * 2)[0]
+            if range_offset:
+                address = ranges + segment * 2 + range_offset + (65 - start) * 2
+                glyph = struct.unpack_from(">H", font_data, address)[0]
+                glyph = (glyph + delta) % 65536 if glyph else 0
+            else:
+                glyph = (65 + delta) % 65536
+            break
+        if glyph:
+            break
+    if not glyph:
+        raise ValueError("The fixture font does not map the letter A")
+    glyph_map = bytearray(265 * 2)
+    struct.pack_into(">H", glyph_map, 264 * 2, glyph)
+    unicode_map = (
+        b"/CIDInit /ProcSet findresource begin 12 dict begin begincmap\n"
+        b"/CIDSystemInfo << /Registry (Adobe) /Ordering (UCS) /Supplement 0 >> def\n"
+        b"/CMapName /FixtureUnicode def /CMapType 2 def\n"
+        b"1 begincodespacerange <00> <ff> endcodespacerange\n"
+        b"1 beginbfchar <41> <0041> endbfchar\n"
+        b"endcmap CMapName currentdict /CMap defineresource pop end end"
+    )
+    content = (
+        b"BT /F1 18 Tf 24 540 Td (Local PDF rendering resources) Tj ET\n"
+        b"BT /F2 24 Tf 24 490 Td (ABC) Tj ET\n"
+        b"BT /F3 24 Tf 24 440 Td <41> Tj ET\n"
+        b"q 0 1 1 0 k 24 250 160 100 re f Q\n"
+    )
+    return _pdf_objects(
+        [
+            b"<< /Type /Catalog /Pages 2 0 R >>",
+            b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+            b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 420 594] "
+            b"/Resources << /Font << /F1 4 0 R /F2 5 0 R /F3 6 0 R >> >> "
+            b"/Contents 10 0 R >>",
+            b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+            b"<< /Type /Font /Subtype /Type1 /BaseFont /Symbol >>",
+            b"<< /Type /Font /Subtype /Type0 /BaseFont /Arial "
+            b"/Encoding /90ms-RKSJ-H /DescendantFonts [7 0 R] /ToUnicode 9 0 R >>",
+            b"<< /Type /Font /Subtype /CIDFontType2 /BaseFont /Arial "
+            b"/CIDSystemInfo << /Registry (Adobe) /Ordering (Japan1) /Supplement 2 >> "
+            b"/FontDescriptor 8 0 R /CIDToGIDMap 12 0 R /DW 1000 /W [264 [667]] >>",
+            b"<< /Type /FontDescriptor /FontName /Arial /Flags 32 "
+            b"/FontBBox [0 -200 1000 900] /ItalicAngle 0 /Ascent 880 "
+            b"/Descent -120 /CapHeight 880 /StemV 80 /FontFile2 11 0 R >>",
+            _pdf_stream(unicode_map),
+            _pdf_stream(content),
+            _pdf_stream(font_data),
+            _pdf_stream(bytes(glyph_map)),
+        ]
+    )
+
+
+def png(page=1):
+    width, height = 480, 720
+
+    def chunk(kind, data):
+        return (
+            struct.pack(">I", len(data))
+            + kind
+            + data
+            + struct.pack(">I", zlib.crc32(kind + data))
+        )
+
+    rows = []
+    for y in range(height):
+        color = (220, 235, 245) if page % 2 else (237, 226, 215)
+        if 70 < y < 280 or 340 < y < 630:
+            color = (65 + page * 10, 90, 110)
+        rows.append(b"\x00" + bytes(color) * width)
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(b"".join(rows)))
+        + chunk(b"IEND", b"")
+    )
+
+
+def epub(*, padding=0, unsafe=False):
+    out = io.BytesIO()
+    with ZipFile(out, "w", ZIP_STORED) as archive:
+        archive.writestr("mimetype", "application/epub+zip")
+        archive.writestr(
+            "META-INF/container.xml",
+            (
+                '<container xmlns="urn:oasis:names:tc:opendocument:xmlns:co'
+                'ntainer"><rootfiles><rootfile '
+                'full-path="OPS/book.opf"/></rootfiles></container>'
+            ),
+        )
+        archive.writestr(
+            "OPS/book.opf",
+            (
+                '<package xmlns="http://www.idpf.org/2007/opf"><metadata '
+                'xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:title>The '
+                "little journey</dc:title></metadata><manifest><item "
+                'id="one" href="one.xhtml" '
+                'media-type="application/xhtml+xml"/><item id="two" '
+                'href="two.xhtml" media-type="application/xhtml+xml"/><item'
+                ' id="nav" href="nav.xhtml" '
+                'media-type="application/xhtml+xml" '
+                'properties="nav"/></manifest><spine><itemref '
+                'idref="one"/><itemref idref="two"/></spine></package>'
+            ),
+        )
+        archive.writestr(
+            "OPS/nav.xhtml",
+            (
+                '<html xmlns="http://www.w3.org/1999/xhtml"><body><nav><a '
+                'href="one.xhtml">A quiet morning</a><a '
+                'href="two.xhtml">Across the city</a></nav></body></html>'
+            ),
+        )
+        malicious = (
+            (
+                "<script>window.bookExecuted=true</script><img "
+                'src="https://external.invalid/track.png"/><iframe '
+                'src="https://external.invalid/"></iframe><a '
+                'href="javascript:alert(1)">Bad link</a><form><input '
+                'name="secret"/></form>'
+            )
+            if unsafe
+            else ""
+        )
+        archive.writestr(
+            "OPS/one.xhtml",
+            (
+                '<html xmlns="http://www.w3.org/1999/xhtml"><body><h1>A '
+                "quiet morning</h1><p>The station was quiet when Mira "
+                "arrived. Her journey began with a map, a notebook and time"
+                " to look around.</p><p>This is a local sample book. "
+                "Chapters and images load only when needed.</p><a "
+                'href="two.xhtml#arrival">Continue to the next chapter</a>'
+            )
+            + malicious
+            + "</body></html>",
+        )
+        archive.writestr(
+            "OPS/two.xhtml",
+            (
+                '<html xmlns="http://www.w3.org/1999/xhtml"><body><h1 '
+                'id="arrival">Across the city</h1><p>Beyond the station, '
+                "the city was waking up. Mira followed the river until the "
+                'streets became familiar.</p><img src="images/page.png" '
+                'alt="Illustrative sample page"/></body></html>'
+            ),
+        )
+        archive.writestr("OPS/images/page.png", png())
+        if padding:
+            archive.writestr("unused/padding.bin", b"x" * padding)
+    return out.getvalue()
+
+
+def cbz(*, padding=0):
+    out = io.BytesIO()
+    with ZipFile(out, "w", ZIP_STORED) as archive:
+        for page in (10, 2, 1):
+            archive.writestr(f"pages/{page}.png", png(page))
+        if padding:
+            archive.writestr("unused/padding.bin", b"x" * padding)
+    return out.getvalue()
+
+
+def cbr():
+    def header(kind, flags, fields=b""):
+        body = struct.pack("<BHH", kind, flags, 7 + len(fields)) + fields
+        return struct.pack("<H", zlib.crc32(body) & 0xFFFF) + body
+
+    output = bytearray(b"Rar!\x1a\x07\x00")
+    output += header(0x73, 0, b"\x00" * 6)
+    for page in (2, 1):
+        name, data = f"{page}.png".encode(), png(page)
+        fields = (
+            struct.pack(
+                "<LLBLLBBHL",
+                len(data),
+                len(data),
+                3,
+                zlib.crc32(data),
+                0,
+                20,
+                0x30,
+                len(name),
+                0x81A4,
+            )
+            + name
+        )
+        output += header(0x74, 0x8000, fields) + data
+    output += header(0x7B, 0)
+    return bytes(output)
+
+
+def manga_epub():
+    """A two-page image-based EPUB using the same generated panels as CBZ."""
+    output = io.BytesIO()
+    with (
+        ZipFile(io.BytesIO(epub())) as original,
+        ZipFile(output, "w", ZIP_STORED) as archive,
+    ):
+        for info in original.infolist():
+            content = original.read(info.filename)
+            if info.filename in {"OPS/one.xhtml", "OPS/two.xhtml"}:
+                content = (
+                    b'<html xmlns="http://www.w3.org/1999/xhtml"><body><div><img '
+                    b'src="images/page.png" alt="Manga page"/></div></body></html>'
+                )
+            archive.writestr(info.filename, content)
+    return output.getvalue()
diff --git a/tests/support/browser_transfer_app.py b/tests/support/browser_transfer_app.py
new file mode 100644
index 00000000..6b2c77d2
--- /dev/null
+++ b/tests/support/browser_transfer_app.py
@@ -0,0 +1,1322 @@
+"""Offline browser fixture using the real application, auth, guard and routes.
+
+Run with ``uv run --group e2e uvicorn tests.support.browser_transfer_app:app``.
+Telegram, database and remote transports are synthetic. No .env or real storage
+is loaded.
+The fixture-only control routes let browser tests advance jobs deterministically.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import io
+import math
+import os
+import struct
+import tempfile
+import time
+import wave
+import zlib
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+from urllib.parse import unquote, urlsplit
+
+from fastapi import Request, Response, UploadFile
+from telethon import types
+from telethon.errors import (
+    PasswordHashInvalidError,
+    PhoneCodeInvalidError,
+    SessionPasswordNeededError,
+)
+
+from tests.support.memory_mongo import FixtureMongoBackend
+from tgdrive.core.config import Settings
+from tgdrive.core.security import SESSION_COOKIE
+from tgdrive.settings.management import ConnectionManager
+from tgdrive.settings.premium_login import PremiumLoginService
+from tgdrive.storage import mongo as fixture_mongo
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import TelegramMessage
+from tgdrive.transfers.manager import TransferCancelled, TransferEmptyFile
+from tgdrive.transfers.remote import RemoteFileInfo
+from tgdrive.transfers.tasks import TransferRecord, TransferRegistry, TransferStatus
+from tgdrive.web.app import create_app
+
+PASSWORD = "offline browser test password"
+CONTROL_HEADER = "tgdrive-offline-browser-fixture"
+
+
+class FixtureClient:
+    name = "offline-browser-storage"
+    display_name = "TGDrive Test Bot"
+    username = "tgdrive_fixture_bot"
+
+    def refresh_identity(self):
+        self.display_name = "TGDrive Refreshed Bot"
+
+    is_connected = False
+
+    def __init__(self, payloads: dict[int, bytes]) -> None:
+        self.payloads = payloads
+
+    async def start(self) -> None:
+        self.is_connected = True
+
+    async def stop(self) -> None:
+        self.is_connected = False
+
+    async def get_messages(self, channel: int, *, message_ids: int) -> Any:
+        content = self.payloads.get(message_ids)
+        if content is None:
+            return None
+        # Real immutable Telegram document identities exercise production pooled
+        # RAM/disk reads. A size-only namespace bypasses that path entirely.
+        native = SimpleNamespace(
+            id=message_ids,
+            chat_id=channel,
+            sender_id=1,
+            raw_text="",
+            photo=None,
+            file=SimpleNamespace(size=len(content), name="fixture.bin"),
+            document=types.Document(
+                id=message_ids + 100000,
+                access_hash=2,
+                file_reference=b"offline-fixture",
+                date=datetime(2026, 10, 18, tzinfo=UTC),
+                mime_type="application/octet-stream",
+                size=len(content),
+                dc_id=2,
+                attributes=[],
+            ),
+        )
+        return TelegramMessage(self, native)
+
+    async def download_thumbnail(
+        self,
+        message: Any,
+        *,
+        max_bytes: int,
+        target_size: int,
+        max_dimension: int,
+    ) -> bytes | None:
+        # Synthetic provider-supplied covers exercise the real bounded endpoint.
+        # These never invoke the file stream, PDF renderer, or video decoder.
+        content = self.payloads[message.id]
+        if content.startswith(b"\x89PNG\r\n\x1a\n"):
+            return content if len(content) <= max_bytes else None
+        if content.startswith(b"%PDF"):
+            kind = "document"
+        elif content.startswith(b"\x1aE\xdf\xa3") or content[4:8] == b"ftyp":
+            kind = "video"
+        else:
+            return None
+        cache = getattr(self, "_thumbnail_samples", {})
+        if kind not in cache:
+            cache[kind] = _thumbnail_png(kind)
+            self._thumbnail_samples = cache
+        return cache[kind]
+
+    def describe_media(self, message: Any) -> dict[str, Any]:
+        original = {
+            "id": "original",
+            "label": "Original",
+            "is_original": True,
+            "size": len(self.payloads[message.id]),
+        }
+        # This source-switch fixture deliberately reuses the real MKV bytes.
+        # It exercises player replacement and HTTP Range, not Telegram encoding.
+        variants = (
+            [
+                {
+                    **original,
+                    "id": "fixture-same-bytes",
+                    "label": "Fixture alternate source",
+                    "is_original": False,
+                }
+            ]
+            if self.payloads[message.id].startswith(b"\x1aE\xdf\xa3")
+            else []
+        )
+        return {"original": original, "variants": variants}
+
+    def select_media_variant(self, message: Any, quality_id: str) -> Any:
+        if quality_id == "fixture-same-bytes" and self.payloads[message.id].startswith(
+            b"\x1aE\xdf\xa3"
+        ):
+            return message
+        raise ValueError("The fixture media variant is unavailable")
+
+    async def stream_media(self, message: Any, *, limit: int, offset: int):
+        content = self.payloads[message.id]
+        chunk = 1024 * 1024
+        for index in range(offset, offset + limit):
+            yield content[index * chunk : (index + 1) * chunk]
+
+
+class FixtureTransfers:
+    def __init__(self, store: DriveStore, payloads: dict[int, bytes]) -> None:
+        self.registry = TransferRegistry(cancel_grace_seconds=0.2)
+        self.store = store
+        self.payloads = payloads
+        self.started: list[dict[str, Any]] = []
+        self.release: dict[str, asyncio.Event] = {}
+        self.fail_deletions: set[str] = set()
+
+    async def receive_browser_upload(
+        self,
+        upload: UploadFile,
+        destination: str,
+        *,
+        is_disconnected: Callable[[], Awaitable[bool]] | None = None,
+        on_created: Callable[[TransferRecord], Awaitable[None]] | None = None,
+    ) -> TransferRecord:
+        self.store.get_directory(destination)
+        record = await self.registry.create("saving", total=upload.size or 0)
+        record.status = TransferStatus.RUNNING
+        try:
+            if on_created:
+                await on_created(record)
+            if record.cancel_event.is_set():
+                raise TransferCancelled("Transfer cancelled")
+            content = await upload.read()
+            if not content:
+                raise TransferEmptyFile("Empty files cannot be uploaded to Telegram")
+            if is_disconnected is not None and await is_disconnected():
+                raise TransferCancelled("Transfer cancelled")
+            self._start(record, upload.filename or "upload.bin", destination, content)
+            return record
+        finally:
+            await upload.close()
+
+    async def enqueue_upload(
+        self,
+        local_path: Path,
+        destination: str,
+        file_name: str,
+        size: int,
+        *,
+        transfer_id: str | None = None,
+        folder_upload: dict[str, Any] | None = None,
+    ) -> TransferRecord:
+        record = await self.registry.create(
+            "queued", total=size, transfer_id=transfer_id
+        )
+        if record.task is not None or record.terminal:
+            return record
+        record.context.update(kind="upload", name=file_name, destination=destination)
+        if folder_upload is not None:
+            record.context["folder_upload"] = dict(folder_upload)
+        self._start(record, file_name, destination, local_path.read_bytes())
+        return record
+
+    async def cancel_job(self, job_id: str) -> TransferRecord:
+        return await self.registry.cancel(job_id)
+
+    async def start_deletion(self, path: str) -> TransferRecord:
+        intent = self.store.begin_deletion(path)
+        record = await self.registry.create(
+            "deleting", total=len(intent["message_ids"]), transfer_id=intent["id"]
+        )
+        record.context.update(
+            kind="delete",
+            name=self.store.get_directory(path, include_trashed=True)["name"],
+            path=path,
+        )
+        self.release[record.id] = asyncio.Event()
+
+        async def delete(item: TransferRecord) -> None:
+            await self.release[item.id].wait()
+            if item.id in self.fail_deletions:
+                self.fail_deletions.remove(item.id)
+                raise RuntimeError("Synthetic catalog deletion failed")
+            self.store.finish_deletion(intent["id"])
+            (
+                await self.registry.update(
+                    item.id, status=TransferStatus.COMPLETED, phase="completed"
+                )
+            )
+
+        self.registry.spawn(record.id, delete)
+        return record
+
+    async def retry_job(self, job_id: str) -> TransferRecord:
+        record = self.registry.get(job_id)
+        if record.context.get("showcase"):
+            (await self.registry.retry(job_id))
+            self._start(
+                record,
+                record.context["name"],
+                record.context["destination"],
+                b"Demo retry result",
+            )
+
+            async def finish():
+                await asyncio.sleep(2)
+                self.release[record.id].set()
+
+            self.showcase_finish_tasks = getattr(self, "showcase_finish_tasks", set())
+            task = asyncio.create_task(finish())
+            self.showcase_finish_tasks.add(task)
+            task.add_done_callback(self.showcase_finish_tasks.discard)
+            return record
+        if record.context.get("kind") != "delete":
+            raise ValueError("Only fixture deletion retries are supported")
+        (await self.registry.retry(job_id))
+        return await self.start_deletion(record.context["path"])
+
+    async def inspect_remote(self, url: str) -> RemoteFileInfo:
+        await asyncio.sleep(0.05)
+        return RemoteFileInfo(
+            url=url,
+            filename=unquote(urlsplit(url).path.rsplit("/", 1)[-1]) or "remote.bin",
+            size=12,
+            content_type="application/octet-stream",
+            etag=None,
+        )
+
+    async def start_remote(
+        self, *, url: str, destination: str, filename: str | None
+    ) -> TransferRecord:
+        self.store.get_directory(destination)
+        record = await self.registry.create("downloading", total=12)
+        name = filename or unquote(urlsplit(url).path.rsplit("/", 1)[-1])
+        self._start(record, name, destination, b"remote-bytes")
+        return record
+
+    def _start(
+        self, record: TransferRecord, name: str, destination: str, content: bytes
+    ) -> None:
+        self.release[record.id] = asyncio.Event()
+        self.started.append({"id": record.id, "name": name, "destination": destination})
+        self.registry.spawn(
+            record.id,
+            lambda transfer: self._simulate(transfer, name, destination, content),
+        )
+
+    async def _simulate(
+        self, record: TransferRecord, name: str, destination: str, content: bytes
+    ) -> None:
+        total = len(content)
+        for numerator in (0, 1, 2, 3):
+            if record.cancel_event.is_set():
+                return
+            (
+                await self.registry.update(
+                    record.id,
+                    status=TransferStatus.RUNNING,
+                    phase="uploading",
+                    current=total * numerator // 4,
+                    total=total,
+                )
+            )
+            await asyncio.sleep(0.15)
+        released = asyncio.create_task(self.release[record.id].wait())
+        cancelled = asyncio.create_task(record.cancel_event.wait())
+        try:
+            await asyncio.wait(
+                {released, cancelled}, return_when=asyncio.FIRST_COMPLETED
+            )
+        finally:
+            released.cancel()
+            cancelled.cancel()
+            await asyncio.gather(released, cancelled, return_exceptions=True)
+        if record.cancel_event.is_set():
+            return
+        (
+            await self.registry.update(
+                record.id, phase="finalizing", current=total, total=total
+            )
+        )
+        await asyncio.sleep(0.15)
+        if record.cancel_event.is_set():
+            return
+        message_id = max(self.payloads, default=100) + 1
+        self.payloads[message_id] = content
+        self.store.add_file(
+            destination, name, message_id, total, operation_id=record.id
+        )
+        (
+            await self.registry.update(
+                record.id,
+                status=TransferStatus.COMPLETED,
+                phase="completed",
+                current=total,
+                total=total,
+            )
+        )
+
+    async def delete_telegram_messages(self, message_ids: list[int]) -> None:
+        for message_id in message_ids:
+            self.payloads.pop(message_id, None)
+
+
+def _preview_pdf(page_count: int = 3) -> bytes:
+    """Real portrait pages for continuous scrolling and bounded PDF rendering."""
+    font_id = page_count + 3
+    content_start = font_id + 1
+    kids = " ".join(f"{number + 3} 0 R" for number in range(page_count))
+    objects = [
+        b"<< /Type /Catalog /Pages 2 0 R >>",
+        f"<< /Type /Pages /Kids [{kids}] /Count {page_count} >>".encode(),
+    ]
+    for number in range(page_count):
+        objects.append(
+            (
+                "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 420 594] "
+                f"/Resources << /Font << /F1 {font_id} 0 R >> >> "
+                f"/Contents {content_start + number} 0 R >>"
+            ).encode()
+        )
+    objects.append(b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>")
+    for number in range(1, page_count + 1):
+        stream = (
+            f"BT /F1 22 Tf 24 540 Td (TGDrive PDF preview page {number}) Tj ET".encode()
+        )
+        objects.append(
+            b"<< /Length "
+            + str(len(stream)).encode()
+            + b" >>\nstream\n"
+            + stream
+            + b"\nendstream"
+        )
+    result = b"%PDF-1.4\n"
+    offsets = [0]
+    for identity, body in enumerate(objects, 1):
+        offsets.append(len(result))
+        result += str(identity).encode() + b" 0 obj\n" + body + b"\nendobj\n"
+    start = len(result)
+    size = len(objects) + 1
+    result += f"xref\n0 {size}\n0000000000 65535 f \n".encode()
+    result += b"".join(f"{offset:010d} 00000 n \n".encode() for offset in offsets[1:])
+    return (
+        result
+        + f"trailer\n<< /Size {size} /Root 1 0 R >>\nstartxref\n{start}\n%%EOF".encode()
+    )
+
+
+def _large_preview_pdf(
+    page_count: int = 48, *, shared_resources=False, filtered=False
+) -> bytes:
+    """A real 36 MiB image document, with distinct uncompressed page images."""
+    result = io.BytesIO()
+    result.write(b"%PDF-1.4\n")
+    offsets = [0]
+    font_id = 3 + page_count * 3
+    resources_id = font_id + 1
+    mask_id = resources_id + int(shared_resources)
+
+    def obj(identity, body):
+        offsets.append(result.tell())
+        result.write(f"{identity} 0 obj\n".encode() + body + b"\nendobj\n")
+
+    kids = " ".join(f"{3 + number * 3} 0 R" for number in range(page_count))
+    obj(1, b"<< /Type /Catalog /Pages 2 0 R >>")
+    obj(2, f"<< /Type /Pages /Kids [{kids}] /Count {page_count} >>".encode())
+    for number in range(page_count):
+        identity = 3 + number * 3
+        obj(
+            identity,
+            (
+                "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 420 594] "
+                + (
+                    f"/Resources {resources_id} 0 R "
+                    if shared_resources
+                    else f"/Resources << /Font << /F1 {font_id} 0 R >> "
+                    f"/XObject << /Im{number} {identity + 1} 0 R >> >> "
+                )
+                + f"/Contents {identity + 2} 0 R >>"
+            ).encode(),
+        )
+        pixels = bytes(
+            channel
+            for y in range(512)
+            for x in range(512)
+            for channel in ((x + number * 7) % 256, y % 256, (x + y + number * 3) % 256)
+        )
+        if filtered:
+            import zlib
+
+            pixels = zlib.compress(pixels, level=0)
+        filter_clause = "/Filter /FlateDecode " if filtered else ""
+        mask_clause = f"/SMask {mask_id} 0 R " if filtered and number == 0 else ""
+        obj(
+            identity + 1,
+            (
+                f"<< /Type /XObject /Subtype /Image /Width 512 /Height 512 "
+                f"/ColorSpace /DeviceRGB /BitsPerComponent 8 "
+                f"{filter_clause}{mask_clause}"
+                f"/Length {len(pixels)} >>\nstream\n"
+            ).encode()
+            + pixels
+            + b"\nendstream",
+        )
+        content = (
+            f"q 360 0 0 450 30 80 cm /Im{number} Do Q "
+            f"BT /F1 18 Tf 24 550 Td (TGDrive large PDF page {number + 1}) Tj ET"
+        ).encode()
+        obj(
+            identity + 2,
+            f"<< /Length {len(content)} >>\nstream\n".encode()
+            + content
+            + b"\nendstream",
+        )
+    obj(font_id, b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>")
+    if shared_resources:
+        images = " ".join(f"/Im{i} {4 + i * 3} 0 R" for i in range(page_count))
+        obj(
+            resources_id,
+            f"<< /Font << /F1 {font_id} 0 R >> /XObject << {images} >> >>".encode(),
+        )
+    if filtered:
+        mask = bytes([200]) * (512 * 512)
+        obj(
+            mask_id,
+            (
+                "<< /Type /XObject /Subtype /Image /Width 512 /Height 512 "
+                f"/ColorSpace /DeviceGray /BitsPerComponent 8 /Length {len(mask)} "
+                ">>\nstream\n"
+            ).encode()
+            + mask
+            + b"\nendstream",
+        )
+    start = result.tell()
+    result.write(f"xref\n0 {len(offsets)}\n0000000000 65535 f \n".encode())
+    for offset in offsets[1:]:
+        result.write(f"{offset:010d} 00000 n \n".encode())
+    result.write(
+        (
+            f"trailer\n<< /Size {len(offsets)} /Root 1 0 R >>\n"
+            f"startxref\n{start}\n%%EOF"
+        ).encode()
+    )
+    return result.getvalue()
+
+
+def _preview_png() -> bytes:
+    """A generated RGB image without an external image or font dependency."""
+
+    def chunk(kind: bytes, data: bytes) -> bytes:
+        return (
+            struct.pack(">I", len(data))
+            + kind
+            + data
+            + struct.pack(">I", zlib.crc32(kind + data))
+        )
+
+    pixels = b"".join(b"\x00" + bytes([40 + y * 5, 90, 150]) * 16 for y in range(16))
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", 16, 16, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(pixels))
+        + chunk(b"IEND", b"")
+    )
+
+
+def _thumbnail_png(kind: str) -> bytes:
+    """Illustrative local-demo provider covers, small enough for a file tile."""
+    width, height = 240, 144
+
+    def pixel(x, y):
+        if kind == "document":
+            if 72 < x < 168 and 12 < y < 132:
+                if 84 < x < 154 and (y - 38) % 15 < 3 and 38 < y < 112:
+                    return (80, 104, 140)
+                return (245, 247, 250)
+            return (214, 225, 239)
+        if y < 80:
+            return (48 + y, 108 + y // 2, 169 + y // 3)
+        if y > 138 - x // 3:
+            return (45, 107, 86)
+        return (78, 144, 116)
+
+    def chunk(kind, data):
+        return (
+            struct.pack(">I", len(data))
+            + kind
+            + data
+            + struct.pack(">I", zlib.crc32(kind + data))
+        )
+
+    pixels = b"".join(
+        b"\x00" + b"".join(bytes(pixel(x, y)) for x in range(width))
+        for y in range(height)
+    )
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(pixels))
+        + chunk(b"IEND", b"")
+    )
+
+
+def _preview_wav() -> bytes:
+    """A short locally generated PCM tone for native audio controls."""
+    stream = io.BytesIO()
+    with wave.open(stream, "wb") as output:
+        output.setnchannels(1)
+        output.setsampwidth(2)
+        output.setframerate(8000)
+        output.writeframes(
+            b"".join(
+                struct.pack("<h", round(4000 * math.sin(index * math.tau * 220 / 8000)))
+                for index in range(2000)
+            )
+        )
+    return stream.getvalue()
+
+
+class FixtureBackup:
+    """Checkpoint transport state for owner UI tests; never contacts Telegram."""
+
+    def __init__(self, store: DriveStore) -> None:
+        self.protected_revision = store.revision
+        self.error: str | None = None
+        self.state_override: str | None = None
+        self.fail_next = False
+        self.calls = 0
+
+    def history(self) -> list[dict[str, Any]]:
+        return []
+
+    def protection_status(self, store: DriveStore) -> dict[str, Any]:
+        status = {
+            "state": self.state_override
+            or (
+                "error"
+                if self.error
+                else "protected"
+                if self.protected_revision >= store.revision
+                else "pending"
+            ),
+            "metadata_revision": store.revision,
+            "protected_revision": self.protected_revision,
+            "checkpoint_message_id": 9000 + self.calls,
+            "last_success_at": "2026-10-16T00:00:00+00:00",
+        }
+        if self.error:
+            status["error"] = self.error
+        return status
+
+    async def ensure_revision(self, store: DriveStore, required_revision: int) -> int:
+        self.calls += 1
+        await asyncio.sleep(0.05)
+        self.state_override = None
+        if self.fail_next:
+            self.fail_next = False
+            self.error = "Synthetic Telegram checkpoint confirmation failed."
+            raise RuntimeError(self.error)
+        self.error = None
+        self.protected_revision = max(store.revision, required_revision)
+        return 9000 + self.calls
+
+    async def snapshot_now(self, store: DriveStore) -> int:
+        return await self.ensure_revision(store, store.revision)
+
+    def set_scenario(self, scenario: str, store: DriveStore) -> None:
+        self.error = None
+        self.state_override = None
+        self.fail_next = False
+        self.protected_revision = store.revision
+        if scenario in {"pending", "error", "stale", "fail-next"}:
+            self.protected_revision = max(0, store.revision - 1)
+        if scenario == "error":
+            self.error = "Synthetic Telegram checkpoint confirmation failed."
+        elif scenario == "stale":
+            self.state_override = "protected"
+        elif scenario == "fail-next":
+            self.fail_next = True
+        elif scenario not in {"protected", "pending"}:
+            raise ValueError("Unknown fixture backup scenario")
+
+
+class FixtureLoginClient:
+    """Synthetic Telegram login transport; never connects to a real account."""
+
+    def __init__(self) -> None:
+        self.session = SimpleNamespace(
+            save=lambda: "synthetic-premium-session-for-browser-tests"
+        )
+
+    async def connect(self) -> None:
+        pass
+
+    async def disconnect(self) -> None:
+        pass
+
+    async def log_out(self) -> None:
+        pass
+
+    async def send_code_request(self, _phone: str) -> Any:
+        return SimpleNamespace(phone_code_hash="synthetic-browser-code-hash")
+
+    async def sign_in(self, *, code=None, password=None, **_kwargs) -> None:
+        if code is not None:
+            if code != "12345":
+                raise PhoneCodeInvalidError(request=None)
+            raise SessionPasswordNeededError(request=None)
+        if password != "synthetic-two-step-password":
+            raise PasswordHashInvalidError(request=None)
+
+    async def get_me(self) -> Any:
+        return SimpleNamespace(id=987654321, bot=False, premium=True)
+
+
+async def fixture_verify_connection(_api_id, _api_hash, row, _channel):
+    """Keep the real private persistence/API; replace only Telegram preflight."""
+    if row.kind == "user":
+        return "synthetic-premium-account"
+    prefix = row.credential.get_secret_value().split(":", 1)[0]
+    return (
+        "offline-browser-storage" if prefix == "123456" else "synthetic-bot-" + prefix
+    )
+
+
+class FixtureReplica:
+    """Deterministic offline contract; no Telegram access or durable secrets."""
+
+    def __init__(self, owner):
+        self.owner = owner
+        self.control = asyncio.Lock()
+        self._operation = asyncio.Lock()
+        self.state = {
+            "enabled": False,
+            "configured": False,
+            "recovery_only": False,
+            "phase": "disabled",
+            "source_channel": -1001234567890,
+            "backup_channel": None,
+            "revision": 9,
+            "protected_revision": 0,
+            "pending_revision": 9,
+            "last_success_at": None,
+            "current_file": "",
+            "total_files": 0,
+            "done_files": 0,
+            "total_parts": 0,
+            "done_parts": 0,
+            "total_bytes": 0,
+            "done_bytes": 0,
+            "error": None,
+            "report": [],
+        }
+        self.destination = None
+        self.catalog_only = False
+        self.events = []
+        self.journal = SimpleNamespace(
+            get=lambda name, default=None: {
+                "restore_point": {"revision": 7, "message_id": 9001},
+            }.get(name, default)
+        )
+
+    def status(self):
+        import copy
+
+        result = copy.deepcopy(self.state)
+        result["recovery_only"] = self.owner.recovery_only
+        return result
+
+    def key(self):
+        return "c" * 64
+
+    def recovery_kit(self):
+        return {
+            "format": "tgdrive-replica-key-v1",
+            "key": self.key(),
+            "restore_point": self.journal.get("restore_point"),
+            "next_backup_key": self.key(),
+            "mongodb_backup_key": None,
+            "instructions": "Synthetic key fixture. Never use it for a real drive.",
+        }
+
+    def start(self):
+        pass
+
+    async def close(self):
+        pass
+
+    async def before_mutation(self):
+        if self.blocked:
+            from tgdrive.settings.managed_settings import SettingsProblem
+
+            raise SettingsProblem("Recovery is in progress.", status=409)
+
+    @property
+    def blocked(self):
+        return self.state["phase"] in {
+            "recovering",
+            "ready_to_activate",
+            "restart_required",
+        }
+
+    def event(self, message):
+        self.state["report"].append(
+            {
+                "at": "2026-10-22T05:00:00Z",
+                "level": "info",
+                "message": message,
+            }
+        )
+        self.state["report"] = self.state["report"][-100:]
+
+    async def configure(self, channel, token, independent):
+        if not independent or channel == self.state["source_channel"]:
+            raise ValueError("Use separate private channels and owner accounts.")
+        self.events.append({"action": "configure", "channel": channel})
+        self.state.update(
+            enabled=True,
+            configured=True,
+            backup_channel=channel,
+            phase="syncing",
+            current_file="Project archive.zip",
+            total_files=3,
+            done_files=1,
+            total_parts=4,
+            done_parts=1,
+            total_bytes=3 * 1024**2,
+            done_bytes=1024**2,
+        )
+        self.event("Private channels verified. Initial synchronization started.")
+        return self.status()
+
+    async def action(self, action):
+        self.events.append({"action": action})
+        if action == "disable":
+            self.state.update(enabled=False, phase="disabled")
+        elif action == "pause":
+            self.state["phase"] = "paused"
+        elif action in {"resume", "retry", "sync"}:
+            self.state.update(
+                enabled=True,
+                phase="recovering" if self.destination else "syncing",
+                error=None,
+            )
+        else:
+            raise ValueError("Unknown backup action")
+        self.event("Operation " + action + " requested.")
+        return self.status()
+
+    async def inspect_recovery(self, channel, token, key, message_id):
+        self.events.append(
+            {"action": "inspect", "channel": channel, "message_id": message_id}
+        )
+        self.state.update(
+            phase="paused",
+            error=None,
+            recovery_candidate={
+                "revision": 7,
+                "files": 3,
+                "bytes": 3 * 1024**2,
+                "channel": channel,
+                "complete": False,
+            },
+        )
+        self.event("Recovery copy authenticated. Nothing has been activated.")
+        return self.status()
+
+    async def recover_to(
+        self, target, target_token, confirmation, *, catalog_only=False
+    ):
+        if confirmation != str(target):
+            raise ValueError("Type the destination channel ID exactly.")
+        self.events.append(
+            {"action": "recover", "channel": target, "catalog_only": catalog_only}
+        )
+        self.destination = target
+        self.catalog_only = catalog_only
+        self.state.update(
+            phase="recovering",
+            error=None,
+            total_files=3,
+            done_files=1,
+            total_parts=4,
+            done_parts=1,
+            total_bytes=3 * 1024**2,
+            done_bytes=1024**2,
+            current_file="Project archive.zip",
+        )
+        self.event(
+            "File verification started." if catalog_only else "Recovery copy started."
+        )
+        return self.status()
+
+    def activate(self):
+        if not self.state.get("recovery_candidate", {}).get("complete"):
+            raise ValueError("Complete recovery first.")
+        self.events.append({"action": "activate"})
+        self.state["phase"] = "restart_required"
+        self.event("Recovery activation saved. Restart TGDrive.")
+        return self.status()
+
+    def scenario(self, scenario):
+        if scenario == "recovery-only":
+            self.owner.recovery_only = True
+        elif scenario == "error":
+            self.state.update(
+                phase="error",
+                error={
+                    "code": "CHANNEL_ACCESS",
+                    "detail": "Backup bot cannot read the target channel.",
+                    "action": (
+                        "Restore the bot's administrator permissions, then retry."
+                    ),
+                },
+            )
+        elif scenario == "waiting":
+            self.state.update(
+                phase="waiting",
+                error={
+                    "code": "FLOOD_WAIT",
+                    "detail": "Telegram asked this bot to wait.",
+                    "action": "TGDrive will retry after the displayed time.",
+                    "retry_at": 1792645260,
+                },
+            )
+        elif scenario == "lagging":
+            self.state.update(revision=10, pending_revision=1, phase="idle")
+        elif scenario == "many-events":
+            for number in range(100):
+                self.event(f"File verification {number + 1} confirmed.")
+        elif scenario == "protected":
+            self.state.update(
+                phase="protected",
+                error=None,
+                protected_revision=9,
+                pending_revision=0,
+                done_files=3,
+                done_parts=4,
+                done_bytes=3 * 1024**2,
+                last_success_at="2026-10-22T05:00:00Z",
+            )
+        elif scenario == "recovery-ready":
+            self.state["recovery_candidate"].update(
+                channel=self.destination, complete=True
+            )
+            self.state.update(
+                phase="ready_to_activate",
+                done_files=3,
+                done_parts=4,
+                done_bytes=3 * 1024**2,
+                current_file="",
+                error=None,
+            )
+        else:
+            raise ValueError("Unknown replica fixture scenario")
+        return self.status()
+
+
+class FixtureRuntime:
+    def __init__(self) -> None:
+        self.mongo = FixtureMongoBackend()
+        self.store = DriveStore.create()
+        self.payloads = {101: b"public content", 102: b"private content"}
+        folder = self.store.create_folder("/", "資料")
+        private = self.store.create_folder("/", "Private folder")
+        self.folder_path = f"/{folder['id']}"
+        self.private_path = f"/{private['id']}"
+        shared_file = self.store.add_file(self.folder_path, "résumé #1.txt", 101, 14)
+        private_file = self.store.add_file(self.private_path, "private.txt", 102, 15)
+        self.shared_file_path = f"{self.folder_path}/{shared_file['id']}"
+        self.private_file_path = f"{self.private_path}/{private_file['id']}"
+        preview = self.store.create_folder("/", "Preview samples")
+        preview_path = f"/{preview['id']}"
+        self.preview_path = preview_path
+        samples = {
+            "sample.json": b'{"message":"<img src=x onerror=alert(1)>","count":3}',
+            "reports.csv": b"name,value\nalpha,3\nbeta,4\n",
+            "source.html": b"<script>window.previewExecuted=true</script>",
+            "sample.pdf": _preview_pdf(),
+            "long.pdf": _preview_pdf(12),
+            "sample.png": _preview_png(),
+            "sample.svg": (
+                b'<svg xmlns="http://www.w3.org/2000/svg" width="120" height="80">'
+                b"<style>rect{fill:rgb(24,160,88)}</style>"
+                b'<rect width="120" height="80"/>'
+                b"<script>parent.svgPreviewExecuted=true</script>"
+                b'<image href="https://svg-external.invalid/track.png" '
+                b'width="1" height="1"/>'
+                b"</svg>"
+            ),
+            "sample.wav": _preview_wav(),
+            "archive.bin": bytes(range(256)),
+            "setup.exe": b"Synthetic fixture bytes; never an executable.",
+            "empty.exe": b"",
+            "installer-"
+            + "very-long-file-name-" * 5
+            + "setup.exe": b"Long-name fixture.",
+            # Self-generated FFmpeg testsrc2 ASF containers distinguish the
+            # suffix from real decoder support: MPEG4 works; MSMPEG4v3 does not
+            # exist in the pinned published WASM decoder build.
+            "software-mpeg4.wmv": (
+                Path(__file__).resolve().parents[1] / "fixtures" / "software-mpeg4.wmv"
+            ).read_bytes(),
+            "unsupported-msmpeg4.wmv": (
+                Path(__file__).resolve().parents[1]
+                / "fixtures"
+                / "unsupported-msmpeg4.wmv"
+            ).read_bytes(),
+            # Self-generated 8s H264/AAC MP4 with English/Hindi mov_text samples;
+            # testsrc2 + sine, FFmpeg libx264/crf30 and AAC32k, no third-party media.
+            # One same-length subtitle payload patch preserves literal inert markup
+            # (the SRT encoder otherwise strips tags); MP4 offsets stay unchanged.
+            "movtext-subtitles.mp4": (
+                Path(__file__).resolve().parents[1]
+                / "fixtures"
+                / "movtext-subtitles.mp4"
+            ).read_bytes(),
+            "multitrack.mkv": (
+                Path(__file__).resolve().parents[1] / "fixtures" / "multitrack.mkv"
+            ).read_bytes(),
+        }
+        for identity, (name, content) in enumerate(samples.items(), 110):
+            self.payloads[identity] = content
+            self.store.add_file(preview_path, name, identity, len(content))
+        self.pool = ClientPool([FixtureClient(self.payloads)])
+        self.transfers = FixtureTransfers(self.store, self.payloads)
+        self.backup = FixtureBackup(self.store)
+        self.recovery_only = False
+        self.replica = FixtureReplica(self)
+        self.ready = False
+
+    async def start(self) -> None:
+        from tgdrive.settings.performance_preferences import get_performance_settings
+
+        await get_performance_settings(settings, self).initialize()
+        await self.pool.start()
+        if os.environ.get("TGDRIVE_UI_SHOWCASE") == "1":
+            from tests.support.showcase_data import seed
+
+            await seed(self, settings)
+            seed_reading_samples(self)
+            await seed_thumbnail_samples(self)
+            self.store.set_starred(self.preview_path, True)
+            self.store.set_starred(self.reading_path, True)
+        self.ready = True
+
+    async def stop(self) -> None:
+        self.ready = False
+        task = getattr(self, "showcase_task", None)
+        if task is not None:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+        await self.transfers.registry.shutdown()
+        await self.preloads.close()
+        await self.pool.stop(drain_timeout=1)
+
+
+_temporary = tempfile.TemporaryDirectory(prefix="tgdrive-browser-fixture-")
+runtime = FixtureRuntime()
+settings = Settings(
+    _env_file=None,
+    MONGODB_URI="mongodb://synthetic.invalid",
+    API_ID=12345,
+    API_HASH="a" * 32,
+    BOT_TOKENS="123456:" + "x" * 30,
+    STORAGE_CHANNEL=-1001234567890,
+    ADMIN_PASSWORD=PASSWORD,
+    SESSION_SECRET="synthetic-browser-test-secret-" * 2,
+    STRING_SESSIONS="",
+    MAIN_BOT_TOKEN="",
+    TELEGRAM_ADMIN_IDS="",
+    DATA_DIR=Path(_temporary.name) / "data",
+    CACHE_DIR=Path(_temporary.name) / "cache",
+    COOKIE_SECURE=False,
+    MAX_FILE_SIZE=(
+        16 * 1024**3
+        if os.environ.get("TGDRIVE_UI_SHOWCASE") == "1"
+        else 32 * 1024 * 1024
+    ),
+)
+# Register only this private fixture directory. Production's required MongoDB
+# interfaces remain active, backed by the explicit in-memory test double.
+fixture_mongo._directories[settings.resolved_data_dir] = runtime.mongo
+fixture_mongo._backends[
+    (settings.mongodb_uri.get_secret_value(), settings.mongodb_database)
+] = runtime.mongo
+
+runtime.connection_manager = ConnectionManager(
+    settings, runtime, verifier=fixture_verify_connection
+)
+app = create_app(settings, runtime=runtime)
+if os.environ.get("TGDRIVE_UI_SHOWCASE") == "1":
+    from tests.support.showcase_data import install
+
+    install(app, runtime)
+app.state.premium_login_service = PremiumLoginService(
+    runtime.connection_manager.login_api,
+    runtime.connection_manager.add_authenticated_session,
+    client_factory=lambda _api_id, _api_hash: FixtureLoginClient(),
+)
+
+
+def _control(request: Request) -> None:
+    from fastapi import HTTPException
+
+    if request.headers.get("x-fixture-control") != CONTROL_HEADER:
+        raise HTTPException(
+            403, "Fixture controls are only available to the test runner"
+        )
+
+
+@app.get("/__test__/state")
+async def state(request: Request) -> dict[str, Any]:
+    _control(request)
+    return {
+        "started": runtime.transfers.started,
+        "records": {
+            record.id: record.as_dict()
+            for record in runtime.transfers.registry._records.values()
+        },
+        "seed": {
+            "folder": runtime.folder_path,
+            "private_folder": runtime.private_path,
+            "file": runtime.shared_file_path,
+            "private_file": runtime.private_file_path,
+            "preview_folder": runtime.preview_path,
+        },
+    }
+
+
+@app.post("/__test__/backup/{scenario}")
+async def backup_scenario(request: Request, scenario: str) -> dict[str, Any]:
+    _control(request)
+    runtime.backup.set_scenario(scenario, runtime.store)
+    return {
+        "recovery": runtime.backup.protection_status(runtime.store),
+        "calls": runtime.backup.calls,
+    }
+
+
+@app.get("/__test__/backup")
+async def backup_state(request: Request) -> dict[str, Any]:
+    _control(request)
+    return {
+        "recovery": runtime.backup.protection_status(runtime.store),
+        "calls": runtime.backup.calls,
+    }
+
+
+@app.post("/__test__/finish/{transfer_id}")
+async def finish(request: Request, transfer_id: str) -> dict[str, str]:
+    _control(request)
+    runtime.transfers.release[transfer_id].set()
+    return {"status": "ok"}
+
+
+@app.post("/__test__/expire-session")
+async def expire_session(request: Request, response: Response) -> dict[str, str]:
+    _control(request)
+    response.set_cookie(
+        SESSION_COOKIE,
+        app.state.sessions.create(
+            now=int(time.time()) - settings.session_ttl_seconds - 2
+        ),
+        httponly=True,
+        samesite="strict",
+        path="/",
+    )
+    return {"status": "ok"}
+
+
+@app.post("/__test__/fail-deletion/{transfer_id}")
+async def fail_deletion(request: Request, transfer_id: str) -> dict[str, str]:
+    _control(request)
+    record = runtime.transfers.registry.get(transfer_id)
+    if record.context.get("kind") != "delete":
+        raise ValueError("The fixture failure must target a deletion")
+    runtime.transfers.fail_deletions.add(transfer_id)
+    runtime.transfers.release[transfer_id].set()
+    return {"status": "ok"}
+
+
+@app.post("/__test__/pdf/large")
+async def seed_large_pdf(request: Request):
+    """Opt-in heavy fixture; ordinary browser tests pay no large-PDF cost."""
+    _control(request)
+    content = _large_preview_pdf(
+        shared_resources=request.query_params.get("shared") == "1",
+        filtered=request.query_params.get("filtered") == "1",
+    )
+    runtime.payloads[900] = content
+    single = runtime.store.add_file(
+        runtime.preview_path, "large-images.pdf", 900, len(content)
+    )
+    boundary = len(content) // 2
+    parts = []
+    for index, data in enumerate((content[:boundary], content[boundary:])):
+        message_id = 901 + index
+        runtime.payloads[message_id] = data
+        parts.append(
+            {
+                "index": index,
+                "offset": 0 if index == 0 else boundary,
+                "size": len(data),
+                "message_id": message_id,
+                "sha256": hashlib.sha256(data).hexdigest(),
+            }
+        )
+    split = runtime.store.add_file(
+        runtime.preview_path, "split-images.pdf", 901, len(content), parts=parts
+    )
+    return {
+        "size": len(content),
+        "pages": 48,
+        "single": runtime.preview_path + "/" + single["id"],
+        "split": runtime.preview_path + "/" + split["id"],
+    }
+
+
+@app.post("/__test__/pdf/features")
+async def seed_pdf_features(request: Request):
+    """Tiny opt-in PDFs exercise password prompts and local rendering resources."""
+    from tests.support.book_samples import encrypted_pdf, resource_pdf
+
+    _control(request)
+    font_data = (
+        Path(__file__).resolve().parents[2]
+        / "website/node_modules/pdfjs-dist/standard_fonts/LiberationSans-Regular.ttf"
+    ).read_bytes()
+    samples = {
+        "password-protected.pdf": encrypted_pdf(),
+        "local-resources.pdf": resource_pdf(font_data),
+    }
+    paths = {}
+    for message_id, (name, content) in enumerate(samples.items(), 930):
+        runtime.payloads[message_id] = content
+        item = runtime.store.add_file(
+            runtime.preview_path, name, message_id, len(content)
+        )
+        paths[name] = runtime.preview_path + "/" + item["id"]
+    return {"files": paths}
+
+
+def seed_reading_samples(target):
+    from tests.support.book_samples import cbr, cbz, epub, manga_epub
+
+    if hasattr(target, "reading_path"):
+        return target.reading_path
+    folder = target.store.create_folder("/", "Reading samples")
+    target.reading_path = "/" + folder["id"]
+    for message_id, (name, data) in enumerate(
+        {
+            "The little journey.epub": epub(unsafe=True),
+            "Sample comic.cbz": cbz(),
+            "Sample manga.cbr": cbr(),
+            "Image-based manga.epub": manga_epub(),
+        }.items(),
+        980,
+    ):
+        target.payloads[message_id] = data
+        target.store.add_file(target.reading_path, name, message_id, len(data))
+    if os.environ.get("TGDRIVE_UI_SHOWCASE") == "1":
+        from datetime import timedelta
+
+        from tgdrive.web.share_links import token_factory
+
+        for label, days in (("Book club", 30), ("Review copy", 7)):
+            target.store.create_share(
+                target.reading_path,
+                label=label,
+                expires_at=(datetime.now(UTC) + timedelta(days=days)).isoformat(),
+                token_factory=token_factory(settings),
+            )
+    return target.reading_path
+
+
+@app.post("/__test__/books")
+async def seed_books(request: Request):
+    _control(request)
+    return {"path": seed_reading_samples(runtime)}
+
+
+@app.post("/__test__/books/large-page")
+async def seed_large_book_page(request: Request):
+    """Opt-in encoded-page limit fixture; original PNG stays byte-for-byte intact."""
+    _control(request)
+    import struct
+    import zlib
+    from zipfile import ZipFile
+
+    from tests.support.book_samples import png
+
+    small = png(2)
+    # A legal private ancillary chunk keeps decoded pixels small while exercising
+    # a genuinely large original PNG through parsing, HTTP, CSP and image decode.
+    payload = b"p" * (39 * 1024**2)
+    chunk = b"tgDr" + payload
+    image = (
+        small[:-12]
+        + struct.pack(">I", len(payload))
+        + chunk
+        + struct.pack(">I", zlib.crc32(chunk))
+        + small[-12:]
+    )
+    output = io.BytesIO()
+    with ZipFile(output, "w") as archive:
+        archive.writestr("unused.bin", b"x" * (48 * 1024**2))
+        archive.writestr("page.png", image)
+    data = output.getvalue()
+    folder = seed_reading_samples(runtime)
+    runtime.payloads[985] = data
+    item = runtime.store.add_file(folder, "Large original page.cbz", 985, len(data))
+    return {
+        "path": folder,
+        "file": folder + "/" + item["id"],
+        "image_size": len(image),
+        "image_sha256": hashlib.sha256(image).hexdigest(),
+        "size": len(data),
+    }
+
+
+async def seed_thumbnail_samples(target):
+    from tests.support.book_samples import png
+    from tgdrive.media.generated_thumbnails import generate, save
+
+    if hasattr(target, "thumbnail_sample_path"):
+        return target.thumbnail_sample_path
+    folder = target.store.create_folder("/", "Thumbnail samples")
+    target.thumbnail_sample_path = "/" + folder["id"]
+    samples = {
+        "Illustration.png": png(2),
+        "Getting started.pdf": _preview_pdf(),
+        "Walkthrough.mp4": (
+            Path(__file__).resolve().parents[1] / "fixtures" / "movtext-subtitles.mp4"
+        ).read_bytes(),
+    }
+    for message_id, (name, data) in enumerate(samples.items(), 990):
+        target.payloads[message_id] = data
+        target.store.add_file(target.thumbnail_sample_path, name, message_id, len(data))
+        with tempfile.TemporaryDirectory() as directory:
+            staged = Path(directory) / name
+            staged.write_bytes(data)
+            cover = await generate(staged, name)
+        if cover:
+            save(
+                settings.resolved_cache_dir / "thumbnails",
+                settings.storage_channel,
+                message_id,
+                cover,
+            )
+    return target.thumbnail_sample_path
+
+
+@app.post("/__test__/thumbnails/generated")
+async def seed_generated_thumbnails(request: Request):
+    _control(request)
+    return {"path": await seed_thumbnail_samples(runtime)}
+
+
+@app.post("/__test__/replica/{scenario}")
+async def replica_scenario(request: Request, scenario: str):
+    _control(request)
+    return runtime.replica.scenario(scenario)
+
+
+@app.get("/__test__/replica")
+async def replica_fixture_state(request: Request):
+    _control(request)
+    return {"state": runtime.replica.status(), "events": runtime.replica.events}
diff --git a/tests/support/memory_mongo.py b/tests/support/memory_mongo.py
new file mode 100644
index 00000000..4e32e19b
--- /dev/null
+++ b/tests/support/memory_mongo.py
@@ -0,0 +1,164 @@
+"""Small explicit database double for the offline HTTP/browser fixture.
+
+This is not a MongoDB emulator or production storage backend. It preserves the
+session, identity and settings interfaces used by that fixture without a client,
+connection string lookup, filesystem database or external database request.
+"""
+
+from __future__ import annotations
+
+import copy
+import threading
+from collections import defaultdict
+from types import SimpleNamespace
+
+from pymongo.errors import DuplicateKeyError
+
+
+def _value(row, key):
+    current = row
+    for part in key.split("."):
+        if not isinstance(current, dict):
+            return None
+        current = current.get(part)
+    return current
+
+
+def _matches(row, query):
+    for key, expected in query.items():
+        value = _value(row, key)
+        if not isinstance(expected, dict):
+            if value != expected:
+                return False
+            continue
+        for operator, bound in expected.items():
+            if operator == "$in":
+                matches = value in bound
+            elif operator == "$ne":
+                matches = value != bound
+            elif value is None:
+                matches = False
+            elif operator == "$gt":
+                matches = value > bound
+            elif operator == "$gte":
+                matches = value >= bound
+            elif operator == "$lt":
+                matches = value < bound
+            elif operator == "$lte":
+                matches = value <= bound
+            else:
+                raise AssertionError(f"Unsupported fixture query: {operator}")
+            if not matches:
+                return False
+    return True
+
+
+class FixtureCursor(list):
+    def sort(self, key, direction=1):
+        super().sort(key=lambda row: _value(row, key), reverse=direction < 0)
+        return self
+
+    def limit(self, count):
+        return FixtureCursor(self[:count])
+
+
+class FixtureCollection:
+    def __init__(self):
+        self.rows = {}
+        self.lock = threading.RLock()
+
+    def find(self, query=None, **_kwargs):
+        with self.lock:
+            return FixtureCursor(
+                copy.deepcopy(row)
+                for row in self.rows.values()
+                if _matches(row, query or {})
+            )
+
+    def find_one(self, query=None, *, sort=None, **kwargs):
+        rows = self.find(query, **kwargs)
+        for key, direction in reversed(sort or []):
+            rows.sort(key, direction)
+        return rows[0] if rows else None
+
+    def insert_one(self, document, **_kwargs):
+        with self.lock:
+            identity = document["_id"]
+            if identity in self.rows:
+                raise DuplicateKeyError("Duplicate fixture identity")
+            self.rows[identity] = copy.deepcopy(document)
+            return SimpleNamespace(inserted_id=identity)
+
+    def replace_one(self, query, document, *, upsert=False, **_kwargs):
+        with self.lock:
+            current = self.find_one(query)
+            if current is None and not upsert:
+                return SimpleNamespace(matched_count=0)
+            document = copy.deepcopy(document)
+            document.setdefault("_id", current["_id"] if current else query["_id"])
+            if current is None and document["_id"] in self.rows:
+                raise DuplicateKeyError("Duplicate fixture identity")
+            self.rows[document["_id"]] = copy.deepcopy(document)
+            return SimpleNamespace(matched_count=int(current is not None))
+
+    def update_one(self, query, changes, *, upsert=False, **_kwargs):
+        with self.lock:
+            current = self.find_one(query)
+            if current is None and not upsert:
+                return SimpleNamespace(matched_count=0)
+            document = current or {"_id": query["_id"]}
+            for operator, values in changes.items():
+                if operator == "$set" or (
+                    operator == "$setOnInsert" and current is None
+                ):
+                    document.update(copy.deepcopy(values))
+                elif operator == "$max":
+                    for key, value in values.items():
+                        document[key] = max(document.get(key, value), value)
+                elif operator != "$setOnInsert":
+                    raise AssertionError(f"Unsupported fixture update: {operator}")
+            self.rows[document["_id"]] = document
+            return SimpleNamespace(matched_count=int(current is not None))
+
+    def delete_many(self, query, **_kwargs):
+        with self.lock:
+            identities = [row["_id"] for row in self.find(query)]
+            for identity in identities:
+                del self.rows[identity]
+            return SimpleNamespace(deleted_count=len(identities))
+
+    def delete_one(self, query, **_kwargs):
+        with self.lock:
+            row = self.find_one(query)
+            if row is not None:
+                del self.rows[row["_id"]]
+            return SimpleNamespace(deleted_count=int(row is not None))
+
+    def create_index(self, *_args, **_kwargs):
+        return "fixture-index"
+
+    def bulk_write(self, operations, **_kwargs):
+        for operation in operations:
+            self.replace_one(
+                operation._filter, operation._doc, upsert=operation._upsert
+            )
+
+
+class FixtureMongoBackend:
+    def __init__(self):
+        collections = defaultdict(FixtureCollection)
+
+        class Database:
+            def __getattr__(self, name):
+                return collections[name]
+
+        self.db = Database()
+        self._settings_lock = threading.RLock()
+        self._settings_cached = False
+        self._settings_document = None
+
+    def write(self, collection, operation, *args, **kwargs):
+        return getattr(collection, operation)(*args, **kwargs)
+
+    def assert_writable(self, **_kwargs):
+        return None
diff --git a/tests/support/mongo_fixtures.py b/tests/support/mongo_fixtures.py
new file mode 100644
index 00000000..497f2757
--- /dev/null
+++ b/tests/support/mongo_fixtures.py
@@ -0,0 +1,224 @@
+"""Explicit, isolated MongoDB doubles for settings and application unit tests."""
+
+from __future__ import annotations
+
+import copy
+import re
+import threading
+from types import SimpleNamespace
+
+from pymongo import DeleteOne, ReplaceOne, UpdateOne
+from pymongo.errors import DuplicateKeyError
+
+
+def _value(document, key):
+    for part in key.split("."):
+        if not isinstance(document, dict) or part not in document:
+            return None
+        document = document[part]
+    return document
+
+
+def _matches(document, query):
+    for key, expected in query.items():
+        if key == "$or":
+            if not any(_matches(document, item) for item in expected):
+                return False
+            continue
+        if key == "$and":
+            if not all(_matches(document, item) for item in expected):
+                return False
+            continue
+        actual = _value(document, key)
+        if isinstance(expected, dict):
+            for operator, value in expected.items():
+                if operator == "$in" and actual not in value:
+                    return False
+                if operator == "$nin" and actual in value:
+                    return False
+                if operator == "$ne" and actual == value:
+                    return False
+                if operator == "$exists" and (actual is not None) != value:
+                    return False
+                if operator == "$gt" and not (actual is not None and actual > value):
+                    return False
+                if operator == "$gte" and not (actual is not None and actual >= value):
+                    return False
+                if operator == "$lt" and not (actual is not None and actual < value):
+                    return False
+                if operator == "$lte" and not (actual is not None and actual <= value):
+                    return False
+                if operator == "$regex" and not re.search(value, str(actual or "")):
+                    return False
+        elif actual != expected:
+            return False
+    return True
+
+
+class Cursor(list):
+    def sort(self, fields, direction=None):
+        if isinstance(fields, str):
+            fields = [(fields, direction)]
+        for key, direction in reversed(fields):
+            super().sort(key=lambda row: _value(row, key), reverse=direction < 0)
+        return self
+
+    def limit(self, count):
+        return Cursor(self[:count])
+
+    def batch_size(self, _count):
+        return self
+
+
+class Collection:
+    def __init__(self):
+        self.rows = []
+
+    def find(self, query=None, **_kwargs):
+        return Cursor(copy.deepcopy([r for r in self.rows if _matches(r, query or {})]))
+
+    def find_one(self, query=None, *, sort=None, **_kwargs):
+        rows = self.find(query)
+        if sort:
+            rows.sort(sort)
+        return next(iter(rows), None)
+
+    def count_documents(self, query, **_kwargs):
+        return len(self.find(query))
+
+    def create_index(self, *_args, **_kwargs):
+        return "synthetic-index"
+
+    def insert_one(self, document, **_kwargs):
+        if self.find_one({"_id": document["_id"]}) is not None:
+            raise DuplicateKeyError("Synthetic duplicate document")
+        self.rows.append(copy.deepcopy(document))
+        return SimpleNamespace(inserted_id=document["_id"])
+
+    def insert_many(self, documents, **kwargs):
+        for document in documents:
+            self.insert_one(document, **kwargs)
+
+    def replace_one(self, query, document, *, upsert=False, **_kwargs):
+        document = copy.deepcopy(document)
+        if "_id" not in document and "_id" in query:
+            document["_id"] = query["_id"]
+        for index, current in enumerate(self.rows):
+            if _matches(current, query):
+                self.rows[index] = copy.deepcopy(document)
+                return SimpleNamespace(matched_count=1)
+        if upsert:
+            self.insert_one(document)
+        return SimpleNamespace(matched_count=0)
+
+    def delete_many(self, query, **_kwargs):
+        before = len(self.rows)
+        self.rows[:] = [row for row in self.rows if not _matches(row, query)]
+        return SimpleNamespace(deleted_count=before - len(self.rows))
+
+    def delete_one(self, query, **_kwargs):
+        row = next((r for r in self.rows if _matches(r, query)), None)
+        if row is not None:
+            self.rows.remove(row)
+        return SimpleNamespace(deleted_count=int(row is not None))
+
+    def update_many(self, query, update, **_kwargs):
+        count = 0
+        for row in self.rows:
+            if _matches(row, query):
+                row.update(copy.deepcopy(update.get("$set", {})))
+                count += 1
+        return SimpleNamespace(matched_count=count)
+
+    def update_one(self, query, update, *, upsert=False, **_kwargs):
+        row = self.find_one(query)
+        created = row is None
+        if row is None:
+            if not upsert:
+                return SimpleNamespace(matched_count=0)
+            row = copy.deepcopy(query)
+        if created:
+            row.update(copy.deepcopy(update.get("$setOnInsert", {})))
+        row.update(copy.deepcopy(update.get("$set", {})))
+        for field, value in update.get("$max", {}).items():
+            row[field] = max(row.get(field, value), value)
+        return self.replace_one(query, row, upsert=upsert)
+
+    def bulk_write(self, requests, **_kwargs):
+        for request in requests:
+            if isinstance(request, ReplaceOne):
+                self.replace_one(request._filter, request._doc, upsert=request._upsert)
+            elif isinstance(request, DeleteOne):
+                self.delete_one(request._filter)
+            elif isinstance(request, UpdateOne):
+                row = self.find_one(request._filter)
+                if row is not None:
+                    row.update(request._doc.get("$set", {}))
+                    self.replace_one(request._filter, row)
+            else:
+                raise AssertionError("Unsupported synthetic database operation")
+
+
+class Database:
+    def __init__(self):
+        self.collections = {}
+
+    def __getitem__(self, name):
+        return self.collections.setdefault(name, Collection())
+
+    def __getattr__(self, name):
+        return self[name]
+
+
+class FakeMongoBackend:
+    def __init__(self):
+        self.db = Database()
+        self._settings_lock = threading.RLock()
+        self._settings_cached = False
+        self._settings_document = None
+
+    def ping(self):
+        pass
+
+    def fence(self, _session):
+        pass
+
+    def check_owner(self):
+        pass
+
+    def write(self, collection, method, *args, **kwargs):
+        return getattr(collection, method)(*args, **kwargs)
+
+    def transaction(self, operation):
+        before = {
+            name: copy.deepcopy(value.rows)
+            for name, value in self.db.collections.items()
+        }
+        try:
+            return operation(object())
+        except BaseException:
+            for name, collection in self.db.collections.items():
+                collection.rows = before.get(name, [])
+            raise
+
+
+def register_test_backend(monkeypatch, settings_or_directory, backend=None):
+    """Opt a fixture into a fake backend without changing production selection."""
+    from tgdrive.storage import mongo
+
+    directory = getattr(
+        settings_or_directory, "resolved_data_dir", settings_or_directory
+    )
+    backend = backend or FakeMongoBackend()
+    monkeypatch.setitem(mongo._directories, directory.resolve(), backend)
+
+    def configured(data_dir, _uri, _database="tgdrive"):
+        result = mongo.for_directory(data_dir)
+        if result is None:
+            raise AssertionError(
+                "Register an isolated MongoDB backend for this fixture"
+            )
+        return result
+
+    monkeypatch.setattr(mongo, "configure", configured)
+    return backend
diff --git a/tests/support/recovery_fixtures.py b/tests/support/recovery_fixtures.py
new file mode 100644
index 00000000..ef8dca4a
--- /dev/null
+++ b/tests/support/recovery_fixtures.py
@@ -0,0 +1,21 @@
+"""Synthetic deployment settings shared by supported channel recovery tests."""
+
+from pathlib import Path
+
+from tgdrive.core.config import Settings
+
+
+def settings(tmp_path: Path) -> Settings:
+    return Settings(
+        _env_file=None,
+        MONGODB_URI="mongodb://synthetic.invalid",
+        API_ID=12345,
+        API_HASH="a" * 32,
+        BOT_TOKENS="123456:" + "x" * 30,
+        STORAGE_CHANNEL=-1001234567890,
+        ADMIN_PASSWORD="correct horse battery staple",
+        SESSION_SECRET="s" * 48,
+        DATA_DIR=tmp_path / "data",
+        CACHE_DIR=tmp_path / "cache",
+        COOKIE_SECURE=False,
+    )
diff --git a/tests/support/showcase_data.py b/tests/support/showcase_data.py
new file mode 100644
index 00000000..13c4918f
--- /dev/null
+++ b/tests/support/showcase_data.py
@@ -0,0 +1,380 @@
+"""Opt-in local UI showcase; never imported by the production application.
+
+TGDRIVE_UI_SHOWCASE=1 adds synthetic content only to the offline browser fixture.
+Sample metrics are explicitly labelled. File/cache/share/trash actions use their
+real stores; illustrative historical resource values never enter production.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import math
+import time
+import zipfile
+from collections import deque
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from fastapi.responses import JSONResponse
+
+from tgdrive.media.media_reader import BLOCK
+from tgdrive.transfers.tasks import TransferStatus
+from tgdrive.web.share_links import token_factory
+
+
+async def seed(runtime, settings):
+    folder = runtime.store.create_folder("/", "Demo workspace")
+    destination = "/" + folder["id"]
+    cache = runtime.preloads.cache
+    for index, (name, blocks) in enumerate(
+        [
+            ("Project reference.bin", (0, 1, 2)),
+            ("Design assets.bin", (0, 2)),
+            ("Interview recording.bin", (0,)),
+            ("Product demo.bin", (1, 2)),
+        ],
+        400,
+    ):
+        size = 3 * BLOCK
+        runtime.payloads[index] = b"x" * size
+        item = runtime.store.add_file(destination, name, index, size)
+        file_path = destination + "/" + item["id"]
+        if index in (400, 401):
+            runtime.store.create_share(
+                file_path,
+                label="Project review" if index == 400 else "Design handoff",
+                expires_at=(
+                    datetime.now(UTC) + timedelta(days=7 if index == 400 else 30)
+                ).isoformat(),
+                token_factory=token_factory(settings),
+            )
+        cache.register_file(
+            channel_id=settings.storage_channel, message_id=index, size=size, name=name
+        )
+        for block in blocks:
+            key = (
+                settings.storage_channel,
+                index,
+                "document",
+                index + 100,
+                size,
+                block,
+            )
+            await cache.get(key, BLOCK, lambda: asyncio.sleep(0, result=b"x" * BLOCK))
+    await cache.flush()
+    runtime.payloads[490] = b"Demo item: restore this from Trash."
+    discarded = runtime.store.add_file(
+        destination, "Old proposal.txt", 490, len(runtime.payloads[490])
+    )
+    runtime.store.set_trashed(destination + "/" + discarded["id"], True)
+    registry = runtime.transfers.registry
+    names = [
+        "Product walkthrough.mp4",
+        "Design assets.zip",
+        "Research notes.pdf",
+        "Project backup.zip",
+        "Team photos.zip",
+        "Release checklist.txt",
+    ]
+    now = time.time()
+    for index in range(64):
+        state = [
+            TransferStatus.COMPLETED,
+            TransferStatus.COMPLETED,
+            TransferStatus.ERROR,
+            TransferStatus.CANCELLED,
+        ][index % 4]
+        size = (index % 8 + 1) * 12 * 1024**2
+        job = await registry.create("completed", total=size)
+        job.created_at = now - 900 - index * 420
+        job.context.update(
+            kind="upload",
+            source_kind="remote" if index % 3 == 0 else "upload",
+            name=f"{index + 1:02d} - {names[index % len(names)]}",
+            destination=destination,
+        )
+        job.context["showcase"] = True
+        if state == TransferStatus.COMPLETED:
+            name = job.context["name"]
+            if name.endswith(".mp4"):
+                content = (
+                    Path(__file__).resolve().parents[1]
+                    / "fixtures/movtext-subtitles.mp4"
+                ).read_bytes()
+            elif name.endswith(".pdf"):
+                content = runtime.payloads[113]
+            elif name.endswith(".zip"):
+                output = io.BytesIO()
+                with zipfile.ZipFile(output, "w") as archive:
+                    archive.writestr("Read me.txt", "TGDrive local demo archive.")
+                content = output.getvalue()
+            else:
+                content = b"TGDrive local demo checklist.\n"
+            identity = 600 + index
+            runtime.payloads[identity] = content
+            size = len(content)
+            runtime.store.add_file(
+                destination, name, identity, size, operation_id=job.id
+            )
+        job.finished_at = job.created_at + 65
+        (
+            await registry.update(
+                job.id,
+                total=size,
+                status=state,
+                phase=state.value,
+                current=size if state == TransferStatus.COMPLETED else size // 3,
+                error="Demo: Telegram connection interrupted. Retry is available."
+                if state == TransferStatus.ERROR
+                else None,
+            )
+        )
+    demo_jobs = []
+    pending = deque()
+    for index, phase in enumerate(["uploading", "downloading", "queued", "queued"]):
+        job = await registry.create(phase, total=(index + 1) * 256 * 1024**2)
+        job.context.update(
+            kind="upload",
+            source_kind="remote" if phase == "downloading" else "upload",
+            name=names[index],
+            destination=destination,
+            showcase_active=True,
+        )
+        demo_jobs.append(job.id)
+        if phase == "queued":
+            pending.append(job.id)
+        (
+            await registry.update(
+                job.id,
+                status=TransferStatus.QUEUED
+                if phase == "queued"
+                else TransferStatus.RUNNING,
+                current=0 if phase == "queued" else job.total // (index + 3),
+                phase=phase,
+            )
+        )
+    runtime.showcase = True
+
+    async def animate_transfers():
+        tick = 0
+        while True:
+            await asyncio.sleep(2)
+            tick += 1
+            (await advance_transfers(registry, demo_jobs, pending, tick))
+
+    runtime.showcase_task = asyncio.create_task(animate_transfers())
+
+
+async def advance_transfers(registry, identities, pending, tick):
+    """Cycle the four illustrative rows without accumulating fake history.
+
+    Each completed stage advances or gives its slot to the oldest queued sample.
+    Only explicitly seeded rows are touched; actual uploads and cancelled samples
+    retain the normal registry lifecycle. API speed/ETA use the registry's ordinary
+    measured-byte samples, rather than invented response fields.
+    """
+    jobs = {job.id: job for job in registry.list() if job.id in identities}
+    for index, identity in enumerate(identities):
+        job = jobs.get(identity)
+        if (
+            job is None
+            or not job.context.get("showcase_active")
+            or job.status != TransferStatus.RUNNING
+            or job.task is not None
+        ):
+            continue
+        if job.phase == "finalizing":
+            (
+                await registry.update(
+                    job.id, status=TransferStatus.QUEUED, phase="queued", current=0
+                )
+            )
+            pending.append(job.id)
+            continue
+        step = int((1.7 + 0.6 * math.sin(tick / 4 + index)) * 2 * 1024**2)
+        current = min(job.total, job.current + step)
+        if current == job.total and job.phase == "downloading":
+            (await registry.update(job.id, phase="uploading", current=0))
+        elif current == job.total:
+            (await registry.update(job.id, phase="finalizing", current=current))
+        else:
+            (await registry.update(job.id, current=current))
+    slots = 2 - sum(job.status == TransferStatus.RUNNING for job in jobs.values())
+    while pending and slots > 0:
+        job = jobs.get(pending.popleft())
+        if job is None or job.status != TransferStatus.QUEUED:
+            continue
+        (
+            await registry.update(
+                job.id,
+                status=TransferStatus.RUNNING,
+                phase="downloading"
+                if job.context.get("source_kind") == "remote"
+                else "uploading",
+                current=0,
+            )
+        )
+        slots -= 1
+
+
+def samples(start, end, count=100):
+    result = []
+    for i in range(count):
+        at = start + (end - start) * i / max(1, count - 1)
+        wave = 0.5 + 0.5 * math.sin(i / 7)
+        result.append(
+            dict(
+                at=at,
+                cpu_percent=12 + wave * 36,
+                cpu_scope="cgroup",
+                memory_bytes=int((1.3 + wave * 0.7) * 1024**3),
+                memory_limit_bytes=4 * 1024**3,
+                received_bytes_per_second=int((1 + wave * 6) * 1024**2),
+                sent_bytes_per_second=int((0.5 + (1 - wave) * 3) * 1024**2),
+                network_interface="demo0",
+            )
+        )
+    return result
+
+
+def install(app, runtime):
+    @app.middleware("http")
+    async def showcase(request, call_next):
+        response = await call_next(request)
+        if not getattr(runtime, "showcase", False) or response.status_code != 200:
+            return response
+        path = request.url.path
+        if path not in {
+            "/api/config",
+            "/api/v1/performance",
+            "/api/v1/performance/history",
+        }:
+            return response
+        body = b"".join([chunk async for chunk in response.body_iterator])
+        value = json.loads(body)
+        now = time.time()
+        if path == "/api/config":
+            value["demo_data"] = True
+        elif path.endswith("/history"):
+            start, end = (
+                float(request.query_params["start"]),
+                float(request.query_params["end"]),
+            )
+            value.update(
+                samples=samples(start, end),
+                earliest_at=now - 31 * 86400,
+                tracked_since=now - 31 * 86400,
+                available=True,
+                totals=dict(
+                    network_received_bytes=154 * 1024**3,
+                    network_sent_bytes=92 * 1024**3,
+                    http_upload_bytes=36 * 1024**3,
+                    http_download_bytes=58 * 1024**3,
+                    telegram_upload_bytes=31 * 1024**3,
+                    telegram_download_bytes=40 * 1024**3,
+                    http_requests=8421,
+                    http_errors=8,
+                ),
+            )
+        else:
+            rows = samples(now - 297, now)
+            value["server"].update(
+                history=rows,
+                cpu=dict(
+                    percent=rows[-1]["cpu_percent"], scope="cgroup", capacity_cores=4
+                ),
+            )
+            value["server"]["memory"].update(
+                cgroup_current=rows[-1]["memory_bytes"], cgroup_limit=4 * 1024**3
+            )
+            value["server"]["network"].update(
+                interface="demo0",
+                available=True,
+                received_bytes=154 * 1024**3,
+                sent_bytes=92 * 1024**3,
+                received_bytes_per_second=rows[-1]["received_bytes_per_second"],
+                sent_bytes_per_second=rows[-1]["sent_bytes_per_second"],
+            )
+            value["telegram"].update(
+                active=3,
+                queued=2,
+                accounts=[
+                    dict(
+                        name="Demo storage bot 1",
+                        kind="bot",
+                        uploads=1,
+                        downloads=1,
+                        combined_limit=3,
+                        cooldown_seconds=0,
+                        requests=dict(
+                            active=4,
+                            queued=1,
+                            configured_limit=8,
+                            effective_limit=8,
+                            configured_parts_per_second=48,
+                            effective_parts_per_second=32,
+                            floods=0,
+                            failed=0,
+                            completed=840,
+                            bytes=121 * 1024**2,
+                            upload_bytes=85 * 1024**2,
+                            download_bytes=36 * 1024**2,
+                        ),
+                    ),
+                    dict(
+                        name="Demo storage bot 2",
+                        kind="bot",
+                        uploads=1,
+                        downloads=0,
+                        combined_limit=3,
+                        cooldown_seconds=12,
+                        requests=dict(
+                            active=0,
+                            queued=1,
+                            configured_limit=8,
+                            effective_limit=4,
+                            configured_parts_per_second=48,
+                            effective_parts_per_second=16,
+                            floods=1,
+                            failed=0,
+                            completed=310,
+                            bytes=54 * 1024**2,
+                            upload_bytes=34 * 1024**2,
+                            download_bytes=20 * 1024**2,
+                        ),
+                    ),
+                ],
+                queue=[
+                    dict(
+                        request_id="demo-queue-1",
+                        position=1,
+                        operation="download",
+                        priority="demand",
+                        waiting_seconds=4,
+                        estimated_wait_seconds=8,
+                    ),
+                    dict(
+                        request_id="demo-queue-2",
+                        position=2,
+                        operation="download",
+                        priority="preload",
+                        waiting_seconds=12,
+                        estimated_wait_seconds=20,
+                    ),
+                ],
+                history=[
+                    dict(at=r["at"], active=1 + i % 4, queued=i % 3)
+                    for i, r in enumerate(rows)
+                ],
+            )
+            value["history_scope"] = (
+                "Illustrative demo activity; not measurements of this laptop."
+            )
+        headers = {
+            key: val
+            for key, val in response.headers.items()
+            if key.lower() not in {"content-length", "content-type"}
+        }
+        return JSONResponse(value, headers=headers)
diff --git a/tests/telegram/__init__.py b/tests/telegram/__init__.py
new file mode 100644
index 00000000..a273ed35
--- /dev/null
+++ b/tests/telegram/__init__.py
@@ -0,0 +1 @@
+"""TGDrive telegram tests."""
diff --git a/tests/telegram/test_bot_mode.py b/tests/telegram/test_bot_mode.py
new file mode 100644
index 00000000..1447b27a
--- /dev/null
+++ b/tests/telegram/test_bot_mode.py
@@ -0,0 +1,359 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.settings.bot_settings import BotUploadPreferences
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.bot_mode import BotMode
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, settings(tmp_path))
+
+
+def settings(tmp_path: Path) -> Settings:
+    return Settings(
+        _env_file=None,
+        MONGODB_URI="mongodb://synthetic.invalid",
+        API_ID=12345,
+        API_HASH="a" * 32,
+        BOT_TOKENS="123456:" + "x" * 30,
+        STORAGE_CHANNEL=-1001234567890,
+        ADMIN_PASSWORD="correct horse battery staple",
+        SESSION_SECRET="s" * 48,
+        TELEGRAM_ADMIN_IDS="1,2",
+        DATA_DIR=tmp_path / "data",
+        CACHE_DIR=tmp_path / "cache",
+    )
+
+
+class FakeBotClient:
+    def __init__(self) -> None:
+        self.deleted: list[int] = []
+
+    async def delete_messages(self, _channel: int, message_id: int) -> None:
+        self.deleted.append(message_id)
+
+
+class FakeLifecycleClient(FakeBotClient):
+    def __init__(self) -> None:
+        super().__init__()
+        self.handlers: list[tuple[object, int]] = []
+        self.starts = 0
+        self.stops = 0
+        self.is_connected = False
+
+    def register_bot(self, mode: object) -> None:
+        self.handlers.append((mode, 0))
+
+    async def start(self) -> None:
+        self.starts += 1
+        self.is_connected = True
+
+    async def stop(self) -> None:
+        self.stops += 1
+        self.is_connected = False
+
+
+class FakeMessage:
+    def __init__(
+        self,
+        user_id: int,
+        *,
+        text: str = "",
+        command: list[str] | None = None,
+        copied: Any | None = None,
+    ) -> None:
+        self.id = 1
+        self.from_user = SimpleNamespace(id=user_id)
+        self.text = text
+        self.command = command if command is not None else text.split()
+        self.copied = copied
+        self.replies: list[tuple[str, Any | None]] = []
+        self.status = SimpleNamespace(edit_text=_async_recorder())
+
+    async def reply_text(self, text: str, reply_markup: Any | None = None) -> Any:
+        self.replies.append((text, reply_markup))
+        return self.status
+
+    async def copy(self, _channel: int, **_kwargs: object) -> Any:
+        return self.copied
+
+
+def _async_recorder():
+    calls: list[object] = []
+
+    async def record(*args: object, **kwargs: object) -> None:
+        calls.append((args, kwargs))
+
+    record.calls = calls
+    return record
+
+
+def root_mode(**kwargs):
+    mode = BotMode(**kwargs)
+    mode.folder_settings.value = BotUploadPreferences(folder_path="/")
+    mode.folder_settings._loaded = True
+    return mode
+
+
+@pytest.mark.asyncio
+async def test_photo_upload_gets_fallback_name_and_metadata(tmp_path: Path) -> None:
+    store = DriveStore.create(tmp_path / "drive.json")
+    client = FakeBotClient()
+    mode = root_mode(client=client, settings=settings(tmp_path), store=store)
+    copied = SimpleNamespace(
+        id=55,
+        media=SimpleNamespace(value="photo"),
+        photo=SimpleNamespace(file_size=3),
+    )
+    message = FakeMessage(1, copied=copied)
+
+    await mode._file(client, message)
+
+    item = next(iter(store.list_directory("/").values()))
+    assert item["name"].startswith("photo-")
+    assert item["name"].endswith("-55.jpg")
+    assert message.replies[0][0].startswith("Saving")
+    assert message.status.edit_text.calls[-1][0][0].startswith("Uploaded")
+    assert client.deleted == []
+
+
+@pytest.mark.asyncio
+async def test_bot_upload_rolls_back_copy_when_metadata_fails(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    store = DriveStore.create(tmp_path / "drive.json")
+    client = FakeBotClient()
+    mode = root_mode(client=client, settings=settings(tmp_path), store=store)
+    copied = SimpleNamespace(
+        id=56,
+        media=SimpleNamespace(value="photo"),
+        photo=SimpleNamespace(file_size=3),
+    )
+    message = FakeMessage(1, copied=copied)
+
+    def fail(*_args: object, **_kwargs: object) -> None:
+        raise RuntimeError("disk full")
+
+    monkeypatch.setattr(store, "add_file", fail)
+    await mode._file(client, message)
+
+    assert client.deleted == [56]
+    assert message.status.edit_text.calls[-1][0][0].startswith("Upload failed")
+
+
+@pytest.mark.asyncio
+async def test_bot_mode_lifecycle_is_idempotent(tmp_path: Path) -> None:
+    store = DriveStore.create(tmp_path / "drive.json")
+    client = FakeLifecycleClient()
+    mode = root_mode(client=client, settings=settings(tmp_path), store=store)
+
+    await mode.start()
+    await mode.start()
+    assert client.starts == 1
+    assert len(client.handlers) == 1
+
+    await mode.stop()
+    await mode.stop()
+    assert client.stops == 1
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("asynchronous", [False, True])
+async def test_bot_import_guard_before_copy_and_after_copy_preserves_metadata(
+    tmp_path, asynchronous
+):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    client = FakeBotClient()
+    copied = SimpleNamespace(id=57, photo=SimpleNamespace(file_size=3))
+    checks = 0
+
+    def guard():
+        nonlocal checks
+        checks += 1
+        if checks == 2:
+            raise SettingsProblem("Connection restart required")
+
+    async def async_guard():
+        guard()
+
+    verified = []
+
+    async def verify_delete():
+        verified.append(True)
+
+    mode = root_mode(
+        client=client,
+        settings=settings(tmp_path),
+        store=store,
+        before_write=async_guard if asynchronous else guard,
+        before_delete=verify_delete,
+    )
+    try:
+        await mode._file(client, FakeMessage(1, copied=copied))
+        assert checks == 2 and verified == [True] and client.deleted == [57]
+        assert not store.list_directory("/")
+        assert mode.active_imports == 0
+    finally:
+        mode.close()
+        store.close()
+
+
+@pytest.mark.asyncio
+async def test_bot_rollback_does_not_delete_after_lineage_conflict(tmp_path):
+    from tgdrive.recovery.backup import RecoveryConflict
+
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    client = FakeBotClient()
+    copied = SimpleNamespace(id=58)  # Invalid media causes rollback.
+
+    async def verify_delete():
+        raise RecoveryConflict("Recovery required")
+
+    mode = root_mode(
+        client=client,
+        settings=settings(tmp_path),
+        store=store,
+        before_delete=verify_delete,
+    )
+    try:
+        await mode._file(client, FakeMessage(1, copied=copied))
+        assert client.deleted == []
+        assert not store.list_directory("/")
+        assert mode.active_imports == 0
+    finally:
+        mode.close()
+        store.close()
+
+
+@pytest.mark.asyncio
+async def test_bot_active_import_counter_covers_copy_and_cancellation(tmp_path):
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    client = FakeBotClient()
+    mode = root_mode(client=client, settings=settings(tmp_path), store=store)
+    entered = asyncio.Event()
+    message = FakeMessage(1)
+
+    async def copy(*_args, **_kwargs):
+        entered.set()
+        await asyncio.Event().wait()
+
+    message.copy = copy
+    task = asyncio.create_task(mode._file(client, message))
+    try:
+        await entered.wait()
+        assert mode.active_imports == 1
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert mode.active_imports == 0
+    finally:
+        mode.close()
+        store.close()
+
+
+@pytest.fixture
+def bot(tmp_path):
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    mode = root_mode(client=FakeBotClient(), settings=settings(tmp_path), store=store)
+    try:
+        yield mode
+    finally:
+        mode.close()
+        store.close()
+
+
+@pytest.mark.asyncio
+async def test_success_feedback_names_actual_file_when_a_duplicate_is_renamed(bot):
+    bot.store.add_file("/", "report.txt", 12, 3)
+    copied = SimpleNamespace(
+        id=59, document=SimpleNamespace(file_name="report.txt", file_size=3)
+    )
+    message = FakeMessage(1, copied=copied)
+    await bot._file(bot.client, message)
+    names = {item["name"] for item in bot.store.list_directory("/").values()}
+    actual = next(name for name in names if name != "report.txt")
+    assert actual in message.status.edit_text.calls[-1][0][0]
+    assert bot.active_imports == 0
+
+
+@pytest.mark.asyncio
+async def test_failed_success_message_edit_does_not_roll_back_committed_upload(bot):
+    copied = SimpleNamespace(id=60, photo=SimpleNamespace(file_size=3))
+    message = FakeMessage(1, copied=copied)
+
+    async def fail(*args, **kwargs):
+        raise RuntimeError("message cannot be edited")
+
+    message.status.edit_text = fail
+    await bot._file(bot.client, message)
+    assert len(bot.store.list_directory("/")) == 1
+    assert not bot.client.deleted
+    assert message.replies[-1][0].startswith("Uploaded")
+
+
+@pytest.mark.asyncio
+async def test_paused_upload_explains_how_to_resume_without_copying(bot):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    def guard():
+        raise SettingsProblem("Connection restart required")
+
+    bot.before_write = guard
+    message = FakeMessage(1)
+    await bot._file(bot.client, message)
+    assert "Connection restart required" in message.replies[-1][0]
+    assert "Open TGDrive" in message.replies[-1][0]
+    assert not bot.store.list_directory("/")
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("failure", ["flood", "protected", "backup"])
+async def test_copy_failures_give_specific_recovery_instructions(bot, failure):
+    from telethon.errors import ChatForwardsRestrictedError, FloodWaitError
+
+    from tgdrive.recovery.backup import BackupError
+
+    errors = {
+        "flood": (FloodWaitError(request=None, capture=15), "Wait 15 seconds"),
+        "protected": (ChatForwardsRestrictedError(request=None), "new attachment"),
+        "backup": (BackupError("synthetic backup failure"), "Storage & Backups"),
+    }
+    error, expected = errors[failure]
+    message = FakeMessage(1)
+
+    async def fail(*args, **kwargs):
+        raise error
+
+    message.copy = fail
+    await bot._file(bot.client, message)
+    assert expected in message.status.edit_text.calls[-1][0][0]
+    assert not bot.store.list_directory("/")
+    assert bot.active_imports == 0
+
+
+@pytest.mark.asyncio
+async def test_uncertain_rollback_asks_user_to_check_drive_before_resending(bot):
+    from tgdrive.recovery.backup import RecoveryConflict
+
+    async def block_delete():
+        raise RecoveryConflict("synthetic lineage mismatch")
+
+    bot.before_delete = block_delete
+    message = FakeMessage(1, copied=SimpleNamespace(id=61))  # No usable media.
+    await bot._file(bot.client, message)
+    feedback = message.status.edit_text.calls[-1][0][0]
+    assert "could not be confirmed" in feedback
+    assert "before sending this file again" in feedback
+    assert not bot.client.deleted
diff --git a/tests/telegram/test_bot_settings.py b/tests/telegram/test_bot_settings.py
new file mode 100644
index 00000000..1c4dbdc3
--- /dev/null
+++ b/tests/telegram/test_bot_settings.py
@@ -0,0 +1,280 @@
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+from fastapi.testclient import TestClient
+from pydantic import ValidationError
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tests.telegram.test_bot_mode import FakeBotClient, FakeMessage, settings
+from tgdrive.settings.bot_settings import (
+    DEFAULT_FOLDER_NAME,
+    SETTINGS_LOCATION,
+    BotSettings,
+    BotUploadPreferences,
+    get_bot_settings,
+)
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.bot_mode import BotMode
+from tgdrive.web.app import create_app
+
+
+@pytest.fixture
+def bot_setup(tmp_path, monkeypatch):
+    configured = settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    backend = register_test_backend(monkeypatch, configured)
+    runtime = SimpleNamespace(store=store, mongo=backend)
+    service = get_bot_settings(configured, runtime)
+    mode = BotMode(
+        client=FakeBotClient(),
+        settings=configured,
+        store=store,
+        folder_settings=service,
+    )
+    try:
+        yield service, mode, store
+    finally:
+        mode.close()
+        store.close()
+
+
+def file_message(user_id=1, identity=100):
+    return FakeMessage(
+        user_id,
+        copied=SimpleNamespace(
+            id=identity,
+            document=SimpleNamespace(file_name="forwarded.txt", file_size=3),
+        ),
+    )
+
+
+async def test_forwarding_creates_dedicated_default_once_for_all_admins(bot_setup):
+    service, bot, store = bot_setup
+    snapshot = await service.snapshot()
+    assert snapshot["folder_path"] is None and snapshot["available"]
+    assert snapshot["folder_label"] == "My Files / TGDriveBotModeFiles"
+    assert store.list_directory("/") == {}  # Viewing settings is read-only.
+    await asyncio.gather(
+        *(
+            bot._file(bot.client, file_message(user_id, identity=100 + user_id))
+            for user_id in (1, 2)
+        )
+    )
+    folders = list(store.list_directory("/").values())
+    assert len(folders) == 1 and folders[0]["name"] == DEFAULT_FOLDER_NAME
+    path = f"/{folders[0]['id']}"
+    assert len(store.list_directory(path)) == 2
+    assert (await service.snapshot())["folder_path"] == path
+    restarted = BotSettings(service.settings, service.runtime)
+    assert (await restarted.snapshot())["folder_path"] == path
+
+
+async def test_website_change_applies_to_next_import_without_restart(bot_setup):
+    service, bot, store = bot_setup
+    folder = store.create_folder("/", "Incoming")
+    path = f"/{folder['id']}"
+    await service.save(
+        BotUploadPreferences(folder_path=path, site_url="https://drive.example")
+    )
+    message = file_message()
+    await bot._file(bot.client, message)
+    assert len(store.list_directory(path)) == 1
+    assert "Incoming" in message.status.edit_text.calls[-1][0][0]
+    link_message = FakeMessage(2, text="/set_folder")
+    await bot._set_folder(bot.client, link_message)
+    text, buttons = link_message.replies[-1]
+    assert "https://drive.example" + SETTINGS_LOCATION in text
+    assert buttons[0][0].type.url == "https://drive.example" + SETTINGS_LOCATION
+    await service.save(BotUploadPreferences(folder_path="/"))
+    message = file_message(2, identity=102)
+    assert (await service.snapshot())[
+        "settings_url"
+    ] == "https://drive.example" + SETTINGS_LOCATION
+    await bot._file(bot.client, message)
+    assert any(item["type"] == "file" for item in store.list_directory("/").values())
+
+
+async def test_missing_destination_blocks_import_and_save_rejects_files_and_trash(
+    bot_setup,
+):
+    service, bot, store = bot_setup
+    folder = store.create_folder("/", "Inbox")
+    path = f"/{folder['id']}"
+    await service.save(BotUploadPreferences(folder_path=path))
+    store.set_trashed(path, True)
+    message = file_message()
+    await bot._file(bot.client, message)
+    assert "/set_folder" in message.replies[-1][0]
+    assert store.list_directory("/") == {}
+    assert not bot.client.deleted
+    assert not (await service.snapshot())["available"]
+    file = store.add_file("/", "not-a-folder", 888, 1)
+    for invalid in (path, f"/{file['id']}", "/missing"):
+        with pytest.raises(SettingsProblem):
+            await service.save(BotUploadPreferences(folder_path=invalid))
+    assert service.value.folder_path == path
+
+
+async def test_default_reuses_existing_folder_and_reset_restores_default(bot_setup):
+    service, _, store = bot_setup
+    folder = store.create_folder("/", DEFAULT_FOLDER_NAME)
+    custom = store.create_folder("/", "Custom")
+    await service.save(BotUploadPreferences(folder_path=f"/{custom['id']}"))
+    await service.save(BotUploadPreferences())
+    assert (await service.destination())[0] == f"/{folder['id']}"
+    store.rename(f"/{folder['id']}", "Renamed inbox")
+    assert (await service.destination())[1] == "My Files / Renamed inbox"
+    assert len(store.list_directory("/")) == 2
+
+
+async def test_folder_change_during_copy_keeps_inflight_file_in_its_original_folder(
+    bot_setup,
+):
+    service, bot, store = bot_setup
+    first = store.create_folder("/", "First")
+    second = store.create_folder("/", "Second")
+    first_path, second_path = f"/{first['id']}", f"/{second['id']}"
+    await service.save(BotUploadPreferences(folder_path=first_path))
+    message = file_message()
+    entered, resume = asyncio.Event(), asyncio.Event()
+
+    async def copy(*args, **kwargs):
+        entered.set()
+        await resume.wait()
+        return message.copied
+
+    message.copy = copy
+    task = asyncio.create_task(bot._file(bot.client, message))
+    try:
+        await entered.wait()
+        await service.save(BotUploadPreferences(folder_path=second_path))
+        resume.set()
+        await task
+        assert len(store.list_directory(first_path)) == 1
+        assert store.list_directory(second_path) == {}
+        await bot._file(bot.client, file_message(2, identity=120))
+        assert len(store.list_directory(second_path)) == 1
+    finally:
+        resume.set()
+        await task
+
+
+async def test_blocked_upload_does_not_create_default_folder(bot_setup):
+    _, bot, store = bot_setup
+
+    def block():
+        raise SettingsProblem("Drive protection needs attention")
+
+    bot.before_write = block
+    await bot._file(bot.client, file_message())
+    assert not store.list_directory("/")
+
+
+async def test_failed_write_does_not_apply_new_folder(bot_setup, monkeypatch):
+    service, _, _ = bot_setup
+    await service.save(BotUploadPreferences(folder_path="/"))
+
+    def fail(value):
+        raise OSError("synthetic write failure")
+
+    monkeypatch.setattr(service, "_write", fail)
+    with pytest.raises(SettingsProblem):
+        await service.save(BotUploadPreferences())
+    assert service.value.folder_path == "/"
+    assert (await BotSettings(service.settings, service.runtime).snapshot())[
+        "folder_path"
+    ] == "/"
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "javascript:alert(1)",
+        "https://user:secret@example.com",
+        "https://example.com/?auth=secret",
+        "https://example.com/#share",
+        "not a url",
+    ],
+)
+def test_settings_links_reject_credentials_tokens_and_non_web_urls(url):
+    with pytest.raises(ValidationError):
+        BotUploadPreferences(site_url=url)
+
+
+async def test_configured_public_url_takes_precedence_over_a_local_browser_address(
+    bot_setup,
+):
+    service, _, _ = bot_setup
+    service.settings.public_url = "https://public.example"
+    await service.save(
+        BotUploadPreferences(folder_path="/", site_url="http://localhost:8000")
+    )
+    assert (await service.snapshot())[
+        "settings_url"
+    ] == "https://public.example" + SETTINGS_LOCATION
+
+
+async def test_mongodb_preferences_survive_service_restart(bot_setup):
+    service, _, store = bot_setup
+
+    class Collection:
+        document = None
+
+        def find_one(self, query):
+            assert query == {"_id": "bot-preferences"}
+            return self.document
+
+        def replace_one(self, query, document, **kwargs):
+            self.document = document
+
+    collection = Collection()
+    backend = SimpleNamespace(db=SimpleNamespace(settings=collection))
+    backend.write = lambda target, method, *args, **kwargs: getattr(target, method)(
+        *args, **kwargs
+    )
+    runtime = SimpleNamespace(store=store, mongo=backend)
+    service = BotSettings(service.settings, runtime)
+    await service.save(
+        BotUploadPreferences(folder_path="/", site_url="https://drive.example")
+    )
+    assert (await BotSettings(service.settings, runtime).snapshot())[
+        "settings_url"
+    ] == "https://drive.example" + SETTINGS_LOCATION
+
+
+def test_bot_settings_owner_api_validates_and_persists(tmp_path, monkeypatch):
+    configured = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, configured)
+    app = create_app(configured, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            url = "/api/v1/settings/bot-mode"
+            assert client.get(url).status_code == 401
+            assert client.patch(url, json={"folder_path": "/"}).status_code == 401
+            login(client)
+            response = client.get(url)
+            assert response.headers["Cache-Control"] == "no-store"
+            assert response.json()["folder_label"].endswith(DEFAULT_FOLDER_NAME)
+            assert store.list_directory("/") == {}
+            for value in (True, 123, "/../escape"):
+                assert client.patch(url, json={"folder_path": value}).status_code == 422
+            assert (
+                client.patch(url, json={"folder_path": "/missing"}).status_code == 409
+            )
+            response = client.patch(
+                url, json={"folder_path": "/", "site_url": "https://testserver"}
+            )
+            assert response.status_code == 200
+            assert response.json()["folder_label"] == "My Files"
+            assert (
+                client.get(url).json()["settings_url"]
+                == "https://testserver" + SETTINGS_LOCATION
+            )
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/telegram/test_checkpoint_transport.py b/tests/telegram/test_checkpoint_transport.py
new file mode 100644
index 00000000..f953ac71
--- /dev/null
+++ b/tests/telegram/test_checkpoint_transport.py
@@ -0,0 +1,111 @@
+"""Real Telethon request contracts for discoverable checkpoint transport."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon import functions, types
+
+from tgdrive.telegram.clients import Client
+
+CHANNEL = -1001234567890
+
+
+class CheckpointNative:
+    def __init__(self, pinned=42):
+        self.requests = []
+        self.pinned = pinned
+        self.get_input_entity = AsyncMock(
+            return_value=types.InputPeerChannel(channel_id=123, access_hash=456)
+        )
+        self.get_messages = AsyncMock(
+            return_value=SimpleNamespace(
+                id=77,
+                chat_id=CHANNEL,
+                sender_id=1,
+                raw_text="marker",
+                photo=None,
+                file=SimpleNamespace(size=3, name="checkpoint.json"),
+            )
+        )
+
+    async def __call__(self, request):
+        self.requests.append(request)
+        if isinstance(request, functions.channels.GetFullChannelRequest):
+            return SimpleNamespace(full_chat=SimpleNamespace(pinned_msg_id=self.pinned))
+        if isinstance(request, functions.messages.SendMediaRequest):
+            return SimpleNamespace(
+                updates=[types.UpdateMessageID(id=77, random_id=request.random_id)]
+            )
+        assert isinstance(request, functions.messages.UpdatePinnedMessageRequest)
+        return SimpleNamespace()
+
+
+def client_for(native):
+    client = Client.__new__(Client)
+    client.name = "checkpoint-test-bot"
+    client.native = native
+    client._upload_parts = AsyncMock(
+        return_value=types.InputFileBig(id=1, parts=1, name="checkpoint.json")
+    )
+    return client
+
+
+async def test_checkpoint_caption_reaches_raw_send_and_known_message_read(tmp_path):
+    native = CheckpointNative()
+    client = client_for(native)
+    path = tmp_path / "checkpoint.json"
+    path.write_bytes(b"{}\n")
+    caption = "TGDrive checkpoint v1\nDrive: portable-id\nRevision: 7"
+    sent = await client.send_document(
+        CHANNEL, path, caption=caption, file_name="checkpoint.json", random_id=987
+    )
+
+    assert sent.id == 77
+    (request,) = native.requests
+    assert isinstance(request, functions.messages.SendMediaRequest)
+    assert request.message == caption
+    assert request.random_id == 987
+    assert request.silent is True
+    native.get_messages.assert_awaited_once_with(CHANNEL, ids=77)
+
+
+@pytest.mark.parametrize("pinned", [None, 42])
+async def test_pin_discovery_uses_full_channel_without_history_or_search(pinned):
+    native = CheckpointNative(pinned)
+    client = client_for(native)
+
+    assert await client.get_pinned_message_id(CHANNEL) == pinned
+
+    (request,) = native.requests
+    assert isinstance(request, functions.channels.GetFullChannelRequest)
+    assert request.channel == types.InputChannel(channel_id=123, access_hash=456)
+    native.get_input_entity.assert_awaited_once_with(CHANNEL)
+    native.get_messages.assert_not_awaited()
+
+
+@pytest.mark.parametrize("pinned", [True, 0, -1, "42"])
+async def test_pin_discovery_rejects_malformed_message_identity(pinned):
+    with pytest.raises(RuntimeError, match="invalid pinned"):
+        await client_for(CheckpointNative(pinned)).get_pinned_message_id(CHANNEL)
+
+
+async def test_pin_uses_resolved_peer_and_silent_update_request():
+    native = CheckpointNative()
+    await client_for(native).pin_message(CHANNEL, 77)
+
+    (request,) = native.requests
+    assert isinstance(request, functions.messages.UpdatePinnedMessageRequest)
+    assert request.peer == types.InputPeerChannel(channel_id=123, access_hash=456)
+    assert request.id == 77
+    assert request.silent is True
+    native.get_input_entity.assert_awaited_once_with(CHANNEL)
+
+
+@pytest.mark.parametrize("message_id", [True, 0, -1, "77"])
+async def test_pin_rejects_invalid_id_before_telegram(message_id):
+    native = CheckpointNative()
+    with pytest.raises(ValueError, match="positive integer"):
+        await client_for(native).pin_message(CHANNEL, message_id)
+    assert native.requests == []
+    native.get_input_entity.assert_not_awaited()
diff --git a/tests/telegram/test_client_access_recovery.py b/tests/telegram/test_client_access_recovery.py
new file mode 100644
index 00000000..7df97107
--- /dev/null
+++ b/tests/telegram/test_client_access_recovery.py
@@ -0,0 +1,268 @@
+"""Revoked-account failures preserve bytes and only reassign safe operations."""
+
+import asyncio
+import json
+from dataclasses import asdict
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon.errors import (
+    AuthKeyUnregisteredError,
+    ChannelPrivateError,
+    SessionRevokedError,
+)
+
+from tests.media.test_pooled_media import account
+from tests.media.test_streaming import FakeStreamClient, make_request, response_body
+from tests.media.test_telegram_cache import Native
+from tests.support.mongo_fixtures import register_test_backend
+from tests.telegram.test_client_pool import FakeClient
+from tests.transfers.test_multipart_transfers import (
+    Account,
+    dispose,
+    manager_for,
+    staged,
+    stored,
+)
+from tgdrive.media.streaming import stream_telegram_file
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.connection_errors import TelegramConnectionError
+from tgdrive.transfers.multipart_transfer import fingerprint
+from tgdrive.transfers.tasks import TransferStatus
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path)
+
+
+@pytest.mark.parametrize("error_type", [AuthKeyUnregisteredError, SessionRevokedError])
+async def test_revoked_account_is_quarantined_and_errors_do_not_leak(error_type):
+    first, second = FakeClient("first"), FakeClient("second")
+    pool = ClientPool([first, second], allow_partial_start=True)
+    await pool.start()
+    try:
+        with pytest.raises(TelegramConnectionError) as caught:
+            async with pool.lease(client_name=first.name):
+                raise error_type(request="secret-token-request")
+        assert caught.value.code == "TELEGRAM_CREDENTIALS_REVOKED"
+        assert "Connections" in str(caught.value)
+        async with pool.lease() as healthy:
+            assert healthy is second
+        status = await pool.status()
+        assert not status[0].healthy and status[0].error
+        assert "secret-token-request" not in json.dumps([asdict(s) for s in status])
+        assert (await pool.health()).ready
+        assert all(s.active_leases == 0 for s in status)
+    finally:
+        await pool.stop()
+
+
+async def test_revocation_wakes_waiters_and_preserves_fixed_sender():
+    first = FakeClient("first")
+    pool = ClientPool([first])
+    await pool.start()
+
+    async def waiter():
+        async with pool.lease(media=True, client_name=first.name):
+            pytest.fail("a revoked sender must not be selected")
+
+    try:
+        with pytest.raises(TelegramConnectionError):
+            async with pool.lease(media=True, client_name=first.name):
+                waiting = asyncio.create_task(waiter())
+                await asyncio.sleep(0)
+                raise SessionRevokedError(request=None)
+        with pytest.raises(TelegramConnectionError):
+            await asyncio.wait_for(waiting, 1)
+        with pytest.raises(TelegramConnectionError, match="no longer configured"):
+            async with pool.lease(media=True, client_name="removed"):
+                pytest.fail("a removed sender must fail with a repair action")
+    finally:
+        await pool.stop()
+
+
+async def test_nested_lease_failure_does_not_disable_an_unrelated_account():
+    first, second = FakeClient("revoked"), FakeClient("healthy")
+    pool = ClientPool([first, second])
+    await pool.start()
+    try:
+        with pytest.raises(TelegramConnectionError):
+            async with (
+                pool.lease(client_name=second.name),
+                pool.lease(client_name=first.name),
+            ):
+                raise SessionRevokedError(request=None)
+        statuses = await pool.status()
+        assert not statuses[0].healthy
+        assert statuses[1].healthy
+    finally:
+        await pool.stop()
+
+
+async def test_verified_channel_repair_restores_access_but_not_revoked_sessions():
+    client = FakeClient("bot")
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        await pool.report_failure(client, ChannelPrivateError(request=None))
+        assert not (await pool.status())[0].healthy
+        await pool.restore_channel_access(client.name)
+        assert (await pool.status())[0].healthy
+        await pool.report_failure(client, SessionRevokedError(request=None))
+        await pool.restore_channel_access(client.name)
+        assert not (await pool.status())[0].healthy
+    finally:
+        await pool.stop()
+
+
+async def test_transient_network_failure_does_not_quarantine_account():
+    client = FakeClient("bot")
+    pool = ClientPool([client])
+    await pool.start()
+    try:
+        with pytest.raises(ConnectionError):
+            async with pool.lease():
+                raise ConnectionError("offline")
+        assert (await pool.status())[0].healthy
+    finally:
+        await pool.stop()
+
+
+async def test_revoked_storage_bot_metadata_falls_back_before_http_headers():
+    payload = b"original bytes"
+    first, second = FakeStreamClient(payload), FakeStreamClient(payload)
+    first.name, second.name = "revoked", "healthy"
+    first.get_messages = AsyncMock(side_effect=AuthKeyUnregisteredError(request=None))
+    pool = ClientPool([first, second])
+    await pool.start()
+    try:
+        response = await stream_telegram_file(
+            pool=pool,
+            channel_id=-100123,
+            message_id=7,
+            file_name="data.bin",
+            expected_size=len(payload),
+            request=make_request(),
+        )
+        assert await asyncio.wait_for(response_body(response), 2) == payload
+        assert not (await pool.status())[0].healthy
+        assert all(item.active_leases == 0 for item in await pool.status())
+    finally:
+        await pool.stop()
+
+
+@pytest.mark.parametrize("error_type", [SessionRevokedError, ChannelPrivateError])
+async def test_payload_recovers_using_another_account(error_type, monkeypatch):
+    class Removed(Native):
+        def iter_download(self, *args, **kwargs):
+            raise error_type(request="secret-request")
+
+    payload = b"original bytes"
+    bot = account("bot", payload)
+    premium = account("premium", payload, native_type=Removed)
+    pool = ClientPool([bot], [premium])
+    await pool.start()
+    lease = pool.lease
+    first_payload = True
+
+    def fault_first_payload(**kwargs):
+        nonlocal first_payload
+        if kwargs.get("download") and first_payload:
+            first_payload = False
+            kwargs["client_name"] = premium.name
+        return lease(**kwargs)
+
+    monkeypatch.setattr(pool, "lease", fault_first_payload)
+    try:
+        response = await stream_telegram_file(
+            pool=pool,
+            channel_id=-100123,
+            message_id=77,
+            file_name="data.bin",
+            expected_size=len(payload),
+            request=make_request(),
+        )
+        assert await asyncio.wait_for(response_body(response), 2) == payload
+        assert bot.native.requests
+        assert not (await pool.status())[1].healthy
+    finally:
+        await pool.stop()
+
+
+async def test_upload_reassigns_only_before_message_dispatch(tmp_path):
+    manager, ledger = await manager_for(tmp_path, users=True)
+    user = next(s.client for s in manager.pool._slots if s.kind == "user")
+    user.send_staged = AsyncMock(side_effect=SessionRevokedError(request=None))
+    payload = b"abcdef"
+    source = staged(manager, payload)
+    checksum, parts = fingerprint(
+        source, len(payload), manager.settings.bot_upload_limit
+    )
+    parts[0]["sender"] = user.name
+    record = await manager.registry.create("queued", total=len(payload))
+    record.context.update(
+        sha256=checksum,
+        multipart_plan=dict(version=1, kind="bot", parts=parts),
+    )
+    (await manager.registry.persist(record))
+    try:
+        await asyncio.wait_for(
+            manager._upload_path(record, source, "/", "data.bin", len(payload)), 2
+        )
+        assert record.status == TransferStatus.COMPLETED
+        user.send_staged.assert_awaited()
+        parts = stored(manager)["parts"]
+        assert (
+            b"".join(ledger.messages[p["message_id"]].content for p in parts) == payload
+        )
+        assert len(ledger.messages) == 2
+        assert all(
+            p["sender"] != "premium" for p in record.context["multipart_plan"]["parts"]
+        )
+        assert not (await manager.pool.status())[-1].healthy
+    finally:
+        await dispose(manager)
+
+
+async def test_post_dispatch_revocation_preserves_bytes_and_operation_identity(
+    tmp_path,
+):
+    manager, ledger = await manager_for(tmp_path)
+
+    class RevokedAfterSend(Account):
+        async def send_staged(self, *args, **kwargs):
+            await super().send_staged(*args, **kwargs)
+            raise SessionRevokedError(request=None)
+
+    await manager.pool.stop()
+    manager.pool = ClientPool([RevokedAfterSend("bot-one", ledger)])
+    await manager.pool.start()
+    source = staged(manager, b"abc")
+    record = await manager.enqueue_upload(source, "/", "data.bin", 3)
+    try:
+        await asyncio.wait_for(record.task, 2)
+        assert record.status == TransferStatus.ERROR
+        assert "Connections" in record.error
+        assert source.exists() and manager.store.list_directory("/") == {}
+        part = record.context["multipart_plan"]["parts"][0]
+        original = (part["sender"], part["random_id"])
+        assert part["send_started"] and len(ledger.messages) == 1
+        await manager.pool.stop()
+        manager.pool = ClientPool([Account("replacement-bot", ledger)])
+        await manager.pool.start()
+        (await manager.retry_job(record.id))
+        await asyncio.wait_for(record.task, 2)
+        assert record.status == TransferStatus.ERROR
+        assert "no longer configured" in record.error
+        assert source.exists() and len(ledger.messages) == 1
+        await manager.pool.stop()
+        manager.pool = ClientPool([Account("bot-one", ledger)])
+        await manager.pool.start()
+        (await manager.retry_job(record.id))
+        await asyncio.wait_for(record.task, 2)
+        assert record.status == TransferStatus.COMPLETED
+        assert (part["sender"], part["random_id"]) == original
+        assert len(ledger.messages) == 1
+    finally:
+        await dispose(manager)
diff --git a/tests/telegram/test_client_identity.py b/tests/telegram/test_client_identity.py
new file mode 100644
index 00000000..729d7796
--- /dev/null
+++ b/tests/telegram/test_client_identity.py
@@ -0,0 +1,210 @@
+"""Optional names are cached, nonblocking, retryable and separate from auth."""
+
+import asyncio
+import threading
+import time
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon.errors import FloodWaitError
+
+from tests.support.mongo_fixtures import register_test_backend
+from tests.telegram.test_telegram_clients import native_transport as native_transport
+from tests.telegram.test_telegram_clients import settings
+from tgdrive.telegram.client_identity import IdentityCache
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import Client
+
+pytestmark = pytest.mark.usefixtures("mongo_backend")
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, settings(tmp_path))
+
+
+def client_for(tmp_path, name="Drive Bot", username="drive_bot"):
+    config = settings(tmp_path)
+    client = Client(name="unused", settings=config, bot_token=config.bot_tokens[0])
+    client.native.me.first_name = name
+    client.native.me.username = username
+    client.native.get_me = AsyncMock(return_value=client.native.me)
+    return client
+
+
+async def settled(client):
+    await asyncio.wait_for(asyncio.shield(client._identity_task), 2)
+
+
+async def test_cache_loading_cannot_delay_authenticated_client_start(
+    tmp_path, monkeypatch
+):
+    client = client_for(tmp_path)
+    release = threading.Event()
+    entered = threading.Event()
+
+    def slow_cache(_account):
+        entered.set()
+        release.wait(3)
+        return None
+
+    monkeypatch.setattr(client._identity_cache, "read", slow_cache)
+    try:
+        await asyncio.wait_for(client.start(), 1)
+        assert client.is_connected
+        await asyncio.to_thread(entered.wait, 1)
+        assert client.identity_refreshing
+        release.set()
+        await settled(client)
+        assert client.display_name == "Drive Bot"
+        assert client.native.get_me.await_count == 1
+    finally:
+        release.set()
+        await client.stop()
+
+
+async def test_names_survive_recreation_refresh_and_status_polling_without_extra_calls(
+    tmp_path,
+):
+    first = client_for(tmp_path, "Original नाम")
+    await first.start()
+    await settled(first)
+    await first.stop()
+    second = client_for(tmp_path, "Changed नाम", "changed_bot")
+    pool = ClientPool([second])
+    try:
+        await pool.start()
+        await settled(second)
+        assert second.display_name == "Original नाम"
+        for _ in range(10):
+            status = (await pool.status())[0]
+            assert status.display_name == "Original नाम"
+            assert status.username == "drive_bot"
+            assert status.name == "storage-bot-123456"
+        assert second.native.get_me.await_count == 1
+        pool.refresh_identities()
+        pool.refresh_identities()
+        await settled(second)
+        assert second.display_name == "Changed नाम"
+        assert second.username == "changed_bot"
+        assert second.native.get_me.await_count == 2
+        cached = IdentityCache(settings(tmp_path).resolved_data_dir)
+        assert cached.read(second.name)["display_name"] == "Changed नाम"
+        assert not (
+            settings(tmp_path).resolved_data_dir / "client-identities.sqlite3"
+        ).exists()
+    finally:
+        await pool.stop()
+
+
+async def test_failed_name_lookup_retries_without_stopping_authenticated_client(
+    tmp_path,
+    monkeypatch,
+):
+    client = client_for(tmp_path, None, None)
+    good = SimpleNamespace(
+        id=123456, bot=True, first_name="Recovered", username="recovered_bot"
+    )
+    client.native.get_me.side_effect = [client.native.me, OSError("offline"), good]
+    waits = []
+
+    async def wait(delay):
+        waits.append(delay)
+
+    monkeypatch.setattr(client, "_wait_identity_retry", wait)
+    try:
+        await client.start()
+        await settled(client)
+        assert waits == [5, 10]
+        assert client.is_connected
+        assert client.display_name == "Recovered"
+        assert client.native.get_me.await_count == 3
+    finally:
+        await client.stop()
+
+
+async def test_refresh_floodwait_retains_name_and_full_account_cooldown(
+    tmp_path,
+    monkeypatch,
+):
+    client = client_for(tmp_path)
+    pool = ClientPool([client])
+    waiting = asyncio.Event()
+    observed = []
+
+    async def wait(delay):
+        observed.append(delay)
+        waiting.set()
+        await asyncio.Event().wait()
+
+    monkeypatch.setattr(client, "_wait_identity_retry", wait)
+    try:
+        await pool.start()
+        await settled(client)
+        client.native.get_me.side_effect = FloodWaitError(request=None, capture=3600)
+        pool.refresh_identities()
+        await asyncio.wait_for(waiting.wait(), 1)
+        assert observed[0] >= 3600.25
+        assert pool._account_cooldowns[client.name] > 0
+        assert client.display_name == "Drive Bot" and client.is_connected
+        pool.refresh_identities()
+        assert client.native.get_me.await_count == 2
+    finally:
+        await pool.stop()
+    assert not client.identity_refreshing
+
+
+async def test_broken_optional_cache_keeps_name_and_client_alive(tmp_path, monkeypatch):
+    client = client_for(tmp_path)
+    waiting = asyncio.Event()
+
+    def broken(*_args):
+        raise OSError("cache unavailable")
+
+    async def wait(_delay):
+        waiting.set()
+        await asyncio.Event().wait()
+
+    monkeypatch.setattr(client._identity_cache, "read", broken)
+    monkeypatch.setattr(client._identity_cache, "write", broken)
+    monkeypatch.setattr(client, "_wait_identity_retry", wait)
+    try:
+        await client.start()
+        await asyncio.wait_for(waiting.wait(), 1)
+        assert client.is_connected and client.display_name == "Drive Bot"
+        assert client.native.get_me.await_count == 1
+    finally:
+        await client.stop()
+
+
+async def test_persisted_name_floodwait_is_honored_after_recreation(
+    tmp_path, monkeypatch
+):
+    client = client_for(tmp_path)
+    cache = client._identity_cache
+    cache.write(client.name, {"display_name": "Cached Bot", "username": "cached_bot"})
+    deadline = time.time() + 3600
+    cache.defer(client.name, deadline)
+    waiting = asyncio.Event()
+    observed = []
+
+    async def wait(delay):
+        observed.append(delay)
+        waiting.set()
+        await asyncio.Event().wait()
+
+    monkeypatch.setattr(client, "_wait_identity_retry", wait)
+    pool = ClientPool([client])
+    try:
+        await pool.start()
+        await asyncio.wait_for(waiting.wait(), 1)
+        assert observed[0] > 3590
+        assert client.display_name == "Cached Bot"
+        assert client.identity_retry_at == deadline
+        assert pool._account_cooldowns[client.name] == deadline
+        assert client.native.get_me.await_count == 1  # Existing auth only.
+        pool.refresh_identities()
+        assert client.native.get_me.await_count == 1
+    finally:
+        await pool.stop()
diff --git a/tests/telegram/test_client_pool.py b/tests/telegram/test_client_pool.py
new file mode 100644
index 00000000..ba1ff52e
--- /dev/null
+++ b/tests/telegram/test_client_pool.py
@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import unittest
+from dataclasses import dataclass
+
+from tgdrive.telegram.client_pool import (
+    ClientPool,
+    ClientPoolStartError,
+    NoPremiumClientAvailable,
+    PoolState,
+)
+
+
+@dataclass
+class StartTracker:
+    active: int = 0
+    maximum: int = 0
+
+
+class FakeClient:
+    def __init__(
+        self,
+        name: str,
+        *,
+        fail_start: bool = False,
+        tracker: StartTracker | None = None,
+    ) -> None:
+        self.name = name
+        self.fail_start = fail_start
+        self.tracker = tracker
+        self.start_calls = 0
+        self.stop_calls = 0
+        self.is_connected = False
+
+    async def start(self) -> FakeClient:
+        self.start_calls += 1
+        if self.tracker is not None:
+            self.tracker.active += 1
+            self.tracker.maximum = max(self.tracker.maximum, self.tracker.active)
+        try:
+            await asyncio.sleep(0)
+            if self.fail_start:
+                raise RuntimeError("synthetic start failure")
+            self.is_connected = True
+            return self
+        finally:
+            if self.tracker is not None:
+                self.tracker.active -= 1
+
+    async def stop(self) -> None:
+        self.stop_calls += 1
+        self.is_connected = False
+        await asyncio.sleep(0)
+
+
+class ClientPoolTests(unittest.IsolatedAsyncioTestCase):
+    async def test_clients_and_async_factories_start_concurrently(self) -> None:
+        tracker = StartTracker()
+        first = FakeClient("first", tracker=tracker)
+        second = FakeClient("second", tracker=tracker)
+        factory_calls = 0
+
+        async def second_factory() -> FakeClient:
+            nonlocal factory_calls
+            factory_calls += 1
+            return second
+
+        pool = ClientPool([first, second_factory])
+        await pool.start()
+
+        self.assertEqual(factory_calls, 1)
+        self.assertEqual(tracker.maximum, 2)
+        self.assertEqual(pool.state, PoolState.RUNNING)
+        await pool.stop()
+
+    async def test_partial_start_failure_stops_every_materialized_client(self) -> None:
+        healthy = FakeClient("healthy")
+        broken = FakeClient("broken", fail_start=True)
+        pool = ClientPool([healthy, broken])
+
+        with self.assertRaises(ClientPoolStartError) as raised:
+            await pool.start()
+
+        self.assertEqual(pool.state, PoolState.FAILED)
+        self.assertEqual(healthy.stop_calls, 1)
+        self.assertEqual(broken.stop_calls, 1)
+        self.assertEqual(raised.exception.failures[0][0], "broken")
+
+        await pool.stop()
+        self.assertEqual(healthy.stop_calls, 1)
+        self.assertEqual(broken.stop_calls, 1)
+
+    async def test_leases_prefer_least_active_and_release_in_finally(self) -> None:
+        first = FakeClient("first")
+        second = FakeClient("second")
+        pool = ClientPool([first, second])
+        await pool.start()
+
+        with self.assertRaisesRegex(RuntimeError, "lease body"):
+            async with pool.lease() as first_lease, pool.lease() as second_lease:
+                self.assertIs(first_lease, first)
+                self.assertIs(second_lease, second)
+                raise RuntimeError("lease body failed")
+
+        status = await pool.status()
+        self.assertEqual([item.active_leases for item in status], [0, 0])
+        async with pool.lease() as next_lease:
+            self.assertIs(next_lease, first)
+        await pool.stop()
+
+    async def test_missing_premium_client_has_clear_error(self) -> None:
+        pool = ClientPool([FakeClient("bot")])
+        await pool.start()
+
+        with self.assertRaisesRegex(
+            NoPremiumClientAvailable,
+            "no premium user clients are configured",
+        ):
+            async with pool.lease(premium=True):
+                self.fail("lease should not be entered")
+        await pool.stop()
+
+    async def test_premium_lease_uses_user_clients_only(self) -> None:
+        bot = FakeClient("bot")
+        user = FakeClient("premium")
+        pool = ClientPool([bot], [user])
+        await pool.start()
+
+        async with pool.lease(premium_required=True) as leased:
+            self.assertIs(leased, user)
+        await pool.stop()
+
+    async def test_stop_drains_active_lease_and_is_idempotent(self) -> None:
+        client = FakeClient("bot")
+        pool = ClientPool([client])
+        await pool.start()
+        entered = asyncio.Event()
+        release = asyncio.Event()
+
+        async def hold_lease() -> None:
+            async with pool.lease():
+                entered.set()
+                await release.wait()
+
+        holder = asyncio.create_task(hold_lease())
+        await entered.wait()
+        stopping = asyncio.create_task(pool.stop())
+        await asyncio.sleep(0)
+
+        self.assertFalse(stopping.done())
+        self.assertEqual(client.stop_calls, 0)
+        release.set()
+        await holder
+        self.assertEqual(await stopping, ())
+        self.assertEqual(client.stop_calls, 1)
+        self.assertEqual(pool.state, PoolState.STOPPED)
+
+        self.assertEqual(await pool.stop(), ())
+        self.assertEqual(client.stop_calls, 1)
+
+    async def test_health_and_manual_health_marking(self) -> None:
+        bot = FakeClient("bot")
+        user = FakeClient("user")
+        pool = ClientPool([bot], [user])
+        await pool.start()
+
+        health = await pool.health()
+        self.assertTrue(health.ready)
+        self.assertEqual(health.bot_clients, 1)
+        self.assertEqual(health.premium_clients, 1)
+
+        await pool.mark_unhealthy(bot, RuntimeError("do not expose this detail"))
+        status = await pool.status()
+        self.assertFalse(status[0].healthy)
+        self.assertEqual(status[0].last_error_type, "RuntimeError")
+        self.assertNotIn("do not expose", repr(status[0]))
+        self.assertFalse((await pool.health()).ready)
+
+        await pool.mark_healthy(bot)
+        self.assertTrue((await pool.health()).ready)
+        await pool.stop()
+
+    async def test_preferred_premium_uses_healthy_user_before_less_busy_bot(
+        self,
+    ) -> None:
+        bot = FakeClient("bot")
+        first = FakeClient("premium-one")
+        second = FakeClient("premium-two")
+        pool = ClientPool([bot], [first, second])
+        await pool.start()
+
+        async with (
+            pool.lease(prefer_premium=True) as one,
+            pool.lease(prefer_premium=True) as two,
+        ):
+            self.assertIs(one, first)
+            self.assertIs(two, second)
+            self.assertEqual(pool.kind_of(one), "user")
+        self.assertEqual((await pool.health()).active_leases, 0)
+        await pool.stop()
+
+    async def test_preferred_premium_falls_back_for_missing_or_unhealthy_users(
+        self,
+    ) -> None:
+        bot = FakeClient("bot")
+        user = FakeClient("premium")
+        pool = ClientPool([bot], [user])
+        await pool.start()
+
+        await pool.mark_unhealthy(user, ConnectionError("unavailable"))
+        async with pool.lease(prefer_premium=True) as leased:
+            self.assertIs(leased, bot)
+        await pool.mark_healthy(user)
+        user.is_connected = False
+        async with pool.lease(prefer_premium=True) as leased:
+            self.assertIs(leased, bot)
+        self.assertEqual((await pool.health()).active_leases, 0)
+        await pool.stop()
+
+        pool = ClientPool([bot])
+        await pool.start()
+        async with pool.lease(prefer_premium=True) as leased:
+            self.assertIs(leased, bot)
+        await pool.stop()
+
+    async def test_preference_does_not_weaken_required_premium_lease(self) -> None:
+        pool = ClientPool([FakeClient("bot")])
+        await pool.start()
+        with self.assertRaises(NoPremiumClientAvailable):
+            async with pool.lease(premium=True, prefer_premium=True):
+                self.fail("a bot cannot satisfy a required user lease")
+        await pool.stop()
+
+    async def test_media_prefers_premium_then_falls_back_without_changing_sender(self):
+        bot, user = FakeClient("bot"), FakeClient("premium")
+        pool = ClientPool([bot], [user])
+        await pool.start()
+        try:
+            options = dict(media=True, allow_users=True, prefer_premium=True)
+            async with pool.lease(**options) as first:
+                self.assertIs(first, user)
+                async with pool.lease(**options) as second:
+                    self.assertIs(second, bot)
+            # A recorded bot sender wins even while Premium is available.
+            async with pool.lease(**options, client_name=bot.name) as fixed:
+                self.assertIs(fixed, bot)
+            await pool.defer_client(user.name, time.time() + 60)
+            async with pool.lease(**options) as cooling_fallback:
+                self.assertIs(cooling_fallback, bot)
+            self.assertEqual((await pool.health()).active_leases, 0)
+        finally:
+            await pool.stop()
+
+    async def test_partial_start_keeps_healthy_bot_and_cleans_failed_accounts(
+        self,
+    ) -> None:
+        bot = FakeClient("healthy-bot")
+        bad_bot = FakeClient("failed-bot", fail_start=True)
+        premium = FakeClient("failed-premium", fail_start=True)
+        pool = ClientPool([bot, bad_bot], [premium], allow_partial_start=True)
+        await pool.start()
+
+        self.assertEqual(pool.state, PoolState.RUNNING)
+        self.assertEqual(bot.stop_calls, 0)
+        self.assertEqual(bad_bot.stop_calls, 1)
+        self.assertEqual(premium.stop_calls, 1)
+        health = await pool.health()
+        self.assertTrue(health.ready)
+        self.assertEqual(health.healthy_clients, 1)
+        self.assertEqual(health.total_clients, 3)
+        async with pool.lease(prefer_premium=True) as leased:
+            self.assertIs(leased, bot)
+        await pool.stop()
+        self.assertEqual(bot.stop_calls, 1)
+        self.assertEqual(bad_bot.stop_calls, 1)
+        self.assertEqual(premium.stop_calls, 1)
+
+    async def test_partial_start_contains_invalid_optional_session_factory(
+        self,
+    ) -> None:
+        def invalid_session() -> FakeClient:
+            raise ValueError("synthetic malformed session")
+
+        pool = ClientPool(
+            [FakeClient("bot")], [invalid_session], allow_partial_start=True
+        )
+        await pool.start()
+        self.assertTrue((await pool.health()).ready)
+        status = await pool.status()
+        self.assertFalse(status[1].started)
+        self.assertEqual(status[1].last_error_type, "ValueError")
+        await pool.stop()
+
+    async def test_partial_start_fails_without_any_healthy_bot(self) -> None:
+        bot = FakeClient("failed-bot", fail_start=True)
+        user = FakeClient("healthy-user")
+        pool = ClientPool([bot], [user], allow_partial_start=True)
+
+        with self.assertRaises(ClientPoolStartError):
+            await pool.start()
+        self.assertEqual(pool.state, PoolState.FAILED)
+        self.assertEqual(bot.stop_calls, 1)
+        self.assertEqual(user.stop_calls, 1)
+        self.assertFalse((await pool.health()).ready)
+        await pool.stop()
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/telegram/test_premium_login.py b/tests/telegram/test_premium_login.py
new file mode 100644
index 00000000..6a7de276
--- /dev/null
+++ b/tests/telegram/test_premium_login.py
@@ -0,0 +1,479 @@
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from pydantic import SecretStr
+from telethon.errors import (
+    FloodWaitError,
+    PasswordHashInvalidError,
+    PhoneCodeInvalidError,
+    SessionPasswordNeededError,
+)
+
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.settings.premium_login import (
+    LOGIN_TTL,
+    PremiumLoginProblem,
+    PremiumLoginService,
+)
+from tgdrive.settings.premium_login_api import LoginStart, LoginVerify
+
+PHONE = "+919876543210"
+SESSION = "new-private-authorized-session"
+
+
+class LoginClient:
+    def __init__(self, *, two_factor=False, premium=True):
+        self.two_factor = two_factor
+        self.premium = premium
+        self.disconnected = False
+        self.logged_out = False
+        self.calls = []
+        self.send_failure = None
+        self.session = SimpleNamespace(save=lambda: SESSION)
+
+    async def connect(self):
+        return None
+
+    async def send_code_request(self, phone):
+        self.calls.append(("send", phone))
+        if self.send_failure:
+            raise self.send_failure
+        return SimpleNamespace(phone_code_hash="private-code-hash")
+
+    async def sign_in(self, **kwargs):
+        self.calls.append(("sign_in", kwargs))
+        if "password" in kwargs:
+            if kwargs["password"] != " correct password ":
+                raise PasswordHashInvalidError(request=None)
+        elif kwargs.get("code") != "12345":
+            raise PhoneCodeInvalidError(request=None)
+        elif self.two_factor:
+            raise SessionPasswordNeededError(request=None)
+
+    async def get_me(self):
+        return SimpleNamespace(bot=False, premium=self.premium)
+
+    async def log_out(self):
+        self.logged_out = True
+
+    async def disconnect(self):
+        self.disconnected = True
+
+
+def login_service(client=None, *, clock=None, saver=None):
+    client = client or LoginClient()
+    saved = saver or AsyncMock(return_value={"revision": 2, "restart_required": True})
+    service = PremiumLoginService(
+        lambda: (12345, SecretStr("a" * 32), 1),
+        saved,
+        client_factory=lambda _id, _hash: client,
+        **({"clock": clock} if clock else {}),
+    )
+    return service, client, saved
+
+
+async def begin(service, *, owner="owner", phone=PHONE):
+    return await service.begin(owner, 1, phone, "Personal account")
+
+
+@pytest.mark.asyncio
+async def test_success_saves_private_session_and_returns_only_redacted_settings():
+    service, client, save = login_service()
+    try:
+        challenge = await begin(service)
+        assert (
+            challenge["stage"] == "code"
+            and challenge["expires_in_seconds"] <= LOGIN_TTL
+        )
+        response = await service.verify(
+            "owner", challenge["challenge_id"], code="12345"
+        )
+        assert response == {
+            "stage": "complete",
+            "settings": {"revision": 2, "restart_required": True},
+        }
+        save.assert_awaited_once_with(1, "Personal account", SESSION)
+        assert SESSION not in str(response) and PHONE not in str(challenge)
+        assert client.disconnected and not client.logged_out
+        assert not service.challenges
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_two_step_password_is_conditional_and_whitespace_is_preserved():
+    service, client, save = login_service(LoginClient(two_factor=True))
+    try:
+        identity = (await begin(service))["challenge_id"]
+        response = await service.verify("owner", identity, code="12345")
+        assert response["stage"] == "password"
+        save.assert_not_awaited()
+        with pytest.raises(PremiumLoginProblem, match="password is incorrect"):
+            await service.verify("owner", identity, password="incorrect secret")
+        response = await service.verify(
+            "owner", identity, password=" correct password "
+        )
+        assert response["stage"] == "complete"
+        assert client.calls[-1] == ("sign_in", {"password": " correct password "})
+        assert "correct password" not in str(response)
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_wrong_owner_cannot_inspect_verify_or_cancel_another_login():
+    service, client, _ = login_service()
+    try:
+        identity = (await begin(service))["challenge_id"]
+        with pytest.raises(PremiumLoginProblem) as result:
+            await service.verify("other-owner", identity, code="12345")
+        assert result.value.status == 410
+        await service.cancel("other-owner", identity)
+        assert identity in service.challenges and not client.disconnected
+        await service.cancel("owner", identity)
+        assert identity not in service.challenges and client.disconnected
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_expired_challenge_disconnects_without_storing_authentication():
+    now = [100.0]
+    service, client, save = login_service(clock=lambda: now[0])
+    try:
+        identity = (await begin(service))["challenge_id"]
+        now[0] += LOGIN_TTL + 1
+        with pytest.raises(PremiumLoginProblem) as result:
+            await service.verify("owner", identity, code="12345")
+        assert result.value.status == 410 and client.disconnected
+        save.assert_not_awaited()
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_bad_codes_have_bounded_attempts_and_never_echo_code():
+    service, client, save = login_service()
+    try:
+        identity = (await begin(service))["challenge_id"]
+        for index in range(5):
+            with pytest.raises(PremiumLoginProblem) as result:
+                await service.verify("owner", identity, code="98765")
+            assert "98765" not in str(result.value)
+            assert result.value.status == (429 if index == 4 else 422)
+        assert not service.challenges and client.disconnected
+        save.assert_not_awaited()
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_non_premium_login_is_revoked_instead_of_saving_an_unusable_account():
+    service, client, save = login_service(LoginClient(premium=False))
+    try:
+        identity = (await begin(service))["challenge_id"]
+        with pytest.raises(PremiumLoginProblem, match="does not have Telegram Premium"):
+            await service.verify("owner", identity, code="12345")
+        assert client.logged_out and client.disconnected and not service.challenges
+        save.assert_not_awaited()
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_settings_conflict_after_authentication_revokes_new_session():
+    save = AsyncMock(
+        side_effect=SettingsProblem(
+            "Reload settings", code="SETTINGS_CONFLICT", status=409
+        )
+    )
+    service, client, _ = login_service(saver=save)
+    try:
+        identity = (await begin(service))["challenge_id"]
+        with pytest.raises(SettingsProblem):
+            await service.verify("owner", identity, code="12345")
+        assert client.logged_out and client.disconnected and not service.challenges
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_send_flood_wait_is_preserved_and_blocks_further_requests():
+    client = LoginClient()
+    client.send_failure = FloodWaitError(request=None, capture=123)
+    service, client, _ = login_service(client)
+    try:
+        with pytest.raises(PremiumLoginProblem) as result:
+            await begin(service)
+        assert result.value.status == 429 and result.value.retry_after == 123
+        assert client.disconnected and not service.challenges
+        with pytest.raises(PremiumLoginProblem) as waiting:
+            await begin(service, phone="+441234567890")
+        assert waiting.value.status == 429 and waiting.value.retry_after >= 122
+        assert len(client.calls) == 1
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_send_rate_capacity_and_revision_checks_do_not_start_extra_clients():
+    service, _, _ = login_service()
+    try:
+        await begin(service)
+        with pytest.raises(PremiumLoginProblem, match="Wait a minute"):
+            await begin(service)
+        await begin(service, phone="+441234567890")
+        with pytest.raises(PremiumLoginProblem, match="Finish or cancel"):
+            await begin(service, phone="+331234567890")
+        assert len(service.challenges) == 2
+    finally:
+        await service.close()
+    other, client, _ = login_service()
+    try:
+        with pytest.raises(PremiumLoginProblem) as conflict:
+            await other.begin("owner", 0, PHONE, "Personal")
+        assert conflict.value.code == "SETTINGS_CONFLICT" and client.calls == []
+    finally:
+        await other.close()
+
+
+@pytest.mark.asyncio
+async def test_concurrent_submission_cannot_save_or_revoke_a_saved_session_twice():
+    service, client, save = login_service()
+    try:
+        identity = (await begin(service))["challenge_id"]
+        results = await asyncio.gather(
+            service.verify("owner", identity, code="12345"),
+            service.verify("owner", identity, code="12345"),
+            return_exceptions=True,
+        )
+        assert sum(isinstance(value, dict) for value in results) == 1
+        save.assert_awaited_once()
+        assert not client.logged_out
+    finally:
+        await service.close()
+
+
+def test_authentication_payload_representations_hide_every_secret():
+    start = LoginStart(expected_revision=1, phone=PHONE, label="Personal")
+    verification = LoginVerify(
+        challenge_id="a" * 43, code="12345", password="private-password"
+    )
+    assert PHONE not in repr(start)
+    assert "12345" not in repr(verification) and "private-password" not in repr(
+        verification
+    )
+
+
+def test_http_login_requires_owner_same_origin_and_hides_validation_secrets(
+    tmp_path, monkeypatch
+):
+    from fastapi.testclient import TestClient
+
+    from tests.support.app_fixtures import FakeRuntime, make_settings
+    from tgdrive.storage.store import DriveStore
+    from tgdrive.web.app import create_app
+
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    app = create_app(settings, runtime=runtime)
+    service, transport, save = login_service()
+    app.state.premium_login_service = service
+    with TestClient(app, base_url="https://testserver") as client:
+        start_path = "/api/v1/settings/premium-login/start"
+        payload = {"expected_revision": 1, "phone": PHONE, "label": "Personal"}
+        assert client.post(start_path, json=payload).status_code == 401
+        assert (
+            client.post(
+                "/api/checkPassword",
+                json={
+                    "pass": settings.admin_password.get_secret_value(),
+                },
+            ).status_code
+            == 200
+        )
+        assert (
+            client.post(
+                start_path, json=payload, headers={"Origin": "https://evil.invalid"}
+            ).status_code
+            == 403
+        )
+        secret = "private-phone-secret-" * 5
+        invalid = client.post(start_path, json=payload | {"phone": secret})
+        assert invalid.status_code == 422 and secret not in invalid.text
+        response = client.post(start_path, json=payload)
+        assert response.status_code == 200
+        identity = response.json()["challenge_id"]
+        assert PHONE not in response.text
+        verified = client.post(
+            "/api/v1/settings/premium-login/verify",
+            json={
+                "challenge_id": identity,
+                "code": "12345",
+            },
+        )
+        assert verified.status_code == 200
+        assert verified.json()["stage"] == "complete"
+        assert SESSION not in verified.text and "12345" not in verified.text
+        save.assert_awaited_once()
+    assert transport.disconnected
+
+
+def test_new_owner_session_cannot_finish_previous_browser_login(tmp_path, monkeypatch):
+    from fastapi.testclient import TestClient
+
+    from tests.support.app_fixtures import FakeRuntime, make_settings
+    from tgdrive.storage.store import DriveStore
+    from tgdrive.web.app import create_app
+
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    app = create_app(settings, runtime=runtime)
+    service, transport, save = login_service()
+    app.state.premium_login_service = service
+    with TestClient(app, base_url="https://testserver") as client:
+        password = {"pass": settings.admin_password.get_secret_value()}
+        client.post("/api/checkPassword", json=password)
+        identity = client.post(
+            "/api/v1/settings/premium-login/start",
+            json={
+                "expected_revision": 1,
+                "phone": PHONE,
+                "label": "Personal",
+            },
+        ).json()["challenge_id"]
+        client.post("/api/logout", json={})
+        client.post("/api/checkPassword", json=password)
+        result = client.post(
+            "/api/v1/settings/premium-login/verify",
+            json={
+                "challenge_id": identity,
+                "code": "12345",
+            },
+        )
+        assert result.status_code == 410
+        save.assert_not_awaited()
+    assert transport.disconnected
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("committed", [True, False, None])
+async def test_ambiguous_save_never_revokes_committed_or_unreadable_private_session(
+    committed,
+):
+    service, client, _ = login_service(
+        saver=AsyncMock(
+            side_effect=OSError("failure after private settings replacement"),
+        )
+    )
+    service.is_session_saved = lambda value: committed if value == SESSION else False
+    try:
+        identity = (await begin(service))["challenge_id"]
+        with pytest.raises(PremiumLoginProblem):
+            await service.verify("owner", identity, code="12345")
+        assert client.disconnected
+        assert client.logged_out is (committed is False)
+        assert not service.challenges
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_lost_sign_in_confirmation_still_revokes_the_owned_new_authorization():
+    service, client, save = login_service()
+    client.sign_in = AsyncMock(side_effect=TimeoutError("server may have authorized"))
+    try:
+        identity = (await begin(service))["challenge_id"]
+        with pytest.raises(PremiumLoginProblem):
+            await service.verify("owner", identity, code="12345")
+        assert client.logged_out and client.disconnected
+        save.assert_not_awaited()
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_close_during_expired_reaper_logout_drains_disconnect_after_map_removal():
+    from contextlib import suppress
+
+    now = [100.0]
+    service, client, _ = login_service(clock=lambda: now[0])
+    await begin(service)
+    service._reaper.cancel()
+    with suppress(asyncio.CancelledError):
+        await service._reaper
+    entered, release = asyncio.Event(), asyncio.Event()
+
+    async def logout():
+        entered.set()
+        await release.wait()
+        client.logged_out = True
+
+    client.log_out = logout
+    now[0] += LOGIN_TTL + 1
+    service._reaper = asyncio.create_task(service._expire())
+    await entered.wait()
+    assert not service.challenges
+    closing = asyncio.create_task(service.close())
+    await asyncio.sleep(0)
+    assert not closing.done()
+    release.set()
+    await asyncio.wait_for(closing, 1)
+    assert client.logged_out and client.disconnected
+    assert not service._cleanups
+
+
+@pytest.mark.asyncio
+async def test_close_cancels_provider_verification_before_waiting_for_challenge_lock():
+    service, client, save = login_service()
+    identity = (await begin(service))["challenge_id"]
+    entered = asyncio.Event()
+
+    async def blocked_sign_in(**_kwargs):
+        entered.set()
+        await asyncio.Event().wait()
+
+    client.sign_in = blocked_sign_in
+    verifying = asyncio.create_task(service.verify("owner", identity, code="12345"))
+    await entered.wait()
+    await asyncio.wait_for(service.close(), 1)
+    assert verifying.cancelled()
+    assert client.logged_out and client.disconnected
+    assert not service.challenges and not service._operations and not service._cleanups
+    save.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_cancelled_http_cleanup_retains_ownership_until_disconnect():
+    service, client, _ = login_service()
+    identity = (await begin(service))["challenge_id"]
+    entered, release = asyncio.Event(), asyncio.Event()
+
+    async def logout():
+        entered.set()
+        await release.wait()
+        client.logged_out = True
+
+    client.log_out = logout
+    cancelling = asyncio.create_task(service.cancel("owner", identity))
+    try:
+        await entered.wait()
+        cancelling.cancel()
+        await asyncio.sleep(0)
+        cancelling.cancel()  # Repeated cancellation cannot abandon cleanup.
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(cancelling, 1)
+        assert client.logged_out and client.disconnected
+        assert not service.challenges and not service._cleanups
+    finally:
+        await service.close()
diff --git a/tests/telegram/test_telegram_clients.py b/tests/telegram/test_telegram_clients.py
new file mode 100644
index 00000000..56fbc03c
--- /dev/null
+++ b/tests/telegram/test_telegram_clients.py
@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any, ClassVar
+
+import pytest
+
+import tgdrive.telegram.clients as clients
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.telegram.connection_errors import TelegramConnectionError
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, settings(tmp_path))
+
+
+def settings(tmp_path: Path, **overrides: Any) -> Settings:
+    values: dict[str, Any] = {
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "API_ID": 12345,
+        "API_HASH": "a" * 32,
+        "BOT_TOKENS": "123456:" + "x" * 30 + ",654321:" + "y" * 30,
+        "STORAGE_CHANNEL": -1001234567890,
+        "ADMIN_PASSWORD": "correct horse battery staple",
+        "SESSION_SECRET": "s" * 48,
+        "STRING_SESSIONS": "session-A,session-B",
+        "DATA_DIR": tmp_path / "data",
+        "CACHE_DIR": tmp_path / "cache",
+    }
+    values.update(overrides)
+    return Settings(_env_file=None, **values)
+
+
+class NativeClient:
+    instances: ClassVar[list[NativeClient]] = []
+
+    def __init__(self, session: Any, api_id: int, api_hash: str, **options: Any):
+        self.options = options
+        self.connected = False
+        self.authorized = True
+        self.sign_ins: list[dict[str, str]] = []
+        if isinstance(session, str):
+            account_id = int(Path(session).name.rsplit("-", 1)[1])
+            path = Path(session + ".session")
+            path.write_bytes(b"synthetic session")
+            path.chmod(0o644)
+            self.session = SimpleNamespace(filename=str(path))
+            self.me = SimpleNamespace(id=account_id, bot=True, premium=False)
+        else:
+            self.session = session
+            self.me = SimpleNamespace(id=session.account_id, bot=False, premium=True)
+        self.instances.append(self)
+
+    def is_connected(self) -> bool:
+        return self.connected
+
+    async def connect(self) -> None:
+        self.connected = True
+
+    async def disconnect(self) -> None:
+        self.connected = False
+
+    async def is_user_authorized(self) -> bool:
+        return self.authorized
+
+    async def get_me(self) -> Any:
+        return self.me
+
+    async def sign_in(self, **kwargs: str) -> None:
+        assert set(kwargs) == {"bot_token"}
+        self.sign_ins.append(kwargs)
+        self.authorized = True
+
+    async def start(self, **_kwargs: Any) -> None:
+        raise AssertionError("Interactive TelegramClient.start must never be called")
+
+
+@pytest.fixture(autouse=True)
+def native_transport(monkeypatch: pytest.MonkeyPatch) -> None:
+    NativeClient.instances.clear()
+    monkeypatch.setattr(clients, "TelegramClient", NativeClient)
+    monkeypatch.setattr(
+        clients,
+        "StringSession",
+        lambda value: SimpleNamespace(
+            account_id={"session-A": 101, "session-B": 202}[value]
+        ),
+    )
+
+
+@pytest.mark.asyncio
+async def test_pool_identity_survives_credential_reordering(tmp_path: Path) -> None:
+    original = settings(tmp_path)
+    pool = clients.build_client_pool(original)
+    await pool.start()
+    names = {item.name for item in await pool.status()}
+    paths = {
+        item.session.filename
+        for item in NativeClient.instances
+        if hasattr(item.session, "filename")
+    }
+    assert names == {
+        "storage-bot-123456",
+        "storage-bot-654321",
+        "premium-user-101",
+        "premium-user-202",
+    }
+    assert all(
+        item.options["receive_updates"] is False for item in NativeClient.instances
+    )
+    assert all(
+        item.options["flood_sleep_threshold"] == 0 for item in NativeClient.instances
+    )
+    assert all(Path(path).stat().st_mode & 0o777 == 0o600 for path in paths)
+    await pool.stop()
+
+    NativeClient.instances.clear()
+    reordered = settings(
+        tmp_path,
+        BOT_TOKENS=",".join(reversed(original.bot_tokens)),
+        STRING_SESSIONS="session-B,session-A",
+    )
+    pool = clients.build_client_pool(reordered)
+    await pool.start()
+    assert {item.name for item in await pool.status()} == names
+    assert {
+        item.session.filename
+        for item in NativeClient.instances
+        if hasattr(item.session, "filename")
+    } == paths
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_rotated_bot_token_retains_the_account_session_path(
+    tmp_path: Path,
+) -> None:
+    first = clients.Client(
+        name="old-position", settings=settings(tmp_path), bot_token="123456:" + "x" * 30
+    )
+    second = clients.Client(
+        name="new-position", settings=settings(tmp_path), bot_token="123456:" + "z" * 30
+    )
+    assert first.name == second.name == "storage-bot-123456"
+    assert first.native.session.filename == second.native.session.filename
+    assert "x" * 30 not in first.native.session.filename
+
+
+@pytest.mark.asyncio
+async def test_bot_authorization_never_enters_interactive_login(tmp_path: Path) -> None:
+    token = "123456:" + "x" * 30
+    client = clients.Client(name="unused", settings=settings(tmp_path), bot_token=token)
+    client.native.authorized = False
+    await client.start()
+    assert client.native.sign_ins == [{"bot_token": token}]
+    assert client.is_connected
+    await client.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("wrong_id,is_bot", [(123, True), (123456, False)])
+async def test_wrong_authorized_account_fails_closed(
+    tmp_path: Path,
+    wrong_id: int,
+    is_bot: bool,
+) -> None:
+    client = clients.Client(
+        name="unused", settings=settings(tmp_path), bot_token="123456:" + "x" * 30
+    )
+    client.native.me = SimpleNamespace(id=wrong_id, bot=is_bot, premium=True)
+    with pytest.raises(RuntimeError, match="identity mismatch"):
+        await client.start()
+    assert not client.is_connected
+
+
+@pytest.mark.asyncio
+async def test_user_session_must_already_be_authorized(tmp_path: Path) -> None:
+    client = clients.Client(
+        name="unused", settings=settings(tmp_path), session_string="session-A"
+    )
+    client.native.authorized = False
+    with pytest.raises(
+        TelegramConnectionError, match="no longer authorized"
+    ) as captured:
+        await client.start()
+    assert captured.value.code == "TELEGRAM_CREDENTIALS_REVOKED"
+    assert not client.native.sign_ins
+    assert not client.is_connected
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("is_bot,premium", [(True, True), (False, False)])
+async def test_premium_session_capability_is_checked(
+    tmp_path: Path,
+    is_bot: bool,
+    premium: bool,
+) -> None:
+    client = clients.Client(
+        name="unused", settings=settings(tmp_path), session_string="session-A"
+    )
+    client.native.me = SimpleNamespace(id=101, bot=is_bot, premium=premium)
+    with pytest.raises(RuntimeError, match="not a Premium"):
+        await client.start()
+    assert not client.is_connected
+
+
+def test_optional_bot_mode_has_separate_update_session(tmp_path: Path) -> None:
+    assert clients.build_bot_mode_client(settings(tmp_path)) is None
+    value = settings(
+        tmp_path, MAIN_BOT_TOKEN="123456:" + "x" * 30, TELEGRAM_ADMIN_IDS="1"
+    )
+    client = clients.build_bot_mode_client(value)
+    assert client is not None
+    assert client.native.options["receive_updates"] is True
+    assert client.name == "bot-mode-123456"
+    assert Path(client.native.session.filename).name == "bot-mode-123456.session"
+
+
+@pytest.mark.asyncio
+async def test_main_bot_bootstraps_storage_with_a_separate_bot_mode_session(
+    tmp_path: Path,
+) -> None:
+    value = settings(
+        tmp_path,
+        BOT_TOKENS="",
+        STRING_SESSIONS="",
+        MAIN_BOT_TOKEN="123456:" + "x" * 30,
+        TELEGRAM_ADMIN_IDS="1",
+    )
+    pool = clients.build_client_pool(value)
+    bot = clients.build_bot_mode_client(value)
+    assert bot is not None
+    try:
+        await pool.start()
+        await bot.start()
+        assert {row.name for row in await pool.status()} == {"storage-bot-123456"}
+        assert bot.name == "bot-mode-123456"
+        assert {item.options["receive_updates"] for item in NativeClient.instances} == {
+            False,
+            True,
+        }
+        assert len({item.session.filename for item in NativeClient.instances}) == 2
+    finally:
+        await bot.stop()
+        await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_optional_session_failure_does_not_disable_working_storage_bots(
+    tmp_path: Path,
+) -> None:
+    pool = clients.build_client_pool(
+        settings(tmp_path, STRING_SESSIONS="synthetic-invalid-session")
+    )
+    await pool.start()
+    assert (await pool.health()).ready
+    assert (await pool.health()).healthy_clients == 2
+    async with pool.lease(prefer_premium=True) as client:
+        assert pool.kind_of(client) == "bot"
+    await pool.stop()
diff --git a/tests/telegram/test_telethon_transport.py b/tests/telegram/test_telethon_transport.py
new file mode 100644
index 00000000..d6e6be65
--- /dev/null
+++ b/tests/telegram/test_telethon_transport.py
@@ -0,0 +1,311 @@
+"""Offline contracts for the real Telethon request types used by the adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from telethon import functions, types
+from telethon.errors import (
+    FileReferenceExpiredError,
+    FileReferenceInvalidError,
+    FilerefUpgradeNeededError,
+)
+
+from tgdrive.telegram.clients import Client, TelegramMessage
+
+MIB = 1024**2
+CHANNEL = -1001234567890
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "text,media,handler",
+    [
+        ("/start", False, "_help"),
+        ("Help", False, "_help"),
+        ("Choose folder", False, "_set_folder"),
+        ("/set_folder@mybot Projects", False, "_set_folder"),
+        ("/folders", False, "_set_folder"),
+        ("Current folder", False, "_current_folder"),
+        ("/cancel", False, "_cancel"),
+        ("Projects", False, "_folder_query"),
+        ("   ", False, "_folder_query"),
+        ("Choose folder", True, "_file"),
+        ("Help", True, "_file"),
+    ],
+)
+async def test_bot_transport_routes_menu_commands_and_media_captions(
+    text, media, handler
+):
+    native = SimpleNamespace(add_event_handler=Mock())
+    client = transport_client(native)
+    handlers = {
+        name: AsyncMock()
+        for name in (
+            "_help",
+            "_set_folder",
+            "_current_folder",
+            "_cancel",
+            "_folder_query",
+            "_file",
+        )
+    }
+    mode = SimpleNamespace(
+        settings=SimpleNamespace(telegram_admin_ids=(1,)), **handlers
+    )
+    client.register_bot(mode)
+    dispatch = native.add_event_handler.call_args_list[0].args[0]
+    message = native_message()
+    message.raw_text = text
+    if not media:
+        message.file = None
+    event = SimpleNamespace(is_private=True, sender_id=1, message=message)
+    await dispatch(event)
+    handlers[handler].assert_awaited_once()
+    assert sum(item.await_count for item in handlers.values()) == 1
+
+    for private, sender in [(False, 1), (True, 999)]:
+        event.is_private, event.sender_id = private, sender
+        await dispatch(event)
+    assert sum(item.await_count for item in handlers.values()) == 1
+
+
+@pytest.mark.asyncio
+async def test_bot_transport_returns_editable_replies_and_preserves_literal_text():
+    sent = native_message()
+    sent.edit = AsyncMock()
+    original = native_message()
+    original.reply = AsyncMock(return_value=sent)
+    client = transport_client(SimpleNamespace())
+    message = TelegramMessage(client, original)
+    reply = await message.reply_text("Saving <file>…", reply_markup="menu")
+    assert isinstance(reply, TelegramMessage)
+    original.reply.assert_awaited_once_with(
+        "Saving <file>…", buttons="menu", parse_mode=None
+    )
+    await reply.edit_text("Saved <file>", reply_markup="new buttons")
+    sent.edit.assert_awaited_once_with(
+        "Saved <file>", buttons="new buttons", parse_mode=None
+    )
+
+
+def native_message(message_id: int = 77) -> Any:
+    return SimpleNamespace(
+        id=message_id,
+        chat_id=CHANNEL,
+        sender_id=1,
+        raw_text="caption",
+        photo=None,
+        file=SimpleNamespace(size=3, name="file.bin"),
+    )
+
+
+class NativeTransport:
+    def __init__(self) -> None:
+        self.requests: list[Any] = []
+        self.get_input_entity = AsyncMock(
+            return_value=types.InputPeerChannel(channel_id=123, access_hash=456)
+        )
+        self.get_messages = AsyncMock(return_value=native_message())
+        self.fail_first = False
+
+    async def __call__(self, request: Any) -> Any:
+        self.requests.append(request)
+        if self.fail_first and len(self.requests) == 1:
+            raise TimeoutError("synthetic ambiguous send")
+        return SimpleNamespace(
+            updates=[types.UpdateMessageID(id=77, random_id=request.random_id)]
+        )
+
+
+def transport_client(native: Any) -> Client:
+    client = Client.__new__(Client)
+    client.name = "storage-bot-123456"
+    client.native = native
+    client._upload_parts = AsyncMock(
+        side_effect=[
+            types.InputFileBig(id=1, parts=1, name="file.bin"),
+            types.InputFileBig(id=2, parts=1, name="file.bin"),
+        ]
+    )
+    return client
+
+
+@pytest.mark.asyncio
+async def test_send_replays_real_raw_request_with_the_persisted_random_id(
+    tmp_path: Path,
+) -> None:
+    native = NativeTransport()
+    native.fail_first = True
+    client = transport_client(native)
+    staged = tmp_path / "file.bin"
+    staged.write_bytes(b"abc")
+    operation_id = -(2**62) + 123
+    progress = AsyncMock()
+    with pytest.raises(TimeoutError, match="ambiguous"):
+        await client.send_staged(
+            CHANNEL,
+            staged,
+            file_name="file.bin",
+            random_id=operation_id,
+            progress=progress,
+        )
+    sent = await client.send_staged(
+        CHANNEL, staged, file_name="file.bin", random_id=operation_id, progress=progress
+    )
+
+    assert sent.id == 77
+    assert len(native.requests) == 2
+    assert all(
+        isinstance(value, functions.messages.SendMediaRequest)
+        for value in native.requests
+    )
+    assert [value.random_id for value in native.requests] == [operation_id] * 2
+    assert [value.media.file.id for value in native.requests] == [1, 2]
+    assert all(value.silent for value in native.requests)
+    assert all(
+        isinstance(value.media, types.InputMediaUploadedDocument)
+        and value.media.force_file
+        for value in native.requests
+    )
+    assert native.requests[-1].media.attributes == [
+        types.DocumentAttributeFilename(file_name="file.bin")
+    ]
+    assert all(
+        call.kwargs["progress"] is progress
+        for call in client._upload_parts.await_args_list
+    )
+    native.get_messages.assert_awaited_once_with(CHANNEL, ids=77)
+
+
+@pytest.mark.asyncio
+async def test_send_document_preserves_explicit_operation_id(tmp_path: Path) -> None:
+    client = transport_client(SimpleNamespace())
+    client.send_staged = AsyncMock(return_value="confirmed")
+    staged = tmp_path / "checkpoint.json"
+    result = await client.send_document(
+        CHANNEL, staged, file_name="drive.json", random_id=999
+    )
+    assert result == "confirmed"
+    client.send_staged.assert_awaited_once_with(
+        CHANNEL, staged, file_name="drive.json", random_id=999, progress=None
+    )
+
+
+@pytest.mark.asyncio
+async def test_copy_and_delete_keep_public_transport_contracts() -> None:
+    native = NativeTransport()
+    native.delete_messages = AsyncMock(return_value=2)
+    client = transport_client(native)
+    media = types.InputMediaDocument(
+        id=types.InputDocument(id=12, access_hash=34, file_reference=b"fresh")
+    )
+    original = SimpleNamespace(media=media, raw_text="literal <caption>")
+    copied = await client.copy_media(CHANNEL, original, random_id=456)
+    request = native.requests[0]
+    assert copied.id == 77
+    assert isinstance(request, functions.messages.SendMediaRequest)
+    assert request.random_id == 456 and request.media is media
+    assert request.message == "literal <caption>"
+    assert await client.delete_messages(CHANNEL, [77, 78]) == 2
+    native.delete_messages.assert_awaited_once_with(CHANNEL, [77, 78], revoke=True)
+
+
+class DownloadIterator:
+    def __init__(self, steps: list[Any]) -> None:
+        self.steps = iter(steps)
+        self.closed = False
+
+    def __aiter__(self) -> DownloadIterator:
+        return self
+
+    async def __anext__(self) -> bytes:
+        value = next(self.steps, None)
+        if value is None:
+            raise StopAsyncIteration
+        if isinstance(value, BaseException):
+            raise value
+        return value
+
+    async def close(self) -> None:
+        self.closed = True
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "error_type",
+    [FileReferenceExpiredError, FileReferenceInvalidError, FilerefUpgradeNeededError],
+)
+async def test_stream_refresh_resumes_after_partial_buffer_without_duplication(
+    error_type: Any,
+) -> None:
+    stale, refreshed = native_message(), native_message()
+    first = DownloadIterator([b"a" * (MIB // 2), error_type(request=None)])
+    second = DownloadIterator([b"b" * (MIB // 2), b"unused"])
+    native = SimpleNamespace(
+        iter_download=Mock(side_effect=[first, second]),
+        get_messages=AsyncMock(return_value=refreshed),
+    )
+    client = transport_client(native)
+    chunks = [part async for part in client.stream_media(stale, limit=1, offset=3)]
+    assert chunks == [b"a" * (MIB // 2) + b"b" * (MIB // 2)]
+    calls = native.iter_download.call_args_list
+    assert [call.kwargs["offset"] for call in calls] == [3 * MIB, 3 * MIB + MIB // 2]
+    assert all(call.kwargs["request_size"] == 512 * 1024 for call in calls)
+    assert calls[1].args[0] is refreshed
+    native.get_messages.assert_awaited_once_with(CHANNEL, ids=77)
+    assert first.closed and second.closed
+
+
+@pytest.mark.asyncio
+async def test_removed_message_is_a_visible_stream_failure() -> None:
+    stream = DownloadIterator([FileReferenceExpiredError(request=None)])
+    native = SimpleNamespace(
+        iter_download=Mock(return_value=stream),
+        get_messages=AsyncMock(return_value=None),
+    )
+    client = transport_client(native)
+    with pytest.raises(FileNotFoundError, match="removed"):
+        _ = [
+            part
+            async for part in client.stream_media(native_message(), limit=1, offset=0)
+        ]
+    assert stream.closed
+
+
+@pytest.mark.asyncio
+async def test_reference_refresh_retry_is_bounded_and_closes_each_iterator() -> None:
+    streams = [
+        DownloadIterator([FileReferenceExpiredError(request=None)]) for _ in range(3)
+    ]
+    native = SimpleNamespace(
+        iter_download=Mock(side_effect=streams),
+        get_messages=AsyncMock(return_value=native_message()),
+    )
+    client = transport_client(native)
+    with pytest.raises(FileReferenceExpiredError):
+        _ = [
+            part
+            async for part in client.stream_media(native_message(), limit=1, offset=0)
+        ]
+    assert native.get_messages.await_count == 2
+    assert all(stream.closed for stream in streams)
+
+
+@pytest.mark.asyncio
+async def test_large_download_offset_is_not_truncated_to_32_bits() -> None:
+    stream = DownloadIterator([b"tail"])
+    native = SimpleNamespace(iter_download=Mock(return_value=stream))
+    chunks = [
+        part
+        async for part in transport_client(native).stream_media(
+            native_message(), limit=1, offset=4096
+        )
+    ]
+    assert chunks == [b"tail"]
+    assert native.iter_download.call_args.kwargs["offset"] == 4 * 1024**3
+    assert stream.closed
diff --git a/tests/transfers/__init__.py b/tests/transfers/__init__.py
new file mode 100644
index 00000000..6eb1aec4
--- /dev/null
+++ b/tests/transfers/__init__.py
@@ -0,0 +1 @@
+"""TGDrive transfers tests."""
diff --git a/tests/transfers/test_available_upload_capacity.py b/tests/transfers/test_available_upload_capacity.py
new file mode 100644
index 00000000..6ef35620
--- /dev/null
+++ b/tests/transfers/test_available_upload_capacity.py
@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from fastapi.testclient import TestClient
+
+import tgdrive.core.config as config_module
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool, current_upload_limit
+from tgdrive.transfers.tasks import TransferRegistry
+from tgdrive.web.app import create_app
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path / "data")
+
+
+class Account:
+    def __init__(self, name: str, *, fail: bool = False) -> None:
+        self.name = name
+        self.fail = fail
+        self.is_connected = False
+
+    async def start(self) -> None:
+        if self.fail:
+            raise ConnectionError("synthetic optional account unavailable")
+        self.is_connected = True
+
+    async def stop(self) -> None:
+        self.is_connected = False
+
+
+class Runtime:
+    def __init__(self, store: DriveStore, pool: ClientPool, user: Account, state: str):
+        self.store = store
+        self.pool = pool
+        self.user = user
+        self.state = state
+        self.transfers = SimpleNamespace(store=store, registry=TransferRegistry())
+        self.ready = False
+
+    async def start(self) -> None:
+        await self.pool.start()
+        if self.state == "disconnected":
+            self.user.is_connected = False
+        if self.state == "unknown":
+            del self.user.is_connected
+        self.ready = True
+
+    async def stop(self) -> None:
+        self.ready = False
+        if hasattr(self.transfers, "uploads"):
+            self.transfers.uploads.close()
+        await self.pool.stop()
+        self.store.close()
+
+
+def settings(tmp_path: Path) -> Settings:
+    return Settings(
+        _env_file=None,
+        MONGODB_URI="mongodb://synthetic.invalid",
+        API_ID=12345,
+        API_HASH="a" * 32,
+        BOT_TOKENS="123456:" + "x" * 30,
+        STRING_SESSIONS="synthetic-user-session",
+        STORAGE_CHANNEL=-1001234567890,
+        ADMIN_PASSWORD="synthetic capacity password",
+        SESSION_SECRET="s" * 48,
+        DATA_DIR=tmp_path / "data",
+        CACHE_DIR=tmp_path / "cache",
+        MIN_FREE_BYTES=0,
+    )
+
+
+@pytest.mark.parametrize("state", ["healthy", "failed", "disconnected", "unknown"])
+def test_api_logical_capacity_is_independent_of_optional_premium(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, state: str, mongo_backend
+) -> None:
+    monkeypatch.setattr(config_module, "_DEFAULT_BOT_LIMIT", 3)
+    config = settings(tmp_path)
+    user = Account("premium", fail=state == "failed")
+    pool = ClientPool([Account("bot")], [user], allow_partial_start=True)
+    runtime = Runtime(DriveStore.create(), pool, user, state)
+    runtime.mongo = mongo_backend
+    app = create_app(config, runtime=runtime)
+    expected = config.upload_limit
+
+    with TestClient(app, base_url="https://testserver") as client:
+        assert client.get("/api/config").json()["max_file_size"] == expected
+        assert (
+            client.post(
+                "/api/checkPassword", json={"pass": "synthetic capacity password"}
+            ).status_code
+            == 200
+        )
+        status = client.get("/api/v1/status")
+        assert status.status_code == 200
+        assert status.json()["max_file_size"] == expected
+        assert status.json()["telegram_ready"] is True
+
+        receipt = client.post(
+            "/api/v1/uploads",
+            json={"name": "four.bin", "parent_id": "/", "total_size": 4},
+        )
+        assert receipt.status_code == 201
+        identity = receipt.json()["id"]
+        user.is_connected = False
+        assert client.get("/api/config").json()["max_file_size"] == expected
+        appended = client.patch(
+            f"/api/v1/uploads/{identity}",
+            content=b"four",
+            headers={"Content-Type": "application/octet-stream", "Upload-Offset": "0"},
+        )
+        assert appended.status_code == 204
+        assert appended.headers["upload-offset"] == "4"
+        assert client.post(f"/api/v1/uploads/{identity}/cancel").status_code == 200
+        rejected = client.post(
+            "/api/v1/uploads",
+            json={
+                "name": "too-big.bin",
+                "parent_id": "/",
+                "total_size": expected + 1,
+            },
+        )
+        assert rejected.status_code == 413
+
+
+@pytest.mark.asyncio
+async def test_unstarted_and_synthetic_pools_keep_logical_limit(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(config_module, "_DEFAULT_BOT_LIMIT", 3)
+    config = settings(tmp_path)
+    pool = ClientPool([Account("bot")], [Account("premium")])
+    assert config.upload_limit == 3 * 4096
+    assert await current_upload_limit(config, pool) == config.upload_limit
+    assert await current_upload_limit(config, object()) == config.upload_limit
+    assert await current_upload_limit(config, None) == config.upload_limit
+
+
+@pytest.mark.asyncio
+async def test_remote_and_legacy_upload_admission_enforces_logical_ceiling(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    from io import BytesIO
+
+    from fastapi import UploadFile
+
+    from tgdrive.transfers.manager import TransferManager, TransferTooLarge
+    from tgdrive.transfers.remote import RemoteTooLarge
+
+    monkeypatch.setattr(config_module, "_DEFAULT_BOT_LIMIT", 3)
+    config = settings(tmp_path)
+    pool = ClientPool(
+        [Account("bot")], [Account("premium", fail=True)], allow_partial_start=True
+    )
+    await pool.start()
+
+    class Remote:
+        async def inspect(self, _url: str):
+            return SimpleNamespace(size=config.upload_limit + 1)
+
+        async def close(self) -> None:
+            pass
+
+    store = DriveStore.create()
+    manager = TransferManager(
+        settings=config,
+        pool=pool,
+        store=store,
+        remote=Remote(),
+        registry=TransferRegistry(),
+    )
+    try:
+        with pytest.raises(RemoteTooLarge) as captured:
+            await manager.inspect_remote("https://example.com/four.bin")
+        assert captured.value.limit == config.upload_limit
+        upload = UploadFile(
+            BytesIO(b"four"), size=config.upload_limit + 1, filename="four.bin"
+        )
+        with pytest.raises(TransferTooLarge):
+            await manager.receive_browser_upload(upload, "/")
+        assert upload.file.closed
+        assert not (config.resolved_cache_dir / "uploads").exists()
+        assert manager.registry.list() == []
+    finally:
+        await manager.close()
+        await pool.stop()
+        store.close()
diff --git a/tests/transfers/test_device_upload_pipeline.py b/tests/transfers/test_device_upload_pipeline.py
new file mode 100644
index 00000000..f47d3f96
--- /dev/null
+++ b/tests/transfers/test_device_upload_pipeline.py
@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from tests.transfers.test_resumable_uploads import mongo_backend as mongo_backend
+from tests.transfers.test_transfers import make_manager
+from tgdrive.transfers.tasks import TransferStatus
+from tgdrive.transfers.uploads import ResumableUploads
+
+pytestmark = pytest.mark.usefixtures("mongo_backend")
+
+
+async def test_receiving_more_files_does_not_wait_for_telegram_or_the_whole_batch(
+    tmp_path,
+):
+    manager, store, client, pool = await make_manager(tmp_path)
+    uploads = manager.uploads = ResumableUploads(manager.settings, manager)
+    client.wait_during_upload = True
+    waiting = uploads.create("still-on-device.bin", "/", 3)
+    jobs = []
+    try:
+        first = uploads.create("first.bin", "/", 3)
+        await uploads.append(first["id"], 0, b"one")
+        jobs.append(await uploads.complete(first["id"]))
+        # Telegram starts while another batch member has not sent any bytes.
+        await asyncio.wait_for(client.started_upload.wait(), 3)
+
+        async def receive_remaining():
+            for name, content in (("second.bin", b"two"), ("third.bin", b"end")):
+                item = uploads.create(name, "/", len(content))
+                await uploads.append(item["id"], 0, content)
+                jobs.append(await uploads.complete(item["id"]))
+
+        # One Telegram upload holds the only client lease. Device receipts and
+        # their durable queue acknowledgements must still finish independently.
+        await asyncio.wait_for(receive_remaining(), 3)
+        assert len(jobs) == 3
+        assert all(job.task is not None and not job.task.done() for job in jobs)
+        assert all(uploads.get(job.id)["state"] == "queued" for job in jobs)
+        assert uploads.get(waiting["id"])["offset"] == 0
+        assert store.list_directory("/") == {}
+
+        # The request that received each file has returned. Only registry-owned
+        # tasks remain, and those finish without further browser activity.
+        client.release_upload.set()
+        await asyncio.wait_for(asyncio.gather(*(job.task for job in jobs)), 3)
+        assert all(job.status is TransferStatus.COMPLETED for job in jobs)
+        assert {item["name"] for item in store.list_directory("/").values()} == {
+            "first.bin",
+            "second.bin",
+            "third.bin",
+        }
+        assert all(uploads.get(job.id)["state"] == "finished" for job in jobs)
+        assert uploads.get(waiting["id"])["state"] == "receiving"
+    finally:
+        client.release_upload.set()
+        await manager.close()
+        await pool.stop()
+        uploads.close()
+        store.close()
+
+
+async def test_folder_identity_survives_real_background_upload_and_history(tmp_path):
+    manager, store, _client, pool = await make_manager(tmp_path)
+    uploads = manager.uploads = ResumableUploads(manager.settings, manager)
+    root = store.create_folder("/", "Photos")
+    destination = "/" + root["id"]
+    folder = {
+        "id": "folder-upload-session-1",
+        "name": "Photos",
+        "root_path": destination,
+        "created_at": 1234.5,
+    }
+    try:
+        item = await uploads.create_async(
+            "image.bin", destination, 3, folder_upload=folder
+        )
+        await uploads.append(item["id"], 0, b"one")
+        job = await uploads.complete(item["id"])
+        assert job.as_dict()["folder_upload"] == folder
+        await asyncio.wait_for(job.task, 3)
+        assert job.status is TransferStatus.COMPLETED
+        page = await manager.registry.task_history(status="finished", limit=1)
+        assert page["total_tasks"] == 1
+        assert page["jobs"][0]["folder_upload"] == folder
+    finally:
+        await manager.close()
+        await pool.stop()
+        uploads.close()
+        store.close()
diff --git a/tests/transfers/test_durable_jobs.py b/tests/transfers/test_durable_jobs.py
new file mode 100644
index 00000000..9644e037
--- /dev/null
+++ b/tests/transfers/test_durable_jobs.py
@@ -0,0 +1,606 @@
+from __future__ import annotations
+
+import asyncio
+import gc
+import hashlib
+import weakref
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from pymongo.errors import ConnectionFailure
+
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.errors import NotFoundError
+from tgdrive.storage.mongo import DatabaseUnavailable, for_directory
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.manager import TransferManager
+from tgdrive.transfers.tasks import TransferNotFound, TransferRegistry, TransferStatus
+
+pytestmark = pytest.mark.usefixtures("mongo_backend")
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path)
+
+
+def registry_for(path, **kwargs):
+    backend = for_directory(path.parent)
+    return TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend, **kwargs)
+
+
+class Telegram:
+    def __init__(self):
+        self.name = "stable-test-account"
+        self.is_connected = False
+        self.messages = {}
+        self.random_ids = {}
+        self.calls = []
+        self.deleted = []
+        self.lose_response = False
+        self.block = False
+        self.started = asyncio.Event()
+        self.fail_delete_call = 0
+        self.delete_calls = 0
+
+    async def start(self):
+        self.is_connected = True
+
+    async def stop(self):
+        self.is_connected = False
+
+    async def send_staged(
+        self,
+        _channel,
+        path,
+        *,
+        random_id,
+        file_name,
+        progress,
+        offset=0,
+        size=None,
+        expected_sha256=None,
+        before_dispatch=None,
+    ):
+        end = offset + size if size is not None else None
+        content = path.read_bytes()[offset:end]
+        if expected_sha256 is not None:
+            assert hashlib.sha256(content).hexdigest() == expected_sha256
+        if before_dispatch is not None:
+            (await before_dispatch())
+        self.calls.append(random_id)
+        if random_id not in self.random_ids:
+            message_id = 101 + len(self.random_ids)
+            message = SimpleNamespace(
+                id=message_id, document=SimpleNamespace(file_size=len(content))
+            )
+            self.random_ids[random_id] = message
+            self.messages[message_id] = message
+        self.started.set()
+        if self.block:
+            await asyncio.Event().wait()
+        if self.lose_response:
+            self.lose_response = False
+            raise TimeoutError("accepted message response was lost")
+        return self.random_ids[random_id]
+
+    async def get_messages(self, _channel, *, message_ids):
+        if isinstance(message_ids, list):
+            return [self.messages.get(message_id) for message_id in message_ids]
+        return self.messages.get(message_ids)
+
+    async def delete_messages(self, _channel, message_ids):
+        self.delete_calls += 1
+        if self.fail_delete_call == self.delete_calls:
+            raise TimeoutError("delete response lost")
+        for message_id in (
+            message_ids if isinstance(message_ids, list) else [message_ids]
+        ):
+            self.messages.pop(message_id, None)
+            self.deleted.append(message_id)
+
+
+def manager_for(tmp_path, pool, *, store=None, registry=None):
+    settings = SimpleNamespace(
+        resolved_cache_dir=tmp_path / "cache",
+        max_concurrent_transfers=1,
+        storage_channel=-100123,
+        bot_upload_limit=2_000_000_000,
+        upload_limit=4_000_000_000,
+    )
+    return TransferManager(
+        settings=settings,
+        pool=pool,
+        store=store or DriveStore.create(tmp_path / "drive.sqlite3"),
+        registry=registry or registry_for(tmp_path / "jobs.sqlite3"),
+        remote=SimpleNamespace(close=AsyncMock()),
+    )
+
+
+async def test_lost_send_response_retries_same_sender_and_random_id(tmp_path):
+    telegram = Telegram()
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"immutable payload")
+    telegram.lose_response = True
+    job = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    await job.task
+    assert job.status == TransferStatus.ERROR
+    assert source.exists()
+    assert len(telegram.messages) == 1
+    sender, random_id = job.context["sender"], job.context["random_id"]
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path / "jobs.sqlite3"),
+    )
+    retry = await recovered.retry_job(job.id)
+    await retry.task
+    assert retry.status == TransferStatus.COMPLETED
+    assert retry.context["sender"] == sender
+    assert telegram.calls == [random_id, random_id]
+    assert len(recovered.store.list_directory("/")) == len(telegram.messages) == 1
+    assert not source.exists()
+    await pool.stop()
+
+
+async def test_retry_after_metadata_commit_does_not_duplicate_visible_file(
+    tmp_path, monkeypatch
+):
+    telegram = Telegram()
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"bytes")
+    original = manager.store.add_file
+
+    def commit_then_lose_response(*args, **kwargs):
+        original(*args, **kwargs)
+        raise RuntimeError("process stopped after metadata committed")
+
+    monkeypatch.setattr(manager.store, "add_file", commit_then_lose_response)
+    job = await manager.enqueue_upload(source, "/", "one.bin", 5)
+    await job.task
+    assert job.status == TransferStatus.ERROR
+    assert len(manager.store.list_directory("/")) == 1
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path / "jobs.sqlite3"),
+    )
+    retry = await recovered.retry_job(job.id)
+    await retry.task
+    assert retry.status == TransferStatus.COMPLETED
+    assert len(recovered.store.list_directory("/")) == 1
+    assert len(telegram.calls) == 1
+    assert not source.exists()
+    await pool.stop()
+
+
+async def test_shutdown_preserves_ambiguous_send_for_restart_reconciliation(tmp_path):
+    telegram = Telegram()
+    telegram.block = True
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"bytes")
+    job = await manager.enqueue_upload(source, "/", "one.bin", 5)
+    await telegram.started.wait()
+    await manager.registry.shutdown()
+    assert job.status == TransferStatus.QUEUED
+    assert source.exists()
+    assert not job.context.get("cancel_requested")
+    telegram.block = False
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path / "jobs.sqlite3"),
+    )
+    await recovered.recover()
+    resumed = recovered.registry.get(job.id)
+    await resumed.task
+    assert resumed.status == TransferStatus.COMPLETED
+    assert len(telegram.messages) == 1
+    assert telegram.calls[0] == telegram.calls[1]
+    await pool.stop()
+
+
+async def test_cancelled_ambiguous_send_stays_recoverable_until_remote_cleanup(
+    tmp_path,
+):
+    telegram = Telegram()
+    telegram.block = True
+    pool = ClientPool([telegram])
+    await pool.start()
+    registry = registry_for(tmp_path / "jobs.sqlite3", cancel_grace_seconds=0.001)
+    manager = manager_for(tmp_path, pool, registry=registry)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"bytes")
+    job = await manager.enqueue_upload(source, "/", "one.bin", 5)
+    await telegram.started.wait()
+    (await registry.cancel(job.id))
+    with pytest.raises(asyncio.CancelledError):
+        await job.task
+    assert job.status == TransferStatus.QUEUED
+    assert job.phase == "cleanup_pending"
+    assert source.exists() and telegram.messages
+    telegram.block = False
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path / "jobs.sqlite3"),
+    )
+    assert recovered.registry.get(job.id).cancel_event.is_set()
+    await recovered.recover()
+    resumed = recovered.registry.get(job.id)
+    await resumed.task
+    assert resumed.status == TransferStatus.CANCELLED
+    assert not telegram.messages and not source.exists()
+    assert recovered.store.list_directory("/") == {}
+    await pool.stop()
+
+
+@pytest.mark.parametrize("confirmed", [0, 100])
+async def test_failed_delete_retries_as_catalog_removal_after_restart(
+    tmp_path, confirmed, monkeypatch
+):
+    telegram = Telegram()
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    folder = manager.store.create_folder("/", "Delete")
+    path = "/" + folder["id"]
+    for message_id in range(1, 106):
+        manager.store.add_file(path, f"{message_id}.bin", message_id, 1)
+        telegram.messages[message_id] = SimpleNamespace(id=message_id)
+    manager.store.set_trashed(path, True)
+    # Preserve a failed deletion intent and its confirmed partial progress.
+    intent = manager.store.begin_deletion(path, channel_id=-100123)
+    manager.store.confirm_deletion_messages(intent["id"], list(range(1, confirmed + 1)))
+    manager.store.fail_deletion(intent["id"], "MessageDeleteForbiddenError")
+    finish = manager.store.finish_deletion
+
+    def database_unavailable(_intent_id):
+        raise RuntimeError("database write failed")
+
+    monkeypatch.setattr(manager.store, "finish_deletion", database_unavailable)
+    job = await manager.start_deletion(path)
+    await job.task
+    assert job.status is TransferStatus.ERROR
+    assert manager.store.message_ids(path, include_trashed=True) == list(range(1, 106))
+    assert telegram.deleted == [] and len(telegram.messages) == 105
+    monkeypatch.setattr(manager.store, "finish_deletion", finish)
+    await manager.close()
+    manager.registry.close()
+    manager.store.close()
+    recovered = manager_for(
+        tmp_path,
+        pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path / "jobs.sqlite3"),
+    )
+    retried = await recovered.retry_job(job.id)
+    await retried.task
+    assert retried.status == TransferStatus.COMPLETED
+    assert telegram.deleted == [] and len(telegram.messages) == 105
+    assert recovered.store.pending_deletions() == []
+    assert recovered.store.list_directory("/") == {}
+    assert recovered.store.export()["deletions"][0]["message_ids"] == []
+    await recovered.close()
+    recovered.registry.close()
+    recovered.store.close()
+    await pool.stop()
+
+
+async def test_permanent_delete_needs_no_telegram_client_and_revokes_shares(tmp_path):
+    pool = ClientPool([Telegram()])  # Deliberately not started.
+    manager = manager_for(tmp_path, pool)
+    file = manager.store.add_file("/", "old.bin", 77, 1)
+    path = "/" + file["id"]
+    token = manager.store.create_share(path)
+    manager.store.set_trashed(path, True)
+    try:
+        job = await manager.start_deletion(path)
+        await job.task
+        assert job.status is TransferStatus.COMPLETED
+        assert manager.store.list_trash() == {}
+        assert manager.store.list_shares() == []
+        with pytest.raises(NotFoundError):
+            manager.store.authorize_file(path, token)
+        assert manager.store.pending_deletions() == []
+    finally:
+        await manager.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+async def test_capacity_eviction_and_ttl_pruning_are_persistent(tmp_path):
+    path = tmp_path / "jobs.sqlite3"
+    registry = registry_for(path, max_entries=1, ttl_seconds=1)
+    first = await registry.create("upload")
+    (await registry.update(first.id, status=TransferStatus.COMPLETED))
+    second = await registry.create("upload")
+    recovered = registry_for(path)
+    assert [record.id for record in recovered.list()] == [second.id]
+    with pytest.raises(TransferNotFound):
+        recovered.get(first.id)
+    (await registry.update(second.id, status=TransferStatus.COMPLETED))
+    (await registry.prune(now=second.updated_at + 2))
+    assert registry_for(path).list() == []
+
+
+async def test_unresolved_jobs_and_staging_survive_ttl_and_capacity_pressure(tmp_path):
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"needed for reconciliation")
+    path = tmp_path / "jobs.sqlite3"
+    registry = registry_for(path, max_entries=1)
+    record = await registry.create("upload")
+    record.context.update(kind="upload", local_path=str(source), send_started=True)
+    (await registry.update(record.id, status=TransferStatus.ERROR))
+    (await registry.prune(now=record.updated_at + 1_000_000))
+    assert registry.get(record.id).id == record.id
+    with pytest.raises(RuntimeError, match="too many"):
+        (await registry.create("other"))
+    assert registry_for(path).get(record.id).context["send_started"]
+
+
+async def test_persistence_failure_rolls_back_reported_job_state(
+    tmp_path, mongo_backend, monkeypatch
+):
+    path = tmp_path / "jobs"
+    registry = registry_for(path)
+    record = await registry.create("upload")
+    original = mongo_backend.db.jobs.replace_one
+
+    def unavailable(*_args, **_kwargs):
+        raise ConnectionFailure("synthetic database outage")
+
+    monkeypatch.setattr(mongo_backend.db.jobs, "replace_one", unavailable)
+    with pytest.raises(DatabaseUnavailable, match="could not be saved to MongoDB"):
+        (await registry.update(record.id, status=TransferStatus.COMPLETED, current=100))
+    assert record.status == TransferStatus.QUEUED and record.current == 0
+    monkeypatch.setattr(mongo_backend.db.jobs, "replace_one", original)
+    assert registry_for(path).get(record.id).status == TransferStatus.QUEUED
+
+
+async def test_permanent_delete_cannot_be_cancelled(tmp_path):
+    registry = registry_for(tmp_path / "jobs.sqlite3")
+    record = await registry.create("deleting")
+    record.context.update(kind="delete", deletion_id="intent")
+    (await registry.persist(record))
+    with pytest.raises(ValueError, match="cannot be cancelled"):
+        (await registry.cancel(record.id))
+
+
+async def test_corrupt_persisted_job_identity_fails_loading_without_reset(
+    tmp_path, mongo_backend
+):
+    path = tmp_path / "jobs"
+    registry = registry_for(path)
+    record = await registry.create("queued")
+    stored = mongo_backend.db.jobs.find_one({"_id": record.id})
+    stored["data"]["id"] = "different-id"
+    mongo_backend.db.jobs.replace_one({"_id": record.id}, stored)
+    with pytest.raises(ValueError, match="job identity"):
+        registry_for(path)
+    assert mongo_backend.db.jobs.count_documents({}) == 1
+
+
+async def test_abandoned_registry_leaves_shared_mongo_connection_and_records_available(
+    tmp_path,
+):
+    path = tmp_path / "jobs"
+    registry = registry_for(path)
+    record = await registry.create("queued")
+    reference = weakref.ref(registry)
+    del registry
+    gc.collect()
+    assert reference() is None
+    restored = registry_for(path)
+    assert restored.get(record.id).id == record.id
+    restored.close()
+    restored.close()
+
+
+async def test_restart_retries_lost_network_response_without_duplicate_upload(tmp_path):
+    telegram = Telegram()
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"immutable payload")
+    telegram.lose_response = True
+    job = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    await job.task
+    assert job.status is TransferStatus.ERROR
+    assert job.context["restart_retryable"] is True
+    assert "restart TGDrive" in job.error
+    random_id = job.context["random_id"]
+    await manager.close()
+    manager.registry.close()
+    manager.store.close()
+    recovered = manager_for(
+        tmp_path, pool, store=DriveStore.load(tmp_path / "drive.sqlite3")
+    )
+    try:
+        await recovered.recover()
+        resumed = recovered.registry.get(job.id)
+        await resumed.task
+        assert resumed.status is TransferStatus.COMPLETED
+        assert telegram.calls == [random_id, random_id]
+        assert len(telegram.messages) == 1
+        assert len(recovered.store.list_directory("/")) == 1
+        assert not source.exists()
+    finally:
+        await recovered.close()
+        recovered.registry.close()
+        recovered.store.close()
+        await pool.stop()
+
+
+async def test_restart_does_not_retry_nontransient_transfer_failure(tmp_path):
+    telegram = Telegram()
+    telegram.send_staged = AsyncMock(side_effect=PermissionError("channel access lost"))
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"bytes")
+    job = await manager.enqueue_upload(source, "/", "one.bin", 5)
+    await job.task
+    assert job.status is TransferStatus.ERROR
+    assert not job.context.get("restart_retryable")
+    await manager.close()
+    manager.registry.close()
+    manager.store.close()
+    recovered = manager_for(
+        tmp_path, pool, store=DriveStore.load(tmp_path / "drive.sqlite3")
+    )
+    try:
+        await recovered.recover()
+        resumed = recovered.registry.get(job.id)
+        assert resumed.status is TransferStatus.ERROR
+        assert resumed.task is None
+        assert telegram.send_staged.await_count == 1
+        assert source.exists()
+    finally:
+        await recovered.close()
+        recovered.registry.close()
+        recovered.store.close()
+        await pool.stop()
+
+
+async def test_recovery_retries_a_finished_task_without_process_restart(tmp_path):
+    telegram = Telegram()
+    telegram.lose_response = True
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"retained payload")
+    try:
+        job = await manager.enqueue_upload(
+            source, "/", "one.bin", source.stat().st_size
+        )
+        failed_task = job.task
+        await failed_task
+        assert job.status is TransferStatus.ERROR
+        assert job.context["restart_retryable"] is True
+        await manager.recover()
+        assert job.task is not failed_task
+        await job.task
+        assert job.status is TransferStatus.COMPLETED
+        assert len(telegram.messages) == 1
+        assert len(manager.store.list_directory("/")) == 1
+    finally:
+        await manager.close()
+        manager.registry.close()
+        manager.store.close()
+        await pool.stop()
+
+
+@pytest.mark.parametrize("resumed", [False, True])
+async def test_live_channel_check_blocks_upload_before_any_telegram_send(
+    tmp_path, resumed
+):
+    from tgdrive.settings.managed_settings import SettingsProblem
+
+    telegram = Telegram()
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    manager._check_upload_allowed = lambda: None
+    manager._ensure_channel = AsyncMock(
+        side_effect=SettingsProblem("Turn storage channel auto-delete off.")
+    )
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"retained payload")
+    try:
+        if resumed:
+            from tgdrive.transfers.multipart_transfer import fingerprint
+
+            checksum, parts = fingerprint(
+                source, source.stat().st_size, source.stat().st_size
+            )
+            parts[0].update(random_id=123, sender=telegram.name, send_started=True)
+            job = await manager.registry.create(
+                "interrupted", total=source.stat().st_size
+            )
+            job.context.update(
+                kind="upload",
+                local_path=str(source),
+                destination="/",
+                destination_id="root",
+                random_id=123,
+                name="one.bin",
+                size=source.stat().st_size,
+                send_started=True,
+                sender=telegram.name,
+                sha256=checksum,
+                multipart_plan=dict(version=1, kind="bot", parts=parts),
+            )
+            (await manager._resume(job))
+        else:
+            job = await manager.enqueue_upload(
+                source, "/", "one.bin", source.stat().st_size
+            )
+        await job.task
+        assert job.status is TransferStatus.ERROR
+        assert "auto-delete" in job.error
+        assert telegram.calls == []
+        assert telegram.messages == {}
+        assert manager.store.list_directory("/") == {}
+        assert source.exists()
+        manager._ensure_channel.assert_awaited_once()
+    finally:
+        await manager.close()
+        manager.registry.close()
+        manager.store.close()
+        await pool.stop()
+
+
+@pytest.mark.parametrize("effect", ["send_started", "remote_message_id"])
+async def test_dispatched_upload_without_part_journal_preserves_staging(
+    tmp_path, effect
+):
+    telegram = Telegram()
+    pool = ClientPool([telegram])
+    await pool.start()
+    manager = manager_for(tmp_path, pool)
+    source = tmp_path / "receipt.part"
+    source.write_bytes(b"retained payload")
+    job = await manager.registry.create("interrupted", total=source.stat().st_size)
+    job.context.update(
+        kind="upload",
+        local_path=str(source),
+        destination="/",
+        destination_id="root",
+        name="one.bin",
+        size=source.stat().st_size,
+        **{effect: True if effect == "send_started" else 101},
+    )
+    (await manager.registry.persist(job))
+    try:
+        (await manager._resume(job))
+        await job.task
+        assert job.status is TransferStatus.ERROR
+        assert "missing its part journal" in job.error
+        assert source.read_bytes() == b"retained payload"
+        assert telegram.calls == []
+        assert telegram.deleted == []
+        assert manager.store.list_directory("/") == {}
+    finally:
+        await manager.close()
+        manager.registry.close()
+        manager.store.close()
+        await pool.stop()
diff --git a/tests/transfers/test_journal_boundaries.py b/tests/transfers/test_journal_boundaries.py
new file mode 100644
index 00000000..6e829faa
--- /dev/null
+++ b/tests/transfers/test_journal_boundaries.py
@@ -0,0 +1,337 @@
+"""Crash and suspended-database boundaries, using synthetic storage only."""
+
+import asyncio
+import threading
+from contextlib import AsyncExitStack
+from io import BytesIO
+
+import httpx2 as httpx
+import pytest
+from fastapi import UploadFile
+from pymongo.errors import ConnectionFailure
+
+from tests.support.app_fixtures import FakeRuntime, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tests.transfers.test_transfers import FakeRemote, make_manager
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.store import DriveStore
+from tgdrive.transfers.manager import TransferManager
+from tgdrive.transfers.remote_scheduler import URLDownloadScheduler
+from tgdrive.transfers.staging import StorageUnavailable, staging_usage
+from tgdrive.transfers.tasks import TransferNotFound, TransferRegistry, TransferStatus
+from tgdrive.transfers.uploads import ResumableUploads
+from tgdrive.web.app import create_app
+
+
+def hold_write(monkeypatch, backend, predicate, *, fail=False):
+    entered, release = threading.Event(), threading.Event()
+    original = backend.write
+
+    def write(collection, method, *args, **kwargs):
+        if (
+            collection is backend.db.jobs
+            and method == "replace_one"
+            and not entered.is_set()
+            and predicate(args[1]["data"])
+        ):
+            entered.set()
+            assert release.wait(5), "Synthetic database write was not released"
+            if fail:
+                raise ConnectionFailure("Synthetic journal rejection")
+        return original(collection, method, *args, **kwargs)
+
+    monkeypatch.setattr(backend, "write", write)
+    return entered, release
+
+
+@pytest.fixture
+async def journal_app(tmp_path, monkeypatch):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create()
+    runtime = FakeRuntime(store)
+    backend = register_test_backend(monkeypatch, settings, runtime.mongo)
+    registry = runtime.transfers.registry = TransferRegistry(
+        mongo=backend.db.jobs, mongo_backend=backend
+    )
+    uploads = runtime.transfers.uploads = ResumableUploads(settings, runtime.transfers)
+    app = create_app(settings, runtime=runtime)
+    async with (
+        app.router.lifespan_context(app),
+        httpx.AsyncClient(
+            transport=httpx.ASGITransport(app=app), base_url="https://testserver"
+        ) as client,
+    ):
+        response = await client.post(
+            "/api/checkPassword", json={"pass": "correct horse battery staple"}
+        )
+        assert response.status_code == 200
+        yield client, registry, backend, uploads
+    await registry.shutdown()
+    registry.close()
+    store.close()
+
+
+@pytest.mark.parametrize("fail", [False, True])
+async def test_pending_completion_is_not_public_and_disconnect_drains_commit(
+    journal_app, monkeypatch, fail
+):
+    client, registry, backend, uploads = journal_app
+    receipt = uploads.create("synthetic.bin", "/", 3)
+    await uploads.append(receipt["id"], 0, b"one")
+    job = await registry.create(
+        "uploading", transfer_id=receipt["id"], total=3, context={"kind": "upload"}
+    )
+    await registry.update(job.id, status=TransferStatus.RUNNING)
+    uploads._reconcile_finished()
+    entered, release = hold_write(
+        monkeypatch, backend, lambda row: row["status"] == "completed", fail=fail
+    )
+    finishing = asyncio.create_task(
+        registry.update(job.id, status=TransferStatus.COMPLETED, phase="completed")
+    )
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        finishing.cancel()
+        await asyncio.sleep(0)
+        finishing.cancel()
+        await asyncio.sleep(0)
+        assert not finishing.done()
+        response = await asyncio.wait_for(client.get("/api/v1/jobs"), 0.5)
+        assert response.status_code == 200
+        assert response.json()["jobs"][0]["status"] == "running"
+        assert response.json()["jobs"][0]["phase"] == "uploading"
+        assert not job.terminal
+        await asyncio.to_thread(uploads._reconcile_finished)
+        assert uploads.get_unchecked(job.id)["state"] == "queued"
+        assert uploads.path(job.id).exists()
+        completed = await client.get("/api/v1/transfers/history?status=completed")
+        assert completed.status_code == 200
+        assert completed.json()["jobs"] == []
+        running = await client.get("/api/v1/transfers/history?status=running")
+        assert running.json()["jobs"][0]["status"] == "running"
+    finally:
+        release.set()
+    with pytest.raises(DatabaseUnavailable if fail else asyncio.CancelledError):
+        await finishing
+    expected = "running" if fail else "completed"
+    assert (await client.get(f"/api/v1/jobs/{job.id}")).json()["status"] == expected
+    assert backend.db.jobs.find_one({"_id": job.id})["data"]["status"] == expected
+    uploads._reconcile_finished()
+    assert uploads.get_unchecked(job.id)["state"] == ("queued" if fail else "finished")
+    assert uploads.path(job.id).exists() is fail
+
+
+async def test_first_job_write_contains_context_and_is_hidden_until_ack(
+    journal_app, monkeypatch
+):
+    client, registry, backend, _uploads = journal_app
+    context = {"kind": "upload", "name": "synthetic.txt", "size": 3}
+    entered, release = hold_write(monkeypatch, backend, lambda _row: True)
+    creating = asyncio.create_task(
+        registry.create("queued", transfer_id="initial-write", total=3, context=context)
+    )
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        context["name"] = "caller-mutated.txt"
+        assert (await client.get("/api/v1/jobs")).json()["jobs"] == []
+        assert (await client.get("/api/v1/jobs/initial-write")).status_code == 404
+        with pytest.raises(TransferNotFound):
+            registry.get("initial-write")
+    finally:
+        release.set()
+    job = await creating
+    assert job.context["name"] == "synthetic.txt"
+    assert backend.db.jobs.find_one({"_id": job.id})["data"]["context"] == job.context
+
+
+@pytest.mark.parametrize("fail", [False, True])
+async def test_cancel_flags_wait_for_ack_and_keep_parallel_part_references(
+    journal_app, monkeypatch, fail
+):
+    _client, registry, backend, _uploads = journal_app
+    job = await registry.create(
+        "uploading",
+        context={
+            "kind": "upload",
+            "send_started": True,
+            "multipart_plan": {"parts": [{"confirmed": False}]},
+        },
+    )
+    await registry.update(job.id, status=TransferStatus.RUNNING)
+    part = job.context["multipart_plan"]["parts"][0]
+    entered, release = hold_write(
+        monkeypatch,
+        backend,
+        lambda row: row["context"].get("cancel_requested"),
+        fail=fail,
+    )
+    cancelling = asyncio.create_task(registry.cancel(job.id))
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        assert not job.cancel_event.is_set()
+        assert not job.context.get("cancel_requested")
+        part["confirmed"] = True
+        following = asyncio.create_task(registry.persist(job))
+        await asyncio.sleep(0)
+        assert not following.done()
+    finally:
+        release.set()
+    if fail:
+        with pytest.raises(DatabaseUnavailable):
+            await cancelling
+    else:
+        await cancelling
+    await following
+    assert job.context["multipart_plan"]["parts"][0] is part
+    assert part["confirmed"]
+    assert job.cancel_event.is_set() is (not fail)
+    assert bool(job.context.get("cancel_requested")) is (not fail)
+    saved = backend.db.jobs.find_one({"_id": job.id})["data"]["context"]
+    assert saved["multipart_plan"]["parts"][0]["confirmed"]
+    assert bool(saved.get("cancel_requested")) is (not fail)
+
+
+async def test_complete_receipt_recovers_if_process_stops_before_spawn(
+    tmp_path, monkeypatch
+):
+    manager, store, _telegram, pool = await make_manager(tmp_path)
+    backend = register_test_backend(monkeypatch, manager.settings)
+    manager.registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    uploads = manager.uploads = ResumableUploads(manager.settings, manager)
+    receipt = uploads.create("crash.bin", "/", 3)
+    await uploads.append(receipt["id"], 0, b"one")
+
+    def interrupted(*_args):
+        raise RuntimeError("Synthetic process stopped before spawn")
+
+    monkeypatch.setattr(manager.registry, "spawn", interrupted)
+    recovered = None
+    try:
+        with pytest.raises(RuntimeError, match="before spawn"):
+            await uploads.complete(receipt["id"])
+        saved = backend.db.jobs.find_one({"_id": receipt["id"]})["data"]["context"]
+        assert saved["kind"] == "upload"
+        assert saved["name"] == "crash.bin"
+        assert saved["size"] == 3
+        assert saved["destination_id"]
+        assert saved["local_path"] == str(uploads.path(receipt["id"]))
+        recovered = TransferManager(
+            settings=manager.settings,
+            pool=pool,
+            store=store,
+            remote=FakeRemote(),
+            registry=TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend),
+        )
+        recovered.uploads = ResumableUploads(manager.settings, recovered)
+        await recovered.recover()
+        job = recovered.registry.get(receipt["id"])
+        await job.task
+        assert job.status == TransferStatus.COMPLETED
+        assert store.has_file_operation(job.id)
+        assert len(store.list_directory("/")) == 1
+        assert recovered.uploads.get_unchecked(job.id)["state"] == "finished"
+        assert not uploads.path(job.id).exists()
+    finally:
+        if recovered is not None:
+            await recovered.close()
+        await manager.close()
+        await pool.stop()
+        store.close()
+
+
+async def test_pending_first_browser_job_still_reserves_staging(tmp_path, monkeypatch):
+    manager, store, _telegram, pool = await make_manager(tmp_path)
+    manager.settings.staging_budget_bytes = 5
+    manager.settings.min_free_bytes = 0
+    backend = register_test_backend(monkeypatch, manager.settings)
+    manager.registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    entered, release = hold_write(
+        monkeypatch, backend, lambda row: row["phase"] == "saving"
+    )
+    first = asyncio.create_task(
+        manager.receive_browser_upload(
+            UploadFile(BytesIO(b"one"), size=3, filename="one.bin"), "/"
+        )
+    )
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        assert manager.registry.list() == []
+        assert staging_usage(manager) == (3, 3)
+        second = UploadFile(BytesIO(b"two"), size=3, filename="two.bin")
+        with pytest.raises(StorageUnavailable, match="reserved"):
+            await manager.receive_browser_upload(second, "/")
+        assert second.file.closed
+    finally:
+        release.set()
+    try:
+        job = await first
+        await job.task
+        assert job.status == TransferStatus.COMPLETED
+        assert manager._pending_staging == {}
+    finally:
+        await manager.close()
+        await pool.stop()
+        store.close()
+
+
+@pytest.mark.parametrize("cancel", [False, True])
+async def test_scheduler_releases_ticket_if_awaited_admission_notify_stops(cancel):
+    scheduler = URLDownloadScheduler(1)
+    entered = asyncio.Event()
+
+    async def notify(mode):
+        if mode == "warm":
+            entered.set()
+            if cancel:
+                await asyncio.Event().wait()
+            raise RuntimeError("Synthetic notification failure")
+
+    async def wait(operation):
+        return await operation
+
+    async def use():
+        async with scheduler.admit(wait, changed=notify):
+            pytest.fail("Failed admission must not yield a ticket")
+
+    admission = asyncio.create_task(use())
+    await entered.wait()
+    if cancel:
+        admission.cancel()
+    with pytest.raises(asyncio.CancelledError if cancel else RuntimeError):
+        await admission
+    assert scheduler._tickets == []
+    assert scheduler._monitor is None
+
+
+async def test_concurrent_scheduler_refresh_cannot_exceed_slots_during_notify():
+    scheduler = URLDownloadScheduler(1)
+    ready = False
+    entered, release = asyncio.Event(), asyncio.Event()
+
+    async def wait(operation):
+        return await operation
+
+    async def notify(mode):
+        if mode == "full":
+            entered.set()
+            await release.wait()
+
+    async with AsyncExitStack() as stack:
+        tickets = [
+            await stack.enter_async_context(
+                scheduler.admit(wait, lambda: ready, notify)
+            )
+            for _ in range(3)
+        ]
+        ready = True
+        first = asyncio.create_task(scheduler.refresh())
+        await entered.wait()
+        second = asyncio.create_task(scheduler.refresh())
+        try:
+            await asyncio.sleep(0)
+            assert sum(ticket.full_speed for ticket in tickets) == 1
+            assert not second.done()
+        finally:
+            release.set()
+        await asyncio.gather(first, second)
+        assert sum(ticket.full_speed for ticket in tickets) == 1
diff --git a/tests/transfers/test_lineage_retry.py b/tests/transfers/test_lineage_retry.py
new file mode 100644
index 00000000..d90d078a
--- /dev/null
+++ b/tests/transfers/test_lineage_retry.py
@@ -0,0 +1,157 @@
+"""Provider cooldowns preserve queued uploads instead of failing ordinary files."""
+
+import asyncio
+import time
+from unittest.mock import AsyncMock
+
+from tests.recovery.test_upload_backup_barrier import (
+    MediaClient,
+    manager_for,
+    staged_file,
+)
+from tests.recovery.test_upload_backup_barrier import mongo_backend as mongo_backend
+from tgdrive.recovery.backup import BackupError, RecoveryConflict
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.tasks import TransferStatus
+
+
+async def ready_manager(tmp_path):
+    client = MediaClient()
+    pool = ClientPool([client])
+    await pool.start()
+    callback = AsyncMock(side_effect=lambda revision: revision)
+    return manager_for(tmp_path, pool, callback), pool, client
+
+
+async def close(manager, pool):
+    await manager.registry.shutdown()
+    manager.registry.close()
+    manager.store.close()
+    await pool.stop()
+
+
+async def wait_phase(record, phase):
+    async with asyncio.timeout(2):
+        while record.phase != phase:  # noqa: ASYNC110 - observe durable job state
+            await asyncio.sleep(0.001)
+
+
+async def test_provider_wait_retries_same_upload_and_exposes_deadline(tmp_path):
+    manager, pool, client = await ready_manager(tmp_path)
+    manager._ensure_lineage = AsyncMock(
+        side_effect=[
+            BackupError("Provider cooldown", retry_after=0.05),
+            None,
+        ]
+    )
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    try:
+        await wait_phase(record, "retry_wait")
+        assert record.as_dict()["retry_at"] > time.time()
+        assert not client.sent
+        await asyncio.wait_for(record.task, 2)
+        assert record.status == TransferStatus.COMPLETED
+        assert manager._ensure_lineage.await_count == 2
+        assert len(client.sent) == 1
+        assert "lineage_retry_at" not in record.context
+        assert not source.exists()
+    finally:
+        await close(manager, pool)
+
+
+async def test_cancel_wakes_an_unsent_provider_wait_without_sending(tmp_path):
+    manager, pool, client = await ready_manager(tmp_path)
+    manager._ensure_lineage = AsyncMock(
+        side_effect=BackupError("Provider cooldown", retry_after=3600)
+    )
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    try:
+        await wait_phase(record, "retry_wait")
+        (await manager.cancel_job(record.id))
+        await asyncio.wait_for(record.task, 1)
+        assert record.status == TransferStatus.CANCELLED
+        assert not client.sent
+        assert not source.exists()
+    finally:
+        await close(manager, pool)
+
+
+async def test_confirmed_conflict_never_retries_or_sends(tmp_path):
+    manager, pool, client = await ready_manager(tmp_path)
+    manager._ensure_lineage = AsyncMock(
+        side_effect=RecoveryConflict("Explicit recovery required", retry_after=0.01)
+    )
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    try:
+        await record.task
+        assert record.status == TransferStatus.ERROR
+        assert manager._ensure_lineage.await_count == 1
+        assert not client.sent
+        assert source.exists()
+    finally:
+        await close(manager, pool)
+
+
+async def test_append_admission_uses_local_guard_but_still_waits_for_checkpoint(
+    tmp_path,
+):
+    manager, pool, client = await ready_manager(tmp_path)
+    manager._ensure_lineage = AsyncMock(
+        side_effect=BackupError("Publication cooldown", retry_after=3600)
+    )
+    checked = []
+    manager._check_upload_allowed = lambda: checked.append(len(client.sent))
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    try:
+        assert checked == [0]  # Admission is guarded before background work begins.
+        await asyncio.wait_for(record.task, 2)
+        assert len(checked) >= 2  # A queued job rechecks admission before sending.
+        assert set(checked) == {0}
+        assert manager._ensure_lineage.await_count == 0
+        assert manager._ensure_backup.await_count == 1
+        assert record.status == TransferStatus.COMPLETED
+        assert len(client.sent) == 1
+    finally:
+        await close(manager, pool)
+
+
+async def test_restart_preserves_guard_deadline_and_sends_only_once(
+    tmp_path, monkeypatch
+):
+    manager, pool, client = await ready_manager(tmp_path)
+    manager._ensure_lineage = AsyncMock(
+        side_effect=BackupError("Provider cooldown", retry_after=0.3)
+    )
+    source = staged_file(tmp_path)
+    record = await manager.enqueue_upload(source, "/", "one.bin", source.stat().st_size)
+    await wait_phase(record, "retry_wait")
+    deadline = record.context["lineage_retry_at"]
+    import tgdrive.transfers.tasks as tasks_module
+
+    monkeypatch.setattr(tasks_module, "_SHUTDOWN_DRAIN_SECONDS", 0.001)
+    await manager.registry.shutdown()
+    manager.registry.close()
+    manager.store.close()
+    resumed = manager_for(
+        tmp_path,
+        pool,
+        AsyncMock(side_effect=lambda revision: revision),
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+    )
+    resumed._ensure_lineage = AsyncMock()
+    try:
+        await resumed.recover()
+        recovered = resumed.registry.get(record.id)
+        assert recovered.context["lineage_retry_at"] == deadline
+        await asyncio.sleep(0.01)
+        assert not client.sent
+        await asyncio.wait_for(recovered.task, 2)
+        assert recovered.status == TransferStatus.COMPLETED
+        assert len(client.sent) == 1
+    finally:
+        await close(resumed, pool)
diff --git a/tests/transfers/test_media_upload_scheduling.py b/tests/transfers/test_media_upload_scheduling.py
new file mode 100644
index 00000000..fce4778e
--- /dev/null
+++ b/tests/transfers/test_media_upload_scheduling.py
@@ -0,0 +1,317 @@
+"""Bounded account leasing, shared channel pacing and staged window publication."""
+
+import asyncio
+import hashlib
+import itertools
+import time
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon import types
+from telethon.errors import FloodWaitError
+
+from tgdrive.telegram.client_pool import ClientPool, ClientPoolNotRunning
+from tgdrive.telegram.clients import Client
+from tgdrive.transfers.file_window import FileWindow
+
+
+class Account:
+    def __init__(self, name):
+        self.name = name
+        self.is_connected = False
+
+    async def start(self):
+        self.is_connected = True
+
+    async def stop(self):
+        self.is_connected = False
+
+
+async def test_media_limit_is_per_account_reads_and_second_bot_remain_available():
+    pool = ClientPool([Account("one"), Account("two")])
+    await pool.start()
+    waiting = asyncio.Event()
+    acquired = asyncio.Event()
+
+    async def fixed_second():
+        waiting.set()
+        async with pool.lease(client_name="one", media=True):
+            acquired.set()
+
+    try:
+        async with pool.lease(client_name="one", media=True):
+            task = asyncio.create_task(fixed_second())
+            await waiting.wait()
+            await asyncio.sleep(0)
+            assert not acquired.is_set()
+            async with pool.lease(client_name="one") as read:
+                assert read.name == "one"
+            async with pool.lease(media=True) as other:
+                assert other.name == "two"
+        await task
+        assert acquired.is_set()
+        assert (await pool.health()).active_leases == 0
+    finally:
+        await pool.stop()
+
+
+async def test_stop_wakes_waiting_media_leases_without_deadlock():
+    pool = ClientPool([Account("one")])
+    await pool.start()
+    waiting = asyncio.Event()
+
+    async def another():
+        waiting.set()
+        with pytest.raises(ClientPoolNotRunning):
+            async with pool.lease(media=True):
+                pytest.fail("stopping pool accepted media")
+
+    async with pool.lease(media=True):
+        waiter = asyncio.create_task(another())
+        await waiting.wait()
+        stopping = asyncio.create_task(pool.stop())
+        await waiter
+    await stopping
+
+
+async def test_account_flood_wait_and_channel_flood_wait_have_different_scope():
+    pool = ClientPool([Account("one"), Account("two")])
+    await pool.start()
+    try:
+        await pool.defer_client("one", time.time() + 0.04)
+        async with pool.lease(media=True) as client:
+            assert client.name == "two"
+        await pool.defer_channel(time.time() + 0.04)
+        start = time.monotonic()
+        async with pool.lease(media=True):
+            assert time.monotonic() - start >= 0.025
+    finally:
+        await pool.stop()
+
+
+async def test_send_gate_paces_backups_and_media_on_same_channel():
+    pool = ClientPool(media_send_interval=0.03)
+    times = []
+
+    async def publish():
+        await pool.pace_send(-100123)
+        times.append(time.monotonic())
+
+    await asyncio.gather(publish(), publish(), publish())
+    assert len(times) == 3
+    assert all(b - a >= 0.02 for a, b in itertools.pairwise(times))
+
+
+def test_file_window_cannot_read_or_seek_into_neighbor_parts(tmp_path):
+    path = tmp_path / "staged"
+    path.write_bytes(b"prefixBODYsuffix")
+    with FileWindow(path, 6, 4) as source:
+        assert source.read(512 * 1024) == b"BODY"
+        assert source.read() == b""
+        source.verify(hashlib.sha256(b"BODY").hexdigest())
+        with pytest.raises(ValueError, match="outside"):
+            source.seek(5)
+        source.seek(0)
+        assert source.read(2) == b"BO"
+        assert source.read() == b"DY"
+
+
+class Native:
+    def __init__(self):
+        self.uploaded = []
+        self.requests = []
+        self.fail_publish = False
+        self.fail_blob = False
+        self.get_input_entity = AsyncMock(return_value=types.InputPeerChannel(1, 2))
+
+    async def upload_parts(self, source, *, file_name, length, progress):
+        if self.fail_blob:
+            raise FloodWaitError(request=None, capture=0)
+        data = bytearray()
+        while chunk := source.read(512 * 1024):
+            data.extend(chunk)
+            if progress:
+                await progress(len(data), length)
+        assert len(data) == length
+        self.uploaded.append(bytes(data))
+        return types.InputFileBig(123, 1, file_name)
+
+    async def __call__(self, request):
+        self.requests.append(request)
+        if self.fail_publish:
+            raise FloodWaitError(request=None, capture=0)
+        return SimpleNamespace()
+
+
+def client_for(native):
+    client = Client.__new__(Client)
+    client.native = native
+    client._upload_parts = AsyncMock(side_effect=native.upload_parts)
+    client._sent = AsyncMock(return_value=SimpleNamespace(id=100))
+    return client
+
+
+async def test_window_upload_hashes_exact_bytes_and_checkpoints_before_send(tmp_path):
+    path = tmp_path / "staged"
+    path.write_bytes(b"beforePAYLOADafter")
+    native = Native()
+    client = client_for(native)
+    calls = []
+
+    async def checkpoint():
+        assert native.uploaded == [b"PAYLOAD"]
+        assert native.requests == []
+        calls.append("durable")
+
+    await client.send_staged(
+        -100123,
+        path,
+        file_name="part.bin",
+        random_id=123,
+        offset=6,
+        size=7,
+        expected_sha256=hashlib.sha256(b"PAYLOAD").hexdigest(),
+        before_dispatch=checkpoint,
+    )
+    assert calls == ["durable"]
+    assert native.requests[0].random_id == 123
+    assert native.requests[0].media.force_file
+
+
+async def test_changed_window_or_failed_durable_checkpoint_cannot_publish(tmp_path):
+    path = tmp_path / "staged"
+    path.write_bytes(b"changed")
+    native = Native()
+    client = client_for(native)
+    with pytest.raises(ValueError, match="changed"):
+        await client.send_staged(
+            -100123,
+            path,
+            file_name="part.bin",
+            random_id=123,
+            size=7,
+            expected_sha256=hashlib.sha256(b"ORIGINAL").hexdigest(),
+        )
+    assert native.requests == []
+
+    async def failed_checkpoint():
+        raise OSError("synthetic journal failure")
+
+    with pytest.raises(OSError, match="journal"):
+        await client.send_staged(
+            -100123,
+            path,
+            file_name="part.bin",
+            random_id=123,
+            size=7,
+            expected_sha256=hashlib.sha256(b"changed").hexdigest(),
+            before_dispatch=failed_checkpoint,
+        )
+    assert native.requests == []
+
+
+async def test_actual_sendmedia_flood_defers_shared_channel_but_blob_flood_does_not(
+    tmp_path,
+):
+    path = tmp_path / "staged"
+    path.write_bytes(b"abc")
+    native = Native()
+    client = client_for(native)
+    gate = AsyncMock()
+    defer = AsyncMock()
+    client.bind_send_gate(gate, defer)
+    native.fail_blob = True
+    with pytest.raises(FloodWaitError) as blob:
+        await client.send_staged(-100123, path, file_name="x", random_id=1)
+    assert not getattr(blob.value, "tgdrive_channel_flood", False)
+    defer.assert_not_awaited()
+    native.fail_blob = False
+    native.fail_publish = True
+    with pytest.raises(FloodWaitError) as message:
+        await client.send_staged(-100123, path, file_name="x", random_id=1)
+    assert message.value.tgdrive_channel_flood
+    gate.assert_awaited_once_with(-100123)
+    defer.assert_awaited_once()
+    assert defer.await_args.args[0] >= time.time()
+
+
+@pytest.mark.parametrize("shared_object", [False, True])
+async def test_duplicate_runtime_identity_has_one_usable_media_slot(shared_object):
+    one = Account("same-account")
+    two = one if shared_object else Account("same-account")
+    pool = ClientPool([one, two], allow_partial_start=True)
+    await pool.start()
+    acquired = asyncio.Event()
+
+    async def another():
+        async with pool.lease(media=True):
+            acquired.set()
+
+    try:
+        states = await pool.status()
+        assert sum(item.healthy for item in states) == 1
+        assert any(item.last_error_type == "DuplicateClientIdentity" for item in states)
+        assert (await pool.health()).ready
+        assert one.is_connected
+        if not shared_object:
+            assert not two.is_connected
+        async with pool.lease(media=True) as leased:
+            assert leased is one
+            waiter = asyncio.create_task(another())
+            await asyncio.sleep(0)
+            assert not acquired.is_set()
+        await waiter
+        assert acquired.is_set()
+    finally:
+        await pool.stop()
+
+
+async def test_prestart_account_cooldown_survives_factory_identity_resolution():
+    async def factory():
+        return Account("actual-telegram-account")
+
+    pool = ClientPool([factory], allow_partial_start=True)
+    deadline = time.time() + 30
+    await pool.defer_client("actual-telegram-account", deadline)
+    await pool.start()
+    try:
+        assert pool._slots[0].cooldown_until == deadline
+        assert (await pool.health()).ready
+    finally:
+        await pool.stop()
+
+
+async def test_live_limit_changes_preserve_running_uploads_and_fifo():
+    pool = ClientPool([Account("one")])
+    await pool.start()
+    entered = []
+    releases = [asyncio.Event() for _ in range(4)]
+
+    async def work(index):
+        async with pool.lease(media=True):
+            entered.append(index)
+            await releases[index].wait()
+
+    tasks = [asyncio.create_task(work(index)) for index in range(4)]
+    try:
+        await asyncio.sleep(0.01)
+        assert entered == [0]
+        await pool.set_uploads_per_bot(2)
+        await asyncio.sleep(0.01)
+        assert entered == [0, 1]
+        await pool.set_uploads_per_bot(1)
+        releases[0].set()
+        await asyncio.sleep(0.01)
+        assert entered == [0, 1]  # Existing second lease finishes; no new admission.
+        releases[1].set()
+        await asyncio.sleep(0.01)
+        assert entered == [0, 1, 2]
+        releases[2].set()
+        await asyncio.sleep(0.01)
+        assert entered == [0, 1, 2, 3]
+    finally:
+        for release in releases:
+            release.set()
+        await asyncio.gather(*tasks)
+        await pool.stop()
diff --git a/tests/transfers/test_multipart_transfers.py b/tests/transfers/test_multipart_transfers.py
new file mode 100644
index 00000000..6916af1d
--- /dev/null
+++ b/tests/transfers/test_multipart_transfers.py
@@ -0,0 +1,845 @@
+"""Small-threshold integration probes for durable multi-message logical files."""
+
+import asyncio
+import hashlib
+import threading
+import time
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from telethon.errors import FloodWaitError
+
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.storage.mongo import for_directory
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.manager import TransferError, TransferManager
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path)
+
+
+def registry_for(directory):
+    backend = for_directory(directory)
+    return TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+
+
+class Ledger:
+    def __init__(self):
+        self.messages = {}
+        self.requests = {}
+        self.calls = []
+        self.next_id = 100
+        self.lose_once = False
+        self.flood_seconds = 0
+        self.rpc_delay = 0
+        self.fail_cleanup = False
+        self.flood_cleanup = False
+        self.hold = False
+        self.dispatched = asyncio.Event()
+        self.both_dispatched = asyncio.Event()
+        self.three_dispatched = asyncio.Event()
+        self.flooded = asyncio.Event()
+        self.release = asyncio.Event()
+        self.active = {}
+        self.max_active = {}
+
+
+class Account:
+    def __init__(self, name, ledger, *, flood=False):
+        self.name = name
+        self.ledger = ledger
+        self.flood = flood
+        self.is_connected = False
+
+    async def start(self):
+        self.is_connected = True
+
+    async def stop(self):
+        self.is_connected = False
+
+    async def send_staged(
+        self,
+        channel,
+        path,
+        *,
+        file_name,
+        random_id,
+        progress,
+        offset,
+        size,
+        expected_sha256,
+        before_dispatch,
+    ):
+        state = self.ledger
+        state.active[self.name] = state.active.get(self.name, 0) + 1
+        state.max_active[self.name] = max(
+            state.max_active.get(self.name, 0), state.active[self.name]
+        )
+        try:
+            state.calls.append((self.name, random_id, offset, size))
+            if self.flood:
+                self.flood = False
+                state.flooded.set()
+                raise FloodWaitError(request=None, capture=state.flood_seconds)
+            content = path.read_bytes()[offset : offset + size]
+            assert len(content) == size
+            assert hashlib.sha256(content).hexdigest() == expected_sha256
+            await progress(size, size)
+            (await before_dispatch())
+            if state.rpc_delay:
+                await asyncio.sleep(state.rpc_delay)
+            key = (self.name, random_id)
+            if key not in state.requests:
+                state.next_id += 1
+                message = SimpleNamespace(
+                    id=state.next_id,
+                    document=SimpleNamespace(file_size=size),
+                    content=content,
+                )
+                message.native = SimpleNamespace(
+                    document=SimpleNamespace(id=10_000 + message.id),
+                )
+                state.messages[message.id] = message
+                state.requests[key] = message.id
+            state.dispatched.set()
+            if len(state.messages) >= 2:
+                state.both_dispatched.set()
+            if len(state.messages) >= 3:
+                state.three_dispatched.set()
+            if state.hold:
+                await state.release.wait()
+            if state.lose_once:
+                state.lose_once = False
+                raise TimeoutError("synthetic lost response after remote publication")
+            return state.messages[state.requests[key]]
+        finally:
+            state.active[self.name] -= 1
+
+    async def get_messages(self, channel, *, message_ids):
+        return self.ledger.messages.get(message_ids)
+
+    async def delete_messages(self, channel, message_ids):
+        if self.ledger.fail_cleanup:
+            raise ConnectionError("synthetic unavailable deletion")
+        if self.ledger.flood_cleanup:
+            self.ledger.flood_cleanup = False
+            raise FloodWaitError(request=None, capture=0)
+        for identity in message_ids if isinstance(message_ids, list) else [message_ids]:
+            self.ledger.messages.pop(identity, None)
+
+
+async def manager_for(
+    tmp_path, *, ledger=None, users=False, callback=None, flood=False
+):
+    ledger = ledger or Ledger()
+    bots = [Account("bot-one", ledger, flood=flood), Account("bot-two", ledger)]
+    pool = ClientPool(bots, [Account("premium", ledger)] if users else [])
+    await pool.start()
+    settings = SimpleNamespace(
+        resolved_cache_dir=tmp_path / "cache",
+        max_concurrent_transfers=2,
+        storage_channel=-100123,
+        bot_upload_limit=4,
+        upload_limit=100,
+        staging_budget_bytes=16 * 1024**3,
+        min_free_bytes=0,
+    )
+    manager = TransferManager(
+        settings=settings,
+        pool=pool,
+        store=DriveStore.create(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path),
+        remote=SimpleNamespace(close=AsyncMock()),
+        ensure_backup=callback,
+    )
+    return manager, ledger
+
+
+async def dispose(manager):
+    await manager.close()
+    await manager.pool.stop()
+    manager.registry.close()
+    manager.store.close()
+
+
+def staged(manager, content):
+    source = manager.cache_dir / "source.upload"
+    source.write_bytes(content)
+    return source
+
+
+def stored(manager):
+    rows = manager.store.list_directory("/")
+    assert len(rows) == 1
+    return manager.store.get_file("/" + next(iter(rows)))
+
+
+async def test_bot_only_parts_commit_once_then_checkpoint(tmp_path):
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def protect(revision):
+        entered.set()
+        await release.wait()
+        return revision
+
+    manager, ledger = await manager_for(tmp_path, callback=protect)
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await asyncio.wait_for(entered.wait(), 2)
+        item = stored(manager)
+        assert item["size"] == 10
+        assert [p["size"] for p in item["parts"]] == [4, 4, 2]
+        assert [p["offset"] for p in item["parts"]] == [0, 4, 8]
+        assert item["sha256"] == hashlib.sha256(b"abcdefghij").hexdigest()
+        assert all(p["document_id"] == 10_000 + p["message_id"] for p in item["parts"])
+        assert (
+            b"".join(ledger.messages[p["message_id"]].content for p in item["parts"])
+            == b"abcdefghij"
+        )
+        assert record.phase == "backup_pending"
+        assert source.exists()
+        assert (await manager.pool.health()).active_leases == 0
+        assert all(value == 1 for value in ledger.max_active.values())
+        release.set()
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        assert not source.exists()
+    finally:
+        release.set()
+        await dispose(manager)
+
+
+async def test_lost_response_replays_same_sender_random_id_skips_confirmed_parts(
+    tmp_path,
+):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.lose_once = True
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await record.task
+        assert record.status == TransferStatus.ERROR
+        plan = record.context["multipart_plan"]
+        identities = [(p["sender"], p["random_id"]) for p in plan["parts"]]
+        assert not manager.store.list_directory("/")
+        before_count = len(ledger.messages)
+        record = await manager.retry_job(record.id)
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        for before, part in zip(identities, plan["parts"], strict=True):
+            assert part["random_id"] == before[1]
+            if before[0] is not None:
+                assert part["sender"] == before[0]
+        assert len(ledger.messages) == 3
+        assert before_count <= 3
+        assert len(ledger.requests) == 3
+        assert len(stored(manager)["parts"]) == 3
+    finally:
+        await dispose(manager)
+
+
+async def test_process_restart_reconciles_ambiguous_part_and_reuses_plan(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    await asyncio.wait_for(ledger.dispatched.wait(), 2)
+    original = [
+        (p["random_id"], p["sha256"]) for p in record.context["multipart_plan"]["parts"]
+    ]
+    identity = record.id
+    await manager.close()
+    manager.registry.close()
+    manager.store.close()
+    await manager.pool.stop()
+    ledger.hold = False
+    ledger.release.set()
+    pool = ClientPool([Account("bot-one", ledger), Account("bot-two", ledger)])
+    await pool.start()
+    recovered = TransferManager(
+        settings=manager.settings,
+        pool=pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path),
+        remote=SimpleNamespace(close=AsyncMock()),
+    )
+    try:
+        await recovered.recover()
+        row = recovered.registry.get(identity)
+        await row.task
+        assert row.status == TransferStatus.COMPLETED
+        assert [
+            (p["random_id"], p["sha256"])
+            for p in row.context["multipart_plan"]["parts"]
+        ] == original
+        assert len(ledger.requests) == len(ledger.messages) == 3
+        assert len(stored(recovered)["parts"]) == 3
+    finally:
+        await dispose(recovered)
+
+
+async def test_cancel_reconciles_and_deletes_every_own_part_before_unlink(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    source = staged(manager, b"abcdefghijkl")
+    record = await manager.enqueue_upload(source, "/", "twelve.bin", 12)
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        (await manager.cancel_job(record.id))
+        assert source.exists()
+        ledger.release.set()
+        await record.task
+        assert record.status == TransferStatus.CANCELLED
+        assert ledger.messages == {}
+        assert not manager.store.list_directory("/")
+        assert not source.exists()
+        assert all(
+            p.get("deleted")
+            for p in record.context["multipart_plan"]["parts"]
+            if p.get("message_id")
+        )
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_cancel_cleanup_failure_retains_bytes_and_retries_cleanup(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    ledger.fail_cleanup = True
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        (await manager.cancel_job(record.id))
+        ledger.release.set()
+        await record.task
+        assert record.status != TransferStatus.CANCELLED
+        assert source.exists() and ledger.messages
+        assert manager.store.list_directory("/") == {}
+        sent = len(ledger.requests)
+        ledger.fail_cleanup = False
+        record = await manager.retry_job(record.id)
+        await record.task
+        assert record.status == TransferStatus.CANCELLED
+        assert not source.exists() and not ledger.messages
+        assert len(ledger.requests) == sent
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+@pytest.mark.parametrize("healthy", [True, False])
+@pytest.mark.parametrize("split_mib", [0, 2000])
+async def test_premium_never_raises_new_part_size(tmp_path, healthy, split_mib):
+    manager, ledger = await manager_for(tmp_path, users=True)
+    manager.settings.upload_split_mib = split_mib
+    if not healthy:
+        user = next(slot.client for slot in manager.pool._slots if slot.kind == "user")
+        await manager.pool.mark_unhealthy(user)
+    source = staged(manager, b"abcdef")
+    record = await manager.enqueue_upload(source, "/", "six.bin", 6)
+    try:
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        assert [part["size"] for part in stored(manager)["parts"]] == [4, 2]
+        assert record.context["multipart_plan"]["kind"] == "bot"
+        assert ledger.calls[0][0] == ("premium" if healthy else "bot-one")
+    finally:
+        await dispose(manager)
+
+
+async def test_smaller_split_applies_to_premium_and_preserves_original(tmp_path):
+    manager, ledger = await manager_for(tmp_path, users=True)
+    manager.settings.bot_upload_limit = 4 * 1024**2
+    manager.settings.upload_split_mib = 1
+    payload = b"a" * (3 * 1024**2 + 7)
+    record = await manager.enqueue_upload(
+        staged(manager, payload), "/", "data.bin", len(payload)
+    )
+    try:
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        parts = stored(manager)["parts"]
+        assert [part["size"] for part in parts] == [1024**2] * 3 + [7]
+        assert ledger.calls[0][0] == "premium"
+        assert (
+            b"".join(ledger.messages[p["message_id"]].content for p in parts) == payload
+        )
+    finally:
+        await dispose(manager)
+
+
+async def test_obsolete_premium_sized_plan_is_rejected_without_sending(tmp_path):
+    from tgdrive.transfers.multipart_transfer import fingerprint
+
+    manager, ledger = await manager_for(tmp_path, users=True)
+    payload = b"abcdef"
+    source = staged(manager, payload)
+    checksum, parts = fingerprint(source, len(payload), len(payload))
+    parts[0]["sender"] = "premium"
+    record = await manager.registry.create("queued", total=len(payload))
+    record.context.update(
+        sha256=checksum,
+        multipart_plan=dict(version=1, kind="user", parts=parts),
+    )
+    (await manager.registry.persist(record))
+    try:
+        with pytest.raises(TransferError, match="multipart journal is invalid"):
+            await manager._upload_path(record, source, "/", "old.bin", len(payload))
+        assert source.read_bytes() == payload
+        assert not ledger.calls and not ledger.messages
+        assert manager.store.list_directory("/") == {}
+        assert record.context["multipart_plan"]["kind"] == "user"
+    finally:
+        await dispose(manager)
+
+
+async def test_upload_part_flood_wait_persists_fixed_sender_and_retries(tmp_path):
+    manager, ledger = await manager_for(tmp_path, flood=True)
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        first = ledger.calls[0]
+        repeated = [call for call in ledger.calls if call[1] == first[1]]
+        assert len(repeated) == 2
+        assert {call[0] for call in repeated} == {first[0]}
+        assert len(ledger.messages) == 3
+    finally:
+        await dispose(manager)
+
+
+async def test_global_media_slot_not_held_while_fixed_sender_cooling(tmp_path):
+    manager, _ledger = await manager_for(tmp_path)
+    await manager.pool.defer_client("bot-one", time.time() + 0.05)
+    async with manager.pool.lease(client_name="bot-one", media=True) as client:
+        assert client.name == "bot-one"
+    assert manager._semaphore._value == 2
+    await dispose(manager)
+
+
+async def test_cancel_refuses_to_delete_replaced_remote_document(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        (await manager.cancel_job(record.id))
+        ledger.release.set()
+        # Replace only during cleanup, after the accepted identity was journalled.
+        original = manager._verify_lineage
+
+        async def replace_before_delete(item=None):
+            if any(
+                p.get("document_id") for p in record.context["multipart_plan"]["parts"]
+            ):
+                message = next(iter(ledger.messages.values()))
+                message.native.document.id += 1
+            await original(item)
+
+        manager._verify_lineage = replace_before_delete
+        await record.task
+        assert record.status != TransferStatus.CANCELLED
+        assert source.exists()
+        assert ledger.messages
+        assert manager.store.list_directory("/") == {}
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_refetch_rejects_changed_native_document_identity(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    # Fail catalog publication after all piece identities have been persisted.
+    original = manager.store.add_file
+    manager.store.add_file = lambda *a, **kw: (_ for _ in ()).throw(
+        OSError("synthetic commit error")
+    )
+    try:
+        await record.task
+        assert record.status == TransferStatus.ERROR
+        part = record.context["multipart_plan"]["parts"][0]
+        part["confirmed"] = False
+        ledger.messages[part["message_id"]].native.document.id += 1
+        (await manager.registry.persist(record))
+        manager.store.add_file = original
+        retried = await manager.retry_job(record.id)
+        await retried.task
+        assert retried.status == TransferStatus.ERROR
+        assert "identity changed" in retried.error
+        assert source.exists()
+        assert manager.store.list_directory("/") == {}
+    finally:
+        await dispose(manager)
+
+
+async def test_cleanup_flood_wait_is_durable_and_does_not_rotate_sender(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    ledger.flood_cleanup = True
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        (await manager.cancel_job(record.id))
+        ledger.release.set()
+        await record.task
+        assert record.status == TransferStatus.CANCELLED
+        assert record.context["channel_retry_at"] > 0
+        assert not ledger.messages
+        assert not source.exists()
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_one_flooding_part_does_not_hide_other_active_part_progress(tmp_path):
+    manager, ledger = await manager_for(tmp_path, flood=True)
+    ledger.hold = True
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        assert ledger.flooded.is_set()
+        assert record.phase in {"uploading", "finalizing"}
+        assert record.as_dict()["retry_at"] is None
+        ledger.release.set()
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_fully_waiting_logical_upload_exposes_provider_retry_deadline(tmp_path):
+    manager, ledger = await manager_for(tmp_path, flood=True)
+    second = next(slot.client for slot in manager.pool._slots if slot.name == "bot-two")
+    await manager.pool.mark_unhealthy(second)
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    try:
+        await asyncio.wait_for(ledger.flooded.wait(), 2)
+        async with asyncio.timeout(2):
+            while record.phase != "retry_wait":  # noqa: ASYNC110 - observe committed state
+                await asyncio.sleep(0.001)
+        assert record.phase == "retry_wait"
+        assert record.as_dict()["retry_at"] > time.time()
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+    finally:
+        await dispose(manager)
+
+
+@pytest.mark.parametrize("lost_acknowledgement", [False, True])
+async def test_cancel_recovery_skips_deleted_unconfirmed_parts(
+    tmp_path,
+    monkeypatch,
+    lost_acknowledgement,
+):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    calls = 0
+    failed = False
+    originals = []
+
+    for slot in manager.pool._slots:
+        client = slot.client
+        original = client.delete_messages
+        originals.append((client, original))
+
+        async def interrupted_delete(channel, identities, *, original=original):
+            nonlocal calls, failed
+            calls += 1
+            if calls == 2 and not failed:
+                failed = True
+                raise ConnectionError("synthetic second-part cleanup interruption")
+            await original(channel, identities)
+
+        monkeypatch.setattr(client, "delete_messages", interrupted_delete)
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        # Let both worker dispatches reach the remote-effect boundary.
+        await asyncio.wait_for(ledger.both_dispatched.wait(), 2)
+        (await manager.cancel_job(record.id))
+        ledger.release.set()
+        await record.task
+        assert record.status == TransferStatus.QUEUED
+        assert source.exists()
+        parts = record.context["multipart_plan"]["parts"]
+        deleted = [p for p in parts if p.get("deleted")]
+        assert len(deleted) == 1
+        assert not deleted[0]["confirmed"]
+        if lost_acknowledgement:
+            deleted[0].pop("deleted")
+            (await manager.registry.persist(record))
+        requests = len(ledger.requests)
+        for client, original in originals:
+            monkeypatch.setattr(client, "delete_messages", original)
+        retried = await manager.retry_job(record.id)
+        await retried.task
+        assert retried.status == TransferStatus.CANCELLED
+        assert not ledger.messages
+        assert not source.exists()
+        assert len(ledger.requests) == requests
+        assert manager.store.list_directory("/") == {}
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_restart_restores_flood_cooldown_from_terminal_error_job(tmp_path):
+    manager, ledger = await manager_for(tmp_path, flood=True)
+    ledger.flood_seconds = 30
+    ledger.lose_once = True
+    source = staged(manager, b"abcdefghij")
+    failed = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    await failed.task
+    assert failed.status == TransferStatus.ERROR
+    assert failed.context["multipart_plan"]["parts"][0]["retry_at"] > time.time()
+    await manager.close()
+    manager.registry.close()
+    manager.store.close()
+    await manager.pool.stop()
+    pool = ClientPool([Account("bot-one", ledger), Account("bot-two", ledger)])
+    await pool.start()
+    recovered = TransferManager(
+        settings=manager.settings,
+        pool=pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path),
+        remote=SimpleNamespace(close=AsyncMock()),
+    )
+    try:
+        await recovered.recover()
+        resumed = recovered.registry.get(failed.id)
+        assert resumed.task is not None
+        assert resumed.context["multipart_plan"]["parts"][0]["retry_at"] > time.time()
+        before = len(ledger.calls)
+        fresh = manager.cache_dir / "new.upload"
+        fresh.write_bytes(b"x")
+        job = await recovered.enqueue_upload(fresh, "/", "new.bin", 1)
+        await asyncio.wait_for(job.task, 2)
+        assert job.status == TransferStatus.COMPLETED
+        assert ledger.calls[-1][0] == "bot-two"
+        assert all(call[0] != "bot-one" for call in ledger.calls[before:])
+        assert time.time() < failed.context["multipart_plan"]["parts"][0]["retry_at"]
+        assert not resumed.task.done()
+    finally:
+        await dispose(recovered)
+
+
+async def test_recover_hydrates_channel_cooldown_before_any_lineage_await(tmp_path):
+    manager, _ = await manager_for(tmp_path)
+    row = await manager.registry.create("failed")
+    row.status = TransferStatus.ERROR
+    row.context.update(kind="upload", channel_retry_at=time.time() + 30)
+    (await manager.registry.persist(row))
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def guard():
+        entered.set()
+        await release.wait()
+
+    # This pending row makes recover await lineage after loading all cooldowns.
+    (await manager.registry.create("queued"))
+    manager._ensure_lineage = guard
+    recovering = asyncio.create_task(manager.recover())
+    try:
+        await asyncio.wait_for(entered.wait(), 2)
+        assert manager.pool._channel_cooldown_until >= row.context["channel_retry_at"]
+        assert all(slot.active == 0 for slot in manager.pool._slots)
+    finally:
+        release.set()
+        await recovering
+        await dispose(manager)
+
+
+@pytest.mark.parametrize("user_cancel", [False, True])
+async def test_hash_thread_is_drained_and_stage_cleanup_distinguishes_shutdown(
+    tmp_path,
+    monkeypatch,
+    user_cancel,
+):
+    from tgdrive.transfers import multipart_transfer
+
+    manager, ledger = await manager_for(tmp_path)
+    source = staged(manager, b"abcdefghij")
+    entered = asyncio.Event()
+    release = threading.Event()
+    finished = threading.Event()
+    loop = asyncio.get_running_loop()
+    original = multipart_transfer.fingerprint
+
+    def slow_hash(*args, **kwargs):
+        loop.call_soon_threadsafe(entered.set)
+        try:
+            assert release.wait(2)
+            return original(*args, **kwargs)
+        finally:
+            finished.set()
+
+    monkeypatch.setattr(multipart_transfer, "fingerprint", slow_hash)
+    record = await manager.enqueue_upload(source, "/", "ten.bin", 10)
+    shutdown = None
+    try:
+        await asyncio.wait_for(entered.wait(), 2)
+        if user_cancel:
+            (await manager.cancel_job(record.id))
+            record.task.cancel()
+        else:
+            shutdown = asyncio.create_task(manager.registry.shutdown())
+        await asyncio.sleep(0)
+        assert source.exists()
+        assert not finished.is_set()
+        assert manager._semaphore._value == 1
+        release.set()
+        if shutdown is not None:
+            await shutdown
+        await asyncio.gather(record.task, return_exceptions=True)
+        assert finished.is_set()
+        assert manager._semaphore._value == 2
+        assert ledger.messages == {}
+        if user_cancel:
+            assert record.status == TransferStatus.CANCELLED
+            assert not source.exists()
+        else:
+            assert record.status == TransferStatus.QUEUED
+            assert source.exists()
+    finally:
+        release.set()
+        if shutdown is not None:
+            await shutdown
+        await dispose(manager)
+
+
+async def test_queued_small_file_gets_media_turn_before_large_file_finishes(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.rpc_delay = 0.005
+    large = staged(manager, b"x" * 40)
+    big = await manager.enqueue_upload(large, "/", "large.bin", 40)
+    try:
+        await asyncio.wait_for(ledger.both_dispatched.wait(), 2)
+        small = manager.cache_dir / "small.upload"
+        small.write_bytes(b"z")
+        tiny = await manager.enqueue_upload(small, "/", "small.bin", 1)
+        await asyncio.gather(big.task, tiny.task)
+        assert big.status == tiny.status == TransferStatus.COMPLETED
+        small_turn = next(
+            index for index, call in enumerate(ledger.calls) if call[3] == 1
+        )
+        assert small_turn < 10
+        assert all(value == 1 for value in ledger.max_active.values())
+    finally:
+        await dispose(manager)
+
+
+async def test_three_bots_upload_ready_files_without_global_two_upload_cap(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    await manager.pool.stop()
+    manager.pool = ClientPool([Account(name, ledger) for name in ("a", "b", "c")])
+    await manager.pool.start()
+    ledger.hold = True
+    records = []
+    try:
+        for index in range(4):
+            source = manager.cache_dir / ("ready-" + str(index))
+            source.write_bytes(b"ab")
+            records.append(await manager.enqueue_upload(source, "/", source.name, 2))
+        async with asyncio.timeout(3):
+            await ledger.three_dispatched.wait()
+        await asyncio.sleep(0.05)  # Let the fourth fingerprint finish and queue.
+        assert len(ledger.calls) == 3
+        assert sorted(ledger.max_active.values()) == [1, 1, 1]
+        assert any(row.status is TransferStatus.QUEUED for row in records)
+        ledger.release.set()
+        async with asyncio.timeout(3):
+            await asyncio.gather(*(record.task for record in records))
+        assert all(row.status is TransferStatus.COMPLETED for row in records)
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+@pytest.mark.parametrize("mixed_clients", [False, True])
+async def test_one_large_file_uses_every_eligible_client_slot(tmp_path, mixed_clients):
+    manager, ledger = await manager_for(tmp_path)
+    await manager.pool.stop()
+    names = ("a", "b", "c")
+    manager.pool = ClientPool(
+        [Account(name, ledger) for name in (names[:2] if mixed_clients else names)],
+        [Account("c", ledger)] if mixed_clients else [],
+    )
+    await manager.pool.start()
+    ledger.hold = True
+    source = staged(
+        manager, b"abcdefghij"
+    )  # Three bot-compatible parts, > Premium limit.
+    record = await manager.enqueue_upload(source, "/", "large.bin", 10)
+    try:
+        await asyncio.wait_for(ledger.three_dispatched.wait(), 2)
+        assert len(ledger.calls) == 3
+        assert set(ledger.max_active) == set(names)
+        assert all(count == 1 for count in ledger.max_active.values())
+        assert not manager.store.list_directory("/")
+        if mixed_clients:
+            (await manager.cancel_job(record.id))
+        ledger.release.set()
+        await asyncio.wait_for(record.task, 2)
+        if mixed_clients:
+            assert record.status == TransferStatus.CANCELLED
+            assert ledger.messages == {}
+        else:
+            assert record.status == TransferStatus.COMPLETED
+            assert (
+                b"".join(
+                    ledger.messages[p["message_id"]].content
+                    for p in stored(manager)["parts"]
+                )
+                == b"abcdefghij"
+            )
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_multipart_workers_follow_live_per_bot_limit(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    await manager.pool.stop()
+    manager.pool = ClientPool([Account("a", ledger)])
+    await manager.pool.start()
+    ledger.hold = True
+    record = await manager.enqueue_upload(
+        staged(manager, b"x" * 12), "/", "large.bin", 12
+    )
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        assert len(ledger.calls) == 1
+        await manager.pool.set_uploads_per_bot(2)
+        await asyncio.wait_for(ledger.both_dispatched.wait(), 3)
+        assert ledger.max_active == {"a": 2}
+        await manager.pool.set_uploads_per_bot(1)
+        assert ledger.active == {
+            "a": 2
+        }  # Lowering drains; it never cancels current sends.
+        ledger.release.set()
+        await asyncio.wait_for(record.task, 2)
+        assert record.status == TransferStatus.COMPLETED
+        assert ledger.max_active == {"a": 2}
+    finally:
+        ledger.release.set()
+        await dispose(manager)
diff --git a/tests/transfers/test_remote.py b/tests/transfers/test_remote.py
new file mode 100644
index 00000000..5a735da9
--- /dev/null
+++ b/tests/transfers/test_remote.py
@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import socket
+import tempfile
+import threading
+import unittest
+from collections import deque
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import patch
+
+from aiohttp.abc import AbstractResolver
+
+from tgdrive.transfers.remote import (
+    RemoteCancelled,
+    RemoteClient,
+    RemoteDestinationExists,
+    RemoteError,
+    RemoteTooLarge,
+    TooManyRedirects,
+    UnsafeRemoteURL,
+    ValidatingResolver,
+    safe_filename,
+)
+
+
+class FakeResolver(AbstractResolver):
+    def __init__(self, answers: dict[str, list[str]]) -> None:
+        self.answers = answers
+        self.calls: list[tuple[str, int, int]] = []
+        self.closed = False
+
+    async def resolve(
+        self,
+        host: str,
+        port: int = 0,
+        family: int = socket.AF_INET,
+    ) -> list[dict[str, Any]]:
+        self.calls.append((host, port, family))
+        return [
+            {
+                "hostname": host,
+                "host": address,
+                "port": port,
+                "family": socket.AF_INET6 if ":" in address else socket.AF_INET,
+                "proto": 0,
+                "flags": 0,
+            }
+            for address in self.answers.get(host, [])
+        ]
+
+    async def close(self) -> None:
+        self.closed = True
+
+
+class FakeContent:
+    def __init__(self, chunks: list[bytes] | None = None) -> None:
+        self.chunks = deque(chunks or [])
+
+    async def read(self, limit: int) -> bytes:
+        await asyncio.sleep(0)
+        if not self.chunks:
+            return b""
+        chunk = self.chunks.popleft()
+        if len(chunk) > limit:
+            self.chunks.appendleft(chunk[limit:])
+            return chunk[:limit]
+        return chunk
+
+
+class FakeResponse:
+    def __init__(
+        self,
+        status: int,
+        *,
+        headers: dict[str, str] | None = None,
+        chunks: list[bytes] | None = None,
+    ) -> None:
+        self.status = status
+        self.headers = headers or {}
+        self.content = FakeContent(chunks)
+        self.released = False
+
+    def release(self) -> None:
+        self.released = True
+
+
+class FakeSession:
+    def __init__(self, responses: list[FakeResponse]) -> None:
+        self.responses = deque(responses)
+        self.calls: list[tuple[str, str, dict[str, Any]]] = []
+        self.closed = False
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> FakeResponse:
+        self.calls.append((method, url, kwargs))
+        if not self.responses:
+            raise AssertionError("unexpected request")
+        return self.responses.popleft()
+
+    async def close(self) -> None:
+        self.closed = True
+
+
+PUBLIC_DNS = {"files.example": ["93.184.216.34"]}
+NON_PUBLIC_REMOTE_ADDRESSES = (
+    "100.64.0.1",
+    "100.100.100.200",
+    "100.127.255.254",
+    "::ffff:100.100.100.200",
+    "fec0::1",
+)
+
+
+class ConstructionTests(unittest.TestCase):
+    def test_client_can_be_constructed_without_a_running_event_loop(self) -> None:
+        client = RemoteClient()
+        asyncio.run(client.close())
+
+
+class ResolverPolicyTests(unittest.IsolatedAsyncioTestCase):
+    async def test_every_dns_answer_must_be_public(self) -> None:
+        resolver = ValidatingResolver(
+            FakeResolver({"mixed.example": ["93.184.216.34", "127.0.0.1"]})
+        )
+
+        with self.assertRaisesRegex(UnsafeRemoteURL, "non-public"):
+            await resolver.resolve("mixed.example", 443, socket.AF_UNSPEC)
+
+    async def test_shared_and_site_local_dns_answers_are_not_public(self) -> None:
+        for address in NON_PUBLIC_REMOTE_ADDRESSES:
+            with self.subTest(address=address):
+                resolver = ValidatingResolver(
+                    FakeResolver({"mixed.example": ["93.184.216.34", address]})
+                )
+                with self.assertRaisesRegex(UnsafeRemoteURL, "non-public"):
+                    await resolver.resolve("mixed.example", 443, socket.AF_UNSPEC)
+
+    async def test_explicit_allow_private_bypasses_address_policy(self) -> None:
+        for address in ("127.0.0.1", *NON_PUBLIC_REMOTE_ADDRESSES):
+            with self.subTest(address=address):
+                session = FakeSession(
+                    [
+                        FakeResponse(200, headers={"Content-Length": "1"})
+                        for _ in range(2)
+                    ]
+                )
+                client = RemoteClient(
+                    allow_private=True,
+                    session=session,
+                    resolver=FakeResolver({"internal.example": [address]}),
+                )
+
+                info = await client.inspect("http://internal.example/file.txt")
+                self.assertEqual(info.size, 1)
+                host = f"[{address}]" if ":" in address else address
+                info = await client.inspect(f"http://{host}/file.txt")
+                self.assertEqual(info.size, 1)
+                self.assertEqual(len(session.calls), 2)
+
+
+class RemoteInspectionTests(unittest.IsolatedAsyncioTestCase):
+    async def test_shared_and_site_local_literals_are_rejected_before_request(
+        self,
+    ) -> None:
+        session = FakeSession([])
+        client = RemoteClient(session=session, resolver=FakeResolver({}))
+        for address in NON_PUBLIC_REMOTE_ADDRESSES:
+            host = f"[{address}]" if ":" in address else address
+            with self.subTest(address=address), self.assertRaises(UnsafeRemoteURL):
+                await client.inspect(f"http://{host}/file.txt")
+        self.assertEqual(session.calls, [])
+
+    async def test_rejects_non_http_and_url_userinfo_before_request(self) -> None:
+        session = FakeSession([])
+        client = RemoteClient(
+            session=session,
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+
+        for url in (
+            "file:///etc/passwd",
+            "ftp://files.example/a",
+            "https://user:secret@files.example/a",
+        ):
+            with self.subTest(url=url), self.assertRaises(UnsafeRemoteURL):
+                await client.inspect(url)
+        self.assertEqual(session.calls, [])
+
+    async def test_inspection_uses_identity_and_content_range_total(self) -> None:
+        response = FakeResponse(
+            206,
+            headers={
+                "Content-Range": "bytes 0-0/12",
+                "Content-Disposition": 'attachment; filename="../../report.txt"',
+                "Content-Type": "text/plain; charset=utf-8",
+                "ETag": '"abc"',
+            },
+        )
+        session = FakeSession([response])
+        resolver = FakeResolver(PUBLIC_DNS)
+        client = RemoteClient(session=session, resolver=resolver)
+
+        info = await client.inspect("https://files.example/fallback.bin#fragment")
+
+        self.assertEqual(info.filename, "report.txt")
+        self.assertEqual(info.size, 12)
+        self.assertEqual(info.content_type, "text/plain")
+        self.assertEqual(info.url, "https://files.example/fallback.bin")
+        self.assertTrue(response.released)
+        request_headers = session.calls[0][2]["headers"]
+        self.assertEqual(request_headers["Accept-Encoding"], "identity")
+        self.assertEqual(request_headers["Range"], "bytes=0-0")
+        self.assertFalse(session.calls[0][2]["allow_redirects"])
+        self.assertEqual(resolver.calls[0][0], "files.example")
+
+    async def test_redirect_target_is_validated_before_following(self) -> None:
+        redirect = FakeResponse(
+            302,
+            headers={"Location": "http://internal.example/secret"},
+        )
+        session = FakeSession([redirect])
+        resolver = FakeResolver(
+            {
+                "files.example": ["93.184.216.34"],
+                "internal.example": ["169.254.169.254"],
+            }
+        )
+        client = RemoteClient(session=session, resolver=resolver)
+
+        with self.assertRaises(UnsafeRemoteURL):
+            await client.inspect("https://files.example/file")
+
+        self.assertEqual(len(session.calls), 1)
+        self.assertTrue(redirect.released)
+
+    async def test_redirect_cannot_reach_shared_or_site_local_dns_answers(self) -> None:
+        for address in NON_PUBLIC_REMOTE_ADDRESSES:
+            with self.subTest(address=address):
+                redirect = FakeResponse(
+                    302, headers={"Location": "http://internal.example/secret"}
+                )
+                session = FakeSession([redirect])
+                client = RemoteClient(
+                    session=session,
+                    resolver=FakeResolver(
+                        {**PUBLIC_DNS, "internal.example": [address]}
+                    ),
+                )
+
+                with self.assertRaises(UnsafeRemoteURL):
+                    await client.inspect("https://files.example/file")
+
+                self.assertEqual(len(session.calls), 1)
+                self.assertTrue(redirect.released)
+
+    async def test_manual_redirect_limit_is_bounded(self) -> None:
+        redirects = [
+            FakeResponse(302, headers={"Location": "/next"}),
+            FakeResponse(302, headers={"Location": "/again"}),
+        ]
+        client = RemoteClient(
+            max_redirects=1,
+            session=FakeSession(redirects),
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+
+        with self.assertRaises(TooManyRedirects):
+            await client.inspect("https://files.example/start")
+
+
+class RemoteDownloadTests(unittest.IsolatedAsyncioTestCase):
+    async def test_free_space_checks_run_off_loop_and_reject_before_writing(self):
+        response = FakeResponse(200, headers={"Content-Length": "3"}, chunks=[b"abc"])
+        client = RemoteClient(
+            min_free_bytes=10,
+            session=FakeSession([response]),
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+        loop_thread = threading.get_ident()
+
+        def disk_usage(_directory):
+            self.assertNotEqual(threading.get_ident(), loop_thread)
+            return SimpleNamespace(free=12)
+
+        with tempfile.TemporaryDirectory() as directory:
+            with (
+                patch(
+                    "tgdrive.transfers.remote.shutil.disk_usage", side_effect=disk_usage
+                ),
+                self.assertRaisesRegex(RemoteError, "Temporary storage is full"),
+            ):
+                await client.download("https://files.example/a", directory)
+            self.assertEqual(list(Path(directory).iterdir()), [])
+        self.assertTrue(response.released)
+
+    async def test_successful_single_stream_download_and_progress(self) -> None:
+        redirect = FakeResponse(307, headers={"Location": "/final/report.txt"})
+        body = FakeResponse(
+            200,
+            headers={"Content-Length": "6", "Content-Type": "text/plain"},
+            chunks=[b"abc", b"def"],
+        )
+        session = FakeSession([redirect, body])
+        client = RemoteClient(
+            max_bytes=10,
+            chunk_size=3,
+            session=session,
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+        progress: list[tuple[int, int | None]] = []
+
+        with tempfile.TemporaryDirectory() as directory:
+            result = await client.download(
+                "https://files.example/start",
+                directory,
+                progress=lambda current, total: progress.append((current, total)),
+            )
+
+            self.assertEqual(result.filename, "report.txt")
+            self.assertEqual(result.size, 6)
+            self.assertEqual(result.path.read_bytes(), b"abcdef")
+            self.assertEqual(progress, [(0, 6), (3, 6), (6, 6)])
+            names = await asyncio.to_thread(os.listdir, directory)
+            self.assertFalse(any(name.endswith(".part") for name in names))
+        self.assertTrue(redirect.released)
+        self.assertTrue(body.released)
+
+    async def test_declared_size_cap_rejects_before_writing(self) -> None:
+        response = FakeResponse(200, headers={"Content-Length": "11"})
+        client = RemoteClient(
+            max_bytes=10,
+            session=FakeSession([response]),
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+
+        with tempfile.TemporaryDirectory() as directory:
+            with self.assertRaises(RemoteTooLarge):
+                await client.download("https://files.example/large.bin", directory)
+            self.assertEqual(await asyncio.to_thread(os.listdir, directory), [])
+
+    async def test_streamed_size_cap_removes_partial_file(self) -> None:
+        response = FakeResponse(200, chunks=[b"123456", b"789012"])
+        client = RemoteClient(
+            max_bytes=10,
+            chunk_size=6,
+            session=FakeSession([response]),
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+
+        with tempfile.TemporaryDirectory() as directory:
+            with self.assertRaises(RemoteTooLarge):
+                await client.download("https://files.example/unknown.bin", directory)
+            self.assertEqual(await asyncio.to_thread(os.listdir, directory), [])
+
+    async def test_cancellation_event_interrupts_and_cleans_partial(self) -> None:
+        response = FakeResponse(200, chunks=[b"abc", b"def"])
+        cancel = asyncio.Event()
+        client = RemoteClient(
+            max_bytes=10,
+            chunk_size=3,
+            session=FakeSession([response]),
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+
+        def progress(current: int, _total: int | None) -> None:
+            if current == 3:
+                cancel.set()
+
+        with tempfile.TemporaryDirectory() as directory:
+            with self.assertRaises(RemoteCancelled):
+                await client.download(
+                    "https://files.example/cancel.bin",
+                    directory,
+                    cancel_event=cancel,
+                    progress=progress,
+                )
+            self.assertEqual(await asyncio.to_thread(os.listdir, directory), [])
+
+    async def test_existing_destination_is_not_overwritten_by_default(self) -> None:
+        response = FakeResponse(200, headers={"Content-Length": "1"}, chunks=[b"x"])
+        client = RemoteClient(
+            session=FakeSession([response]),
+            resolver=FakeResolver(PUBLIC_DNS),
+        )
+
+        with tempfile.TemporaryDirectory() as directory:
+            destination = Path(directory) / "file.bin"
+            destination.write_bytes(b"original")
+            with self.assertRaises(RemoteDestinationExists):
+                await client.download("https://files.example/file.bin", directory)
+            self.assertEqual(destination.read_bytes(), b"original")
+
+
+class SafeFilenameTests(unittest.TestCase):
+    def test_filename_strips_paths_controls_and_windows_devices(self) -> None:
+        self.assertEqual(
+            safe_filename('attachment; filename="..\\..\\safe.txt"', "https://x/a"),
+            "safe.txt",
+        )
+        self.assertEqual(safe_filename(None, "https://x/%43ON"), "_CON")
+        self.assertEqual(
+            safe_filename(None, "https://x/", "application/pdf"),
+            "download.pdf",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/transfers/test_remote_job_recovery.py b/tests/transfers/test_remote_job_recovery.py
new file mode 100644
index 00000000..5a43c1cb
--- /dev/null
+++ b/tests/transfers/test_remote_job_recovery.py
@@ -0,0 +1,168 @@
+"""A URL job can restart after atomic local publication but before context commit."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+
+import pytest
+
+from tests.transfers.test_multipart_transfers import (
+    Account,
+    dispose,
+    manager_for,
+    registry_for,
+)
+from tests.transfers.test_multipart_transfers import mongo_backend as mongo_backend
+from tests.transfers.test_remote import (
+    PUBLIC_DNS,
+    FakeResolver,
+    FakeResponse,
+    FakeSession,
+)
+from tests.transfers.test_upload_destinations import folder
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.manager import TransferManager
+from tgdrive.transfers.remote import RemoteClient, RemoteDestinationExists
+from tgdrive.transfers.tasks import TransferStatus
+
+
+def remote(content):
+    return RemoteClient(
+        max_bytes=100,
+        session=FakeSession(
+            [
+                FakeResponse(
+                    200,
+                    headers={"Content-Length": str(len(content))},
+                    chunks=[content],
+                )
+            ]
+        ),
+        resolver=FakeResolver(PUBLIC_DNS),
+    )
+
+
+@pytest.mark.parametrize("mode", ["retry", "restart_retry", "restart_recover"])
+async def test_url_retry_replaces_only_own_unpublished_stage_after_publication_crash(
+    tmp_path, monkeypatch, mode
+):
+    manager, ledger = await manager_for(tmp_path)
+    old, new = b"old bytes", b"new verified bytes"
+    client = remote(old)
+    manager.remote = client
+    original = client._publish_temp
+
+    def crash_after_publication(*args, **kwargs):
+        original(*args, **kwargs)
+        raise OSError("synthetic crash after durable local publication")
+
+    monkeypatch.setattr(client, "_publish_temp", crash_after_publication)
+    target = folder(manager.store, "Target")
+    record = await manager.start_remote(
+        url="https://files.example/source.bin", destination=target, filename=None
+    )
+    await record.task
+    assert record.status == TransferStatus.ERROR
+    assert record.context["kind"] == "remote"
+    own_stage = manager.cache_dir / "remote" / record.id / "source.bin"
+    assert own_stage.read_bytes() == old
+    assert ledger.messages == {}
+    unrelated = manager.cache_dir / "remote" / "unrelated.bin"
+    unrelated.write_bytes(b"keep this file")
+    fresh = remote(new)
+    manager.store.move(target, folder(manager.store, "Other"))
+    expected_destination = manager.store.resolve_id(target[1:])
+    if mode != "retry":
+        # A true process crash leaves an unfinished row rather than the
+        # synthetic ERROR above; the saved folder identity remains unchanged.
+        if mode == "restart_recover":
+            record.status = TransferStatus.QUEUED
+            record.phase = "interrupted"
+        (await manager.registry.persist(record))
+        settings = manager.settings
+        await dispose(manager)
+        pool = ClientPool([Account("bot-one", ledger), Account("bot-two", ledger)])
+        await pool.start()
+        manager = TransferManager(
+            settings=settings,
+            pool=pool,
+            store=DriveStore.load(tmp_path / "drive.sqlite3"),
+            registry=registry_for(tmp_path),
+            remote=fresh,
+        )
+    else:
+        await client.close()
+        manager.remote = fresh
+    try:
+        if mode == "restart_recover":
+            await manager.recover()
+            retried = manager.registry.get(record.id)
+        else:
+            retried = await manager.retry_job(record.id)
+        await retried.task
+        assert retried.status == TransferStatus.COMPLETED
+        assert retried.context["destination"] == expected_destination
+        items = manager.store.list_directory(expected_destination)
+        item = manager.store.get_file(expected_destination + "/" + next(iter(items)))
+        actual = b"".join(
+            ledger.messages[p["message_id"]].content for p in item["parts"]
+        )
+        assert actual == new
+        assert item["sha256"] == hashlib.sha256(new).hexdigest()
+        assert unrelated.read_bytes() == b"keep this file"
+        assert not own_stage.exists()
+    finally:
+        await dispose(manager)
+
+
+async def test_remote_default_still_refuses_existing_arbitrary_destination(tmp_path):
+    source = tmp_path / "source.bin"
+    source.write_bytes(b"existing caller data")
+    client = remote(b"replacement")
+    try:
+        with pytest.raises(RemoteDestinationExists):
+            await client.download("https://files.example/source.bin", tmp_path)
+        assert source.read_bytes() == b"existing caller data"
+    finally:
+        await client.close()
+
+
+async def test_url_destination_move_while_retrieval_waits_preserves_folder_identity(
+    tmp_path,
+):
+    manager, ledger = await manager_for(tmp_path)
+    target = folder(manager.store, "Target")
+    entered, release = asyncio.Event(), asyncio.Event()
+    response = FakeResponse(200, headers={"Content-Length": "3"}, chunks=[b"one"])
+    original = response.content.read
+
+    async def blocked(limit):
+        entered.set()
+        await release.wait()
+        return await original(limit)
+
+    response.content.read = blocked
+    manager.remote = RemoteClient(
+        max_bytes=100,
+        session=FakeSession([response]),
+        resolver=FakeResolver(PUBLIC_DNS),
+    )
+    record = await manager.start_remote(
+        url="https://files.example/source.bin", destination=target, filename=None
+    )
+    try:
+        await asyncio.wait_for(entered.wait(), 2)
+        manager.store.move(target, folder(manager.store, "Other"))
+        expected = manager.store.resolve_id(target[1:])
+        release.set()
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        assert record.context["destination"] == expected
+        items = manager.store.list_directory(expected)
+        assert len(items) == 1
+        assert next(iter(ledger.messages.values())).content == b"one"
+    finally:
+        release.set()
+        await dispose(manager)
diff --git a/tests/transfers/test_remote_ranges.py b/tests/transfers/test_remote_ranges.py
new file mode 100644
index 00000000..fdaa791d
--- /dev/null
+++ b/tests/transfers/test_remote_ranges.py
@@ -0,0 +1,312 @@
+"""Synthetic HTTP range responses; no external downloads or speed claims."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import threading
+from itertools import pairwise
+
+import pytest
+
+from tests.transfers.test_remote import PUBLIC_DNS, FakeResolver, FakeResponse
+from tgdrive.transfers.remote import RemoteCancelled, RemoteClient, UnsafeRemoteURL
+from tgdrive.transfers.remote_ranges import RangeConcurrency, RangePolicy, _retry_after
+
+
+class RangeSource:
+    def __init__(self, *, failure=None):
+        self.data = bytes(range(128))
+        self.calls = []
+        self.responses = []
+        self.failure = failure
+        self.full_requests = 0
+
+    async def request(self, method, url, **kwargs):
+        headers = kwargs["headers"]
+        self.calls.append((url, headers))
+        if "Range" not in headers:
+            self.full_requests += 1
+            response = FakeResponse(
+                200,
+                headers={"Content-Length": str(len(self.data)), "ETag": '"version-1"'},
+                chunks=[self.data],
+            )
+        else:
+            assert headers["If-Range"] == '"version-1"'
+            start, last = map(
+                int, re.fullmatch(r"bytes=(\d+)-(\d+)", headers["Range"]).groups()
+            )
+            response = FakeResponse(
+                206,
+                headers={
+                    "Content-Range": f"bytes {start}-{last}/{len(self.data)}",
+                    "Content-Length": str(last - start + 1),
+                    "ETag": '"version-1"',
+                },
+                chunks=[self.data[start : last + 1]],
+            )
+            if self.failure is not None:
+                self.failure(response)
+        self.responses.append(response)
+        return response
+
+    async def close(self):
+        pass
+
+
+def client_for(source, **kwargs):
+    return RemoteClient(
+        session=source,
+        resolver=FakeResolver(PUBLIC_DNS),
+        range_policy=RangePolicy(minimum_size=16, block_size=8, max_connections=4),
+        **kwargs,
+    )
+
+
+async def test_parallel_ranges_assemble_exact_original_and_monotonic_progress(tmp_path):
+    source = RangeSource()
+    client = client_for(source)
+    progress = []
+    result = await client.download(
+        "https://files.example/movie.mov",
+        tmp_path,
+        progress=lambda current, total: progress.append((current, total)),
+    )
+    assert result.path.read_bytes() == source.data
+    assert source.full_requests == 1
+    ranges = [headers["Range"] for _, headers in source.calls if "Range" in headers]
+    assert ranges
+    intervals = sorted(tuple(map(int, re.findall(r"\d+", value))) for value in ranges)
+    assert intervals[0][0] == 8
+    assert intervals[-1][1] == len(source.data) - 1
+    assert all(left[1] + 1 == right[0] for left, right in pairwise(intervals))
+    assert progress[0] == (0, len(source.data))
+    assert progress[-1] == (len(source.data), len(source.data))
+    assert [row[0] for row in progress] == sorted(row[0] for row in progress)
+    assert all(response.released for response in source.responses)
+    assert not list(tmp_path.glob("*.part"))
+
+
+async def test_parallel_workers_overlap_instead_of_serializing_range_requests(tmp_path):
+    source = RangeSource()
+    second_range = asyncio.Event()
+    original_request = source.request
+    range_count = 0
+
+    async def request(method, url, **kwargs):
+        nonlocal range_count
+        response = await original_request(method, url, **kwargs)
+        if "Range" in kwargs["headers"]:
+            range_count += 1
+            if range_count == 1:
+                original_read = response.content.read
+
+                async def wait_for_peer(limit):
+                    await second_range.wait()
+                    return await original_read(limit)
+
+                response.content.read = wait_for_peer
+            else:
+                second_range.set()
+        return response
+
+    source.request = request
+    result = await asyncio.wait_for(
+        client_for(source).download("https://files.example/movie.mov", tmp_path), 3
+    )
+    assert second_range.is_set()
+    assert result.path.read_bytes() == source.data
+
+
+@pytest.mark.parametrize(
+    "failure",
+    [
+        "ignored",
+        "rejected",
+        "wrong_range",
+        "different_total",
+        "changed_etag",
+        "missing_etag",
+        "compressed",
+        "short",
+        "long",
+    ],
+)
+async def test_unsuitable_ranges_fall_back_once_without_mixing_bytes(tmp_path, failure):
+    def fail(response):
+        if failure == "ignored":
+            response.status = 200
+        elif failure == "rejected":
+            response.status = 416
+        elif failure == "wrong_range":
+            response.headers["Content-Range"] = "bytes 0-7/128"
+        elif failure == "different_total":
+            response.headers["Content-Range"] = response.headers[
+                "Content-Range"
+            ].replace("/128", "/129")
+        elif failure == "changed_etag":
+            response.headers["ETag"] = '"version-2"'
+            source.data = b"n" * 128
+        elif failure == "missing_etag":
+            del response.headers["ETag"]
+        elif failure == "compressed":
+            response.headers["Content-Encoding"] = "gzip"
+        elif failure == "short":
+            response.content.chunks.clear()
+        elif failure == "long":
+            response.content.chunks.append(b"extra")
+
+    source = RangeSource(failure=fail)
+    result = await client_for(source).download("https://files.example/a", tmp_path)
+    assert source.full_requests == 2
+    assert result.path.read_bytes() == source.data
+    assert all(response.released for response in source.responses)
+    assert len(list(tmp_path.iterdir())) == 1
+
+
+@pytest.mark.parametrize("etag", [None, 'W/"weak"'])
+async def test_sources_without_strong_identity_keep_the_initial_full_stream(
+    tmp_path, etag
+):
+    source = RangeSource()
+    request = source.request
+
+    async def without_validator(*args, **kwargs):
+        response = await request(*args, **kwargs)
+        if etag is None:
+            response.headers.pop("ETag", None)
+        else:
+            response.headers["ETag"] = etag
+        return response
+
+    source.request = without_validator
+    result = await client_for(source).download("https://files.example/a", tmp_path)
+    assert result.path.read_bytes() == source.data
+    assert len(source.calls) == 1
+
+
+async def test_compatibility_mode_does_not_probe_ranges(tmp_path):
+    source = RangeSource()
+    result = await client_for(source).download(
+        "https://files.example/a", tmp_path, single_threaded=True
+    )
+    assert result.path.read_bytes() == source.data
+    assert len(source.calls) == 1
+
+
+async def test_range_redirects_cannot_reach_private_networks(tmp_path):
+    def redirect(response):
+        response.status = 302
+        response.headers["Location"] = "http://127.0.0.1/private"
+
+    source = RangeSource(failure=redirect)
+    with pytest.raises(UnsafeRemoteURL):
+        await client_for(source).download("https://files.example/a", tmp_path)
+    assert all("127.0.0.1" not in url for url, _ in source.calls)
+    assert not list(tmp_path.iterdir())
+
+
+async def test_retry_after_wait_is_cancellable_and_does_not_hammer_source(tmp_path):
+    cancel = asyncio.Event()
+
+    def throttle(response):
+        response.status = 429
+        response.headers["Retry-After"] = "3600"
+        release = response.release
+
+        def cancelled_release():
+            release()
+            cancel.set()
+
+        response.release = cancelled_release
+
+    source = RangeSource(failure=throttle)
+    with pytest.raises(RemoteCancelled):
+        await asyncio.wait_for(
+            client_for(source).download(
+                "https://files.example/a", tmp_path, cancel_event=cancel
+            ),
+            3,
+        )
+    assert source.full_requests == 1
+    assert not list(tmp_path.iterdir())
+
+
+async def test_cancellation_drains_disk_workers_before_closing_staging(
+    tmp_path, monkeypatch
+):
+    source = RangeSource()
+    client = client_for(source)
+    entered, release = threading.Event(), threading.Event()
+    original_write = client._write_chunk
+    closed_early = []
+
+    def blocked_write(output, *args):
+        entered.set()
+        release.wait(3)
+        closed_early.append(output.closed)
+        original_write(output, *args)
+
+    monkeypatch.setattr(client, "_write_chunk", blocked_write)
+    download = asyncio.create_task(client.download("https://files.example/a", tmp_path))
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        download.cancel()
+        await asyncio.sleep(0)
+        assert not download.done()
+    finally:
+        release.set()
+    with pytest.raises(asyncio.CancelledError):
+        await download
+    assert closed_early and not any(closed_early)
+    assert not list(tmp_path.iterdir())
+
+
+def test_adaptive_width_retains_only_useful_extra_connections():
+    controller = RangeConcurrency(8)
+    assert controller.target == 2
+    assert controller.observe(10) == 4
+    assert controller.observe(18) == 8
+    assert controller.observe(19) == 4
+    assert controller.observe(18) == 4
+    assert controller.observe(5) == 4
+    assert controller.observe(5) == 2
+
+
+def test_adaptive_width_and_retry_after_are_bounded_and_validated():
+    controller = RangeConcurrency(8)
+    assert controller.observe(10) == 4
+    assert controller.observe(20) == 8
+    assert controller.observe(40) == 8
+    assert _retry_after("120") == 120
+    with pytest.raises(ValueError):
+        RangePolicy(max_connections=0)
+    with pytest.raises(ValueError):
+        RangePolicy(block_size=0)
+
+
+async def test_promoted_stream_keeps_its_prefix_when_switching_to_ranges(tmp_path):
+    source = RangeSource()
+    client = client_for(source, chunk_size=3)
+    ready = False
+    modes = []
+
+    async def progress(current, _total):
+        nonlocal ready
+        if current >= 3:
+            ready = True
+            await client.scheduler.refresh()
+
+    result = await client.download(
+        "https://files.example/movie.mov",
+        tmp_path,
+        can_promote=lambda: ready,
+        mode_changed=modes.append,
+        progress=progress,
+    )
+    assert result.path.read_bytes() == source.data
+    assert modes == ["queued", "warm", "full"]
+    assert source.full_requests == 1
+    intervals = [headers["Range"] for _, headers in source.calls if "Range" in headers]
+    assert intervals[0].startswith("bytes=11-")
diff --git a/tests/transfers/test_remote_retries.py b/tests/transfers/test_remote_retries.py
new file mode 100644
index 00000000..5aef08f6
--- /dev/null
+++ b/tests/transfers/test_remote_retries.py
@@ -0,0 +1,265 @@
+"""Offline recovery for incomplete HTTP bodies, backoff and admission fairness."""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock
+
+import aiohttp
+import pytest
+
+from tests.transfers.test_remote import (
+    PUBLIC_DNS,
+    FakeResolver,
+    FakeResponse,
+    FakeSession,
+)
+from tests.transfers.test_remote_ranges import RangeSource, client_for
+from tgdrive.transfers.remote import (
+    RemoteCancelled,
+    RemoteClient,
+    RemoteHTTPError,
+    RemoteRetriesExhausted,
+    RemoteTimeout,
+    UnsafeRemoteURL,
+    source_retryable,
+)
+
+
+def client_for_responses(responses, monkeypatch, **kwargs):
+    session = FakeSession(responses)
+    client = RemoteClient(session=session, resolver=FakeResolver(PUBLIC_DNS), **kwargs)
+    wait = AsyncMock()
+    monkeypatch.setattr(client, "_wait_for_retry", wait)
+    return client, session, wait
+
+
+def broken_body():
+    response = FakeResponse(200, headers={"Content-Length": "6"}, chunks=[b"old"])
+    original = response.content.read
+    calls = 0
+
+    async def read(size):
+        nonlocal calls
+        calls += 1
+        if calls > 1:
+            raise aiohttp.ClientPayloadError("body interrupted with a private URL")
+        return await original(size)
+
+    response.content.read = read
+    return response
+
+
+async def test_payload_failure_restarts_cleanly_and_publishes_only_complete_bytes(
+    tmp_path, monkeypatch
+):
+    first = broken_body()
+    second = FakeResponse(200, headers={"Content-Length": "6"}, chunks=[b"newnew"])
+    client, session, wait = client_for_responses([first, second], monkeypatch)
+    scheduled = []
+
+    async def on_retry(attempt, delay, error):
+        assert not list(tmp_path.iterdir())
+        assert client.scheduler._tickets == []
+        assert first.released
+        scheduled.append((attempt, delay, type(error).__name__))
+
+    result = await client.download(
+        "https://files.example/book.epub", tmp_path, retry=on_retry
+    )
+    assert result.path.read_bytes() == b"newnew"
+    assert scheduled == [(2, 2, "ClientPayloadError")]
+    assert len(session.calls) == 2
+    wait.assert_awaited_once()
+    assert not list(tmp_path.glob("*.part"))
+
+
+async def test_short_declared_body_also_recovers_without_a_payload_exception(
+    tmp_path, monkeypatch
+):
+    client, _, _ = client_for_responses(
+        [
+            FakeResponse(200, headers={"Content-Length": "6"}, chunks=[b"old"]),
+            FakeResponse(200, headers={"Content-Length": "6"}, chunks=[b"abcdef"]),
+        ],
+        monkeypatch,
+    )
+    result = await client.download("https://files.example/a", tmp_path)
+    assert result.path.read_bytes() == b"abcdef"
+
+
+async def test_retry_budget_exhausts_after_four_attempts_with_bounded_backoff(
+    tmp_path, monkeypatch
+):
+    client, session, wait = client_for_responses(
+        [broken_body() for _ in range(4)], monkeypatch
+    )
+    with pytest.raises(RemoteRetriesExhausted, match="after 4 attempts") as error:
+        await client.download("https://files.example/a", tmp_path)
+    assert isinstance(error.value.__cause__, aiohttp.ClientPayloadError)
+    assert len(session.calls) == 4
+    assert [call.args[0] for call in wait.await_args_list] == [2, 4, 8]
+    assert not list(tmp_path.iterdir())
+
+
+@pytest.mark.parametrize("status", [408, 429, 500, 502, 503, 504])
+async def test_temporary_http_errors_retry_and_respect_retry_after(
+    tmp_path, monkeypatch, status
+):
+    client, session, wait = client_for_responses(
+        [
+            FakeResponse(status, headers={"Retry-After": "120"}),
+            FakeResponse(200, headers={"Content-Length": "1"}, chunks=[b"x"]),
+        ],
+        monkeypatch,
+    )
+    result = await client.download("https://files.example/a", tmp_path)
+    assert result.path.read_bytes() == b"x"
+    assert len(session.calls) == 2
+    assert wait.await_args.args[0] == 120
+
+
+@pytest.mark.parametrize("status", [400, 401, 403, 404, 410, 501])
+async def test_permanent_http_errors_do_not_retry(tmp_path, monkeypatch, status):
+    client, session, wait = client_for_responses([FakeResponse(status)], monkeypatch)
+    with pytest.raises(RemoteHTTPError):
+        await client.download("https://files.example/a", tmp_path)
+    assert len(session.calls) == 1
+    wait.assert_not_awaited()
+
+
+async def test_cancellation_during_backoff_stops_without_another_request(tmp_path):
+    session = FakeSession([broken_body()])
+    client = RemoteClient(session=session, resolver=FakeResolver(PUBLIC_DNS))
+    cancel = asyncio.Event()
+    scheduled = asyncio.Event()
+
+    def on_retry(*_args):
+        scheduled.set()
+
+    task = asyncio.create_task(
+        client.download(
+            "https://files.example/a", tmp_path, cancel_event=cancel, retry=on_retry
+        )
+    )
+    await asyncio.wait_for(scheduled.wait(), 3)
+    cancel.set()
+    with pytest.raises(RemoteCancelled):
+        await asyncio.wait_for(task, 3)
+    assert len(session.calls) == 1
+    assert client.scheduler._tickets == []
+
+
+async def test_total_timeout_includes_backoff_and_does_not_start_a_fresh_budget(
+    tmp_path,
+):
+    from tgdrive.transfers.remote import RemoteTimeouts
+
+    client = RemoteClient(
+        session=FakeSession([broken_body()]),
+        resolver=FakeResolver(PUBLIC_DNS),
+        timeouts=RemoteTimeouts(total=0.1),
+    )
+    with pytest.raises(RemoteTimeout):
+        await client.download("https://files.example/a", tmp_path)
+    assert client.scheduler._tickets == []
+    assert not list(tmp_path.iterdir())
+
+
+async def test_initial_parallel_stream_payload_error_uses_a_fresh_single_response(
+    tmp_path, monkeypatch
+):
+    source = RangeSource()
+    original = source.request
+
+    async def request(*args, **kwargs):
+        response = await original(*args, **kwargs)
+        if "Range" not in kwargs["headers"] and source.full_requests == 1:
+
+            async def broken_read(_size):
+                raise aiohttp.ClientPayloadError("initial range stream interrupted")
+
+            response.content.read = broken_read
+        return response
+
+    source.request = request
+    client = client_for(source)
+    wait = AsyncMock()
+    monkeypatch.setattr(client, "_wait_for_retry", wait)
+    result = await client.download("https://files.example/a", tmp_path)
+    assert result.path.read_bytes() == source.data
+    assert source.full_requests == 2
+    assert all(response.released for response in source.responses)
+    assert not list(tmp_path.glob("*.part"))
+
+
+def test_unsafe_destinations_and_tls_failures_are_never_retryable():
+    assert not source_retryable(UnsafeRemoteURL("blocked"))
+    assert not source_retryable(aiohttp.ClientSSLError(None, OSError("TLS error")))
+
+
+async def test_pipeline_publishes_retry_status_releases_staging_and_uploads_once(
+    tmp_path, monkeypatch
+):
+    from tests.transfers.test_transfers import make_manager
+    from tgdrive.transfers.tasks import TransferStatus
+
+    manager, store, _transport, pool = await make_manager(tmp_path, max_size=100)
+    client, session, _ = client_for_responses(
+        [
+            broken_body(),
+            FakeResponse(200, headers={"Content-Length": "6"}, chunks=[b"abcdef"]),
+        ],
+        monkeypatch,
+    )
+    manager.remote = client
+    observed = []
+
+    async def waiting(delay, cancel_event):
+        snapshot = record.as_dict()
+        assert snapshot["phase"] == "source_retry_wait"
+        assert snapshot["status"] == "running"
+        assert snapshot["source_attempt"] == 2
+        assert snapshot["source_max_attempts"] == 4
+        assert snapshot["retry_at"] is not None
+        assert snapshot["eta_seconds"] is None
+        assert snapshot["error"] is None
+        assert record.context["staging_size"] == record.context["staging_written"] == 0
+        assert client.scheduler._tickets == []
+        observed.append(delay)
+
+    monkeypatch.setattr(client, "_wait_for_retry", waiting)
+    record = await manager.start_remote(
+        url="https://files.example/book.epub", destination="/", filename="book.epub"
+    )
+    try:
+        await record.task
+        assert record.status == TransferStatus.COMPLETED, record.error
+        assert observed == [2]
+        assert len(session.calls) == 2
+        assert len(store.list_directory("/")) == 1
+        assert "source_retry_at" not in record.context
+    finally:
+        await manager.close()
+        await pool.stop()
+        store.close()
+
+
+async def test_explicit_saved_retry_deadline_is_waited_before_contacting_source(
+    tmp_path, monkeypatch
+):
+    import time
+
+    client, session, _wait = client_for_responses(
+        [FakeResponse(200, headers={"Content-Length": "1"}, chunks=[b"x"])], monkeypatch
+    )
+
+    async def delayed(delay, cancel_event):
+        assert 118 <= delay <= 120
+        assert session.calls == []
+
+    monkeypatch.setattr(client, "_wait_for_retry", delayed)
+    await client.download(
+        "https://files.example/a", tmp_path, retry_not_before=time.time() + 120
+    )
+    assert len(session.calls) == 1
diff --git a/tests/transfers/test_remote_scheduler.py b/tests/transfers/test_remote_scheduler.py
new file mode 100644
index 00000000..b4b34698
--- /dev/null
+++ b/tests/transfers/test_remote_scheduler.py
@@ -0,0 +1,98 @@
+"""Offline admission and pacing checks; no network timing benchmarks."""
+
+import asyncio
+from contextlib import AsyncExitStack
+
+import pytest
+
+from tgdrive.transfers.remote_scheduler import (
+    WARM_BYTES_PER_SECOND,
+    URLDownloadScheduler,
+)
+
+
+async def wait(operation):
+    return await operation
+
+
+async def test_two_full_speed_slots_promote_waiting_sources_fifo():
+    scheduler = URLDownloadScheduler()
+    contexts = [scheduler.admit(wait) for _ in range(4)]
+    tickets = [await context.__aenter__() for context in contexts]
+    try:
+        assert [ticket.full_speed for ticket in tickets] == [True, True, False, False]
+        await contexts.pop(0).__aexit__(None, None, None)
+        assert [ticket.full_speed for ticket in tickets] == [True, True, True, False]
+    finally:
+        for context in reversed(contexts):
+            await context.__aexit__(None, None, None)
+    assert scheduler._tickets == []
+    assert scheduler._monitor is None
+
+
+async def test_storage_eligibility_and_live_settings_control_promotions():
+    scheduler = URLDownloadScheduler(1)
+    ready = False
+    async with AsyncExitStack() as stack:
+        first = await stack.enter_async_context(scheduler.admit(wait))
+        held = await stack.enter_async_context(scheduler.admit(wait, lambda: ready))
+        eligible = await stack.enter_async_context(scheduler.admit(wait))
+        await scheduler.configure(2)
+        assert first.full_speed and eligible.full_speed and not held.full_speed
+        ready = True
+        await scheduler.configure(3)
+        assert held.full_speed
+        await scheduler.configure(1)
+        fourth = await stack.enter_async_context(scheduler.admit(wait))
+        assert not fourth.full_speed  # Existing full-speed work drains normally.
+        assert sum(ticket.full_speed for ticket in scheduler._tickets) == 3
+
+
+@pytest.mark.parametrize("limit", [0, 9, True, 1.5])
+def test_concurrency_is_an_integer_between_one_and_eight(limit):
+    with pytest.raises(ValueError):
+        URLDownloadScheduler(limit)
+
+
+async def test_source_connections_are_bounded_and_queued_cancellation_is_clean():
+    scheduler = URLDownloadScheduler(1)
+    modes = []
+    async with AsyncExitStack() as stack:
+        for _ in range(9):
+            await stack.enter_async_context(scheduler.admit(wait))
+        entered = asyncio.Event()
+
+        async def extra():
+            async with scheduler.admit(wait, changed=modes.append):
+                entered.set()
+
+        pending = asyncio.create_task(extra())
+        try:
+            await asyncio.sleep(0)
+            assert modes == ["queued"]
+            assert not entered.is_set()
+            assert len(scheduler._tickets) == 9
+            pending.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await pending
+            assert len(scheduler._tickets) == 9
+        finally:
+            pending.cancel()
+            await asyncio.gather(pending, return_exceptions=True)
+
+
+async def test_waiting_reads_are_paced_and_promotion_wakes_them(monkeypatch):
+    scheduler = URLDownloadScheduler(1)
+    async with scheduler.admit(wait, lambda: False) as ticket:
+        monkeypatch.setattr(
+            "tgdrive.transfers.remote_scheduler.time.monotonic", lambda: 10
+        )
+        ticket.received(WARM_BYTES_PER_SECOND)
+        assert ticket.next_read == 11
+        waiting = asyncio.create_task(ticket.pace())
+        await asyncio.sleep(0)
+        assert not waiting.done()
+        ticket.can_promote = lambda: True
+        await scheduler.refresh()
+        await asyncio.wait_for(waiting, 1)
+        assert ticket.full_speed
diff --git a/tests/transfers/test_resumable_uploads.py b/tests/transfers/test_resumable_uploads.py
new file mode 100644
index 00000000..db8c2ef4
--- /dev/null
+++ b/tests/transfers/test_resumable_uploads.py
@@ -0,0 +1,745 @@
+from __future__ import annotations
+
+import asyncio
+import copy
+import gc
+import hashlib
+import logging
+import threading
+import weakref
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from pydantic import SecretStr
+from pymongo.errors import ConnectionFailure
+
+import tgdrive.transfers.uploads as module
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.storage.mongo import for_directory
+from tgdrive.storage.store import DriveStore
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+from tgdrive.transfers.uploads import CHUNK_SIZE, ResumableUploads, UploadError
+
+pytestmark = pytest.mark.usefixtures("mongo_backend")
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path / "data")
+
+
+class Manager:
+    def __init__(self, tmp_path: Path, *, backend=None):
+        self.store = DriveStore.create()
+        if backend is None:
+            backend = for_directory(tmp_path / "data")
+        self.registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+        self.enqueued = 0
+
+    async def enqueue_upload(
+        self, source, destination, name, size, *, transfer_id, folder_upload=None
+    ):
+        self.enqueued += 1
+        job = await self.registry.create("queued", transfer_id=transfer_id, total=size)
+        job.context.update(
+            kind="upload",
+            local_path=str(source),
+            destination=destination,
+            name=name,
+            size=size,
+        )
+        if folder_upload is not None:
+            job.context["folder_upload"] = copy.deepcopy(folder_upload)
+        (await self.registry.persist(job))
+        return job
+
+
+def make(tmp_path: Path, *, manager=None, **overrides):
+    config = dict(
+        mongodb_uri=SecretStr("mongodb://synthetic.invalid"),
+        mongodb_database="tgdrive",
+        resolved_cache_dir=tmp_path / "cache",
+        resolved_data_dir=tmp_path / "data",
+        max_concurrent_transfers=2,
+        upload_limit=CHUNK_SIZE * 3,
+        staging_budget_bytes=CHUNK_SIZE * 6,
+        min_free_bytes=0,
+        upload_session_ttl_seconds=60,
+    )
+    config.update(overrides)
+    manager = manager or Manager(tmp_path)
+    return ResumableUploads(SimpleNamespace(**config), manager), manager
+
+
+async def test_restart_resumes_exact_committed_offset_and_checksums(tmp_path):
+    uploads, manager = make(tmp_path)
+    data, tail = b"a" * CHUNK_SIZE, b"last"
+    item = uploads.create("example.bin", "/", len(data) + len(tail))
+    await uploads.append(item["id"], 0, data)
+    # Simulate bytes written before a process died before committing its offset.
+    with uploads.path(item["id"]).open("ab") as handle:
+        handle.write(b"uncommitted tail")
+    uploads.close()
+    resumed, _ = make(tmp_path, manager=manager)
+    assert resumed.get(item["id"])["offset"] == CHUNK_SIZE
+    await resumed.append(item["id"], CHUNK_SIZE, tail)
+    assert resumed.path(item["id"]).read_bytes() == data + tail
+    state = resumed.get(item["id"])
+    assert state["checksums"][0]["sha256"] == hashlib.sha256(data).hexdigest()
+    job = await resumed.complete(item["id"])
+    assert job.id == item["id"]
+    assert manager.enqueued == 1
+
+
+async def test_complete_is_idempotent_after_worker_removed_staging(tmp_path):
+    uploads, manager = make(tmp_path)
+    item = uploads.create("one.bin", "/", 3)
+    await uploads.append(item["id"], 0, b"one")
+    first = await uploads.complete(item["id"])
+    (await manager.registry.update(first.id, status=TransferStatus.COMPLETED))
+    uploads.path(item["id"]).unlink()
+    uploads.release(item["id"])
+    second = await uploads.complete(item["id"])
+    assert first.id == second.id
+    assert manager.enqueued == 1
+
+
+@pytest.mark.parametrize("state", ["finished", "cancelled"])
+async def test_terminal_receipt_cache_uses_persisted_expiry_after_restart(
+    tmp_path, mongo_backend, monkeypatch, state
+):
+    uploads, manager = make(tmp_path)
+    item = uploads.create("one.bin", "/", 3)
+    if state == "cancelled":
+        await uploads.cancel(item["id"])
+    else:
+        await uploads.append(item["id"], 0, b"one")
+        job = await uploads.complete(item["id"])
+        (await manager.registry.update(job.id, status=TransferStatus.COMPLETED))
+        uploads.path(item["id"]).unlink()
+        uploads.release(item["id"])
+    saved = mongo_backend.db.receipts.find_one({"_id": item["id"]})
+    deadline = saved["purge_at"].timestamp()
+    assert deadline > item["expires_at"]
+
+    monkeypatch.setattr(module.time, "time", lambda: item["expires_at"] + 1)
+    assert uploads.get_unchecked(item["id"])["state"] == state
+    restarted, _ = make(tmp_path, manager=manager)
+    assert restarted.get_unchecked(item["id"])["state"] == state
+
+    monkeypatch.setattr(module.time, "time", lambda: deadline + 1)
+    replacement = restarted.create("replacement.bin", "/", 3)
+    assert [row["id"] for row in restarted._all()] == [replacement["id"]]
+    assert item["id"] not in restarted._items
+    assert item["id"] not in restarted._terminal_expiry
+    assert mongo_backend.db.receipts.find_one({"_id": item["id"]}) == saved
+    restored, _ = make(tmp_path, manager=manager)
+    with pytest.raises(UploadError) as expired:
+        restored.get_unchecked(item["id"])
+    assert expired.value.status == 404
+
+
+@pytest.mark.parametrize("status", [TransferStatus.QUEUED, TransferStatus.ERROR])
+async def test_receipt_cache_expiry_retains_unfinished_job(
+    tmp_path, mongo_backend, monkeypatch, status
+):
+    uploads, manager = make(tmp_path)
+    item = uploads.create("retry.bin", "/", 3)
+    job = await manager.registry.create("uploading", transfer_id=item["id"], total=3)
+    job.context.update(kind="upload", send_started=True)
+    (await manager.registry.update(job.id, status=status))
+    item["state"] = "finished"
+    uploads._save(item)
+    deadline = mongo_backend.db.receipts.find_one({"_id": item["id"]})[
+        "purge_at"
+    ].timestamp()
+    monkeypatch.setattr(module.time, "time", lambda: deadline + 1)
+
+    assert uploads.get_unchecked(item["id"])["state"] == "finished"
+    assert [row["id"] for row in uploads._all()] == [item["id"]]
+    assert uploads.path(item["id"]).is_file()
+    assert manager.registry.get(job.id).context["send_started"] is True
+
+
+async def test_receipt_lock_waiters_keep_expired_cache_owned(
+    tmp_path, mongo_backend, monkeypatch
+):
+    uploads, _ = make(tmp_path)
+    item = uploads.create("cancelled.bin", "/", 3)
+    await uploads.cancel(item["id"])
+    deadline = mongo_backend.db.receipts.find_one({"_id": item["id"]})[
+        "purge_at"
+    ].timestamp()
+    lock = uploads.locks.setdefault(item["id"], asyncio.Lock())
+    reference = weakref.ref(lock)
+    await lock.acquire()
+    waiting = asyncio.create_task(uploads.cancel(item["id"]))
+    try:
+        await asyncio.sleep(0)
+        assert not waiting.done()
+        monkeypatch.setattr(module.time, "time", lambda: deadline + 1)
+        assert [row["id"] for row in uploads._all()] == [item["id"]]
+
+        lock.release()
+        lock = None
+        # The awakened waiter owns the old lock before it resumes execution.
+        assert reference() is uploads.locks[item["id"]]
+        assert [row["id"] for row in uploads._all()] == [item["id"]]
+        assert (await waiting)["state"] == "cancelled"
+        gc.collect()
+        assert reference() is None
+        assert item["id"] not in uploads.locks
+        assert uploads._all() == []
+    finally:
+        if lock is not None:
+            lock.release()
+        waiting.cancel()
+        await asyncio.gather(waiting, return_exceptions=True)
+
+
+async def test_idle_receipt_locks_are_released_after_failed_lookups(tmp_path):
+    uploads, _ = make(tmp_path)
+    for index in range(20):
+        with pytest.raises(UploadError) as missing:
+            await uploads.cancel(f"{index:032x}")
+        assert missing.value.status == 404
+    del missing
+    gc.collect()
+    assert not uploads.locks
+
+
+async def test_receipt_logs_acceptance_once_without_chunk_or_private_data(
+    tmp_path, caplog
+):
+    caplog.set_level(logging.INFO, logger="tgdrive.transfers.uploads")
+    uploads, manager = make(tmp_path)
+    item = uploads.create("private-name.bin", "/", 3)
+    await uploads.append(item["id"], 0, b"one")
+    assert not caplog.records
+    await uploads.complete(item["id"])
+    await uploads.complete(item["id"])
+
+    assert len(caplog.records) == 1
+    assert (
+        f"Device upload accepted id={item['id']} job_id={item['id']} bytes=3"
+        in caplog.text
+    )
+    assert "verify_seconds=" in caplog.text and "handoff_seconds=" in caplog.text
+    assert "private-name" not in caplog.text
+    assert "one" not in caplog.text
+    uploads.close()
+    manager.registry.close()
+
+
+async def test_corrupted_receipt_logs_failed_verification_without_acceptance(
+    tmp_path, caplog
+):
+    caplog.set_level(logging.INFO, logger="tgdrive.transfers.uploads")
+    uploads, manager = make(tmp_path)
+    item = uploads.create("private-name.bin", "/", 3)
+    await uploads.append(item["id"], 0, b"one")
+    uploads.path(item["id"]).write_bytes(b"two")
+    with pytest.raises(UploadError, match="checksum"):
+        await uploads.complete(item["id"])
+    assert "Device upload verification failed" in caplog.text
+    assert "cancel this receipt and upload the original file again" in caplog.text
+    assert "Device upload accepted" not in caplog.text
+    assert "private-name" not in caplog.text
+    uploads.close()
+    manager.registry.close()
+
+
+async def test_complete_rejects_corrupted_and_missing_staging(tmp_path):
+    uploads, manager = make(tmp_path)
+    item = uploads.create("one.bin", "/", 3)
+    await uploads.append(item["id"], 0, b"one")
+    uploads.path(item["id"]).write_bytes(b"two")
+    with pytest.raises(UploadError, match="checksum"):
+        await uploads.complete(item["id"])
+    uploads.path(item["id"]).unlink()
+    with pytest.raises(UploadError, match="missing"):
+        await uploads.complete(item["id"])
+    assert manager.enqueued == 0
+
+
+async def test_wrong_offset_and_short_nonfinal_chunks_do_not_advance(tmp_path):
+    uploads, _ = make(tmp_path)
+    item = uploads.create("big.bin", "/", CHUNK_SIZE + 1)
+    with pytest.raises(UploadError, match="offset") as conflict:
+        await uploads.append(item["id"], 1, b"wrong")
+    assert conflict.value.status == 409
+    assert conflict.value.code == "UPLOAD_OFFSET_CHANGED"
+    with pytest.raises(UploadError, match="last chunk") as invalid:
+        await uploads.append(item["id"], 0, b"short")
+    assert invalid.value.code == "UPLOAD_ERROR"
+    assert uploads.get(item["id"])["offset"] == 0
+    assert uploads.path(item["id"]).stat().st_size == 0
+
+
+async def test_failed_offset_commit_replays_written_bytes_safely(tmp_path, monkeypatch):
+    uploads, _ = make(tmp_path)
+    item = uploads.create("one.bin", "/", 3)
+    save = uploads._save
+
+    def fail(_item):
+        raise ConnectionFailure("disk full")
+
+    monkeypatch.setattr(uploads, "_save", fail)
+    with pytest.raises(ConnectionFailure, match="disk full"):
+        await uploads.append(item["id"], 0, b"one")
+    assert uploads.get(item["id"])["offset"] == 0
+    monkeypatch.setattr(uploads, "_save", save)
+    await uploads.append(item["id"], 0, b"two")
+    assert uploads.path(item["id"]).read_bytes() == b"two"
+    assert uploads.get(item["id"])["offset"] == 3
+
+
+async def test_receipt_cancellation_waits_for_disk_write_then_cannot_resurrect(
+    tmp_path, monkeypatch
+):
+    uploads, _ = make(tmp_path)
+    item = uploads.create("one.bin", "/", 3)
+    started, release = threading.Event(), threading.Event()
+    fsync = module.os.fsync
+
+    def blocked(descriptor):
+        started.set()
+        assert release.wait(3)
+        fsync(descriptor)
+
+    monkeypatch.setattr(module.os, "fsync", blocked)
+    append = asyncio.create_task(uploads.append(item["id"], 0, b"one"))
+    try:
+        assert await asyncio.to_thread(started.wait, 2)
+        cancel = asyncio.create_task(uploads.cancel(item["id"]))
+        await asyncio.sleep(0)
+        assert not cancel.done()
+        release.set()
+        await append
+        await cancel
+    finally:
+        release.set()
+    assert uploads.get_unchecked(item["id"])["state"] == "cancelled"
+    assert not uploads.path(item["id"]).exists()
+
+
+async def test_request_disconnect_waits_for_thread_and_records_committed_offset(
+    tmp_path, monkeypatch
+):
+    uploads, _ = make(tmp_path)
+    item = uploads.create("one.bin", "/", 3)
+    started, release = threading.Event(), threading.Event()
+    fsync = module.os.fsync
+
+    def blocked(descriptor):
+        started.set()
+        assert release.wait(3)
+        fsync(descriptor)
+
+    monkeypatch.setattr(module.os, "fsync", blocked)
+    append = asyncio.create_task(uploads.append(item["id"], 0, b"one"))
+    try:
+        assert await asyncio.to_thread(started.wait, 2)
+        append.cancel()
+        await asyncio.sleep(0)
+        append.cancel()
+        await asyncio.sleep(0)
+        assert not append.done()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await append
+    finally:
+        release.set()
+    assert uploads.get(item["id"])["offset"] == 3
+    assert uploads.path(item["id"]).read_bytes() == b"one"
+
+
+async def test_request_disconnect_during_verification_still_enqueues_receipt(
+    tmp_path, monkeypatch
+):
+    uploads, manager = make(tmp_path)
+    item = uploads.create("one.bin", "/", 3)
+    await uploads.append(item["id"], 0, b"one")
+    started, release = threading.Event(), threading.Event()
+    verify = uploads._verify
+
+    def blocked(state, path):
+        started.set()
+        assert release.wait(3)
+        verify(state, path)
+
+    monkeypatch.setattr(uploads, "_verify", blocked)
+    completion = asyncio.create_task(uploads.complete(item["id"]))
+    try:
+        assert await asyncio.to_thread(started.wait, 2)
+        completion.cancel()
+        await asyncio.sleep(0)
+        completion.cancel()
+        await asyncio.sleep(0)
+        assert not completion.done()
+        assert uploads.locks[item["id"]].locked()
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await completion
+    finally:
+        release.set()
+    assert uploads.get(item["id"])["state"] == "queued"
+    job = manager.registry.get(item["id"])
+    assert job.context["local_path"] == str(uploads.path(item["id"]))
+    assert (await uploads.complete(item["id"])).id == job.id
+    assert manager.enqueued == 1
+
+
+async def test_budget_free_space_expiration_and_postrestart_release(
+    tmp_path, monkeypatch
+):
+    uploads, manager = make(tmp_path, staging_budget_bytes=3)
+    item = uploads.create("one.bin", "/", 3)
+    with pytest.raises(UploadError) as full:
+        uploads.create("two.bin", "/", 1)
+    assert full.value.status == 507
+    await uploads.append(item["id"], 0, b"one")
+    record = await uploads.complete(item["id"])
+    # Worker finished before receipts were constructed after a restart.
+    (await manager.registry.update(record.id, status=TransferStatus.COMPLETED))
+    restarted, _ = make(tmp_path, manager=manager, staging_budget_bytes=3)
+    assert restarted.get(item["id"])["state"] == "finished"
+    assert not restarted.path(item["id"]).exists()
+    other = restarted.create("two.bin", "/", 3)
+    monkeypatch.setattr(module.time, "time", lambda: other["expires_at"] + 1)
+    with pytest.raises(UploadError) as expired:
+        restarted.get(other["id"])
+    assert expired.value.status == 410
+    assert not restarted.path(other["id"]).exists()
+    monkeypatch.undo()
+    monkeypatch.setattr(module.shutil, "disk_usage", lambda _: SimpleNamespace(free=0))
+    with pytest.raises(UploadError) as disk:
+        restarted.create("three.bin", "/", 1)
+    assert disk.value.status == 507
+
+
+def test_untrusted_receipt_ids_and_database_outage_fail_closed(
+    tmp_path, mongo_backend, monkeypatch
+):
+    uploads, manager = make(tmp_path)
+    for invalid in ["../other", "", "0" * 33]:
+        with pytest.raises(UploadError) as error:
+            uploads.path(invalid)
+        assert error.value.status == 404
+    uploads.close()
+
+    def unavailable(_query):
+        raise ConnectionFailure("synthetic receipt database outage")
+
+    monkeypatch.setattr(mongo_backend.db.receipts, "find", unavailable)
+    with pytest.raises(ConnectionFailure):
+        make(tmp_path, manager=manager)
+    assert not (tmp_path / "data" / "uploads.sqlite3").exists()
+
+
+async def test_restart_reconciles_job_committed_before_receipt_queue_commit(
+    tmp_path, monkeypatch
+):
+    uploads, manager = make(tmp_path, staging_budget_bytes=3)
+    item = uploads.create("one.bin", "/", 3)
+    await uploads.append(item["id"], 0, b"one")
+    save = uploads._save
+
+    def fail_queued(state):
+        if state["state"] == "queued":
+            raise ConnectionFailure("receipt commit failed")
+        save(state)
+
+    monkeypatch.setattr(uploads, "_save", fail_queued)
+    with pytest.raises(ConnectionFailure):
+        await uploads.complete(item["id"])
+    assert uploads.get(item["id"])["state"] == "receiving"
+    record = manager.registry.get(item["id"])
+    (await manager.registry.update(record.id, status=TransferStatus.COMPLETED))
+    restarted, _ = make(tmp_path, manager=manager, staging_budget_bytes=3)
+    assert restarted.get(item["id"])["state"] == "finished"
+    assert restarted.create("replacement.bin", "/", 3)["offset"] == 0
+
+
+def test_abandoned_upload_service_retains_shared_mongodb_receipts(
+    tmp_path, mongo_backend
+):
+    uploads, manager = make(tmp_path)
+    item = uploads.create("committed.bin", "/", 3)
+    reference = weakref.ref(uploads)
+    del uploads
+    gc.collect()
+    assert reference() is None
+    assert mongo_backend.db.receipts.find_one({"_id": item["id"]}) is not None
+    restored, _ = make(tmp_path, manager=manager)
+    assert restored.get(item["id"])["offset"] == 0
+    restored.close()
+    restored.close()
+
+
+def make_cloud(tmp_path, monkeypatch, **overrides):
+    rows = {}
+    collection = SimpleNamespace(find=lambda _query: list(rows.values()))
+
+    def write(target, method, query, document, *, upsert):
+        assert target is collection and method == "replace_one" and upsert
+        rows[query["_id"]] = copy.deepcopy(document)
+
+    backend = SimpleNamespace(db=SimpleNamespace(receipts=collection), write=write)
+    monkeypatch.setattr("tgdrive.storage.mongo.for_settings", lambda _settings: backend)
+    uploads, manager = make(tmp_path, **overrides)
+    manager.uploads = uploads
+    return uploads, manager, backend, rows
+
+
+async def test_cloud_creation_reserves_shared_budget_and_drains_after_disconnect(
+    tmp_path, monkeypatch
+):
+    from tgdrive.transfers.staging import StorageUnavailable, check_staging
+
+    uploads, manager, backend, rows = make_cloud(
+        tmp_path, monkeypatch, staging_budget_bytes=3
+    )
+    entered, release = threading.Event(), threading.Event()
+    loop_thread = threading.get_ident()
+    fsync, write = module.os.fsync, backend.write
+
+    def worker_fsync(descriptor):
+        assert threading.get_ident() != loop_thread
+        return fsync(descriptor)
+
+    def slow_commit(*args, **kwargs):
+        assert threading.get_ident() != loop_thread
+        entered.set()
+        assert release.wait(3), "The event loop could not release receipt creation"
+        return write(*args, **kwargs)
+
+    monkeypatch.setattr(module.os, "fsync", worker_fsync)
+    monkeypatch.setattr(backend, "write", slow_commit)
+    creation = asyncio.create_task(uploads.create_async("one.bin", "/", 3))
+    second = None
+    try:
+        assert await asyncio.to_thread(entered.wait, 2)
+        assert not creation.done()
+        assert rows == {}
+        [pending] = uploads._all()
+        assert pending["total_size"] == 3
+        # URL/multipart admissions use the same accounting while the first
+        # receipt has not received a durable cloud acknowledgement.
+        with pytest.raises(StorageUnavailable):
+            check_staging(uploads.settings, manager, 1)
+        with pytest.raises(UploadError) as unavailable:
+            uploads.get_unchecked(pending["id"])
+        assert unavailable.value.status == 404
+        second = asyncio.create_task(uploads.create_async("two.bin", "/", 1))
+        await asyncio.sleep(0)
+        assert not second.done()
+        creation.cancel()
+        await asyncio.sleep(0)
+        creation.cancel()
+        await asyncio.sleep(0)
+        assert not creation.done()
+        assert uploads._creation_lock.locked()
+        assert len(uploads._all()) == 1
+        release.set()
+        with pytest.raises(asyncio.CancelledError):
+            await creation
+        with pytest.raises(UploadError) as full:
+            await second
+        assert full.value.status == 507
+        committed = uploads.get_unchecked(pending["id"])
+        assert committed["state"] == "receiving"
+        assert committed["offset"] == 0
+        assert rows[pending["id"]]["data"] == committed
+        assert uploads.path(pending["id"]).is_file()
+        assert uploads._pending == {}
+        assert len(uploads._all()) == 1
+    finally:
+        release.set()
+        await asyncio.gather(
+            creation, *([second] if second is not None else []), return_exceptions=True
+        )
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+async def test_cloud_creation_cleans_up_local_failure_before_persistence(
+    tmp_path, monkeypatch
+):
+    uploads, manager, _backend, rows = make_cloud(tmp_path, monkeypatch)
+
+    def broken_fsync(_descriptor):
+        raise OSError("Synthetic local receipt failure")
+
+    monkeypatch.setattr(module.os, "fsync", broken_fsync)
+    try:
+        with pytest.raises(OSError, match="Synthetic local"):
+            await uploads.create_async("one.bin", "/", 3)
+        assert uploads._pending == {}
+        assert uploads._all() == []
+        assert rows == {}
+        assert not list(uploads.root.glob("*.part"))
+    finally:
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+@pytest.mark.parametrize("committed", [False, True])
+async def test_unknown_cloud_creation_commit_keeps_file_and_reservation(
+    tmp_path, monkeypatch, committed
+):
+    from tgdrive.storage.mongo import DatabaseUnavailable
+
+    uploads, manager, backend, rows = make_cloud(
+        tmp_path, monkeypatch, staging_budget_bytes=3
+    )
+    write = backend.write
+
+    def unknown(*args, **kwargs):
+        if committed:
+            write(*args, **kwargs)
+        raise DatabaseUnavailable("Synthetic unknown receipt commit")
+
+    monkeypatch.setattr(backend, "write", unknown)
+    try:
+        with pytest.raises(DatabaseUnavailable):
+            await uploads.create_async("one.bin", "/", 3)
+        assert uploads._pending == {}
+        [retained] = uploads._all()
+        assert uploads.path(retained["id"]).is_file()
+        assert (retained["id"] in rows) is committed
+        with pytest.raises(UploadError) as full:
+            await uploads.create_async("two.bin", "/", 1)
+        assert full.value.status == 507
+        monkeypatch.setattr(backend, "write", write)
+        monkeypatch.setattr(module.time, "time", lambda: retained["expires_at"] + 1)
+        assert uploads._all() == [retained]
+        replacement = await uploads.create_async("two.bin", "/", 3)
+        assert replacement["state"] == "receiving"
+        assert uploads.get_unchecked(retained["id"])["state"] == "cancelled"
+        assert not uploads.path(retained["id"]).exists()
+    finally:
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+async def test_cloud_creation_reconciles_jobs_on_loop_and_saves_on_worker(
+    tmp_path, monkeypatch
+):
+    uploads, manager, backend, _rows = make_cloud(
+        tmp_path, monkeypatch, staging_budget_bytes=3
+    )
+    item = uploads.create("finished.bin", "/", 3)
+    job = await manager.registry.create("queued", transfer_id=item["id"], total=3)
+    (await manager.registry.update(job.id, status=TransferStatus.COMPLETED))
+    loop_thread = threading.get_ident()
+    write, get = backend.write, manager.registry.get
+
+    def worker_write(*args, **kwargs):
+        assert threading.get_ident() != loop_thread
+        return write(*args, **kwargs)
+
+    def loop_get(*args, **kwargs):
+        assert threading.get_ident() == loop_thread
+        return get(*args, **kwargs)
+
+    monkeypatch.setattr(backend, "write", worker_write)
+    monkeypatch.setattr(manager.registry, "get", loop_get)
+    try:
+        replacement = await uploads.create_async("replacement.bin", "/", 3)
+        assert replacement["state"] == "receiving"
+        assert uploads.get_unchecked(item["id"])["state"] == "finished"
+        assert not uploads.path(item["id"]).exists()
+    finally:
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+async def test_explicit_folder_metadata_survives_receipt_restart_and_job_handoff(
+    tmp_path,
+):
+    uploads, manager = make(tmp_path)
+    folder = manager.store.create_folder("/", "Photos")
+    root_path = "/" + folder["id"]
+    metadata = {
+        "id": "folder-upload-session-1",
+        "name": "Photos",
+        "root_path": root_path,
+        "created_at": 1234.5,
+    }
+    original = copy.deepcopy(metadata)
+    try:
+        item = await uploads.create_async(
+            "one.bin", root_path, 3, folder_upload=metadata
+        )
+        metadata["name"] = "Caller mutation"
+        assert item["folder_upload"] == original
+        uploads.close()
+        uploads, _ = make(tmp_path, manager=manager)
+        assert uploads.get_unchecked(item["id"])["folder_upload"] == original
+        await uploads.append(item["id"], 0, b"one")
+        job = await uploads.complete(item["id"])
+        assert job.context["folder_upload"] == original
+        assert job.as_dict()["folder_upload"] == original
+        history = await manager.registry.history()
+        assert history["jobs"][0]["folder_upload"] == original
+        standalone = uploads.create("standalone.bin", "/", 3)
+        assert "folder_upload" not in standalone
+        with pytest.raises(UploadError, match="outside"):
+            uploads.create("outside.bin", "/", 3, folder_upload=original)
+    finally:
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+@pytest.mark.parametrize("move_ancestor", [False, True])
+async def test_new_folder_receipts_follow_moved_root_and_ancestor(
+    tmp_path, move_ancestor
+):
+    uploads, manager = make(tmp_path)
+    store = manager.store
+    ancestor = store.create_folder("/", "Original parent")
+    ancestor_path = "/" + ancestor["id"]
+    folder = store.create_folder(ancestor_path, "Photos")
+    original_root = ancestor_path + "/" + folder["id"]
+    child = store.create_folder(original_root, "Nested")
+    original_parent = original_root + "/" + child["id"]
+    target = store.create_folder("/", "Moved here")
+    target_path = "/" + target["id"]
+    metadata = {
+        "id": "folder-upload-session-moved",
+        "name": "Photos",
+        "root_path": original_root,
+        "created_at": 1234.5,
+    }
+    try:
+        store.move(ancestor_path if move_ancestor else original_root, target_path)
+        current_root = store.resolve_id(folder["id"])
+        current_parent = store.resolve_id(child["id"])
+        item = await uploads.create_async(
+            "later.bin", original_parent, 3, folder_upload=metadata
+        )
+        assert item["parent_id"] == current_parent
+        assert item["parent_node_id"] == child["id"]
+        assert item["folder_upload"] == metadata | {"root_path": current_root}
+        assert metadata["root_path"] == original_root
+        await uploads.append(item["id"], 0, b"one")
+        job = await uploads.complete(item["id"])
+        assert job.context["destination"] == current_parent
+        assert job.context["folder_upload"]["id"] == metadata["id"]
+        assert job.context["folder_upload"]["name"] == metadata["name"]
+        assert job.context["folder_upload"]["root_path"] == current_root
+        with pytest.raises(UploadError, match="outside"):
+            await uploads.create_async(
+                "unrelated.bin", target_path, 3, folder_upload=metadata
+            )
+    finally:
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
diff --git a/tests/transfers/test_showcase_transfers.py b/tests/transfers/test_showcase_transfers.py
new file mode 100644
index 00000000..14165d82
--- /dev/null
+++ b/tests/transfers/test_showcase_transfers.py
@@ -0,0 +1,65 @@
+"""Illustrative demo jobs keep moving without touching real transfer lifecycles."""
+
+from collections import deque
+from types import SimpleNamespace
+
+import tgdrive.transfers.tasks as tasks
+from tests.support.showcase_data import advance_transfers
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+
+async def test_showcase_cycles_stages_queue_slots_and_measured_speed(monkeypatch):
+    clock = SimpleNamespace(now=1000.0)
+    monkeypatch.setattr(tasks.time, "time", lambda: clock.now)
+    monkeypatch.setattr(tasks.time, "monotonic", lambda: clock.now)
+    registry = TransferRegistry()
+    jobs = []
+    for phase in ("downloading", "uploading", "queued", "queued"):
+        job = await registry.create(phase, total=32 * 1024**2)
+        job.context.update(
+            showcase_active=True,
+            source_kind="remote" if phase == "downloading" else "upload",
+        )
+        (
+            await registry.update(
+                job.id,
+                status=TransferStatus.QUEUED
+                if phase == "queued"
+                else TransferStatus.RUNNING,
+                current=0,
+            )
+        )
+        jobs.append(job)
+    ordinary = await registry.create("uploading", total=100)
+    (await registry.update(ordinary.id, status=TransferStatus.RUNNING, current=50))
+    pending = deque(job.id for job in jobs[2:])
+    seen = {job.id: set() for job in jobs}
+    speeds = []
+    for tick in range(1, 140):
+        clock.now += 2
+        (await advance_transfers(registry, [job.id for job in jobs], pending, tick))
+        assert sum(job.status == TransferStatus.RUNNING for job in jobs) == 2
+        for job in jobs:
+            seen[job.id].add((job.status, job.phase))
+            assert job.current != job.total - 1
+            if speed := job.as_dict()["speed_bytes_per_second"]:
+                speeds.append(speed)
+                assert speed > 0
+                assert job.as_dict()["eta_seconds"] > 0
+        assert ordinary.current == 50
+    assert speeds
+    for phases in seen.values():
+        assert (TransferStatus.RUNNING, "uploading") in phases
+        assert (TransferStatus.RUNNING, "finalizing") in phases
+        assert (TransferStatus.QUEUED, "queued") in phases
+    (
+        await registry.update(
+            jobs[0].id, status=TransferStatus.CANCELLED, phase="cancelled"
+        )
+    )
+    snapshot = jobs[0].as_dict()
+    for tick in range(140, 160):
+        clock.now += 2
+        (await advance_transfers(registry, [job.id for job in jobs], pending, tick))
+    assert jobs[0].as_dict() == snapshot
+    registry.close()
diff --git a/tests/transfers/test_staging_admission.py b/tests/transfers/test_staging_admission.py
new file mode 100644
index 00000000..23fd178f
--- /dev/null
+++ b/tests/transfers/test_staging_admission.py
@@ -0,0 +1,424 @@
+from __future__ import annotations
+
+import asyncio
+import errno
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tests.support.app_fixtures import make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tests.transfers.test_resumable_uploads import make
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.settings.performance_preferences import PerformanceSettings
+from tgdrive.transfers.staging import staging_usage
+from tgdrive.transfers.tasks import TransferStatus
+from tgdrive.transfers.uploads import UploadError
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    return register_test_backend(monkeypatch, tmp_path / "data")
+
+
+async def test_upload_reservations_prevent_overbooking_and_release_after_cancel(
+    tmp_path, monkeypatch
+):
+    uploads, _manager = make(
+        tmp_path, min_free_bytes=20, upload_limit=100, staging_budget_bytes=1000
+    )
+    monkeypatch.setattr(
+        "tgdrive.transfers.staging.shutil.disk_usage",
+        lambda path: SimpleNamespace(free=150),
+    )
+
+    async def admit(name):
+        return uploads.create(name, "/", 80)
+
+    results = await asyncio.gather(admit("a"), admit("b"), return_exceptions=True)
+    assert sum(isinstance(item, dict) for item in results) == 1
+    failure = next(item for item in results if isinstance(item, UploadError))
+    assert failure.status == 507 and "free disk space" in str(failure)
+    item = next(item for item in results if isinstance(item, dict))
+    assert uploads.path(item["id"]).stat().st_size == 0
+    await uploads.cancel(item["id"])
+    assert uploads.create("c", "/", 80)["offset"] == 0
+
+
+async def test_browser_admission_includes_url_reservations_and_retained_bytes(
+    tmp_path, monkeypatch
+):
+    uploads, manager = make(
+        tmp_path, upload_limit=1000, staging_budget_bytes=1000, min_free_bytes=10
+    )
+    manager.uploads = uploads
+    job = await manager.registry.create("downloading", total=100)
+    job.context.update(staging_size=100, staging_written=40)
+    (await manager.registry.update(job.id, status=TransferStatus.RUNNING))
+    monkeypatch.setattr(
+        "tgdrive.transfers.staging.shutil.disk_usage",
+        lambda path: SimpleNamespace(free=150),
+    )
+    with pytest.raises(UploadError) as error:
+        uploads.create("b", "/", 90)
+    assert error.value.status == 507
+    assert staging_usage(manager) == (100, 60)
+    # Terminal failure releases future claims; retained bytes still count.
+    path = tmp_path / "retained"
+    path.write_bytes(b"x" * 40)
+    job.context["local_path"] = str(path)
+    (await manager.registry.update(job.id, status=TransferStatus.ERROR))
+    assert staging_usage(manager) == (40, 0)
+
+
+def test_large_declared_upload_can_exceed_16_gib_without_allocating_file(
+    tmp_path, monkeypatch
+):
+    size = 20 * 1024**3
+    uploads, _ = make(
+        tmp_path,
+        upload_limit=32 * 1024**3,
+        staging_budget_bytes=64 * 1024**3,
+        min_free_bytes=1024**3,
+    )
+    seen = []
+
+    def disk(path):
+        seen.append(path)
+        return SimpleNamespace(free=100 * 1024**3)
+
+    monkeypatch.setattr("tgdrive.transfers.staging.shutil.disk_usage", disk)
+    item = uploads.create("large.bin", "/", size)
+    assert item["total_size"] == size
+    assert uploads.path(item["id"]).stat().st_size == 0
+    assert seen == [uploads.settings.resolved_cache_dir]
+
+
+async def test_restart_keeps_future_bytes_reserved_and_does_not_double_count_job(
+    tmp_path, monkeypatch
+):
+    uploads, manager = make(
+        tmp_path, staging_budget_bytes=200, upload_limit=100, min_free_bytes=10
+    )
+    item = uploads.create("a", "/", 80)
+    uploads.close()
+    resumed, _ = make(
+        tmp_path,
+        manager=manager,
+        staging_budget_bytes=200,
+        upload_limit=100,
+        min_free_bytes=10,
+    )
+    manager.uploads = resumed
+    assert staging_usage(manager) == (80, 80)
+    monkeypatch.setattr(
+        "tgdrive.transfers.staging.shutil.disk_usage",
+        lambda path: SimpleNamespace(free=150),
+    )
+    with pytest.raises(UploadError):
+        resumed.create("b", "/", 80)
+    await resumed.append(item["id"], 0, b"x" * 80)
+    await resumed.complete(item["id"])
+    assert staging_usage(manager) == (80, 0)
+
+
+async def test_disk_quota_error_keeps_receipt_acknowledgement_for_resume(
+    tmp_path, monkeypatch
+):
+    uploads, _ = make(tmp_path)
+    item = uploads.create("a", "/", 3)
+    original = uploads.path(item["id"]).open
+
+    class FullFile:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *args):
+            pass
+
+        def truncate(self, offset):
+            pass
+
+        def seek(self, offset):
+            pass
+
+        def write(self, body):
+            raise OSError(errno.ENOSPC, "full")
+
+    monkeypatch.setattr(
+        type(uploads.root),
+        "open",
+        lambda self, *args, **kwargs: (
+            FullFile() if self.name.endswith(".part") else original(*args, **kwargs)
+        ),
+    )
+    with pytest.raises(UploadError) as error:
+        await uploads.append(item["id"], 0, b"abc")
+    assert error.value.status == 507
+    assert uploads.get(item["id"])["offset"] == 0
+
+
+async def test_owner_limits_persist_and_reject_invalid_combinations(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    settings.max_file_size = None
+    settings.staging_budget_bytes = 24 * 1024**3
+    state = SimpleNamespace(
+        mongo=mongo_backend,
+        pool=SimpleNamespace(
+            _slots=[], set_media_per_bot=AsyncMock(), set_media_queue_limit=AsyncMock()
+        ),
+    )
+    service = PerformanceSettings(settings, state)
+    assert (await service.snapshot())["max_file_size"] == 24 * 1024**3
+    for changes in [
+        {"max_file_size": 32 * 1024**3},
+        {"min_free_bytes": 0},
+        {"staging_budget_bytes": True},
+    ]:
+        with pytest.raises((SettingsProblem, ValueError)):
+            await service.save(changes)
+    after = await service.save(
+        {
+            "max_file_size": 32 * 1024**3,
+            "staging_budget_bytes": 64 * 1024**3,
+            "min_free_bytes": 1024**3,
+        }
+    )
+    assert settings.upload_limit == 32 * 1024**3
+    second = PerformanceSettings(settings, state)
+    assert (await second.snapshot())["staging_budget_bytes"] == after[
+        "staging_budget_bytes"
+    ]
+    await state.preloads.close()
+
+
+def test_unavailable_disk_fails_before_creating_receipt(tmp_path, monkeypatch):
+    uploads, _ = make(tmp_path)
+
+    def missing(path):
+        raise OSError("drive offline")
+
+    monkeypatch.setattr("tgdrive.transfers.staging.shutil.disk_usage", missing)
+    with pytest.raises(UploadError) as error:
+        uploads.create("a", "/", 3)
+    assert error.value.status == 503
+    assert not list(uploads.root.glob("*.part"))
+
+
+@pytest.mark.parametrize("known", [True, False])
+@pytest.mark.parametrize("reserved", [True, False])
+async def test_url_import_checks_shared_space_before_reading_body(
+    tmp_path, monkeypatch, known, reserved
+):
+    from tests.transfers.test_remote import (
+        PUBLIC_DNS,
+        FakeResolver,
+        FakeResponse,
+        FakeSession,
+    )
+    from tests.transfers.test_transfers import make_manager
+    from tgdrive.transfers.remote import RemoteClient
+
+    manager, store, _, pool = await make_manager(tmp_path, max_size=100)
+    manager.settings.min_free_bytes = 10
+    response = FakeResponse(
+        200, headers={"Content-Length": "80"} if known else {}, chunks=[b"x" * 80]
+    )
+    manager.remote = RemoteClient(
+        max_bytes=100,
+        session=FakeSession([response]),
+        resolver=FakeResolver(PUBLIC_DNS),
+    )
+    monkeypatch.setattr(
+        "tgdrive.transfers.staging.shutil.disk_usage",
+        lambda path: SimpleNamespace(free=50),
+    )
+    record = await manager.start_remote(
+        url="https://files.example/a", destination="/", filename=None
+    )
+    if reserved:
+        # A restarted import must recheck admission even if its old reservation
+        # has the same size as this source response.
+        record.context.update(staging_size=80 if known else 100, staging_written=40)
+        (await manager.registry.persist(record))
+    import asyncio
+
+    waiting = asyncio.Event()
+    original_cancelable = manager.remote._cancelable
+
+    async def observe_wait(operation, event, **kwargs):
+        if record.context.get("download_mode") == "waiting_storage":
+            waiting.set()
+        return await original_cancelable(operation, event, **kwargs)
+
+    monkeypatch.setattr(manager.remote, "_cancelable", observe_wait)
+    await asyncio.wait_for(waiting.wait(), 3)
+    assert not record.task.done()
+    assert list(response.content.chunks) == [b"x" * 80]
+    record.cancel_event.set()
+    await record.task
+    assert record.status == TransferStatus.CANCELLED
+    assert not list((tmp_path / "cache" / "remote" / record.id).glob("*.part"))
+    await manager.remote.close()
+    await pool.stop()
+    store.close()
+
+
+async def test_owner_cannot_shrink_budget_below_reserved_receipts(
+    tmp_path, mongo_backend
+):
+    settings = make_settings(tmp_path)
+    uploads, manager = make(tmp_path)
+    manager.uploads = uploads
+    uploads.settings.upload_limit = 32 * 1024**3
+    uploads.settings.staging_budget_bytes = 64 * 1024**3
+    # Metadata-only reservation; no large allocation is required.
+    item = uploads.create("held.bin", "/", 3)
+    item["total_size"] = 24 * 1024**3
+    uploads._save(item)
+    state = SimpleNamespace(
+        transfers=manager, pool=SimpleNamespace(_slots=[]), mongo=mongo_backend
+    )
+    service = PerformanceSettings(settings, state)
+    before = await service.snapshot()
+    with pytest.raises(SettingsProblem) as error:
+        await service.save(
+            {"staging_budget_bytes": 16 * 1024**3, "max_file_size": 16 * 1024**3}
+        )
+    assert error.value.status == 409
+    assert (await service.snapshot())["revision"] == before["revision"]
+    await state.preloads.close()
+
+
+@pytest.mark.parametrize("known", [True, False])
+async def test_url_reserves_once_and_reports_live_written_bytes(
+    tmp_path, monkeypatch, known, mongo_backend
+):
+    from tests.transfers.test_remote import (
+        PUBLIC_DNS,
+        FakeResolver,
+        FakeResponse,
+        FakeSession,
+    )
+    from tests.transfers.test_transfers import make_manager
+    from tgdrive.transfers.remote import RemoteClient
+    from tgdrive.transfers.staging import check_staging
+    from tgdrive.transfers.tasks import TransferRegistry
+
+    manager, store, _, pool = await make_manager(tmp_path, max_size=100)
+    manager.registry = TransferRegistry(
+        mongo=mongo_backend.db.jobs, mongo_backend=mongo_backend
+    )
+    manager.settings.min_free_bytes = 0
+    response = FakeResponse(
+        200,
+        headers={"Content-Length": "64"} if known else {},
+        chunks=[b"x"] * 64,
+    )
+    manager.remote = RemoteClient(
+        max_bytes=100,
+        session=FakeSession([response]),
+        resolver=FakeResolver(PUBLIC_DNS),
+    )
+    admissions = []
+    written = []
+
+    def admit(*args, **kwargs):
+        admissions.append(args[2])
+        return check_staging(*args, **kwargs)
+
+    monkeypatch.setattr("tgdrive.transfers.manager.check_staging", admit)
+    original_progress = manager.remote._report_progress
+
+    async def observe(callback, current, total):
+        await original_progress(callback, current, total)
+        written.append(current)
+        expected = 64 if known else 100
+        assert staging_usage(manager) == (expected, expected - current)
+        assert manager.registry._durable[record.id]["current"] == 0
+        assert manager.registry._durable[record.id]["context"]["staging_written"] == 0
+
+    monkeypatch.setattr(manager.remote, "_report_progress", observe)
+    record = await manager.start_remote(
+        url="https://files.example/a", destination="/", filename=None
+    )
+    try:
+        await record.task
+        assert record.status == TransferStatus.COMPLETED, record.error
+        assert admissions == [64 if known else 100]
+        assert written == list(range(65))
+    finally:
+        await manager.close()
+        await pool.stop()
+        store.close()
+
+
+async def test_waiting_url_reserves_a_window_instead_of_the_whole_file(
+    tmp_path, monkeypatch
+):
+    import asyncio
+
+    from tests.transfers.test_remote import (
+        PUBLIC_DNS,
+        FakeResolver,
+        FakeResponse,
+        FakeSession,
+    )
+    from tests.transfers.test_transfers import make_manager
+    from tgdrive.transfers.remote import RemoteClient
+
+    manager, store, _, pool = await make_manager(tmp_path, max_size=100)
+    manager.settings.staging_budget_bytes = 64
+    manager.settings.min_free_bytes = 0
+    monkeypatch.setattr("tgdrive.transfers.remote_scheduler.WARM_STAGING_WINDOW", 8)
+    first_read, warm_read = asyncio.Event(), asyncio.Event()
+    first = FakeResponse(200, headers={"Content-Length": "48"}, chunks=[b"x" * 48])
+    second = FakeResponse(200, headers={"Content-Length": "48"}, chunks=[b"y" * 48])
+
+    async def held_read(_size):
+        first_read.set()
+        await asyncio.Event().wait()
+
+    original_read = second.content.read
+
+    async def observe_read(size):
+        warm_read.set()
+        return await original_read(size)
+
+    first.content.read = held_read
+    second.content.read = observe_read
+    manager.remote = RemoteClient(
+        max_bytes=100,
+        chunk_size=4,
+        download_concurrency=1,
+        session=FakeSession([first, second]),
+        resolver=FakeResolver(PUBLIC_DNS),
+    )
+    records = []
+    try:
+        records.append(
+            await manager.start_remote(
+                url="https://files.example/first", destination="/", filename=None
+            )
+        )
+        await asyncio.wait_for(first_read.wait(), 3)
+        records.append(
+            await manager.start_remote(
+                url="https://files.example/second", destination="/", filename=None
+            )
+        )
+        await asyncio.wait_for(warm_read.wait(), 3)
+        assert records[0].context["staging_size"] == 48
+        assert records[1].context["staging_size"] == 8
+        assert records[1].context["download_mode"] == "warm"
+        assert staging_usage(manager)[0] == 56
+    finally:
+        for record in records:
+            record.cancel_event.set()
+        await asyncio.gather(*(record.task for record in records))
+        await manager.close()
+        await pool.stop()
+        store.close()
diff --git a/tests/transfers/test_tasks.py b/tests/transfers/test_tasks.py
new file mode 100644
index 00000000..21892e52
--- /dev/null
+++ b/tests/transfers/test_tasks.py
@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+import asyncio
+import errno
+import logging
+import time
+
+import pytest
+
+from tests.support.mongo_fixtures import FakeMongoBackend
+from tgdrive.transfers.tasks import (
+    TransferNotFound,
+    TransferRegistry,
+    TransferStatus,
+)
+
+
+async def test_lifecycle_logs_skip_progress_and_unchanged_waits(caplog) -> None:
+    caplog.set_level(logging.INFO, logger="tgdrive.transfers.tasks")
+    registry = TransferRegistry()
+    record = await registry.create("queued", total=100)
+    record.context.update(kind="upload", name="private-name", url="private-url")
+    (await registry.update(record.id, status=TransferStatus.RUNNING, phase="uploading"))
+    for current in range(100):
+        (await registry.update(record.id, current=current))
+        (await registry.persist(record))
+    (await registry.update(record.id, phase="waiting_for_telegram"))
+    for _ in range(10):
+        (await registry.update(record.id, phase="waiting_for_telegram"))
+    record.context["retry_at"] = time.time() + 60
+    for _ in range(10):
+        (await registry.persist(record))
+    (await registry.update(record.id, phase="retry_wait"))
+    (
+        await registry.update(
+            record.id, status=TransferStatus.COMPLETED, phase="completed", current=100
+        )
+    )
+    (await registry.persist(record))
+
+    messages = [row.getMessage() for row in caplog.records]
+    assert len(messages) == 4
+    assert sum("Transfer started" in message for message in messages) == 1
+    assert sum("Transfer finished" in message for message in messages) == 1
+    assert sum("Transfer waiting" in message for message in messages) == 1
+    assert sum("Transfer retry scheduled" in message for message in messages) == 1
+    assert "telegram_cooldown" in caplog.text
+    assert "private-name" not in caplog.text and "private-url" not in caplog.text
+
+
+@pytest.mark.asyncio
+async def test_failure_log_has_cause_type_and_action_without_private_detail(caplog):
+    caplog.set_level(logging.INFO, logger="tgdrive.transfers.tasks")
+    registry = TransferRegistry()
+    record = await registry.create("uploading")
+
+    async def fail(_record):
+        raise TimeoutError("private-source-url password=secret")
+
+    await registry.spawn(record.id, fail)
+
+    assert "error_type=TimeoutError retryable=True" in caplog.text
+    assert "code=TRANSPORT_INTERRUPTED" in caplog.text
+    assert "restore the connection and retry" in caplog.text
+    assert "private-source-url" not in caplog.text
+    assert "secret" not in caplog.text
+    assert "Traceback" not in caplog.text
+
+
+def test_failure_diagnostics_classify_repairs_without_private_messages():
+    from tgdrive.storage.mongo import DatabaseUnavailable
+    from tgdrive.telegram.connection_errors import TelegramConnectionError
+    from tgdrive.transfers.remote import RemoteHTTPError
+    from tgdrive.transfers.tasks import _failure_diagnostic
+
+    for error, expected in (
+        (DatabaseUnavailable("private database URI"), "DATABASE_UNAVAILABLE"),
+        (OSError(errno.ENOSPC, "private path"), "STAGING_FULL"),
+        (RemoteHTTPError(403, "https://private-source"), "REMOTE_HTTP_403"),
+        (
+            TelegramConnectionError("private account", "TELEGRAM_CHANNEL_ACCESS"),
+            "TELEGRAM_CHANNEL_ACCESS",
+        ),
+    ):
+        code, action = _failure_diagnostic(error)
+        assert code == expected
+        assert "private" not in action
+
+
+async def test_reloaded_transfer_does_not_repeat_existing_lifecycle(caplog, tmp_path):
+    caplog.set_level(logging.INFO, logger="tgdrive.transfers.tasks")
+    backend = FakeMongoBackend()
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = await registry.create("uploading", total=10)
+    (await registry.update(record.id, status=TransferStatus.RUNNING))
+    registry.close()
+    caplog.clear()
+
+    resumed = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    (await resumed.persist(resumed.get(record.id)))
+    assert not caplog.records
+    resumed.close()
+
+
+async def test_registry_updates_and_prunes_terminal_records() -> None:
+    registry = TransferRegistry(ttl_seconds=60)
+    record = await registry.create("saving", total=10)
+    (
+        await registry.update(
+            record.id,
+            status=TransferStatus.COMPLETED,
+            current=10,
+            total=10,
+        )
+    )
+    record.updated_at = 1.0
+
+    (await registry.prune(now=62.0))
+    with pytest.raises(TransferNotFound):
+        registry.get(record.id)
+
+
+async def test_registry_cancellation_sets_event() -> None:
+    registry = TransferRegistry()
+    record = await registry.create("downloading")
+
+    (await registry.cancel(record.id))
+    assert record.cancel_event.is_set()
+    assert record.status is TransferStatus.CANCELLED
+    assert record.phase == "cancelling"
+    assert record.error == "Transfer cancelled"
+
+
+async def test_late_progress_cannot_mutate_cancelled_snapshot() -> None:
+    registry = TransferRegistry()
+    record = await registry.create("uploading", total=100)
+    (
+        await registry.update(
+            record.id,
+            status=TransferStatus.RUNNING,
+            current=40,
+        )
+    )
+
+    (await registry.cancel(record.id))
+    cancelled_snapshot = record.as_dict()
+    (
+        await registry.update(
+            record.id,
+            status=TransferStatus.COMPLETED,
+            phase="completed",
+            current=100,
+        )
+    )
+
+    assert record.as_dict() == cancelled_snapshot
+    assert record.status is TransferStatus.CANCELLED
+    assert record.current == 40 and record.total == 100
+    assert record.error == "Transfer cancelled"
+
+
+@pytest.mark.asyncio
+async def test_spawn_observes_errors() -> None:
+    registry = TransferRegistry()
+    record = await registry.create("uploading")
+
+    async def fail(_record: object) -> None:
+        raise RuntimeError("network failed")
+
+    task = registry.spawn(record.id, fail)
+    await task
+
+    assert record.status is TransferStatus.ERROR
+    assert record.error == "network failed"
+
+
+@pytest.mark.asyncio
+async def test_shutdown_cancels_and_drains_tasks() -> None:
+    registry = TransferRegistry(ttl_seconds=60)
+    record = await registry.create("uploading")
+    started = asyncio.Event()
+
+    async def wait_forever(_record: object) -> None:
+        started.set()
+        await asyncio.Event().wait()
+
+    registry.spawn(record.id, wait_forever)
+    await started.wait()
+    expired = await registry.create("completed")
+    (await registry.update(expired.id, status=TransferStatus.COMPLETED))
+    expired.updated_at = time.monotonic() - 61
+    await registry.shutdown()
+
+    assert record.cancel_event.is_set()
+    assert record.status is TransferStatus.CANCELLED
+
+
+@pytest.mark.asyncio
+async def test_uncooperative_cancel_is_forced_after_grace_period() -> None:
+    registry = TransferRegistry(cancel_grace_seconds=0.01)
+    record = await registry.create("uploading")
+    started = asyncio.Event()
+
+    async def ignore_event(_record: object) -> None:
+        started.set()
+        await asyncio.Event().wait()
+
+    task = registry.spawn(record.id, ignore_event)
+    await started.wait()
+    (await registry.cancel(record.id))
+
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+    assert record.status is TransferStatus.CANCELLED
+    assert record.cancel_handle is None
+
+
+@pytest.mark.asyncio
+async def test_cancelling_one_transfer_does_not_affect_another() -> None:
+    registry = TransferRegistry(cancel_grace_seconds=0.01)
+    first = await registry.create("uploading")
+    second = await registry.create("uploading")
+    first_started = asyncio.Event()
+    second_started = asyncio.Event()
+    second_release = asyncio.Event()
+
+    async def hold_first(record: object) -> None:
+        (await registry.update(first.id, status=TransferStatus.RUNNING))
+        first_started.set()
+        await asyncio.Event().wait()
+
+    async def finish_second(record: object) -> None:
+        (await registry.update(second.id, status=TransferStatus.RUNNING))
+        second_started.set()
+        await second_release.wait()
+        (
+            await registry.update(
+                second.id,
+                status=TransferStatus.COMPLETED,
+                phase="completed",
+            )
+        )
+
+    first_task = registry.spawn(first.id, hold_first)
+    second_task = registry.spawn(second.id, finish_second)
+    await asyncio.gather(first_started.wait(), second_started.wait())
+
+    (await registry.cancel(first.id))
+
+    assert first.status is TransferStatus.CANCELLING
+    assert not second.cancel_event.is_set()
+    assert second.status is TransferStatus.RUNNING
+
+    second_release.set()
+    await second_task
+    with pytest.raises(asyncio.CancelledError):
+        await first_task
+
+    assert second.status is TransferStatus.COMPLETED
+
+
+@pytest.mark.asyncio
+async def test_cancelled_running_task_cannot_be_pruned_or_evicted() -> None:
+    registry = TransferRegistry(max_entries=1)
+    record = await registry.create("uploading")
+    started = asyncio.Event()
+
+    async def hold(_record: object) -> None:
+        started.set()
+        await asyncio.Event().wait()
+
+    registry.spawn(record.id, hold)
+    await started.wait()
+    (await registry.cancel(record.id))
+    record.updated_at = 1
+    (await registry.prune(now=10000))
+
+    assert registry.get(record.id) is record
+    with pytest.raises(RuntimeError, match="too many active"):
+        (await registry.create("uploading"))
+
+    await registry.shutdown()
+    with pytest.raises(RuntimeError, match="shutting down"):
+        (await registry.create("uploading"))
+
+
+@pytest.mark.asyncio
+async def test_shutdown_retries_cancellation_of_stalled_finalizer(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    import tgdrive.transfers.tasks as tasks_module
+
+    monkeypatch.setattr(tasks_module, "_SHUTDOWN_DRAIN_SECONDS", 0.01)
+    registry = TransferRegistry()
+    record = await registry.create("uploading")
+    started = asyncio.Event()
+
+    async def stall_cleanup(_record: object) -> None:
+        try:
+            started.set()
+            await asyncio.Event().wait()
+        finally:
+            await asyncio.Event().wait()
+
+    task = registry.spawn(record.id, stall_cleanup)
+    await started.wait()
+    await asyncio.wait_for(registry.shutdown(), timeout=1)
+
+    assert task.done()
+    assert task.cancelled()
+
+
+def test_multipart_progress_distinguishes_sent_bytes_from_channel_publication():
+    from tgdrive.transfers.tasks import TransferRecord
+
+    record = TransferRecord(
+        id="multipart-counter",
+        phase="uploading",
+        current=3200,
+        total=4500,
+        context={
+            "multipart_plan": {
+                "parts": [
+                    {"size": 2000, "confirmed": False, "sender": "private-client"},
+                    {"size": 2000, "confirmed": False},
+                    {"size": 500, "confirmed": False},
+                ]
+            }
+        },
+    )
+    snapshot = record.as_dict()
+    assert snapshot["current"] == 3200
+    assert snapshot["telegram_parts"] == {"total": 3, "stored": 0}
+    assert "private-client" not in str(snapshot)
+    record.context["multipart_plan"]["parts"][0]["confirmed"] = True
+    assert record.as_dict()["telegram_parts"] == {"total": 3, "stored": 1}
+
+
+@pytest.mark.parametrize(
+    ("error", "retryable"),
+    [
+        (TimeoutError("provider timeout"), True),
+        (ConnectionError("connection lost"), True),
+        (OSError(errno.ENETUNREACH, "network unreachable"), True),
+        (OSError(errno.ENOSPC, "disk full"), False),
+        (PermissionError("no permission"), False),
+        (ValueError("invalid configuration"), False),
+    ],
+)
+async def test_only_temporary_connection_errors_are_marked_for_restart(
+    tmp_path, error, retryable
+):
+    backend = FakeMongoBackend()
+    registry = TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend)
+    record = await registry.create("uploading")
+    record.context["kind"] = "upload"
+
+    async def fail(_record):
+        raise error
+
+    try:
+        await registry.spawn(record.id, fail)
+        assert record.status is TransferStatus.ERROR
+        assert bool(record.context.get("restart_retryable")) is retryable
+        if retryable:
+            assert "restart TGDrive" in record.error
+        (await registry.retry(record.id))
+        assert "restart_retryable" not in record.context
+    finally:
+        registry.close()
diff --git a/tests/transfers/test_transfer_history.py b/tests/transfers/test_transfer_history.py
new file mode 100644
index 00000000..643f0aa7
--- /dev/null
+++ b/tests/transfers/test_transfer_history.py
@@ -0,0 +1,637 @@
+from __future__ import annotations
+
+import copy
+import json
+import time
+from types import SimpleNamespace
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.storage.mongo import for_directory
+from tgdrive.storage.store import DriveStore
+from tgdrive.transfers.tasks import TransferNotFound, TransferRegistry, TransferStatus
+from tgdrive.web.app import create_app
+
+pytestmark = pytest.mark.usefixtures("mongo_backend")
+
+
+@pytest.fixture
+def mongo_backend(tmp_path, monkeypatch):
+    backend = register_test_backend(monkeypatch, tmp_path)
+    register_test_backend(monkeypatch, tmp_path / "data", backend)
+    return backend
+
+
+def registry_for(path, **kwargs):
+    if path is None:
+        return TransferRegistry(**kwargs)
+    backend = for_directory(path.parent)
+    return TransferRegistry(mongo=backend.db.jobs, mongo_backend=backend, **kwargs)
+
+
+async def add(
+    registry,
+    name,
+    status,
+    *,
+    created=1000,
+    identity=None,
+    kind="upload",
+    folder_upload=None,
+):
+    record = await registry.create("uploading", total=100, transfer_id=identity)
+    record.context.update(
+        name=name,
+        destination="/",
+        kind=kind,
+        local_path="/private/staged-file",
+        source_url="https://private/?token=secret",
+    )
+    if folder_upload is not None:
+        record.context["folder_upload"] = copy.deepcopy(folder_upload)
+    record.created_at = created
+    (
+        await registry.update(
+            record.id,
+            status=status,
+            current=100 if status is TransferStatus.COMPLETED else 20,
+        )
+    )
+    return record
+
+
+@pytest.mark.asyncio
+async def test_history_survives_prune_and_reopen_without_private_context(tmp_path):
+    path = tmp_path / "jobs.sqlite3"
+    registry = registry_for(path, ttl_seconds=60)
+    record = await add(registry, "kept.bin", TransferStatus.COMPLETED)
+    (await registry.prune(now=time.time() + 61))
+    with pytest.raises(TransferNotFound):
+        registry.get(record.id)
+    assert registry.list() == []
+    page = await registry.history(status="completed")
+    assert page["jobs"][0]["name"] == "kept.bin"
+    assert page["jobs"][0]["retained"] is False
+    assert "secret" not in json.dumps(page)
+    assert "context" not in json.dumps(page)
+    assert "staged-file" not in json.dumps(page)
+    registry.close()
+    reopened = registry_for(path)
+    assert reopened.list() == []
+    assert (await reopened.history())["jobs"][0]["id"] == record.id
+    reopened.close()
+
+
+@pytest.mark.asyncio
+async def test_name_search_filters_before_cursor_pagination_across_archives(tmp_path):
+    registry = registry_for(tmp_path / "search.sqlite3", ttl_seconds=1)
+    for index in range(75):
+        (
+            await add(
+                registry,
+                f"other-{index}.bin",
+                TransferStatus.COMPLETED,
+                created=2000 + index,
+            )
+        )
+    for index in range(3):
+        (
+            await add(
+                registry,
+                f"Résumé [.*] {index}.txt",
+                TransferStatus.COMPLETED,
+                created=1000 + index,
+                identity=f"match-{index}",
+            )
+        )
+    (await registry.prune(now=time.time() + 2))
+    first = await registry.history(status="finished", query="RÉSUMÉ [.*]", limit=2)
+    assert [row["id"] for row in first["jobs"]] == ["match-2", "match-1"]
+    assert first["has_more"]
+    second = await registry.history(
+        status="finished",
+        query="résumé [.*]",
+        limit=2,
+        before=(first["next_before"], first["next_before_id"]),
+    )
+    assert [row["id"] for row in second["jobs"]] == ["match-0"]
+    assert not second["has_more"]
+    assert (await registry.history(query="never present"))["jobs"] == []
+    registry.close()
+
+
+@pytest.mark.asyncio
+async def test_history_cursor_filters_and_deletions_are_independent_of_live_eviction(
+    tmp_path,
+):
+    registry = registry_for(tmp_path / "jobs.sqlite3", ttl_seconds=1)
+    for index in range(5):
+        (
+            await add(
+                registry,
+                str(index),
+                TransferStatus.COMPLETED,
+                created=1000 + index,
+                identity="history-" + str(index),
+            )
+        )
+    (await add(registry, "not-a-transfer", TransferStatus.COMPLETED, kind="delete"))
+    (await registry.prune(now=time.time() + 2))
+    queued = await add(registry, "queued", TransferStatus.QUEUED, created=1006)
+    (await add(registry, "running", TransferStatus.RUNNING, created=1007))
+    (await add(registry, "failed", TransferStatus.ERROR, created=1008))
+    first = await registry.history(limit=3)
+    assert [job["name"] for job in first["jobs"]] == ["failed", "running", "queued"]
+    assert first["has_more"]
+    second = await registry.history(
+        limit=3, before=(first["next_before"], first["next_before_id"])
+    )
+    assert [job["name"] for job in second["jobs"]] == ["4", "3", "2"]
+    assert second["has_more"]
+    third = await registry.history(
+        limit=3, before=(second["next_before"], second["next_before_id"])
+    )
+    assert [job["name"] for job in third["jobs"]] == ["1", "0"]
+    assert not third["has_more"]
+    assert (await registry.history(status="queued"))["jobs"][0]["id"] == queued.id
+    assert len((await registry.history(status="completed"))["jobs"]) == 5
+    assert (await registry.history(status="running"))["jobs"][0]["name"] == "running"
+    (await registry.retry((await registry.history(status="error"))["jobs"][0]["id"]))
+    assert (await registry.history(status="error"))["jobs"] == []
+    registry.close()
+
+
+async def test_history_http_owner_boundary_and_validation(tmp_path):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "catalog.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = for_directory(tmp_path)
+    record = await add(
+        runtime.transfers.registry, "owner-only.bin", TransferStatus.COMPLETED
+    )
+    try:
+        with TestClient(
+            create_app(settings, runtime=runtime), base_url="https://testserver"
+        ) as client:
+            route = "/api/v1/transfers/history"
+            assert client.get(route).status_code == 401
+            login(client)
+            response = client.get(route, params={"status": "completed", "limit": 1})
+            assert response.status_code == 200
+            assert response.headers["cache-control"] == "no-store"
+            assert response.json()["jobs"][0]["id"] == record.id
+            assert (
+                client.get(route, params={"status": "finished"}).json()["jobs"][0]["id"]
+                == record.id
+            )
+            assert client.get(route, params={"limit": 201}).status_code == 422
+            assert client.get(route, params={"status": "unknown"}).status_code == 422
+            assert client.get(route, params={"before": 1000}).status_code == 400
+            assert (
+                client.get(
+                    route, params={"before": "nan", "before_id": "safe"}
+                ).status_code
+                == 422
+            )
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("persistent", [False, True])
+async def test_finished_history_pages_mix_terminal_outcomes_without_active_jobs(
+    tmp_path, persistent
+):
+    registry = registry_for(
+        tmp_path / "jobs.sqlite3" if persistent else None,
+        ttl_seconds=1,
+    )
+    try:
+        (await add(registry, "success", TransferStatus.COMPLETED, created=1000))
+        (await add(registry, "cancelled", TransferStatus.CANCELLED, created=1001))
+        (await registry.prune(now=time.time() + 2))
+        (await add(registry, "failed", TransferStatus.ERROR, created=1002))
+        (await add(registry, "running", TransferStatus.RUNNING, created=1003))
+        (await add(registry, "queued", TransferStatus.QUEUED, created=1004))
+        first = await registry.history(status="finished", limit=2)
+        assert [job["name"] for job in first["jobs"]] == ["failed", "cancelled"]
+        assert first["has_more"]
+        second = await registry.history(
+            status="finished",
+            limit=2,
+            before=(first["next_before"], first["next_before_id"]),
+        )
+        assert [job["name"] for job in second["jobs"]] == ["success"]
+        assert not second["has_more"]
+        (await registry.retry(first["jobs"][0]["id"]))
+        assert [
+            job["name"] for job in (await registry.history(status="finished"))["jobs"]
+        ] == ["cancelled", "success"]
+    finally:
+        registry.close()
+
+
+@pytest.mark.asyncio
+async def test_history_search_reads_can_overlap_archive_writes_without_connection_races(
+    tmp_path,
+):
+    import asyncio
+
+    registry = registry_for(tmp_path / "concurrent.sqlite3", ttl_seconds=1)
+    done = asyncio.Event()
+    reads = 0
+
+    async def reader():
+        nonlocal reads
+        while not done.is_set():
+            page = await registry.history(status="finished", query="résumé", limit=200)
+            assert all("Résumé" in item["name"] for item in page["jobs"])
+            reads += 1
+
+    workers = [asyncio.create_task(reader()) for _ in range(8)]
+    try:
+        for index in range(100):
+            (
+                await add(
+                    registry,
+                    f"Résumé {index}",
+                    TransferStatus.COMPLETED,
+                    created=1000 + index,
+                )
+            )
+            (await registry.prune(now=time.time() + 2))
+            await asyncio.sleep(0)
+        done.set()
+        await asyncio.gather(*workers)
+        assert reads >= 8
+        assert (
+            len(
+                (await registry.history(status="finished", query="RÉSUMÉ", limit=200))[
+                    "jobs"
+                ]
+            )
+            == 100
+        )
+    finally:
+        done.set()
+        await asyncio.gather(*workers)
+        registry.close()
+
+
+class HistoryCursor(list):
+    def batch_size(self, _size):
+        return self
+
+    def sort(self, fields):
+        for key, direction in reversed(fields):
+            super().sort(key=lambda row: row.get(key), reverse=direction < 0)
+        return self
+
+    def limit(self, count):
+        return HistoryCursor(self[:count])
+
+
+class HistoryMongo:
+    """The archive operations used by task pages, without a MongoDB service."""
+
+    def __init__(self):
+        self.rows = {}
+
+    def find(self, query):
+        rows = list(self.rows.values())
+        if query.get("archived") is True:
+            rows = [row for row in rows if row.get("archived") is True]
+            if "$or" in query:
+                folders = query["$or"][0]["summary.folder_upload.id"]["$in"]
+                identities = query["$or"][1]["_id"]["$in"]
+                rows = [
+                    row
+                    for row in rows
+                    if row["_id"] in identities
+                    or row["summary"].get("folder_upload", {}).get("id") in folders
+                ]
+        else:
+            rows = [row for row in rows if row.get("archived") is not True]
+        return HistoryCursor(copy.deepcopy(rows))
+
+    def replace_one(self, query, document, **_kwargs):
+        self.rows[query["_id"]] = copy.deepcopy(document)
+
+    def delete_one(self, query):
+        self.rows.pop(query["_id"], None)
+
+    def delete_many(self, query):
+        removed = [
+            identity
+            for identity, row in self.rows.items()
+            if row.get("archived") is True
+            and row["status"] in query["status"]["$in"]
+            and row["summary"].get("folder_upload", {}).get("id")
+            not in query["summary.folder_upload.id"]["$nin"]
+        ]
+        for identity in removed:
+            del self.rows[identity]
+        return SimpleNamespace(deleted_count=len(removed))
+
+
+@pytest.fixture(params=["memory", "mongo"])
+def task_registry(request, tmp_path):
+    registry = TransferRegistry(
+        mongo=HistoryMongo() if request.param == "mongo" else None,
+        ttl_seconds=1,
+    )
+    try:
+        yield registry
+    finally:
+        registry.close()
+
+
+def folder_metadata(
+    identity="folder-session-0001", name="Holiday photos", created=1000
+):
+    return {
+        "id": identity,
+        "name": name,
+        "root_path": "/prepared-folder",
+        "created_at": created,
+    }
+
+
+async def test_clear_history_preserves_active_folders_and_recovery(task_registry):
+    registry = task_registry
+    active_folder = folder_metadata()
+    browser_folder = folder_metadata("browser-folder-0001")
+    for status in (
+        TransferStatus.COMPLETED,
+        TransferStatus.ERROR,
+        TransferStatus.CANCELLED,
+    ):
+        (await add(registry, "archived-" + status, status, kind="legacy"))
+    (
+        await add(
+            registry,
+            "active-child",
+            TransferStatus.COMPLETED,
+            folder_upload=active_folder,
+        )
+    )
+    (
+        await add(
+            registry,
+            "browser-child",
+            TransferStatus.COMPLETED,
+            folder_upload=browser_folder,
+        )
+    )
+    running = await add(
+        registry, "running", TransferStatus.RUNNING, folder_upload=active_folder
+    )
+    (await registry.prune(now=time.time() + 2))
+    for status in (TransferStatus.COMPLETED, TransferStatus.CANCELLED):
+        (await add(registry, "live-" + status, status))
+    failed = await add(registry, "retryable", TransferStatus.ERROR)
+    queued = await add(registry, "queued", TransferStatus.QUEUED)
+    deletion = await add(registry, "deletion", TransferStatus.COMPLETED, kind="delete")
+
+    assert (await registry.clear_history(exclude_folders=[browser_folder["id"]])) == 6
+    assert (await registry.clear_history(exclude_folders=[browser_folder["id"]])) == 0
+    names = {row["name"] for row in (await registry.history())["jobs"]}
+    assert names == {"active-child", "browser-child", "running", "queued"}
+    assert registry.get(failed.id).context["source_url"].endswith("token=secret")
+    assert registry.get(failed.id).history_hidden
+    assert not registry.get(running.id).history_hidden
+    assert not registry.get(queued.id).history_hidden
+    assert not registry.get(deletion.id).history_hidden
+    assert (await registry.task_history(status="finished"))["total_tasks"] == 1
+
+    (await registry.retry(failed.id))
+    assert not registry.get(failed.id).history_hidden
+    assert failed.id in {row["id"] for row in (await registry.history())["jobs"]}
+    (await registry.prune(now=time.time() + 2))
+    assert not any(
+        row["name"].startswith(("archived-", "live-"))
+        for row in (await registry.history())["jobs"]
+    )
+
+
+async def test_cleared_history_stays_cleared_after_restart_and_pruning(tmp_path):
+    path = tmp_path / "clear-history.sqlite3"
+    registry = registry_for(path, ttl_seconds=1)
+    completed = await add(registry, "completed", TransferStatus.COMPLETED)
+    failed = await add(registry, "failed", TransferStatus.ERROR)
+    assert (await registry.clear_history()) == 2
+    registry.close()
+    reopened = registry_for(path, ttl_seconds=1)
+    try:
+        assert reopened.get(failed.id).history_hidden
+        assert (await reopened.history())["jobs"] == []
+        (await reopened.prune(now=time.time() + 2))
+        assert (await reopened.task_history())["total_tasks"] == 0
+        with pytest.raises(TransferNotFound):
+            reopened.get(completed.id)
+    finally:
+        reopened.close()
+
+
+async def test_clear_history_api_requires_login_and_keeps_live_jobs(tmp_path):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "clear-api.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = for_directory(tmp_path)
+    finished = await add(
+        runtime.transfers.registry, "finished", TransferStatus.COMPLETED
+    )
+    queued = await add(runtime.transfers.registry, "queued", TransferStatus.QUEUED)
+    try:
+        with TestClient(
+            create_app(settings, runtime=runtime), base_url="https://testserver"
+        ) as client:
+            route = "/api/v1/transfers/history"
+            assert client.request("DELETE", route, json={}).status_code == 401
+            login(client)
+            response = client.request("DELETE", route, json={"exclude_folders": []})
+            assert response.status_code == 200
+            assert response.json() == {"cleared": 1}
+            assert response.headers["cache-control"] == "no-store"
+            jobs = {row["id"]: row for row in client.get("/api/v1/jobs").json()["jobs"]}
+            assert jobs[finished.id]["history_cleared"] is True
+            assert jobs[queued.id]["history_cleared"] is False
+            assert client.get(route).json()["jobs"][0]["id"] == queued.id
+            # Existing receipt/job polling still works after its display row is cleared.
+            assert client.get("/api/v1/jobs/" + finished.id).status_code == 200
+            assert client.request("DELETE", route, json={}).json() == {"cleared": 0}
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
+
+
+async def test_numbered_pages_count_folders_once_and_keep_every_member(task_registry):
+    registry = task_registry
+    folder = folder_metadata()
+    children = [
+        (
+            await add(
+                registry,
+                f"image-{index}.jpg",
+                TransferStatus.COMPLETED,
+                identity=f"image-{index}",
+                created=1000 + index,
+                folder_upload=folder,
+            )
+        ).id
+        for index in range(72)
+    ]
+    (await registry.prune(now=time.time() + 2))
+    for index in range(21):
+        (
+            await add(
+                registry,
+                f"separate-{index}.bin",
+                TransferStatus.COMPLETED,
+                created=2000 + index,
+                kind="remote" if index % 2 else "upload",
+            )
+        )
+    first = await registry.task_history(status="finished", page=1, limit=20)
+    assert first["total_tasks"] == 22
+    assert first["total_pages"] == 2
+    assert len(first["jobs"]) == 20
+    assert first["has_more"]
+    second = await registry.task_history(status="finished", page=2, limit=20)
+    assert len(second["jobs"]) == 73
+    assert {row["id"] for row in second["jobs"] if row.get("folder_upload")} == set(
+        children
+    )
+    assert not second["has_more"]
+    assert second["page"] == 2
+    assert (await registry.task_history(page=99, limit=20))["page"] == 2
+
+
+async def test_task_status_and_search_apply_before_pagination_across_live_archive(
+    task_registry,
+):
+    registry = task_registry
+    folder = folder_metadata(name="Résumé [.*] album")
+    for index in range(3):
+        (
+            await add(
+                registry,
+                f"photo-{index}.jpg",
+                TransferStatus.COMPLETED,
+                folder_upload=folder,
+            )
+        )
+    (await registry.prune(now=time.time() + 2))
+    running = await add(
+        registry,
+        "special-child.jpg",
+        TransferStatus.RUNNING,
+        created=1100,
+        folder_upload=folder,
+    )
+    (await add(registry, "standalone.bin", TransferStatus.COMPLETED, created=1200))
+    finished = await registry.task_history(status="finished", limit=1)
+    assert finished["total_tasks"] == 1
+    assert [row["name"] for row in finished["jobs"]] == ["standalone.bin"]
+    for term in ["RÉSUMÉ [.*]", "special-child"]:
+        matching = await registry.task_history(status="running", query=term, limit=1)
+        assert matching["total_tasks"] == 1
+        assert len(matching["jobs"]) == 4
+    (await registry.update(running.id, status=TransferStatus.COMPLETED))
+    assert (await registry.task_history(status="running"))["jobs"] == []
+    assert (await registry.task_history(status="finished"))["total_tasks"] == 2
+
+
+async def test_folder_task_metadata_survives_mongo_history_reopen(tmp_path):
+    path = tmp_path / "folder-history.sqlite3"
+    registry = registry_for(path, ttl_seconds=1)
+    folder = folder_metadata()
+    for index in range(3):
+        (
+            await add(
+                registry,
+                f"child-{index}",
+                TransferStatus.COMPLETED,
+                folder_upload=folder,
+            )
+        )
+    (await registry.prune(now=time.time() + 2))
+    registry.close()
+    reopened = registry_for(path)
+    try:
+        page = await reopened.task_history(limit=1)
+        assert page["total_tasks"] == 1
+        assert len(page["jobs"]) == 3
+        assert all(row["folder_upload"] == folder for row in page["jobs"])
+        assert all(not row["retained"] for row in page["jobs"])
+    finally:
+        reopened.close()
+
+
+async def test_task_history_http_bounds_owner_boundary_and_current_folder_metadata(
+    tmp_path,
+):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "task-catalog.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = for_directory(tmp_path)
+    registry = runtime.transfers.registry
+    folder = folder_metadata()
+    children = [
+        (
+            await add(
+                registry, str(index), TransferStatus.COMPLETED, folder_upload=folder
+            )
+        ).id
+        for index in range(3)
+    ]
+    route = "/api/v1/transfers/history/tasks"
+    payload = {
+        "status": "finished",
+        "page": 1,
+        "limit": 1,
+    }
+    try:
+        with TestClient(
+            create_app(settings, runtime=runtime), base_url="https://testserver"
+        ) as client:
+            assert client.post(route, json=payload).status_code == 401
+            login(client)
+            response = client.post(route, json=payload)
+            assert response.status_code == 200
+            assert response.headers["cache-control"] == "no-store"
+            assert response.json()["total_tasks"] == 1
+            assert len(response.json()["jobs"]) == 3
+            assert (
+                client.get("/api/v1/transfers/history", params={"page": 1}).json()[
+                    "total_tasks"
+                ]
+                == 1
+            )
+            assert client.post(route, json=payload | {"offset": -1}).status_code == 422
+            assert client.post(route, json=payload | {"page": 0}).status_code == 422
+            unsupported = payload | {
+                "folders": [{"folder_upload": folder, "transfer_ids": children}]
+            }
+            assert client.post(route, json=unsupported).status_code == 422
+            excluded = client.post(
+                route, json=payload | {"exclude_folders": [folder["id"]]}
+            )
+            assert excluded.json()["jobs"] == []
+            assert excluded.json()["total_tasks"] == 0
+            response = client.post(route, content=b"x" * (256 * 1024 + 1))
+            assert response.status_code == 413
+            assert (
+                client.get(
+                    "/api/v1/transfers/history",
+                    params={"page": 1, "before": 1000, "before_id": "safe"},
+                ).status_code
+                == 400
+            )
+    finally:
+        registry.close()
+        store.close()
diff --git a/tests/transfers/test_transfer_locations.py b/tests/transfers/test_transfer_locations.py
new file mode 100644
index 00000000..239c496a
--- /dev/null
+++ b/tests/transfers/test_transfer_locations.py
@@ -0,0 +1,94 @@
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.storage.store import DriveStore
+from tgdrive.transfers.transfer_locations import locate_transfer
+from tgdrive.web.app import create_app
+
+
+def check_locations(store):
+    folder = store.create_folder("/", "Upload Folder")
+    saved = store.create_folder("/", "Saved")
+    folder["path"] = store.resolve_id(folder["id"])
+    saved["path"] = store.resolve_id(saved["id"])
+    original = store.add_file(
+        folder["path"], "same.txt", 101, 20, operation_id="upload-exact"
+    )
+    duplicate = store.add_file(
+        folder["path"], "same.txt", 102, 20, operation_id="other", keep_both=True
+    )
+    original["path"] = store.resolve_id(original["id"])
+    first = locate_transfer(store, {"id": "upload-exact", "status": "completed"})
+    assert first["item_id"] == original["id"] != duplicate["id"]
+    assert first["display_path"] == "My Files / Upload Folder / same.txt"
+    store.move(original["path"], saved["path"])
+    current = store.resolve_id(original["id"])
+    store.rename(current, "renamed.txt")
+    moved = locate_transfer(
+        store,
+        {"id": "upload-exact", "status": "completed", "destination": folder["path"]},
+    )
+    assert moved["item_id"] == original["id"]
+    assert moved["folder_path"] == saved["path"]
+    assert moved["display_path"] == "My Files / Saved / renamed.txt"
+    store.set_trashed(current, True)
+    assert locate_transfer(store, {"id": "upload-exact", "status": "completed"}) == {
+        "available": False,
+        "reason": "Item is in Trash",
+    }
+    deletion = store.begin_deletion(current, channel_id=-1001234567890)
+    store.confirm_deletion_messages(deletion["id"], deletion["message_ids"])
+    store.finish_deletion(deletion["id"])
+    assert not locate_transfer(store, {"id": "upload-exact", "status": "completed"})[
+        "available"
+    ]
+    queued = locate_transfer(store, {"id": "unfinished", "destination": folder["path"]})
+    assert queued["available"] and queued["item_id"] is None
+    assert queued["folder_path"] == folder["path"]
+    assert not locate_transfer(store, {"id": "unknown", "status": "completed"})[
+        "available"
+    ]
+
+
+def test_exact_locations_follow_moves_and_renames_without_matching_names(tmp_path):
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    try:
+        check_locations(store)
+    finally:
+        store.close()
+
+
+async def test_owner_location_api_and_history_enrichment(tmp_path, monkeypatch):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    row = await runtime.transfers.registry.create(
+        "queued", transfer_id="committed-upload"
+    )
+    row.context.update(name="original.txt", kind="upload", destination="/")
+    saved = store.add_file("/", "original.txt", 101, 2, operation_id=row.id)
+    app = create_app(settings, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            endpoint = "/api/v1/transfers/location"
+            payload = {"transfer_id": row.id, "completed": True}
+            assert client.post(endpoint, json=payload).status_code == 401
+            login(client)
+            response = client.post(endpoint, json=payload)
+            assert response.headers["Cache-Control"] == "no-store"
+            assert response.json()["item_id"] == saved["id"]
+            history = client.get("/api/v1/transfers/history").json()
+            assert (
+                history["jobs"][0]["location"]["display_path"]
+                == "My Files / original.txt"
+            )
+            assert "message_id" not in str(history["jobs"][0]["location"])
+            assert (
+                client.post(endpoint, json={"transfer_id": "invalid/id"}).status_code
+                == 422
+            )
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/transfers/test_transfer_policy.py b/tests/transfers/test_transfer_policy.py
new file mode 100644
index 00000000..b074dd46
--- /dev/null
+++ b/tests/transfers/test_transfer_policy.py
@@ -0,0 +1,70 @@
+import asyncio
+from unittest.mock import AsyncMock
+
+from tests.transfers.test_multipart_transfers import (
+    dispose,
+    manager_for,
+    staged,
+    stored,
+)
+from tests.transfers.test_multipart_transfers import mongo_backend as mongo_backend
+from tests.transfers.test_transfers import make_manager
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+
+async def test_smaller_operator_split_preserves_all_bytes(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    manager.settings.bot_upload_limit = 4 * 1024**2
+    manager.settings.upload_split_mib = 1
+    manager.settings.upload_limit = 16 * 1024**2
+    payload = b"a" * (2 * 1024**2) + b"end"
+    source = staged(manager, payload)
+    record = await manager.enqueue_upload(source, "/", "split.bin", len(payload))
+    try:
+        await asyncio.wait_for(record.task, 5)
+        assert record.status is TransferStatus.COMPLETED
+        item = stored(manager)
+        assert [part["size"] for part in item["parts"]] == [1024**2, 1024**2, 3]
+        result = b"".join(
+            ledger.messages[part["message_id"]].content for part in item["parts"]
+        )
+        assert result == payload
+    finally:
+        await dispose(manager)
+
+
+async def test_url_source_remains_remote_after_staging_and_resume_uses_staged_file(
+    tmp_path, mongo_backend
+):
+    manager, store, client, pool = await make_manager(tmp_path)
+    manager.registry = TransferRegistry(
+        mongo=mongo_backend.db.jobs, mongo_backend=mongo_backend
+    )
+    client.wait_during_upload = True
+    job = await manager.start_remote(
+        url="https://example.com/file.bin", destination="/", filename=None
+    )
+    try:
+        await asyncio.wait_for(client.started_upload.wait(), 2)
+        assert manager.registry.history_snapshot(job)["kind"] == "remote"
+        # Simulate interruption after durable local staging, before final publication.
+        await manager.registry.shutdown()
+        assert job.status is TransferStatus.QUEUED
+        manager.registry.close()
+        manager.registry = TransferRegistry(
+            mongo=mongo_backend.db.jobs, mongo_backend=mongo_backend
+        )
+        job = manager.registry.get(job.id)
+        assert manager.registry.history_snapshot(job)["kind"] == "remote"
+        manager._upload_path = AsyncMock()
+        manager._remote_pipeline = AsyncMock()
+        (await manager._resume(job))
+        await job.task
+        manager._upload_path.assert_awaited_once()
+        manager._remote_pipeline.assert_not_awaited()
+    finally:
+        client.release_upload.set()
+        await manager.close()
+        await pool.stop()
+        store.close()
+        manager.registry.close()
diff --git a/tests/transfers/test_transfer_preferences.py b/tests/transfers/test_transfer_preferences.py
new file mode 100644
index 00000000..03c08a63
--- /dev/null
+++ b/tests/transfers/test_transfer_preferences.py
@@ -0,0 +1,91 @@
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.settings.transfer_preferences import TransferPreferences, UploadPreferences
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+
+def preference_runtime(backend=None):
+    return SimpleNamespace(
+        mongo=backend,
+        pool=SimpleNamespace(
+            set_uploads_per_bot=AsyncMock(),
+            status=AsyncMock(
+                return_value=[
+                    SimpleNamespace(kind="bot", started=True, healthy=True),
+                    SimpleNamespace(kind="bot", started=True, healthy=True),
+                    SimpleNamespace(kind="user", started=True, healthy=True),
+                ]
+            ),
+        ),
+    )
+
+
+async def test_saved_limit_survives_restart_and_failed_write_does_not_apply(
+    tmp_path, monkeypatch
+):
+    settings = make_settings(tmp_path)
+    backend = register_test_backend(monkeypatch, settings)
+    runtime = preference_runtime(backend)
+    service = TransferPreferences(settings, runtime)
+    assert (await service.snapshot())["bot_upload_slots"] == 2
+    assert (await service.save(UploadPreferences(uploads_per_bot=3)))[
+        "bot_upload_slots"
+    ] == 6
+    restarted = TransferPreferences(settings, preference_runtime(backend))
+    assert (await restarted.snapshot())["uploads_per_bot"] == 3
+
+    def failed(_value):
+        raise OSError("synthetic failed write")
+
+    monkeypatch.setattr(service, "_write", failed)
+    with pytest.raises(SettingsProblem):
+        await service.save(UploadPreferences(uploads_per_bot=2))
+    assert (await service.snapshot())["uploads_per_bot"] == 3
+    assert runtime.pool.set_uploads_per_bot.await_args.args == (3,)
+
+
+def test_owner_api_rejects_invalid_limits_and_applies_without_restart(
+    tmp_path, monkeypatch
+):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    runtime.pool = preference_runtime().pool
+    app = create_app(settings, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            url = "/api/v1/settings/uploads"
+            assert client.get(url).status_code == 401
+            login(client)
+            response = client.get(url)
+            assert response.status_code == 200
+            assert response.headers["Cache-Control"] == "no-store"
+            assert response.json()["uploads_per_bot"] == 1
+            for value in (0, 5, 1.5, True, "2"):
+                assert (
+                    client.patch(url, json={"uploads_per_bot": value}).status_code
+                    == 422
+                )
+            assert (
+                client.patch(url, json={"uploads_per_bot": 2, "extra": 1}).status_code
+                == 422
+            )
+            assert (
+                client.patch(url, json={"uploads_per_bot": 2}).json()[
+                    "bot_upload_slots"
+                ]
+                == 4
+            )
+            assert client.get(url).json()["uploads_per_bot"] == 2
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/transfers/test_transfers.py b/tests/transfers/test_transfers.py
new file mode 100644
index 00000000..1eca5ea2
--- /dev/null
+++ b/tests/transfers/test_transfers.py
@@ -0,0 +1,433 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from io import BytesIO
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from fastapi import UploadFile
+
+from tgdrive.core.config import Settings
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.manager import (
+    TransferCancelled,
+    TransferEmptyFile,
+    TransferManager,
+    TransferTooLarge,
+)
+from tgdrive.transfers.remote import DownloadResult
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+
+
+class StopTransmission(Exception):
+    pass
+
+
+class FakeTelegramClient:
+    def __init__(self) -> None:
+        self.name = "transfer-test"
+        self.is_connected = False
+        self.deleted: list[int] = []
+        self.started_upload = asyncio.Event()
+        self.release_upload = asyncio.Event()
+        self.wait_during_upload = False
+        self.wait_after_progress = False
+        self.fail_upload = False
+        self.progress_reported = asyncio.Event()
+        self.release_after_progress = asyncio.Event()
+
+    async def start(self) -> None:
+        self.is_connected = True
+
+    async def stop(self) -> None:
+        self.is_connected = False
+
+    def stop_transmission(self) -> None:
+        raise StopTransmission
+
+    async def send_staged(
+        self,
+        _channel: int,
+        path: Path,
+        *,
+        file_name: str,
+        progress: object,
+        offset: int = 0,
+        size: int | None = None,
+        expected_sha256: str | None = None,
+        before_dispatch=None,
+        **_kwargs: object,
+    ):
+        if self.fail_upload:
+            raise RuntimeError("Telegram unavailable")
+        end = offset + size if size is not None else None
+        content = path.read_bytes()[offset:end]
+        if expected_sha256 is not None:
+            assert hashlib.sha256(content).hexdigest() == expected_sha256
+        self.started_upload.set()
+        if self.wait_during_upload:
+            await self.release_upload.wait()
+        try:
+            await progress(len(content), len(content))
+        except StopTransmission:
+            return None
+        self.progress_reported.set()
+        if self.wait_after_progress:
+            await self.release_after_progress.wait()
+        if before_dispatch is not None:
+            (await before_dispatch())
+        return SimpleNamespace(
+            id=99,
+            document=SimpleNamespace(file_size=len(content), file_name=file_name),
+        )
+
+    async def delete_messages(self, _channel: int, ids: int | list[int]) -> None:
+        self.deleted.extend(ids if isinstance(ids, list) else [ids])
+
+
+class FakeRemote:
+    async def inspect(self, url: str):
+        return SimpleNamespace(
+            url=url,
+            filename="remote.bin",
+            size=6,
+            content_type="application/octet-stream",
+        )
+
+    async def download(
+        self,
+        url: str,
+        output_dir: Path,
+        *,
+        filename: str | None,
+        cancel_event: asyncio.Event,
+        progress: object,
+        **_kwargs: object,
+    ) -> DownloadResult:
+        assert not cancel_event.is_set()
+        output_dir.mkdir(parents=True, exist_ok=True)
+        path = output_dir / (filename or "remote.bin")
+        path.write_bytes(b"remote")
+        await progress(6, 6)
+        return DownloadResult(
+            path=path,
+            url=url,
+            filename=path.name,
+            size=6,
+            content_type="application/octet-stream",
+        )
+
+    async def close(self) -> None:
+        return None
+
+
+def make_settings(tmp_path: Path, *, max_size: int = 1024) -> Settings:
+    return Settings(
+        _env_file=None,
+        MONGODB_URI="mongodb://synthetic.invalid",
+        API_ID=12345,
+        API_HASH="a" * 32,
+        BOT_TOKENS="123456:" + "x" * 30,
+        STORAGE_CHANNEL=-1001234567890,
+        ADMIN_PASSWORD="correct horse battery staple",
+        SESSION_SECRET="s" * 48,
+        DATA_DIR=tmp_path / "data",
+        CACHE_DIR=tmp_path / "cache",
+        MAX_FILE_SIZE=max_size,
+        COOKIE_SECURE=False,
+    )
+
+
+async def make_manager(tmp_path: Path, *, max_size: int = 1024):
+    settings = make_settings(tmp_path, max_size=max_size)
+    client = FakeTelegramClient()
+    pool = ClientPool([client])
+    await pool.start()
+    store = DriveStore.create(tmp_path / "drive.json")
+    manager = TransferManager(
+        settings=settings,
+        pool=pool,
+        store=store,
+        remote=FakeRemote(),
+        registry=TransferRegistry(),
+    )
+    return manager, store, client, pool
+
+
+@pytest.mark.asyncio
+async def test_browser_upload_completes_and_cleans_temp_file(tmp_path: Path) -> None:
+    manager, store, _, pool = await make_manager(tmp_path)
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="../hello + 100%.txt")
+
+    record = await manager.receive_browser_upload(upload, "/")
+    assert record.task is not None
+    await record.task
+
+    assert record.status is TransferStatus.COMPLETED
+    item = next(iter(store.list_directory("/").values()))
+    assert item["name"] == "hello + 100%.txt"
+    assert not (manager.cache_dir / "uploads" / f"{record.id}.upload").exists()
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_upload_cancellation_does_not_create_metadata(tmp_path: Path) -> None:
+    manager, store, client, pool = await make_manager(tmp_path)
+    client.wait_during_upload = True
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="hello.txt")
+
+    record = await manager.receive_browser_upload(upload, "/")
+    await client.started_upload.wait()
+    (await manager.registry.cancel(record.id))
+    assert record.status is TransferStatus.CANCELLING
+    client.release_upload.set()
+    assert record.task is not None
+    await record.task
+
+    assert record.status is TransferStatus.CANCELLED
+    assert store.list_directory("/") == {}
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_complete_byte_count_enters_finalizing_phase(tmp_path: Path) -> None:
+    manager, store, client, pool = await make_manager(tmp_path)
+    client.wait_after_progress = True
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="hello.txt")
+
+    record = await manager.receive_browser_upload(upload, "/")
+    await client.progress_reported.wait()
+
+    assert record.status is TransferStatus.RUNNING
+    assert record.phase == "finalizing"
+    assert record.current == record.total == 5
+
+    client.release_after_progress.set()
+    assert record.task is not None
+    await record.task
+    assert record.status is TransferStatus.COMPLETED
+    assert len(store.list_directory("/")) == 1
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_interrupted_browser_request_cancels_and_cleans_partial_file(
+    tmp_path: Path,
+) -> None:
+    manager, store, _, pool = await make_manager(tmp_path)
+    read_started = asyncio.Event()
+    never_finish = asyncio.Event()
+
+    class InterruptedUpload:
+        filename = "partial.bin"
+        size = 5
+
+        def __init__(self) -> None:
+            self.closed = False
+
+        async def read(self, _size: int) -> bytes:
+            read_started.set()
+            await never_finish.wait()
+            return b""
+
+        async def close(self) -> None:
+            self.closed = True
+
+    upload = InterruptedUpload()
+    request_task = asyncio.create_task(manager.receive_browser_upload(upload, "/"))
+    await read_started.wait()
+    record = next(iter(manager.registry._records.values()))
+    request_task.cancel()
+
+    with pytest.raises(asyncio.CancelledError):
+        await request_task
+
+    assert upload.closed
+    assert record.status is TransferStatus.CANCELLED
+    assert record.cancel_event.is_set()
+    assert store.list_directory("/") == {}
+    assert not (manager.cache_dir / "uploads" / f"{record.id}.upload").exists()
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_disconnected_browser_does_not_spawn_unknown_telegram_transfer(
+    tmp_path: Path,
+) -> None:
+    manager, store, client, pool = await make_manager(tmp_path)
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="hello.txt")
+
+    async def disconnected() -> bool:
+        return True
+
+    with pytest.raises(TransferCancelled):
+        await manager.receive_browser_upload(
+            upload,
+            "/",
+            is_disconnected=disconnected,
+        )
+
+    record = next(iter(manager.registry._records.values()))
+    assert record.status is TransferStatus.CANCELLED
+    assert record.task is None
+    assert not client.started_upload.is_set()
+    assert store.list_directory("/") == {}
+    assert not (manager.cache_dir / "uploads" / f"{record.id}.upload").exists()
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_duplicate_upload_keeps_both_without_overwriting(tmp_path: Path) -> None:
+    manager, store, client, pool = await make_manager(tmp_path)
+    store.add_file("/", "duplicate.txt", 1, 1)
+    upload = UploadFile(BytesIO(b"new"), size=3, filename="duplicate.txt")
+
+    record = await manager.receive_browser_upload(upload, "/")
+    assert record.task is not None
+    await record.task
+
+    assert record.status is TransferStatus.COMPLETED
+    assert client.deleted == []
+    assert len(store.list_directory("/")) == 2
+    assert len({item["name"] for item in store.list_directory("/").values()}) == 2
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_oversized_upload_is_rejected_before_disk_write(tmp_path: Path) -> None:
+    manager, store, _, pool = await make_manager(tmp_path, max_size=3)
+    upload = UploadFile(BytesIO(b"four"), size=4, filename="large.bin")
+
+    with pytest.raises(TransferTooLarge):
+        await manager.receive_browser_upload(upload, "/")
+
+    assert store.list_directory("/") == {}
+    assert not (manager.cache_dir / "uploads").exists()
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_remote_pipeline_downloads_then_uploads(tmp_path: Path) -> None:
+    manager, store, _, pool = await make_manager(tmp_path)
+
+    info = await manager.inspect_remote("https://example.com/remote.bin")
+    assert info.filename == "remote.bin"
+    record = await manager.start_remote(
+        url="https://example.com/remote.bin",
+        destination="/",
+        filename="chosen.bin",
+    )
+    assert record.task is not None
+    await record.task
+
+    assert record.status is TransferStatus.COMPLETED
+    item = next(iter(store.list_directory("/").values()))
+    assert item["name"] == "chosen.bin"
+    assert not (manager.cache_dir / "remote" / record.id).exists()
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_telegram_error_retains_staging_for_retry(
+    tmp_path: Path,
+) -> None:
+    manager, store, client, pool = await make_manager(tmp_path)
+    client.fail_upload = True
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="hello.txt")
+
+    record = await manager.receive_browser_upload(upload, "/")
+    assert record.task is not None
+    await record.task
+
+    assert record.status is TransferStatus.ERROR
+    assert "Telegram unavailable" in (record.error or "")
+    assert store.list_directory("/") == {}
+    assert (manager.cache_dir / "uploads" / f"{record.id}.upload").exists()
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_delete_messages_is_chunked(tmp_path: Path) -> None:
+    manager, _, client, pool = await make_manager(tmp_path)
+    message_ids = list(range(1, 206))
+
+    await manager.delete_telegram_messages(message_ids)
+
+    assert client.deleted == message_ids
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("declared_size", [0, None])
+async def test_empty_file_is_rejected_and_closed(
+    tmp_path: Path, declared_size: int | None
+) -> None:
+    manager, store, client, pool = await make_manager(tmp_path)
+    upload = UploadFile(BytesIO(), size=declared_size, filename="empty.txt")
+
+    with pytest.raises(TransferEmptyFile, match="Empty files"):
+        await manager.receive_browser_upload(upload, "/")
+
+    assert upload.file.closed
+    assert not client.started_upload.is_set()
+    assert store.list_directory("/") == {}
+    assert not list(manager.cache_dir.rglob("*.upload"))
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_creation_callback_can_cancel_before_saving(tmp_path: Path) -> None:
+    manager, _, client, pool = await make_manager(tmp_path)
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="hello.txt")
+    created: list[str] = []
+
+    async def cancel_immediately(record: object) -> None:
+        created.append(record.id)
+        (await manager.registry.cancel(record.id))
+
+    with pytest.raises(TransferCancelled):
+        await manager.receive_browser_upload(upload, "/", on_created=cancel_immediately)
+
+    record = manager.registry.get(created[0])
+    assert record.status is TransferStatus.CANCELLED
+    assert not client.started_upload.is_set()
+    assert upload.file.closed
+    assert not list(manager.cache_dir.rglob("*.upload"))
+    await manager.close()
+    await pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_staging_setup_failure_closes_upload_and_marks_bound_record(
+    tmp_path: Path,
+) -> None:
+    manager, _, client, pool = await make_manager(tmp_path)
+    # A file occupying the expected staging-directory path is a realistic
+    # permission/filesystem setup failure before the first multipart read.
+    (manager.cache_dir / "uploads").write_bytes(b"occupied")
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="hello.txt")
+    bound: list[object] = []
+
+    with pytest.raises(FileExistsError):
+        await manager.receive_browser_upload(upload, "/", on_created=bound.append)
+
+    assert len(bound) == 1
+    assert bound[0].status is TransferStatus.ERROR
+    assert upload.file.closed
+    assert not client.started_upload.is_set()
+    await manager.close()
+    await pool.stop()
diff --git a/tests/transfers/test_upload_admission_guard.py b/tests/transfers/test_upload_admission_guard.py
new file mode 100644
index 00000000..2c0861e0
--- /dev/null
+++ b/tests/transfers/test_upload_admission_guard.py
@@ -0,0 +1,46 @@
+"""MongoDB upload admission is independent of optional Telegram snapshots."""
+
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+from tests.support.recovery_fixtures import settings
+from tgdrive.recovery.backup import RecoveryConflict
+from tgdrive.recovery.mongo_backup import MongoProtection
+from tgdrive.storage.mongo import DatabaseUnavailable
+
+
+def protection(tmp_path):
+    configured = settings(tmp_path)
+    backend = SimpleNamespace(check_owner=Mock())
+    pool = Mock()
+    service = MongoProtection(configured, pool, backend)
+    store = SimpleNamespace(storage_channel_id=configured.storage_channel)
+    return service, backend, pool, store
+
+
+def test_upload_admission_does_not_wait_for_optional_telegram_backup(tmp_path):
+    service, backend, pool, store = protection(tmp_path)
+    service._last_error = "Telegram snapshot is waiting before retry"
+    service.check_upload_allowed(store)
+    backend.check_owner.assert_called_once_with()
+    assert pool.mock_calls == []
+
+
+def test_unavailable_database_ownership_blocks_upload_admission(tmp_path):
+    service, backend, pool, store = protection(tmp_path)
+    backend.check_owner.side_effect = DatabaseUnavailable(
+        "MongoDB ownership is unavailable"
+    )
+    with pytest.raises(DatabaseUnavailable):
+        service.check_upload_allowed(store)
+    assert pool.mock_calls == []
+
+
+def test_changed_channel_blocks_upload_admission_without_telegram_rpc(tmp_path):
+    service, _, pool, store = protection(tmp_path)
+    store.storage_channel_id = -100999
+    with pytest.raises(RecoveryConflict, match="different Telegram channel"):
+        service.check_upload_allowed(store)
+    assert pool.mock_calls == []
diff --git a/tests/transfers/test_upload_destinations.py b/tests/transfers/test_upload_destinations.py
new file mode 100644
index 00000000..5ceae357
--- /dev/null
+++ b/tests/transfers/test_upload_destinations.py
@@ -0,0 +1,295 @@
+"""Folder identity remains stable across receipt, queue, send and restart boundaries."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from tests.support.mongo_fixtures import register_test_backend
+from tests.transfers.test_multipart_transfers import (
+    Account,
+    dispose,
+    manager_for,
+    registry_for,
+    staged,
+)
+from tests.transfers.test_resumable_uploads import make
+from tgdrive.core.errors import (
+    DriveError,
+    NotFoundError,
+    PersistenceError,
+    TrashedItemError,
+)
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.transfers.manager import TransferManager
+from tgdrive.transfers.tasks import TransferStatus
+from tgdrive.transfers.uploads import UploadError
+
+
+@pytest.fixture(autouse=True)
+def mongo_backend(tmp_path, monkeypatch):
+    backend = register_test_backend(monkeypatch, tmp_path)
+    return register_test_backend(monkeypatch, tmp_path / "data", backend)
+
+
+def folder(store, name, parent="/"):
+    node = store.create_folder(parent, name)
+    return store.resolve_id(node["id"])
+
+
+@pytest.fixture
+def receipt(tmp_path):
+    uploads, manager = make(tmp_path)
+    try:
+        yield uploads, manager
+    finally:
+        uploads.close()
+        manager.registry.close()
+        manager.store.close()
+
+
+async def test_receipt_follows_moved_ancestor_and_rejects_new_stale_requests(receipt):
+    uploads, manager = receipt
+    parent = folder(manager.store, "Original")
+    target = folder(manager.store, "資料", parent)
+    receiving = uploads.create("file.bin", target, 3)
+    identity = receiving["parent_node_id"]
+    outer = folder(manager.store, "Other")
+    manager.store.move(parent, outer)
+    current = manager.store.resolve_id(identity)
+    assert current != target
+    with pytest.raises(NotFoundError):
+        uploads.create("forged.bin", target, 3)
+    with pytest.raises(NotFoundError):
+        uploads.create("forged.bin", "/wrong/" + identity, 3)
+    await uploads.append(receiving["id"], 0, b"one")
+    job = await uploads.complete(receiving["id"])
+    assert job.context["destination"] == current
+    assert uploads.get(receiving["id"])["parent_id"] == current
+
+
+async def test_move_during_receipt_verification_uses_latest_path(receipt, monkeypatch):
+    uploads, manager = receipt
+    target = folder(manager.store, "Target")
+    receiving = uploads.create("file.bin", target, 3)
+    await uploads.append(receiving["id"], 0, b"one")
+    entered = asyncio.Event()
+    release = threading.Event()
+    loop = asyncio.get_running_loop()
+    original = uploads._verify
+
+    def verify(*args):
+        loop.call_soon_threadsafe(entered.set)
+        assert release.wait(2)
+        original(*args)
+
+    monkeypatch.setattr(uploads, "_verify", verify)
+    work = asyncio.create_task(uploads.complete(receiving["id"]))
+    try:
+        await asyncio.wait_for(entered.wait(), 2)
+        manager.store.move(target, folder(manager.store, "Other"))
+        expected = manager.store.resolve_id(receiving["parent_node_id"])
+        release.set()
+        assert (await work).context["destination"] == expected
+    finally:
+        release.set()
+        await asyncio.gather(work, return_exceptions=True)
+
+
+async def test_receipt_trash_blocks_writes_but_restore_or_cancel_remains_available(
+    receipt,
+):
+    uploads, manager = receipt
+    target = folder(manager.store, "Target")
+    receiving = uploads.create("file.bin", target, 3)
+    manager.store.set_trashed(target, True)
+    assert uploads.get(receiving["id"])["offset"] == 0
+    with pytest.raises(UploadError, match="destination folder"):
+        await uploads.append(receiving["id"], 0, b"one")
+    assert uploads.path(receiving["id"]).read_bytes() == b""
+    manager.store.set_trashed(target, False)
+    await uploads.append(receiving["id"], 0, b"one")
+    manager.store.set_trashed(target, True)
+    with pytest.raises(UploadError, match="destination folder"):
+        await uploads.complete(receiving["id"])
+    manager.store.delete(target)
+    assert (await uploads.cancel(receiving["id"]))["state"] == "cancelled"
+    assert not (uploads.root / (receiving["id"] + ".part")).exists()
+    assert manager.enqueued == 0
+
+
+async def test_receipt_rejects_destination_with_pending_permanent_deletion(receipt):
+    uploads, manager = receipt
+    target = folder(manager.store, "Target")
+    receiving = uploads.create("file.bin", target, 3)
+    manager.store.set_trashed(target, True)
+    manager.store.begin_deletion(target)
+    with pytest.raises(UploadError, match="destination folder"):
+        await uploads.append(receiving["id"], 0, b"one")
+    with pytest.raises(DriveError):
+        uploads.create("new.bin", target, 3)
+
+
+async def test_queued_restart_follows_uuid_after_destination_move(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    target = folder(manager.store, "Target")
+    source = staged(manager, b"abcdefghij")
+    manager._semaphore = asyncio.Semaphore(0)
+    record = await manager.enqueue_upload(source, target, "ten.bin", 10)
+    await asyncio.sleep(0)
+    await manager.close()
+    manager.store.move(target, folder(manager.store, "Other"))
+    expected = manager.store.resolve_id(target[1:])
+    settings = manager.settings
+    manager.registry.close()
+    manager.store.close()
+    await manager.pool.stop()
+    pool = ClientPool([Account("bot-one", ledger), Account("bot-two", ledger)])
+    await pool.start()
+    recovered = TransferManager(
+        settings=settings,
+        pool=pool,
+        store=DriveStore.load(tmp_path / "drive.sqlite3"),
+        registry=registry_for(tmp_path),
+        remote=SimpleNamespace(close=AsyncMock()),
+    )
+    try:
+        await recovered.recover()
+        current = recovered.registry.get(record.id)
+        await current.task
+        assert current.status == TransferStatus.COMPLETED
+        assert current.context["destination"] == expected
+        assert current.context["destination_id"] == target[1:]
+        items = recovered.store.list_directory(expected)
+        assert len(items) == 1
+        assert (
+            recovered.store.get_file(expected + "/" + next(iter(items)))["size"] == 10
+        )
+    finally:
+        await dispose(recovered)
+
+
+async def test_move_during_remote_send_commits_in_same_current_shared_folder(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    target = folder(manager.store, "Target")
+    shared = folder(manager.store, "Shared")
+    token = manager.store.create_share(shared)
+    record = await manager.enqueue_upload(
+        staged(manager, b"abcdefghij"), target, "ten.bin", 10
+    )
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        manager.store.move(target, shared)
+        expected = manager.store.resolve_id(record.context["destination_id"])
+        ledger.release.set()
+        await record.task
+        assert record.status == TransferStatus.COMPLETED
+        items = manager.store.list_directory(expected)
+        path = expected + "/" + next(iter(items))
+        assert manager.store.authorize_file(path, token)
+        assert record.context["destination"] == expected
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_trashed_destination_during_send_reconciles_and_cleans_own_parts(
+    tmp_path,
+):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    target = folder(manager.store, "Target")
+    source = staged(manager, b"abcdefghij")
+    record = await manager.enqueue_upload(source, target, "ten.bin", 10)
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        manager.store.set_trashed(target, True)
+        ledger.release.set()
+        await record.task
+        assert record.status == TransferStatus.CANCELLED
+        assert not ledger.messages and not source.exists()
+        assert not manager.store.has_file_operation(record.id)
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+async def test_delete_worker_matches_moved_destination_uuid_before_cleanup(tmp_path):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    target = folder(manager.store, "Target")
+    record = await manager.enqueue_upload(
+        staged(manager, b"abcdefghij"), target, "ten.bin", 10
+    )
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        manager.store.move(target, folder(manager.store, "Other"))
+        current = manager.store.resolve_id(record.context["destination_id"])
+        assert record.context["destination"] == target
+        manager.store.set_trashed(current, True)
+        deletion = await manager.start_deletion(current)
+        await asyncio.wait_for(record.cancel_event.wait(), 2)
+        ledger.release.set()
+        await asyncio.wait_for(deletion.task, 2)
+        assert record.status == TransferStatus.CANCELLED
+        assert deletion.status == TransferStatus.COMPLETED
+        assert not ledger.messages
+        with pytest.raises(NotFoundError):
+            manager.store.resolve_id(target[1:])
+    finally:
+        ledger.release.set()
+        await dispose(manager)
+
+
+def test_store_destination_binding_requires_a_folder_and_honors_live_ancestry():
+    store = DriveStore.create()
+    try:
+        parent = folder(store, "Parent")
+        target = folder(store, "Target", parent)
+        file = store.add_file("/", "file.bin", 5, 1)
+        with pytest.raises(DriveError):
+            store.upload_destination("/", directory_id=file["id"])
+        store.set_trashed(parent, True)
+        with pytest.raises(TrashedItemError):
+            store.upload_destination(target, directory_id=target.rsplit("/", 1)[1])
+        assert store.upload_destination("/") == {"id": "root", "path": "/"}
+    finally:
+        store.close()
+
+
+async def test_catalog_outage_does_not_turn_destination_validation_into_cancellation(
+    tmp_path, monkeypatch
+):
+    manager, ledger = await manager_for(tmp_path)
+    ledger.hold = True
+    target = folder(manager.store, "Target")
+    source = staged(manager, b"abcdefgh")
+    record = await manager.enqueue_upload(source, target, "eight.bin", 8)
+    original = manager.store.upload_destination
+
+    def unavailable(*_args, **_kwargs):
+        raise PersistenceError("synthetic catalog read outage")
+
+    try:
+        await asyncio.wait_for(ledger.dispatched.wait(), 2)
+        monkeypatch.setattr(manager.store, "upload_destination", unavailable)
+        ledger.release.set()
+        await record.task
+        assert record.status == TransferStatus.ERROR
+        assert not record.context.get("cancel_requested")
+        assert source.exists() and ledger.messages
+        sent = len(ledger.requests)
+        monkeypatch.setattr(manager.store, "upload_destination", original)
+        retried = await manager.retry_job(record.id)
+        await retried.task
+        assert retried.status == TransferStatus.COMPLETED
+        assert len(ledger.requests) == sent
+    finally:
+        ledger.release.set()
+        await dispose(manager)
diff --git a/tests/transfers/test_upload_pipeline.py b/tests/transfers/test_upload_pipeline.py
new file mode 100644
index 00000000..6f689129
--- /dev/null
+++ b/tests/transfers/test_upload_pipeline.py
@@ -0,0 +1,303 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from collections import Counter
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from telethon import functions, types
+from telethon.errors import FloodPremiumWaitError, FloodWaitError
+
+from tgdrive.media.media_scheduler import MediaScheduler
+from tgdrive.telegram.clients import Client
+
+PART = 512 * 1024
+
+
+class Native:
+    def __init__(self):
+        self.parts = {}
+        self.calls = Counter()
+        self.active = 0
+        self.maximum = 0
+        self.published = []
+        self.fail_part = None
+        self.flood_part = None
+        self.flood_seconds = 1
+        self.flood_count = 1
+        self.flood_error = FloodWaitError
+        self.hold = None
+        self.get_input_entity = AsyncMock(return_value="channel")
+
+    async def __call__(self, request):
+        if isinstance(
+            request,
+            (
+                functions.upload.SaveFilePartRequest,
+                functions.upload.SaveBigFilePartRequest,
+            ),
+        ):
+            self.calls[request.file_part] += 1
+            self.active += 1
+            self.maximum = max(self.maximum, self.active)
+            try:
+                if self.hold is not None:
+                    await self.hold.wait()
+                await asyncio.sleep(0.005 if request.file_part == 0 else 0.001)
+                if (
+                    self.calls[request.file_part] <= self.flood_count
+                    and request.file_part == self.flood_part
+                ):
+                    raise self.flood_error(request, capture=self.flood_seconds)
+                if (
+                    self.calls[request.file_part] == 1
+                    and request.file_part == self.fail_part
+                ):
+                    raise TimeoutError("transient part failure")
+                self.parts[request.file_part] = request.bytes
+                return True
+            finally:
+                self.active -= 1
+        self.published.append(request)
+        return SimpleNamespace(updates=[])
+
+
+def client(native, *, limit=2):
+    value = Client.__new__(Client)
+    value.native = native
+    value.name = "storage-bot-1"
+    value._upload_pipeline = 4
+    value._media_scheduler = MediaScheduler(limit=limit, rate=512)
+    value._sent = AsyncMock(return_value="stored")
+    value._defer_read = AsyncMock()
+    return value
+
+
+@pytest.mark.asyncio
+async def test_pipeline_retries_only_failed_part_and_preserves_window_hash_and_dispatch(
+    tmp_path,
+):
+    payload = b"a" * PART + b"b" * PART + b"tail"
+    path = tmp_path / "staged"
+    path.write_bytes(b"prefix" + payload + b"suffix")
+    native = Native()
+    native.fail_part = 1
+    adapter = client(native)
+    progress = AsyncMock()
+    boundary = AsyncMock()
+    assert (
+        await adapter.send_staged(
+            123,
+            path,
+            file_name="file.bin",
+            offset=6,
+            size=len(payload),
+            expected_sha256=hashlib.sha256(payload).hexdigest(),
+            random_id=987,
+            progress=progress,
+            before_dispatch=boundary,
+        )
+        == "stored"
+    )
+    assert b"".join(native.parts[index] for index in sorted(native.parts)) == payload
+    assert native.calls == {0: 1, 1: 2, 2: 1}
+    assert 1 < native.maximum <= 2
+    request = native.published[0]
+    assert request.random_id == 987
+    assert (
+        request.media.file.md5_checksum
+        == hashlib.md5(payload, usedforsecurity=False).hexdigest()
+    )
+    boundary.assert_awaited_once()
+    assert progress.await_args.args == (len(payload), len(payload))
+
+
+@pytest.mark.asyncio
+async def test_big_file_pipeline_retries_one_part_without_resending_acked_parts(
+    tmp_path,
+):
+    # Telegram uses SaveBigFilePart/InputFileBig above 10MiB. Keep a nonaligned
+    # window/tail so total-parts and neighboring staged bytes are both checked.
+    payload = bytes(range(256)) * (10 * 1024 * 1024 // 256) + b"last-part" * 57
+    total_parts = (len(payload) + PART - 1) // PART
+    path = tmp_path / "large-stage"
+    path.write_bytes(b"prefix" + payload + b"suffix")
+
+    class BigNative(Native):
+        async def __call__(self, request):
+            if isinstance(request, functions.upload.SaveBigFilePartRequest):
+                assert request.file_total_parts == total_parts
+            assert not isinstance(request, functions.upload.SaveFilePartRequest)
+            return await super().__call__(request)
+
+    native = BigNative()
+    native.fail_part = 7
+    adapter = client(native, limit=3)
+    progress = AsyncMock()
+    await adapter.send_staged(
+        123,
+        path,
+        file_name="large.bin",
+        offset=6,
+        size=len(payload),
+        expected_sha256=hashlib.sha256(payload).hexdigest(),
+        random_id=987,
+        progress=progress,
+    )
+    assert b"".join(native.parts[index] for index in range(total_parts)) == payload
+    assert native.calls == {
+        index: 2 if index == native.fail_part else 1 for index in range(total_parts)
+    }
+    assert 1 < native.maximum <= 3
+    assert len(native.published) == 1
+    uploaded = native.published[0].media.file
+    assert isinstance(uploaded, types.InputFileBig)
+    assert uploaded.parts == total_parts
+    assert uploaded.name == "large.bin"
+    assert progress.await_args.args == (len(payload), len(payload))
+    assert adapter._media_scheduler.active == 0
+    assert adapter._media_scheduler.snapshot()["queued"] == 0
+
+
+@pytest.mark.asyncio
+async def test_pipeline_cancellation_drains_all_parts_and_does_not_publish(tmp_path):
+    path = tmp_path / "staged"
+    path.write_bytes(b"x" * (PART * 8))
+    native = Native()
+    native.hold = asyncio.Event()
+    adapter = client(native)
+    task = asyncio.create_task(
+        adapter.send_staged(
+            123,
+            path,
+            file_name="file.bin",
+            random_id=1,
+        )
+    )
+    async with asyncio.timeout(2):
+        while native.active < 2:  # noqa: ASYNC110 - observe the synthetic RPC boundary.
+            await asyncio.sleep(0)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert native.active == 0
+    assert native.published == []
+    assert adapter._media_scheduler.active == 0
+    assert adapter._media_scheduler.snapshot()["queued"] == 0
+
+
+@pytest.mark.asyncio
+async def test_pipeline_refuses_publication_after_integrity_failure(tmp_path):
+    path = tmp_path / "staged"
+    path.write_bytes(b"actual bytes")
+    native = Native()
+    adapter = client(native)
+    boundary = AsyncMock()
+    with pytest.raises(ValueError, match="changed"):
+        await adapter.send_staged(
+            123,
+            path,
+            file_name="file.bin",
+            random_id=1,
+            expected_sha256="0" * 64,
+            before_dispatch=boundary,
+        )
+    assert native.published == []
+    boundary.assert_not_called()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("seconds, occurrences", [(1, 1), (45, 4)])
+@pytest.mark.parametrize("flood_error", [FloodWaitError, FloodPremiumWaitError])
+async def test_pipeline_flood_feedback_retries_individual_part(
+    tmp_path, seconds, occurrences, flood_error
+):
+    path = tmp_path / "staged"
+    path.write_bytes(b"x" * (PART * 3))
+    native = Native()
+    native.flood_part = 1
+    native.flood_seconds = seconds
+    native.flood_count = occurrences
+    native.flood_error = flood_error
+    adapter = client(native, limit=4)
+    original = adapter._media_scheduler.flood
+
+    async def feedback(seconds):
+        assert seconds >= native.flood_seconds
+        await original(0)
+
+    adapter._media_scheduler.flood = feedback
+    await adapter.send_staged(123, path, file_name="file.bin", random_id=1)
+    assert native.calls == {0: 1, 1: occurrences + 1, 2: 1}
+    assert adapter._defer_read.await_count == occurrences
+    assert adapter._media_scheduler.floods == occurrences
+    assert adapter._media_scheduler.effective_limit == max(1, 4 // 2**occurrences)
+
+
+class EndpointNative:
+    def __init__(self, fail=False):
+        self.session = SimpleNamespace(
+            dc_id=5,
+            server_address="old",
+            port=443,
+            auth_key=object(),
+            save=Mock(),
+        )
+        self.session.set_dc = self.set_dc
+        self.disconnect = AsyncMock()
+        self.connect = AsyncMock(
+            side_effect=[OSError("unreachable"), None] if fail else None
+        )
+        self.is_user_authorized = AsyncMock(return_value=True)
+
+    def set_dc(self, dc_id, server_address, port):
+        self.session.dc_id = dc_id
+        self.session.server_address = server_address
+        self.session.port = port
+
+    async def __call__(self, request):
+        assert isinstance(request, functions.help.GetConfigRequest)
+        return SimpleNamespace(
+            dc_options=[
+                SimpleNamespace(
+                    id=4,
+                    ip_address="wrong-dc",
+                    port=443,
+                    media_only=False,
+                    cdn=False,
+                    ipv6=False,
+                ),
+                SimpleNamespace(
+                    id=5,
+                    ip_address="media-only",
+                    port=443,
+                    media_only=True,
+                    cdn=False,
+                    ipv6=False,
+                ),
+                SimpleNamespace(
+                    id=5,
+                    ip_address="current",
+                    port=443,
+                    media_only=False,
+                    cdn=False,
+                    ipv6=False,
+                ),
+            ]
+        )
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("fail", [False, True])
+async def test_live_endpoint_refresh_preserves_dc_auth_and_rolls_back_on_failure(fail):
+    native = EndpointNative(fail)
+    auth_key = native.session.auth_key
+    adapter = client(native)
+    await adapter._refresh_main_endpoint()
+    assert native.session.dc_id == 5
+    assert native.session.auth_key is auth_key
+    assert native.session.server_address == ("old" if fail else "current")
+    assert native.connect.await_count == (2 if fail else 1)
+    assert native.disconnect.await_count == (2 if fail else 1)
diff --git a/tests/web/__init__.py b/tests/web/__init__.py
new file mode 100644
index 00000000..65364806
--- /dev/null
+++ b/tests/web/__init__.py
@@ -0,0 +1 @@
+"""TGDrive web tests."""
diff --git a/tests/web/test_access_revalidation.py b/tests/web/test_access_revalidation.py
new file mode 100644
index 00000000..507dd7c8
--- /dev/null
+++ b/tests/web/test_access_revalidation.py
@@ -0,0 +1,146 @@
+"""Capabilities are checked again after slow metadata/preview work."""
+
+import pytest
+
+import tgdrive.web.app as app_module
+from tests.support.app_fixtures import app_client as client_fixture
+from tests.support.app_fixtures import login
+
+app_client = client_fixture
+
+
+@pytest.mark.parametrize(
+    "endpoint,helper",
+    [
+        ("/api/v1/preview", "describe_preview"),
+        ("/api/v1/media", "describe_media"),
+    ],
+)
+def test_revoked_during_preview_work_is_not_delivered_even_to_owner(
+    app_client, monkeypatch, endpoint, helper
+):
+    client, store, _, _ = app_client
+    identity = store.add_file("/", "secret.txt", 123, 4)["id"]
+    path = "/" + identity
+    token = store.create_share(path)
+    login(client)
+
+    async def slow_result(**kwargs):
+        assert store.authorize_file(path, token)
+        store.revoke_share(path)
+        return {"kind": "text", "text": "secret", "size": 4}
+
+    monkeypatch.setattr(app_module, helper, slow_result)
+    response = client.get(endpoint, params={"path": path, "auth": token})
+    assert response.status_code == 403
+    assert "secret" not in response.text
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("owner", [False, True])
+async def test_revoking_a_share_stops_cached_http_body_even_with_owner_cookie(
+    tmp_path, owner
+):
+    from urllib.parse import urlencode
+
+    from tests.media.test_pooled_media import account
+    from tests.media.test_stream_delivery import request
+    from tests.media.test_streaming import response_body
+    from tests.support.app_fixtures import FakeRuntime, make_settings
+    from tgdrive.core.security import SESSION_COOKIE
+    from tgdrive.media.media_reader import BLOCK
+    from tgdrive.media.streaming import stream_telegram_file
+    from tgdrive.storage.store import DriveStore
+    from tgdrive.telegram.client_pool import ClientPool
+
+    settings = make_settings(tmp_path)
+    payload = b"".join(bytes([index]) * BLOCK for index in range(8))
+    client = account("bot", payload)
+    pool = ClientPool([client], media_cache_dir=tmp_path / "media-cache")
+    await pool.start()
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    identity = store.add_file("/", "private.mkv", 77, len(payload))["id"]
+    path = "/" + identity
+    token = store.create_share(path)
+    runtime = FakeRuntime(store)
+    runtime.pool = pool
+    app = app_module.create_app(settings, runtime=runtime)
+    headers = [(b"host", b"testserver")]
+    if owner:
+        cookie = app.state.sessions.create()
+        headers.append((b"cookie", f"{SESSION_COOKIE}={cookie}".encode()))
+
+    def scope(*, supplied_token=True):
+        params = {"path": path}
+        if supplied_token:
+            params["auth"] = token
+        return {
+            "type": "http",
+            "http_version": "1.1",
+            "method": "GET",
+            "scheme": "https",
+            "path": "/file",
+            "raw_path": b"/file",
+            "query_string": urlencode(params).encode(),
+            "headers": headers,
+            "server": ("testserver", 443),
+            "client": ("test", 123),
+            "asgi": {"version": "3.0", "spec_version": "2.4"},
+        }
+
+    async def receive():
+        return {"type": "http.disconnect"}
+
+    sent = []
+    try:
+        warm = await stream_telegram_file(
+            pool=pool,
+            channel_id=settings.storage_channel,
+            message_id=77,
+            file_name="private.mkv",
+            expected_size=len(payload),
+            request=request(),
+        )
+        assert await response_body(warm) == payload
+        reads = sum(client.native.requests.values())
+
+        async def revoke_on_first_body(value):
+            sent.append(value)
+            if value["type"] == "http.response.body" and value.get("body"):
+                store.revoke_share(path)
+
+        # Once headers/body have started, ASGI cannot replace the status with
+        # 403. It aborts delivery instead, keeping already-sent bytes unrecalled.
+        with pytest.raises(RuntimeError, match="response already started"):
+            await app(scope(), receive, revoke_on_first_body)
+        delivered = b"".join(
+            value.get("body", b"")
+            for value in sent
+            if value["type"] == "http.response.body"
+        )
+        assert delivered == payload[:BLOCK]
+        assert sum(client.native.requests.values()) == reads
+        assert pool._media_read_cache.scratch.used == 0
+        assert pool._media_read_cache._active_streams == 0
+        assert not pool._media_read_cache.memory.flights
+        assert all(row.active_leases == 0 for row in await pool.status())
+
+        denied = []
+
+        async def collect(value):
+            denied.append(value)
+
+        await app(scope(), receive, collect)
+        assert denied[0]["status"] == 403
+        if owner:
+            denied.clear()
+            await app(scope(supplied_token=False), receive, collect)
+            assert denied[0]["status"] == 200
+            assert b"".join(value.get("body", b"") for value in denied) == payload
+        assert store.get_file(path)["size"] == len(payload)
+    finally:
+        await pool._media_read_cache.close()
+        await pool.stop()
+        app.state.sessions.close()
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/web/test_app.py b/tests/web/test_app.py
new file mode 100644
index 00000000..b6ae2bdb
--- /dev/null
+++ b/tests/web/test_app.py
@@ -0,0 +1,1202 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+from fastapi import Request
+from fastapi.responses import Response
+from fastapi.testclient import TestClient
+
+import tgdrive.web.app as app_module
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.app_fixtures import app_client as app_client
+from tests.support.mongo_fixtures import FakeMongoBackend, register_test_backend
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+
+def test_home_security_headers_and_static_traversal(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, _, _ = app_client
+
+    home = client.get("/")
+    assert home.status_code == 200
+    assert "default-src 'self'" in home.headers["content-security-policy"]
+    policy = home.headers["content-security-policy"]
+    assert "script-src 'self' 'wasm-unsafe-eval';" in policy
+    assert "style-src-elem 'self';" in policy
+    assert "style-src-attr 'unsafe-inline';" in policy
+    assert "media-src 'self' blob:;" in policy
+    assert "script-src 'self' 'unsafe-inline'" not in policy
+    assert home.headers["x-content-type-options"] == "nosniff"
+    assert "localStorage" not in home.text
+
+    traversal = client.get("/static/%2e%2e/%2e%2e/.env")
+    assert traversal.status_code == 404
+    assert traversal.json() == {"detail": "Not Found"}
+
+
+def test_login_cookie_and_directory_access_control(app_client: tuple[Any, ...]) -> None:
+    client, _, _, _ = app_client
+
+    denied = client.post("/api/getDirectory", json={"path": "/", "auth": None})
+    assert denied.status_code == 401
+
+    wrong = client.post("/api/checkPassword", json={"pass": "wrong"})
+    assert wrong.status_code == 401
+    assert "tgdrive_session" not in wrong.cookies
+
+    response = client.post(
+        "/api/checkPassword", json={"pass": "correct horse battery staple"}
+    )
+    cookie = response.headers["set-cookie"].lower()
+    assert "httponly" in cookie
+    assert "secure" in cookie
+    assert "samesite=strict" in cookie
+
+    directory = client.post("/api/getDirectory", json={"path": "/"})
+    assert directory.status_code == 200
+    assert directory.json()["data"]["contents"] == {}
+
+
+def test_wrong_password_and_known_folder_ids_cannot_browse_private_directories(
+    app_client,
+):
+    client, store, _, _ = app_client
+    private = store.create_folder("/", "Private directory")
+    private_path = "/" + private["id"]
+    child = store.create_folder(private_path, "Private subdirectory")
+    child_path = private_path + "/" + child["id"]
+    store.add_file(child_path, "private-document.txt", 123, 4)
+
+    wrong = client.post("/api/checkPassword", json={"pass": "wrong"})
+    assert wrong.status_code == 401
+    assert "tgdrive_session" not in client.cookies
+
+    for path in ("/", private_path, child_path):
+        for auth in (None, "wrong"):
+            denied = client.post(
+                "/api/getDirectory",
+                json={"path": path, "auth": auth, "password": "wrong"},
+            )
+            assert denied.status_code == 401
+            assert "data" not in denied.json()
+            assert "private-document.txt" not in denied.text
+
+    for path in (private_path, child_path):
+        for auth in (None, "wrong"):
+            denied = client.post(
+                "/api/getDirectory",
+                json={"path": "/share_" + path.lstrip("/"), "auth": auth},
+            )
+            assert denied.status_code == 403
+            assert "data" not in denied.json()
+            assert "private-document.txt" not in denied.text
+
+
+def test_revoked_client_returns_actionable_503_and_owner_status(app_client):
+    from telethon.errors import SessionRevokedError
+
+    from tests.telegram.test_client_pool import FakeClient
+    from tgdrive.telegram.client_pool import ClientPool
+
+    client, _, runtime, _ = app_client
+    runtime.pool = ClientPool([FakeClient("bot")])
+
+    @client.app.get("/__test__/revoked")
+    async def revoked():
+        await runtime.pool.start()
+        try:
+            async with runtime.pool.lease():
+                raise SessionRevokedError(request="secret-request")
+        finally:
+            await runtime.pool.stop()
+
+    response = client.get("/__test__/revoked")
+    assert response.status_code == 503
+    assert response.json()["code"] == "TELEGRAM_CREDENTIALS_REVOKED"
+    assert "Connections" in response.json()["detail"]
+    assert "secret-request" not in response.text
+    login(client)
+    status = client.get("/api/v1/status").json()
+    assert status["telegram_ready"] is False
+    assert status["telegram_issues"][0]["code"] == "TELEGRAM_CREDENTIALS_REVOKED"
+
+
+def test_folder_lifecycle_search_trash_and_permanent_delete(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, store, runtime, _ = app_client
+    login(client)
+
+    created = client.post(
+        "/api/createNewFolder", json={"path": "/", "name": "Projects"}
+    )
+    assert created.status_code == 200
+    folder = next(iter(store.list_directory("/").values()))
+    folder_path = f"/{folder['id']}"
+    store.add_file(folder_path, "report.txt", 777, 12)
+
+    search = client.post(
+        "/api/getDirectory", json={"path": "/search_report", "auth": None}
+    )
+    assert search.status_code == 200
+    result = next(iter(search.json()["data"]["contents"].values()))
+    assert result["name"] == "report.txt"
+
+    trashed = client.post(
+        "/api/trashFileFolder", json={"path": folder_path, "trash": True}
+    )
+    assert trashed.status_code == 200
+    trash = client.post("/api/getDirectory", json={"path": "/trash"})
+    trashed_item = next(iter(trash.json()["data"]["contents"].values()))
+    assert trashed_item["name"] == "Projects"
+
+    deleted = client.post("/api/deleteFileFolder", json={"path": folder_path})
+    assert deleted.status_code == 202
+
+    async def wait_for_deletion() -> None:
+        record = runtime.transfers.registry.get(deleted.json()["id"])
+        assert record.task is not None
+        await record.task
+
+    assert client.portal is not None
+    client.portal.call(wait_for_deletion)
+    assert client.get("/api/v1/jobs").headers["cache-control"] == "no-store"
+    assert (
+        client.get("/api/v1/jobs/" + deleted.json()["id"]).headers["cache-control"]
+        == "no-store"
+    )
+    assert runtime.transfers.deleted_messages == []
+    assert store.list_directory("/") == {}
+
+
+def test_share_token_is_scoped_and_file_access_accepts_folder_token(
+    app_client: tuple[Any, ...], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    client, store, _, _ = app_client
+    first = store.create_folder("/", "Shared")
+    second = store.create_folder("/", "Private")
+    first_path = f"/{first['id']}"
+    second_path = f"/{second['id']}"
+    file_data = store.add_file(first_path, "movie.mp4", 123, 4)
+    file_path = f"{first_path}/{file_data['id']}"
+    login(client)
+
+    token_response = client.post("/api/getFolderShareAuth", json={"path": first_path})
+    token = token_response.json()["auth"]
+    client.post("/api/logout")
+
+    allowed = client.post(
+        "/api/getDirectory",
+        json={"path": f"/share_{first_path.lstrip('/')}", "auth": token},
+    )
+    assert allowed.status_code == 200
+    assert allowed.json()["auth_home_path"] == first_path
+
+    denied = client.post(
+        "/api/getDirectory",
+        json={"path": f"/share_{second_path.lstrip('/')}", "auth": token},
+    )
+    assert denied.status_code == 403
+
+    async def fake_stream(**kwargs: Any) -> Response:
+        request = kwargs["request"]
+        assert isinstance(request, Request)
+        return Response(b"data", media_type="video/mp4")
+
+    monkeypatch.setattr(app_module, "stream_telegram_file", fake_stream)
+    shared_file = client.get("/file", params={"path": file_path, "auth": token})
+    assert shared_file.status_code == 200
+    assert shared_file.content == b"data"
+
+    other_file = store.add_file(second_path, "private.txt", 456, 1)
+    private_path = f"{second_path}/{other_file['id']}"
+    denied_file = client.get("/file", params={"path": private_path, "auth": token})
+    assert denied_file.status_code == 403
+
+
+def test_health_and_logout_are_stable(app_client: tuple[Any, ...]) -> None:
+    client, _, _, _ = app_client
+    assert client.get("/health/live").json() == {"status": "ok"}
+    assert client.get("/healthz").json() == {"status": "ok"}
+    assert client.post("/api/logout").json() == {"status": "ok"}
+
+
+def test_upload_remote_and_transfer_progress_endpoints(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, runtime, settings = app_client
+    assert client.get("/api/config").json()["max_file_size"] == settings.upload_limit
+    login(client)
+
+    upload = client.post(
+        "/api/upload",
+        data={"path": "/"},
+        files={"file": ("hello.txt", b"abc", "text/plain")},
+    )
+    assert upload.status_code == 200
+    transfer_id = upload.json()["id"]
+
+    progress = client.post("/api/getTransferProgress", json={"id": transfer_id})
+    assert progress.status_code == 200
+    assert progress.json()["data"]["phase"] == "uploading"
+
+    cancelled = client.post("/api/cancelUpload", json={"id": transfer_id})
+    assert cancelled.status_code == 200
+    cancelled_record = runtime.transfers.registry.get(transfer_id)
+    assert cancelled_record.cancel_event.is_set()
+    assert cancelled_record.status.value == "cancelled"
+    assert cancelled_record.phase == "cancelling"
+
+    info = client.post(
+        "/api/getFileInfoFromUrl", json={"url": "https://example.com/file.bin"}
+    )
+    assert info.json()["data"] == {
+        "file_name": "remote.bin",
+        "file_size": 12,
+        "content_type": "application/octet-stream",
+    }
+    started = client.post(
+        "/api/startFileDownloadFromUrl",
+        json={
+            "url": "https://example.com/file.bin",
+            "path": "/",
+            "filename": "renamed.bin",
+            "singleThreaded": False,
+        },
+    )
+    assert started.status_code == 200
+    assert runtime.transfers.remote_requests == [
+        ("https://example.com/file.bin", "/", "renamed.bin")
+    ]
+
+
+@pytest.mark.parametrize(
+    ("original", "name", "supported"),
+    [
+        ("earth.mp4", "earth", "planet.mp4"),
+        ("earth.mp4", "earth.pdf", "planet.mp4"),
+        ("earth.mp4", "earth.mp4.exe", "planet.mp4"),
+        ("image.svg", "image.\u017fvg", "renamed.svg"),
+        ("file.ss", "file.\u00df", "renamed.ss"),
+    ],
+)
+def test_rename_api_rejects_file_extension_changes(
+    app_client, original, name, supported
+):
+    client, store, _, _ = app_client
+    item = store.add_file("/", original, 5, 2)
+    path = "/" + item["id"]
+    login(client)
+    before = store.export()
+
+    response = client.post("/api/renameFileFolder", json={"path": path, "name": name})
+
+    assert response.status_code == 400
+    assert "extension cannot be changed" in response.json()["detail"]
+    assert store.export() == before
+
+    renamed = client.post(
+        "/api/renameFileFolder", json={"path": path, "name": supported}
+    )
+    assert renamed.status_code == 200
+    assert store.get_file(path)["name"] == supported
+
+
+def test_mutation_validation_and_file_share_scope(
+    app_client: tuple[Any, ...], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    client, store, _, _ = app_client
+    folder = store.create_folder("/", "Original")
+    folder_path = f"/{folder['id']}"
+    file_data = store.add_file(folder_path, "report.txt", 5, 2)
+    file_path = f"{folder_path}/{file_data['id']}"
+    login(client)
+
+    delete_visible = client.post("/api/deleteFileFolder", json={"path": file_path})
+    assert delete_visible.status_code == 409
+
+    renamed = client.post(
+        "/api/renameFileFolder", json={"path": folder_path, "name": "Renamed"}
+    )
+    assert renamed.status_code == 200
+    duplicate = client.post(
+        "/api/createNewFolder", json={"path": "/", "name": "renamed"}
+    )
+    assert duplicate.status_code == 409
+    invalid = client.post(
+        "/api/createNewFolder", json={"path": "/", "name": "bad/name"}
+    )
+    assert invalid.status_code == 400
+
+    token = client.post("/api/getFileShareAuth", json={"path": file_path}).json()[
+        "auth"
+    ]
+    client.post("/api/logout")
+    folder_denied = client.post(
+        "/api/getDirectory",
+        json={"path": f"/share_{folder_path.lstrip('/')}", "auth": token},
+    )
+    assert folder_denied.status_code == 403
+
+    async def fake_stream(**_kwargs: Any) -> Response:
+        return Response(b"ok")
+
+    monkeypatch.setattr(app_module, "stream_telegram_file", fake_stream)
+    assert client.get("/file", params={"path": file_path}).status_code == 403
+    shared = client.get("/file", params={"path": file_path, "auth": token})
+    assert shared.status_code == 200
+
+
+def test_video_player_requires_a_path(app_client: tuple[Any, ...]) -> None:
+    client, _, _, _ = app_client
+    assert client.get("/stream").status_code == 422
+    response = client.get("/stream", params={"path": "/abc"})
+    assert response.status_code == 200
+    assert "video-player.js" in response.text
+
+
+def test_remote_start_idempotency_and_request_recovery(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, runtime, _ = app_client
+    login(client)
+    payload = {
+        "url": "https://example.com/file.bin",
+        "path": "/",
+        "filename": "file.bin",
+        "client_request_id": "remote-request-0001",
+    }
+    first = client.post("/api/startFileDownloadFromUrl", json=payload)
+    second = client.post("/api/startFileDownloadFromUrl", json=payload)
+    assert first.status_code == second.status_code == 200
+    assert first.json()["id"] == second.json()["id"]
+    assert len(runtime.transfers.remote_requests) == 1
+
+    lookup = client.post(
+        "/api/getTransferByRequest",
+        json={"client_request_id": payload["client_request_id"]},
+    )
+    assert lookup.status_code == 200
+    assert lookup.json()["data"]["id"] == first.json()["id"]
+
+    changed = client.post(
+        "/api/startFileDownloadFromUrl", json={**payload, "filename": "different.bin"}
+    )
+    assert changed.status_code == 409
+    assert len(runtime.transfers.remote_requests) == 1
+
+
+@pytest.mark.parametrize("single_threaded", [False, True])
+def test_url_start_returns_job_without_contacting_source(
+    app_client, monkeypatch, single_threaded
+):
+    from unittest.mock import AsyncMock
+
+    client, _, runtime, _ = app_client
+    login(client)
+    inspect = AsyncMock(
+        side_effect=AssertionError("source lookup blocked start request")
+    )
+    monkeypatch.setattr(runtime.transfers, "inspect_remote", inspect)
+    response = client.post(
+        "/api/startFileDownloadFromUrl",
+        json={
+            "url": "https://example.com/slow-source.mov",
+            "path": "/",
+            "singleThreaded": single_threaded,
+        },
+    )
+    assert response.status_code == 200
+    assert response.json()["id"]
+    assert runtime.transfers.remote_modes == [single_threaded]
+    inspect.assert_not_awaited()
+
+
+def test_cancel_request_before_start_prevents_late_remote_job(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, runtime, _ = app_client
+    login(client)
+    request_id = "cancel-before-start-0001"
+    cancelled = client.post("/api/cancelUpload", json={"client_request_id": request_id})
+    assert cancelled.status_code == 200
+    assert cancelled.json()["data"]["status"] == "cancelled"
+    started = client.post(
+        "/api/startFileDownloadFromUrl",
+        json={
+            "url": "https://example.com/file.bin",
+            "path": "/",
+            "client_request_id": request_id,
+        },
+    )
+    assert started.status_code == 409
+    assert runtime.transfers.remote_requests == []
+
+
+def test_upload_request_reuses_record_and_cancel_tombstone_blocks_late_body(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, runtime, _ = app_client
+    login(client)
+    request_id = "browser-request-0001"
+    form = {"path": "/", "client_request_id": request_id}
+    first = client.post("/api/upload", data=form, files={"file": ("hello.txt", b"abc")})
+    second = client.post(
+        "/api/upload", data=form, files={"file": ("hello.txt", b"abc")}
+    )
+    assert first.status_code == second.status_code == 200
+    assert first.json()["id"] == second.json()["id"]
+    assert len(runtime.transfers.registry._records) == 1
+    cancelled = client.post("/api/cancelUpload", json={"client_request_id": request_id})
+    assert cancelled.json()["data"]["status"] == "cancelled"
+
+    blocked_id = "browser-cancel-before-body"
+    client.post("/api/cancelUpload", json={"client_request_id": blocked_id})
+    blocked = client.post(
+        "/api/upload",
+        data={"path": "/", "client_request_id": blocked_id},
+        files={"file": ("hello.txt", b"abc")},
+    )
+    assert blocked.status_code == 409
+    assert len(runtime.transfers.registry._records) == 1
+
+
+def test_request_lookup_and_cancellation_are_authenticated(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, _, _ = app_client
+    payload = {"client_request_id": "browser-request-0001"}
+    assert client.post("/api/getTransferByRequest", json=payload).status_code == 401
+    assert client.post("/api/cancelUpload", json=payload).status_code == 401
+    login(client)
+    assert client.post("/api/getTransferByRequest", json=payload).status_code == 404
+    assert client.post("/api/cancelUpload", json={}).status_code == 422
+
+
+def test_cookie_mutations_reject_cross_origin_including_sibling_subdomain(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, store, _, _ = app_client
+    login(client)
+    for origin in ("https://evil.example", "https://sub.testserver", "null"):
+        denied = client.post(
+            "/api/createNewFolder",
+            json={"path": "/", "name": "Unwanted"},
+            headers={"Origin": origin},
+        )
+        assert denied.status_code == 403
+    assert store.list_directory("/") == {}
+    allowed = client.post(
+        "/api/createNewFolder",
+        json={"path": "/", "name": "Allowed"},
+        headers={"Origin": "https://testserver:443"},
+    )
+    assert allowed.status_code == 200
+
+
+def test_json_body_limit_applies_before_decode_and_to_chunked_requests(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, _, _ = app_client
+    oversized = b'{"pass":"' + b"x" * 70000 + b'"}'
+    declared = client.post(
+        "/api/checkPassword",
+        content=oversized,
+        headers={"Content-Type": "application/json"},
+    )
+    assert declared.status_code == 413
+
+    def chunks():
+        yield b'{"pass":"'
+        yield b"x" * 70000
+        yield b'"}'
+
+    chunked = client.post(
+        "/api/checkPassword",
+        content=chunks(),
+        headers={"Content-Type": "application/json"},
+    )
+    assert chunked.status_code == 413
+    private = client.post(
+        "/api/createNewFolder",
+        content=oversized,
+        headers={"Content-Type": "application/json"},
+    )
+    assert private.status_code == 401
+
+
+def test_owner_logout_revokes_copied_session_cookie(app_client):
+    client, _, _, _ = app_client
+    login(client)
+    token = client.cookies.get("tgdrive_session")
+    assert client.get("/api/v1/session").json()["authenticated"] is True
+    assert client.post("/api/logout").status_code == 200
+    client.cookies.set("tgdrive_session", token)
+    assert client.get("/api/v1/session").json()["authenticated"] is False
+    assert client.get("/api/v1/jobs").status_code == 401
+
+
+async def test_devices_share_owner_access_but_keep_independent_sessions(
+    tmp_path, monkeypatch
+):
+    import asyncio
+    from contextlib import AsyncExitStack
+
+    import httpx2
+
+    from tgdrive.core.security import SESSION_COOKIE
+
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    runtime = FakeRuntime(store)
+    runtime.mongo = register_test_backend(monkeypatch, settings)
+    app = create_app(settings, runtime=runtime)
+    collection = runtime.mongo.db.sessions
+
+    try:
+        async with app.router.lifespan_context(app), AsyncExitStack() as stack:
+            devices = [
+                await stack.enter_async_context(
+                    httpx2.AsyncClient(
+                        transport=httpx2.ASGITransport(app=app),
+                        base_url="https://testserver",
+                    )
+                )
+                for _ in range(3)
+            ]
+            password = {"pass": "correct horse battery staple"}
+            simultaneous_logins = await asyncio.gather(
+                *(
+                    device.post("/api/checkPassword", json=password)
+                    for device in devices[:2]
+                )
+            )
+            assert sorted(response.status_code for response in simultaneous_logins) == [
+                200,
+                429,
+            ]
+            for device, response in zip(devices, simultaneous_logins, strict=False):
+                if response.status_code == 429:
+                    assert response.headers["retry-after"] == "1"
+                    assert response.json()["detail"] == "Login busy; retry shortly"
+                    assert response.json()["code"] == "LOGIN_BUSY"
+                    assert (
+                        await device.post("/api/checkPassword", json=password)
+                    ).status_code == 200
+
+            original_tokens = [
+                device.cookies.get(SESSION_COOKIE) for device in devices[:2]
+            ]
+            assert all(original_tokens) and original_tokens[0] != original_tokens[1]
+            changes = await asyncio.gather(
+                *(
+                    device.post(
+                        "/api/createNewFolder",
+                        json={"path": "/", "name": f"Device {index}"},
+                    )
+                    for index, device in enumerate(devices[:2])
+                )
+            )
+            assert [response.status_code for response in changes] == [200, 200]
+            assert (
+                await devices[2].post("/api/checkPassword", json=password)
+            ).status_code == 200
+            assert [
+                device.cookies.get(SESSION_COOKIE) for device in devices[:2]
+            ] == original_tokens
+            assert len({device.cookies.get(SESSION_COOKIE) for device in devices}) == 3
+            assert all(
+                response.status_code == 200
+                for response in await asyncio.gather(
+                    *(device.get("/api/v1/nodes") for device in devices)
+                )
+            )
+            assert collection.count_documents({}) == 3
+
+            assert (await devices[0].post("/api/logout")).status_code == 200
+            assert devices[0].cookies.get(SESSION_COOKIE) is None
+            devices[0].cookies.set(SESSION_COOKIE, original_tokens[0])
+            assert (await devices[0].get("/api/v1/nodes")).status_code == 401
+            assert (
+                await devices[0].post(
+                    "/api/createNewFolder", json={"path": "/", "name": "Revoked device"}
+                )
+            ).status_code == 401
+            assert collection.count_documents({}) == 2
+            remaining = await asyncio.gather(
+                *(
+                    device.post(
+                        "/api/createNewFolder",
+                        json={"path": "/", "name": f"Still active {index}"},
+                    )
+                    for index, device in enumerate(devices[1:], 1)
+                )
+            )
+            assert [response.status_code for response in remaining] == [200, 200]
+            for device in devices[1:]:
+                listing = await device.get("/api/v1/nodes")
+                assert listing.status_code == 200
+                assert {item["name"] for item in listing.json()["items"]} == {
+                    "Device 0",
+                    "Device 1",
+                    "Still active 1",
+                    "Still active 2",
+                }
+    finally:
+        store.close()
+
+
+@pytest.mark.parametrize(
+    "cookie_state", ["missing", "invalid", "expired", "revoked", "valid"]
+)
+def test_logout_only_writes_for_active_owner_sessions(
+    app_client, monkeypatch, cookie_state
+):
+    import hashlib
+    import time
+    from unittest.mock import Mock
+
+    from tgdrive.core.security import SESSION_COOKIE, InvalidSession
+
+    client, _, _, _ = app_client
+    sessions = client.app.state.sessions
+    backend = FakeMongoBackend()
+    collection = backend.db.sessions
+    backend.write = Mock(wraps=backend.write)
+    # Exercise the production MongoDB session path without any external service.
+    monkeypatch.setattr(sessions, "_mongo", collection)
+    monkeypatch.setattr(sessions, "_mongo_backend", backend)
+    token = None
+    if cookie_state == "invalid":
+        token = "forged-owner-session"
+    elif cookie_state == "expired":
+        token = sessions.create(now=int(time.time()) - sessions._ttl_seconds - 1)
+    elif cookie_state in {"revoked", "valid"}:
+        token = sessions.create()
+        if cookie_state == "revoked":
+            sessions.revoke(token)
+    if token is not None:
+        client.cookies.set(SESSION_COOKIE, token)
+    backend.write.reset_mock()
+    revoke = Mock(wraps=sessions.revoke)
+    monkeypatch.setattr(sessions, "revoke", revoke)
+
+    response = client.post("/api/logout")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+    assert "Max-Age=0" in response.headers["set-cookie"]
+    if cookie_state == "valid":
+        revoke.assert_called_once_with(token)
+        backend.write.assert_called_once_with(
+            collection,
+            "delete_one",
+            {"_id": hashlib.sha256(token.encode()).hexdigest()},
+        )
+        with pytest.raises(InvalidSession, match="revoked"):
+            sessions.verify(token)
+    else:
+        revoke.assert_not_called()
+        backend.write.assert_not_called()
+
+
+def test_local_http_owner_session_and_origin_protection(tmp_path):
+    settings = make_settings(tmp_path).model_copy(update={"cookie_secure": False})
+    store = DriveStore.create(tmp_path / "drive.json")
+    app = create_app(settings, runtime=FakeRuntime(store))
+    with TestClient(app, base_url="http://localhost:8000") as client:
+        response = client.post(
+            "/api/checkPassword",
+            json={"pass": "correct horse battery staple"},
+            headers={"Origin": "http://localhost:8000"},
+        )
+        assert response.status_code == 200
+        cookie = response.headers["set-cookie"].lower()
+        assert "secure" not in cookie
+        assert "httponly" in cookie and "samesite=strict" in cookie
+        assert "strict-transport-security" not in response.headers
+        assert client.get("/api/v1/session").json()["authenticated"] is True
+
+        for origin in ("http://localhost:8001", "http://127.0.0.1:8000"):
+            denied = client.post(
+                "/api/createNewFolder",
+                json={"path": "/", "name": "Unwanted"},
+                headers={
+                    "Origin": origin,
+                    "X-Forwarded-Host": origin.removeprefix("http://"),
+                    "X-Forwarded-Proto": "https",
+                },
+            )
+            assert denied.status_code == 403
+        assert store.list_directory("/") == {}
+        assert client.post("/api/logout").status_code == 200
+        assert client.get("/api/v1/session").json()["authenticated"] is False
+
+
+def test_cross_origin_login_and_logout_do_not_change_owner_session(app_client):
+    client, _, _, _ = app_client
+    response = client.post(
+        "/api/checkPassword",
+        json={"pass": "correct horse battery staple"},
+        headers={"Origin": "https://evil.example"},
+    )
+    assert response.status_code == 403
+    assert "set-cookie" not in response.headers
+    assert client.get("/api/v1/session").json()["authenticated"] is False
+    login(client)
+    response = client.post("/api/logout", headers={"Origin": "https://evil.example"})
+    assert response.status_code == 403
+    assert client.get("/api/v1/session").json()["authenticated"] is True
+
+
+def test_mongodb_outage_refuses_app_auth_without_leaking_provider_error(tmp_path):
+    from unittest.mock import Mock
+
+    from pymongo.errors import ConnectionFailure
+
+    from tgdrive.storage.mongo import DatabaseUnavailable
+
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    sessions = SimpleNamespace(
+        find=Mock(side_effect=ConnectionFailure("synthetic-private-database-token"))
+    )
+    backend = SimpleNamespace(db=SimpleNamespace(sessions=sessions), write=Mock())
+    runtime = FakeRuntime(store)
+    runtime.mongo = backend
+    try:
+        with pytest.raises(
+            DatabaseUnavailable, match="Restore database access, then restart TGDrive"
+        ) as captured:
+            create_app(settings, runtime=runtime)
+        assert "synthetic-private-database-token" not in str(captured.value)
+        assert not (settings.resolved_data_dir / "auth.sqlite3").exists()
+        backend.write.assert_not_called()
+    finally:
+        store.close()
+
+
+def test_owner_credential_rotation_preserves_existing_share_links(tmp_path):
+    from pydantic import SecretStr
+
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    item = store.add_file("/", "shared.pdf", 7, 100)
+    path = "/" + item["id"]
+    with TestClient(
+        create_app(settings, runtime=FakeRuntime(store)),
+        base_url="https://testserver",
+    ) as client:
+        login(client)
+        token = client.post("/api/v1/shares", json={"path": path}).json()["auth"]
+
+    rotated = settings.model_copy(
+        update={"admin_password": SecretStr("a replacement owner password")}
+    )
+    with TestClient(
+        create_app(rotated, runtime=FakeRuntime(store)),
+        base_url="https://testserver",
+    ) as client:
+        shared = client.get("/api/v1/preview", params={"path": path, "auth": token})
+        assert shared.status_code == 200
+        assert client.get("/api/v1/preview", params={"path": path}).status_code == 403
+
+
+@pytest.mark.parametrize("hashed", [False, True])
+def test_restarts_preserve_sessions_but_password_changes_revoke_them(tmp_path, hashed):
+    from argon2 import PasswordHasher
+    from pydantic import SecretStr
+
+    settings = make_settings(tmp_path)
+    if hashed:
+        settings = settings.model_copy(
+            update={
+                "admin_password_hash": SecretStr(
+                    PasswordHasher().hash("correct horse battery staple")
+                )
+            }
+        )
+    store = DriveStore.create(tmp_path / "drive.json")
+    backend = FakeMongoBackend()
+
+    def app(config):
+        runtime = FakeRuntime(store)
+        runtime.mongo = backend
+        return create_app(config, runtime=runtime)
+
+    with TestClient(app(settings), base_url="https://testserver") as client:
+        login(client)
+        token = client.cookies.get("tgdrive_session")
+    with TestClient(app(settings), base_url="https://testserver") as client:
+        client.cookies.set("tgdrive_session", token)
+        assert client.get("/api/v1/session").json()["authenticated"] is True
+
+    replacement = "a replacement owner password"
+    changes = {"admin_password": SecretStr(replacement)}
+    if hashed:
+        changes["admin_password_hash"] = SecretStr(PasswordHasher().hash(replacement))
+    rotated = settings.model_copy(update=changes)
+    with TestClient(app(rotated), base_url="https://testserver") as client:
+        client.cookies.set("tgdrive_session", token)
+        assert client.get("/api/v1/session").json()["authenticated"] is False
+        assert client.get("/api/v1/jobs").status_code == 401
+        assert (
+            client.post("/api/checkPassword", json={"pass": replacement}).status_code
+            == 200
+        )
+
+
+def test_hashed_password_preserves_intentional_whitespace(tmp_path):
+    from argon2 import PasswordHasher
+    from pydantic import SecretStr
+
+    password = "  correct horse battery staple  "
+    settings = make_settings(tmp_path).model_copy(
+        update={"admin_password_hash": SecretStr(PasswordHasher().hash(password))}
+    )
+    store = DriveStore.create(tmp_path / "drive.json")
+    app = create_app(settings, runtime=FakeRuntime(store))
+    with TestClient(app, base_url="https://testserver") as client:
+        assert (
+            client.post(
+                "/api/checkPassword", json={"pass": password.strip()}
+            ).status_code
+            == 401
+        )
+        assert (
+            client.post("/api/checkPassword", json={"pass": password}).status_code
+            == 200
+        )
+
+
+def test_password_hashing_does_not_stall_health_or_spawn_unbounded_work(
+    app_client, monkeypatch
+):
+    from concurrent.futures import ThreadPoolExecutor
+    from threading import Event
+
+    client, _, _, _ = app_client
+    checking = Event()
+    release = Event()
+
+    def slow_password_check(_candidate, _expected):
+        checking.set()
+        assert release.wait(5)
+        return True
+
+    monkeypatch.setattr(app_module, "verify_password", slow_password_check)
+    with ThreadPoolExecutor(max_workers=1) as workers:
+        first = workers.submit(client.post, "/api/checkPassword", json={"pass": "test"})
+        try:
+            assert checking.wait(5)
+            assert client.get("/health/live").status_code == 200
+            busy = client.post("/api/checkPassword", json={"pass": "test"})
+            assert busy.status_code == 429
+            assert busy.headers["retry-after"] == "1"
+            assert busy.json()["code"] == "LOGIN_BUSY"
+        finally:
+            release.set()
+        assert first.result(timeout=5).status_code == 200
+
+
+@pytest.mark.parametrize(
+    "headers",
+    [
+        {"Sec-Fetch-Site": "same-site"},
+        {"Sec-Fetch-Site": "cross-site"},
+        {"Referer": "https://sub.testserver/settings"},
+        {"Referer": "https://evil.example/settings"},
+        {"Origin": "https://testserver:0"},
+        [("Origin", "https://evil.example"), ("Origin", "https://testserver")],
+    ],
+)
+def test_browser_mutations_reject_missing_or_ambiguous_origin(app_client, headers):
+    client, store, _, _ = app_client
+    login(client)
+    denied = client.post(
+        "/api/createNewFolder",
+        json={"path": "/", "name": "Unwanted"},
+        headers=headers,
+    )
+    assert denied.status_code == 403
+    assert store.list_directory("/") == {}
+
+
+def test_legacy_same_origin_referrer_and_headerless_api_clients_are_allowed(app_client):
+    client, _, _, _ = app_client
+    login(client)
+    for index, headers in enumerate(
+        (
+            {"Referer": "https://testserver/settings?tab=files"},
+            {},
+            {"Sec-Fetch-Site": "same-origin"},
+        )
+    ):
+        response = client.post(
+            "/api/createNewFolder",
+            json={"path": "/", "name": f"Allowed {index}"},
+            headers=headers,
+        )
+        assert response.status_code == 200
+
+
+def test_v1_chunk_receipt_requires_owner_and_durable_offsets(app_client):
+    import hashlib
+
+    client, _, _, _ = app_client
+    assert (
+        client.post(
+            "/api/v1/uploads",
+            json={
+                "name": "receipt.bin",
+                "parent_id": "/",
+                "total_size": 3,
+            },
+        ).status_code
+        == 401
+    )
+    login(client)
+    created = client.post(
+        "/api/v1/uploads",
+        json={
+            "name": "../../receipt.bin",
+            "parent_id": "/",
+            "total_size": 3,
+        },
+    )
+    assert created.status_code == 201
+    session = created.json()
+    assert session["name"] == "receipt.bin"
+    address = "/api/v1/uploads/" + session["id"]
+    assert client.head(address).headers["upload-offset"] == "0"
+    assert (
+        client.patch(
+            address,
+            content=b"abc",
+            headers={
+                "Content-Type": "application/octet-stream",
+                "Upload-Offset": "0",
+            },
+        ).status_code
+        == 204
+    )
+    assert client.head(address).headers["upload-offset"] == "3"
+    item = client.get(address).json()
+    assert item["checksums"] == [
+        {
+            "offset": 0,
+            "size": 3,
+            "sha256": hashlib.sha256(b"abc").hexdigest(),
+        }
+    ]
+    conflict = client.patch(
+        address,
+        content=b"abc",
+        headers={
+            "Content-Type": "application/octet-stream",
+            "Upload-Offset": "0",
+        },
+    )
+    assert conflict.status_code == 409
+    assert conflict.json()["code"] == "UPLOAD_OFFSET_CHANGED"
+
+
+def test_v1_move_to_shared_folder_requires_confirmed_exposure(app_client):
+    client, store, _, _ = app_client
+    source = store.create_folder("/", "Private")
+    destination = store.create_folder("/", "Published")
+    login(client)
+    share = client.post(
+        "/api/v1/shares",
+        json={
+            "path": "/" + destination["id"],
+            "expires_in_days": None,
+        },
+    )
+    assert share.status_code == 201
+    assert share.json()["expires_at"] is None
+    listing = client.get("/api/v1/shares").json()["shares"]
+    assert listing[0]["name"] == "Published"
+    move = {"paths": ["/" + source["id"]], "destination": "/" + destination["id"]}
+    rejected = client.post("/api/v1/nodes/move", json=move)
+    assert rejected.status_code == 409
+    assert rejected.json()["code"] == "PUBLIC_EXPOSURE_CONFIRMATION_REQUIRED"
+    assert store.get_directory("/" + source["id"])["name"] == "Private"
+    move["allow_public_exposure"] = True
+    assert client.post("/api/v1/nodes/move", json=move).status_code == 200
+
+
+def test_explicit_item_share_survives_move_but_inherited_share_does_not(
+    app_client,
+    monkeypatch,
+):
+    client, store, _, _ = app_client
+    shared = store.create_folder("/", "Shared")
+    private = store.create_folder("/", "Private")
+    item = store.add_file("/" + shared["id"], "report.txt", 343, 4)
+    old_path = "/" + shared["id"] + "/" + item["id"]
+    inherited_token = store.create_share("/" + shared["id"])
+    own_token = store.create_share(old_path)
+    login(client)
+    moved = client.post(
+        "/api/v1/nodes/move",
+        json={
+            "paths": [old_path],
+            "destination": "/" + private["id"],
+        },
+    )
+    assert moved.status_code == 200
+
+    async def content(**kwargs):
+        return Response(b"safe")
+
+    monkeypatch.setattr(app_module, "stream_telegram_file", content)
+    client.cookies.clear()
+    assert (
+        client.get(
+            "/file",
+            params={
+                "path": old_path,
+                "auth": inherited_token,
+            },
+        ).status_code
+        == 403
+    )
+    assert (
+        client.get(
+            "/file",
+            params={
+                "path": old_path,
+                "auth": own_token,
+            },
+        ).content
+        == b"safe"
+    )
+
+
+def test_preview_and_media_require_owner_or_in_scope_share(app_client):
+    client, store, _runtime, _settings = app_client
+    folder = store.create_folder("/", "Shared")
+    folder_path = "/" + folder["id"]
+    file = store.add_file(folder_path, "manual.pdf", 7, 100)
+    path = folder_path + "/" + file["id"]
+    other = store.add_file("/", "private.pdf", 8, 100)
+    for endpoint in ("/api/v1/preview", "/api/v1/media"):
+        assert client.get(endpoint, params={"path": path}).status_code == 403
+    token = store.create_share(folder_path)
+    preview = client.get("/api/v1/preview", params={"path": path, "auth": token})
+    assert preview.status_code == 200
+    assert preview.json()["kind"] == "pdf"
+    assert "preview=1" in preview.json()["url"]
+    assert (
+        client.get(
+            "/api/v1/preview", params={"path": "/" + other["id"], "auth": token}
+        ).status_code
+        == 403
+    )
+    store.revoke_share(folder_path)
+    assert (
+        client.get("/api/v1/preview", params={"path": path, "auth": token}).status_code
+        == 403
+    )
+    login(client)
+    assert client.get("/api/v1/preview", params={"path": path}).status_code == 200
+
+
+def test_unsupported_preview_does_not_open_telegram(app_client):
+    client, store, _runtime, _settings = app_client
+    item = store.add_file("/", "archive.zip", 7, 123)
+    login(client)
+    response = client.get("/api/v1/preview", params={"path": "/" + item["id"]})
+    assert response.status_code == 200
+    assert response.json()["kind"] == "unsupported"
+    assert "Download" in response.json()["reason"]
+
+
+def test_bundled_viewer_license_is_readable_without_owner_session(
+    app_client: tuple[Any, ...],
+) -> None:
+    client, _, _, _ = app_client
+    response = client.get("/third-party/movi-player-LICENSE.txt")
+    assert response.status_code == 200
+    assert "Apache License" in response.text
+    assert response.headers["x-content-type-options"] == "nosniff"
+    denied = client.get("/third-party/%2e%2e/%2e%2e/.env")
+    assert denied.status_code == 404
+
+
+def test_recopied_share_retains_token_after_rename_move_and_revokes(
+    app_client, monkeypatch
+):
+    client, store, _, _ = app_client
+    item = store.add_file("/", "original.txt", 42, 4)
+    original = "/" + item["id"]
+    target = store.create_folder("/", "Reports")
+    login(client)
+    created = client.post(
+        "/api/v1/shares", json={"path": original, "expires_in_days": None}
+    )
+    assert created.status_code == 201
+    token = created.json()["auth"]
+    listing = client.get("/api/v1/shares")
+    assert listing.headers["cache-control"] == "no-store"
+    share = listing.json()["shares"][0]
+    assert share["copyable"] and share["folder_label"] == "My Files"
+    assert "auth" not in share and "token_hash" not in share
+    assert token not in str(store.export())
+    store.rename(original, "renamed.txt")
+    store.move(original, "/" + target["id"])
+    result = client.post("/api/v1/shares/link", json={"path": original})
+    assert result.status_code == 200
+    assert result.json()["auth"] == token
+    assert result.headers["cache-control"] == "no-store"
+    listed = client.get("/api/v1/shares").json()["shares"][0]
+    assert listed["name"] == "renamed.txt"
+    assert listed["folder_label"] == "My Files / Reports"
+
+    async def content(**kwargs):
+        return Response(b"safe")
+
+    monkeypatch.setattr(app_module, "stream_telegram_file", content)
+    client.cookies.clear()
+    assert (
+        client.post("/api/v1/shares/link", json={"path": original}).status_code == 401
+    )
+    assert (
+        client.get("/file", params={"path": original, "auth": token}).content == b"safe"
+    )
+    login(client)
+    assert (
+        client.request("DELETE", "/api/v1/shares", json={"path": original}).status_code
+        == 200
+    )
+    assert (
+        client.post("/api/v1/shares/link", json={"path": original}).status_code == 410
+    )
+    client.cookies.clear()
+    assert (
+        client.get("/file", params={"path": original, "auth": token}).status_code == 403
+    )
+
+
+def test_expired_shares_listed_and_legacy_links_not_rotated(app_client, monkeypatch):
+    client, store, _, _settings = app_client
+    item = store.add_file("/", "legacy.txt", 52, 4)
+    path = "/" + item["id"]
+    token = store.create_share(path)
+    login(client)
+    assert client.get("/api/v1/shares").json()["shares"][0]["copyable"] is False
+    assert client.post("/api/v1/shares/link", json={"path": path}).status_code == 409
+    assert store.authorize_file(path, token)
+    assert len(store.list_shares()) == 1
+    monkeypatch.setattr(
+        "tgdrive.storage.store._utc_now", lambda: "9999-01-01T00:00:00Z"
+    )
+    assert store.list_shares() == []
+    assert len(client.get("/api/v1/shares").json()["shares"]) == 1
+    assert client.post("/api/v1/shares/link", json={"path": path}).status_code == 410
+    assert not store.authorize_file(path, token)
diff --git a/tests/web/test_bulk_actions.py b/tests/web/test_bulk_actions.py
new file mode 100644
index 00000000..eee1f21a
--- /dev/null
+++ b/tests/web/test_bulk_actions.py
@@ -0,0 +1,180 @@
+"""Bulk owner actions either commit complete metadata or leave it unchanged."""
+
+import sqlite3
+from contextlib import closing
+
+import pytest
+
+from tests.support.app_fixtures import app_client as app_client
+from tests.support.app_fixtures import login
+
+
+def test_move_rolls_back_earlier_item_when_later_path_is_missing(app_client):
+    client, store, _, _ = app_client
+    item = store.add_file("/", "original.txt", 9101, 4)
+    destination = store.create_folder("/", "Destination")
+    snapshot = store.export()
+    login(client)
+
+    response = client.post(
+        "/api/v1/nodes/move",
+        json={
+            "paths": ["/" + item["id"], "/" + "missing" * 8],
+            "destination": "/" + destination["id"],
+        },
+    )
+
+    assert response.status_code == 404
+    assert store.export() == snapshot
+    assert store.get_file("/" + item["id"])["name"] == "original.txt"
+
+
+def test_trash_rollback_restores_shares_and_revision(app_client):
+    client, store, _, _ = app_client
+    item = store.add_file("/", "shared.txt", 9102, 4)
+    path = "/" + item["id"]
+    token = store.create_share(path)
+    snapshot = store.export()
+    login(client)
+
+    response = client.post(
+        "/api/v1/nodes/bulk",
+        json={"paths": [path, "/" + "missing" * 8], "action": "trash"},
+    )
+
+    assert response.status_code == 404
+    assert store.export() == snapshot
+    assert store.authorize_file(path, token)
+
+
+def test_restore_rollback_preserves_trash_names_and_shares(app_client):
+    client, store, _, _ = app_client
+    first = store.add_file("/", "same.txt", 9103, 4)
+    first_path = "/" + first["id"]
+    store.set_trashed(first_path, True)
+    store.add_file("/", "same.txt", 9104, 5)
+    parent = store.create_folder("/", "Parent")
+    parent_path = "/" + parent["id"]
+    child = store.add_file(parent_path, "child.txt", 9105, 6)
+    child_path = parent_path + "/" + child["id"]
+    store.set_trashed(child_path, True)
+    store.set_trashed(parent_path, True)
+    snapshot = store.export()
+    login(client)
+
+    response = client.post(
+        "/api/v1/nodes/bulk",
+        json={"paths": [first_path, child_path], "action": "restore"},
+    )
+
+    assert response.status_code == 404
+    assert store.export() == snapshot
+    assert store.list_trash()[first["id"]]["name"] == "same.txt"
+
+
+@pytest.mark.parametrize("action", ["move", "trash", "restore"])
+def test_sqlite_failure_cannot_commit_only_part_of_metadata_batch(app_client, action):
+    client, store, _, _ = app_client
+    first = store.add_file("/", "first.txt", 9106, 4)
+    second = store.add_file("/", "second.txt", 9107, 5)
+    destination = store.create_folder("/", "Destination")
+    paths = ["/" + first["id"], "/" + second["id"]]
+    if action == "restore":
+        for path in paths:
+            store.set_trashed(path, True)
+    snapshot = store.export()
+    with closing(sqlite3.connect(store.database_path)) as db:
+        db.execute(
+            f"""CREATE TRIGGER fail_second_bulk_item BEFORE UPDATE ON nodes
+            WHEN OLD.id='{second["id"]}'
+            BEGIN SELECT RAISE(ABORT,'simulated bulk storage failure'); END"""
+        )
+        db.commit()
+    login(client)
+
+    if action == "move":
+        response = client.post(
+            "/api/v1/nodes/move",
+            json={"paths": paths, "destination": "/" + destination["id"]},
+        )
+    else:
+        response = client.post(
+            "/api/v1/nodes/bulk", json={"paths": paths, "action": action}
+        )
+
+    assert response.status_code == 500
+    assert store.export() == snapshot
+
+
+@pytest.mark.parametrize("action", ["trash", "restore", "move"])
+def test_complete_metadata_batch_preserves_every_selected_identity(app_client, action):
+    client, store, _, _ = app_client
+    first = store.add_file("/", "first.txt", 9108, 4)
+    second = store.add_file("/", "second.txt", 9109, 5)
+    destination = store.create_folder("/", "Destination")
+    paths = ["/" + first["id"], "/" + second["id"]]
+    if action == "restore":
+        for path in paths:
+            store.set_trashed(path, True)
+    login(client)
+
+    if action == "move":
+        response = client.post(
+            "/api/v1/nodes/move",
+            json={"paths": paths, "destination": "/" + destination["id"]},
+        )
+        actual = store.list_directory("/" + destination["id"])
+    else:
+        response = client.post(
+            "/api/v1/nodes/bulk", json={"paths": paths, "action": action}
+        )
+        actual = store.list_trash() if action == "trash" else store.list_directory("/")
+
+    assert response.status_code == 200
+    assert [item["path"] for item in response.json()["results"]] == paths
+    assert {first["id"], second["id"]} <= set(actual)
+    parent = "/" + destination["id"] if action == "move" else ""
+    assert store.message_ids(parent + "/" + first["id"], include_trashed=True) == [9108]
+    assert store.message_ids(parent + "/" + second["id"], include_trashed=True) == [
+        9109
+    ]
+
+
+def test_invalid_delete_selection_does_not_start_earlier_valid_item(app_client):
+    client, store, runtime, _ = app_client
+    item = store.add_file("/", "trashed.txt", 9110, 4)
+    path = "/" + item["id"]
+    store.set_trashed(path, True)
+    snapshot = store.export()
+    login(client)
+
+    response = client.post(
+        "/api/v1/nodes/bulk",
+        json={"paths": [path, "/" + "missing" * 8], "action": "delete"},
+    )
+
+    assert response.status_code == 404
+    assert store.export() == snapshot
+    assert runtime.transfers.registry.list() == []
+    assert runtime.transfers.deleted_messages == []
+    assert store.pending_deletions() == []
+
+
+def test_delete_selection_preflights_trash_policy_before_creating_jobs(app_client):
+    client, store, runtime, _ = app_client
+    trashed = store.add_file("/", "trashed.txt", 9111, 4)
+    visible = store.add_file("/", "visible.txt", 9112, 4)
+    path = "/" + trashed["id"]
+    store.set_trashed(path, True)
+    snapshot = store.export()
+    login(client)
+
+    response = client.post(
+        "/api/v1/nodes/bulk",
+        json={"paths": [path, "/" + visible["id"]], "action": "delete"},
+    )
+
+    assert response.status_code == 404
+    assert store.export() == snapshot
+    assert runtime.transfers.registry.list() == []
+    assert store.pending_deletions() == []
diff --git a/tests/web/test_demo_admin_auth.py b/tests/web/test_demo_admin_auth.py
new file mode 100644
index 00000000..6c51a093
--- /dev/null
+++ b/tests/web/test_demo_admin_auth.py
@@ -0,0 +1,318 @@
+"""Demo visitor and administrator sessions have independent signed authority."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+from contextlib import contextmanager
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from argon2 import PasswordHasher
+from fastapi.testclient import TestClient
+from pydantic import ValidationError
+
+from tests.core.test_config import settings_values
+from tests.support.app_fixtures import FakeRuntime, make_settings
+from tests.support.mongo_fixtures import FakeMongoBackend, register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.core.security import (
+    SESSION_COOKIE,
+    InvalidSession,
+    SessionManager,
+    credential_session_key,
+    demo_admin_session_key,
+)
+from tgdrive.storage.mongo import bootstrap_values
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+VISITOR = "correct horse battery staple"
+ADMIN = "private demonstration administrator password"
+ORIGIN = {"Origin": "https://testserver"}
+
+
+@contextmanager
+def auth_client(tmp_path, **overrides):
+    values = make_settings(tmp_path).model_dump(by_alias=True)
+    values.update(DEMO_MODE=True, DEMO_ADMIN_PASSWORD=ADMIN)
+    values.update(overrides)
+    settings = Settings(_env_file=None, **values)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.replica = SimpleNamespace(
+        blocked=False,
+        recovery_kit=Mock(return_value={"key": "synthetic offline recovery key"}),
+    )
+    try:
+        with pytest.MonkeyPatch.context() as monkeypatch:
+            register_test_backend(monkeypatch, settings, runtime.mongo)
+            with TestClient(
+                create_app(settings, runtime=runtime), base_url="https://testserver"
+            ) as client:
+                yield client, settings, runtime
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
+
+
+def sign_in(client, password, **extra):
+    return client.post("/api/checkPassword", json={"pass": password, **extra})
+
+
+@pytest.mark.parametrize("password,privileged", [(VISITOR, False), (ADMIN, True)])
+def test_same_login_form_grants_only_the_passwords_signed_access(
+    tmp_path, password, privileged, monkeypatch
+):
+    preference_save = AsyncMock(return_value={"uploads_per_bot": 2})
+    monkeypatch.setattr(
+        "tgdrive.settings.management_api.get_transfer_preferences",
+        lambda *_args: SimpleNamespace(save=preference_save),
+    )
+    with auth_client(tmp_path) as (client, settings, runtime):
+        assert sign_in(client, password, demo_admin=True).status_code == 200
+        token = client.cookies.get(SESSION_COOKIE)
+        assert (
+            client.app.state.sessions.verify(token).get("demo_admin", False)
+            is privileged
+        )
+        config = client.get("/api/config")
+        session = client.get("/api/v1/session")
+        for response in (config, session):
+            assert response.headers["cache-control"] == "no-store"
+            assert response.json()["demo_mode"] is True
+            assert response.json()["demo_admin"] is privileged
+            assert response.json()["demo_read_only"] is not privileged
+            assert ADMIN not in response.text
+        assert session.json()["authenticated"] is True
+        saved = client.patch(
+            "/api/v1/settings/uploads", json={"uploads_per_bot": 2}, headers=ORIGIN
+        )
+        key = client.get("/api/v1/replica/key")
+        assert saved.status_code == (200 if privileged else 403)
+        assert key.status_code == (200 if privileged else 403)
+        assert preference_save.await_count == int(privileged)
+        assert runtime.replica.recovery_kit.call_count == int(privileged)
+        assert settings.demo_mode is True
+        assert client.post("/api/logout", json={}, headers=ORIGIN).status_code == 200
+        assert client.get("/api/v1/session").json() == {
+            "authenticated": False,
+            "demo_mode": True,
+            "demo_admin": False,
+            "demo_read_only": True,
+        }
+        with pytest.raises(InvalidSession, match="revoked"):
+            client.app.state.sessions.verify(token)
+
+
+def test_legacy_demo_without_second_password_remains_restricted(tmp_path):
+    with auth_client(tmp_path, DEMO_ADMIN_PASSWORD=None) as (client, _, _):
+        assert sign_in(client, ADMIN).status_code == 401
+        assert sign_in(client, VISITOR).status_code == 200
+        assert client.get("/api/config").json()["demo_read_only"] is True
+        assert client.get("/api/v1/replica/key").status_code == 403
+        with pytest.raises(ValueError, match="not configured"):
+            client.app.state.sessions.create(demo_admin=True)
+
+
+def test_second_password_is_inactive_outside_demo_deployments(tmp_path):
+    with auth_client(tmp_path, DEMO_MODE=False) as (client, _, _):
+        assert sign_in(client, ADMIN).status_code == 401
+        assert sign_in(client, VISITOR).status_code == 200
+        assert client.get("/api/v1/session").json() == {"authenticated": True}
+        config = client.get("/api/config").json()
+        assert config["demo_mode"] is False
+        assert config["demo_read_only"] is False
+        assert config["demo_admin"] is False
+        assert client.get("/api/v1/replica/key").status_code == 200
+
+
+@pytest.mark.parametrize("plaintext", [None, "unused private fallback password"])
+def test_demo_administrator_hash_takes_precedence_and_supports_login(
+    tmp_path, plaintext
+):
+    hashed = PasswordHasher().hash(ADMIN)
+    with auth_client(
+        tmp_path,
+        DEMO_ADMIN_PASSWORD=plaintext,
+        DEMO_ADMIN_PASSWORD_HASH=hashed,
+    ) as (client, _, _):
+        assert sign_in(client, "unused private fallback password").status_code == 401
+        assert sign_in(client, ADMIN).status_code == 200
+        assert client.get("/api/config").json()["demo_admin"] is True
+
+
+def test_invalid_login_uses_existing_shared_rate_limit(tmp_path):
+    with auth_client(tmp_path) as (client, _, _):
+        for _attempt in range(5):
+            assert sign_in(client, "invalid password").status_code == 401
+        limited = sign_in(client, ADMIN)
+        assert limited.status_code == 429
+        assert int(limited.headers["retry-after"]) > 0
+
+
+def test_ordinary_sessions_are_never_promoted_by_configuring_demo_admin(tmp_path):
+    owner_key = credential_session_key(b"s" * 32, VISITOR)
+    legacy = SessionManager(owner_key, 300)
+    token = legacy.create(now=1000)
+    current = SessionManager(
+        owner_key,
+        300,
+        demo_admin_key=demo_admin_session_key(b"s" * 32, ADMIN),
+    )
+    assert "demo_admin" not in current.verify(token, now=1001)
+    encoded, _signature = token.split(".")
+    payload = json.loads(base64.urlsafe_b64decode(encoded + "=" * (-len(encoded) % 4)))
+    payload["demo_admin"] = True
+    encoded = base64.urlsafe_b64encode(json.dumps(payload).encode()).rstrip(b"=")
+    signature = base64.urlsafe_b64encode(
+        hmac.new(owner_key, encoded, hashlib.sha256).digest()
+    ).rstrip(b"=")
+    forged = (encoded + b"." + signature).decode()
+    with pytest.raises(InvalidSession, match="signature"):
+        current.verify(forged, now=1001)
+
+
+def test_demo_admin_rotation_or_removal_does_not_revoke_ordinary_sessions(monkeypatch):
+    monkeypatch.setattr("tgdrive.core.security.time.time", lambda: 1000)
+    key = credential_session_key(b"s" * 32, VISITOR)
+    backend = FakeMongoBackend()
+    original = SessionManager(
+        key,
+        300,
+        mongo_backend=backend,
+        demo_admin_key=demo_admin_session_key(b"s" * 32, ADMIN),
+    )
+    visitor = original.create(now=1000)
+    elevated = original.create(now=1000, demo_admin=True)
+    original.close()
+    for credential in (ADMIN, "rotated private administrator password", None):
+        current = SessionManager(
+            key,
+            300,
+            mongo_backend=backend,
+            demo_admin_key=(
+                demo_admin_session_key(b"s" * 32, credential) if credential else None
+            ),
+        )
+        try:
+            assert "demo_admin" not in current.verify(visitor, now=1001)
+            if credential == ADMIN:
+                assert current.verify(elevated, now=1001)["demo_admin"] is True
+            else:
+                with pytest.raises(InvalidSession):
+                    current.verify(elevated, now=1001)
+        finally:
+            current.close()
+
+
+def test_unsigned_deeply_nested_session_payload_is_rejected_before_decoding():
+    manager = SessionManager(b"s" * 32, 300, demo_admin_key=b"d" * 32)
+    encoded = base64.urlsafe_b64encode(b"[" * 2000 + b"0" + b"]" * 2000)
+    with pytest.raises(InvalidSession, match="signature"):
+        manager.verify(encoded.decode() + ".invalid-signature")
+
+
+@pytest.mark.parametrize("value", [None, "", "   "])
+def test_blank_optional_demo_administrator_credentials_are_absent(value):
+    settings = Settings(
+        _env_file=None,
+        **settings_values(DEMO_ADMIN_PASSWORD=value, DEMO_ADMIN_PASSWORD_HASH=value),
+    )
+    assert settings.demo_admin_password is None
+    assert settings.demo_admin_password_hash is None
+
+
+@pytest.mark.parametrize("value", ["short", "<replace-with-password>"])
+def test_demo_administrator_password_rejects_unsafe_values_without_echo(value):
+    with pytest.raises(ValidationError) as caught:
+        Settings(_env_file=None, **settings_values(DEMO_ADMIN_PASSWORD=value))
+    assert value not in str(caught.value)
+
+
+@pytest.mark.parametrize("variant", ["malformed", "weak", "excessive", "argon2i"])
+def test_demo_administrator_hash_uses_the_owner_security_limits(variant):
+    value = PasswordHasher().hash(ADMIN)
+    value = {
+        "malformed": "not-a-password-hash",
+        "weak": value.replace("m=65536,t=3,p=4", "m=19455,t=1,p=4"),
+        "excessive": value.replace("m=65536,t=3,p=4", "m=262145,t=3,p=4"),
+        "argon2i": value.replace("$argon2id$", "$argon2i$"),
+    }[variant]
+    with pytest.raises(ValidationError) as caught:
+        Settings(_env_file=None, **settings_values(DEMO_ADMIN_PASSWORD_HASH=value))
+    assert value not in str(caught.value)
+
+
+@pytest.mark.parametrize(
+    "hashed_owner,hashed_demo",
+    [(False, False), (True, False), (False, True), (True, True)],
+)
+def test_identical_effective_passwords_are_rejected_when_detectable(
+    hashed_owner, hashed_demo
+):
+    encoded = PasswordHasher().hash(VISITOR)
+    with pytest.raises(ValidationError, match="must differ"):
+        Settings(
+            _env_file=None,
+            **settings_values(
+                DEMO_MODE=True,
+                ADMIN_PASSWORD_HASH=encoded if hashed_owner else None,
+                DEMO_ADMIN_PASSWORD=None if hashed_demo else VISITOR,
+                DEMO_ADMIN_PASSWORD_HASH=encoded if hashed_demo else None,
+            ),
+        )
+
+
+def test_differently_salted_equal_passwords_resolve_to_restricted_access(tmp_path):
+    with auth_client(
+        tmp_path,
+        ADMIN_PASSWORD_HASH=PasswordHasher().hash(VISITOR),
+        DEMO_ADMIN_PASSWORD_HASH=PasswordHasher().hash(VISITOR),
+    ) as (client, _, _):
+        assert sign_in(client, VISITOR).status_code == 200
+        assert client.get("/api/config").json()["demo_read_only"] is True
+
+
+def test_demo_credentials_are_not_saved_or_restored_as_mongo_bootstrap(
+    tmp_path, monkeypatch
+):
+    encoded = PasswordHasher().hash(ADMIN)
+    settings = Settings(
+        _env_file=None,
+        **settings_values(DEMO_ADMIN_PASSWORD=ADMIN, DEMO_ADMIN_PASSWORD_HASH=encoded),
+    )
+    collection = Mock()
+    saved = bootstrap_values(settings)
+    assert "DEMO_ADMIN_PASSWORD" not in saved
+    assert "DEMO_ADMIN_PASSWORD_HASH" not in saved
+    bootstrap = settings_values(
+        DEMO_ADMIN_PASSWORD=ADMIN, DEMO_ADMIN_PASSWORD_HASH=encoded, DEMO_MODE=True
+    )
+    for key in (*bootstrap, "ADMIN_PASSWORD_HASH"):
+        monkeypatch.delenv(key, raising=False)
+    monkeypatch.setenv("MONGODB_URI", "mongodb://synthetic.invalid")
+    monkeypatch.setenv("DATA_DIR", str(tmp_path))
+    monkeypatch.setenv("TGDRIVE_AUTO_SECRETS", "false")
+    collection.find_one.return_value = {"document": bootstrap}
+    monkeypatch.setattr(
+        "tgdrive.storage.mongo.configure",
+        lambda *_args: SimpleNamespace(db=SimpleNamespace(settings=collection)),
+    )
+    monkeypatch.setattr(
+        "tgdrive.settings.managed_settings.read_document", lambda _dir: None
+    )
+    restored = Settings(_env_file=None)
+    assert restored.demo_mode is False
+    assert restored.demo_admin_password is None
+    assert restored.demo_admin_password_hash is None
+    assert restored.api_id == bootstrap["API_ID"]
+
+
+def test_demo_credentials_survive_validated_settings_copy_for_replica_startup():
+    original = Settings(_env_file=None, **settings_values(DEMO_ADMIN_PASSWORD=ADMIN))
+    copied = Settings(_env_file=None, **original.model_dump(by_alias=True))
+    assert copied.demo_admin_password == original.demo_admin_password
diff --git a/tests/web/test_demo_files.py b/tests/web/test_demo_files.py
new file mode 100644
index 00000000..13726431
--- /dev/null
+++ b/tests/web/test_demo_files.py
@@ -0,0 +1,478 @@
+"""Demo content stays readable while its stable catalog subtree rejects writes."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import threading
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi.responses import Response
+
+from tests.storage.test_mongodb import backend as mongo_backend_fixture
+from tests.support.mongo_fixtures import FakeMongoBackend
+from tests.web.test_demo_admin_auth import ADMIN, ORIGIN, VISITOR, auth_client, sign_in
+from tgdrive.core.errors import DuplicateNameError
+from tgdrive.storage.demo_files import (
+    DEMO_FILES_ID,
+    DEMO_FILES_NAME,
+    DemoFilesReadOnly,
+    write_policy,
+)
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.storage.store import ROOT_ID, DriveStore
+from tgdrive.transfers.tasks import TransferRegistry, TransferStatus
+from tgdrive.web.share_links import token_factory
+
+DEMO = "/" + DEMO_FILES_ID
+backend = mongo_backend_fixture
+
+
+def path(item):
+    return item["path"].rstrip("/") + "/" + item["id"]
+
+
+@pytest.fixture(
+    params=[
+        "sqlite",
+        "mongo-cache",
+        pytest.param(
+            "mongo-live",
+            marks=pytest.mark.skipif(
+                os.environ.get("TGDRIVE_MONGO_TESTS") != "1",
+                reason="Set TGDRIVE_MONGO_TESTS=1 for isolated MongoDB parity",
+            ),
+        ),
+    ]
+)
+def catalog(tmp_path, request):
+    if request.param == "sqlite":
+        store = DriveStore.create(tmp_path / "catalog.sqlite3")
+    elif request.param == "mongo-live":
+        store = MongoStore.create(request.getfixturevalue("backend"))
+    else:
+        # Exercise MongoStore's actual domain methods and copy-on-write transactions;
+        # this cache fixture does not claim to validate MongoDB server persistence.
+        store = object.__new__(MongoStore)
+        store._lock = threading.RLock()
+        store._local = threading.local()
+        store._closed = False
+        store.backend = SimpleNamespace(check_owner=lambda: None)
+        store._committed = {
+            "metadata": {"revision": 1, "backed_up_revision": 1, "generation": 0},
+            "nodes": {ROOT_ID: store._node(ROOT_ID, None, "/", "folder")},
+            "shares": {},
+            "operations": {},
+            "deletions": {},
+            "preparations": {},
+        }
+        store._commit = lambda _before: None
+    try:
+        yield store
+    finally:
+        store.close()
+
+
+def test_demo_folder_created_once_and_identity_survives_owner_changes(catalog):
+    first = catalog.ensure_demo_files()
+    revision = catalog.revision
+    assert first["id"] == DEMO_FILES_ID and first["name"] == DEMO_FILES_NAME
+    assert catalog.ensure_demo_files() == first
+    assert catalog.revision == revision
+    parent = catalog.create_folder("/", "Owner container")
+    catalog.rename(DEMO, "Owner sample library")
+    catalog.move(DEMO, path(parent))
+    current = catalog.ensure_demo_files()
+    assert current["id"] == DEMO_FILES_ID
+    assert current["name"] == "Owner sample library"
+    assert current["path"] == path(parent)
+    with write_policy(True), pytest.raises(DemoFilesReadOnly):
+        catalog.create_folder(catalog.resolve_id(DEMO_FILES_ID), "Guest change")
+    with write_policy(True), pytest.raises(DemoFilesReadOnly):
+        catalog.rename(path(parent), "Guest container")
+
+
+@pytest.mark.parametrize("existing_type", ["folder", "file"])
+def test_demo_folder_name_conflict_preserves_existing_content(catalog, existing_type):
+    if existing_type == "folder":
+        original = catalog.create_folder("/", DEMO_FILES_NAME)
+    else:
+        original = catalog.add_file("/", DEMO_FILES_NAME, 333, 3)
+    revision = catalog.revision
+    before = catalog.list_directory("/")
+    with pytest.raises(DuplicateNameError, match="Disable demo mode"):
+        catalog.ensure_demo_files()
+    assert catalog.revision == revision
+    assert catalog.list_directory("/") == before
+    assert original["id"] in before
+
+
+@pytest.mark.parametrize(
+    "action",
+    ["add", "rename", "trash", "star", "share", "revoke", "move-out", "move-in"],
+)
+def test_catalog_enforces_demo_policy_inside_mutation_transaction(catalog, action):
+    catalog.ensure_demo_files()
+    sample = catalog.add_file(DEMO, "sample.txt", 333, 3)
+    sample_path = path(sample)
+    outside = catalog.create_folder("/", "Visitor folder")
+    share = catalog.create_share(sample_path)
+    share_id = catalog.list_shares(sample_path)[0]["id"]
+    revision = catalog.revision
+    operations = {
+        "add": lambda: catalog.add_file(DEMO, "changed.txt", 334, 4),
+        "rename": lambda: catalog.rename(sample_path, "changed.txt"),
+        "trash": lambda: catalog.set_trashed(sample_path, True),
+        "star": lambda: catalog.set_starred(sample_path, True),
+        "share": lambda: catalog.create_share(sample_path),
+        "revoke": lambda: catalog.revoke_share(share_id),
+        "move-out": lambda: catalog.move(sample_path, "/"),
+        "move-in": lambda: catalog.move(path(outside), DEMO),
+    }
+    with write_policy(True), pytest.raises(DemoFilesReadOnly):
+        operations[action]()
+    assert catalog.revision == revision
+    assert catalog.get_file(sample_path)["name"] == "sample.txt"
+    assert catalog.authorize_file(sample_path, share)
+    with write_policy(True):
+        catalog.create_folder("/", "Guest can write outside")
+
+
+def test_demo_deletion_checks_existing_intents_and_final_commit(catalog):
+    catalog.ensure_demo_files()
+    item = catalog.add_file(DEMO, "owner-trash.txt", 333, 3)
+    catalog.set_trashed(path(item), True)
+    intent = catalog.begin_deletion(path(item), channel_id=-1001234567890)
+    revision = catalog.revision
+    with write_policy(True):
+        for operation in (
+            lambda: catalog.validate_deletion(path(item)),
+            lambda: catalog.begin_deletion(path(item), channel_id=-1001234567890),
+            lambda: catalog.finish_deletion(intent["id"]),
+        ):
+            with pytest.raises(DemoFilesReadOnly):
+                operation()
+    assert catalog.revision == revision
+    catalog.finish_deletion(intent["id"])
+    assert catalog.get_directory(DEMO)["contents"] == {}
+
+
+def test_full_owner_can_delete_and_recreate_reserved_folder(catalog):
+    catalog.ensure_demo_files()
+    catalog.add_file(DEMO, "disposable.txt", 333, 3)
+    catalog.set_trashed(DEMO, True)
+    intent = catalog.begin_deletion(DEMO, channel_id=-1001234567890)
+    catalog.finish_deletion(intent["id"])
+    recreated = catalog.ensure_demo_files()
+    assert recreated["id"] == DEMO_FILES_ID
+    assert recreated["path"] == "/" and recreated["name"] == DEMO_FILES_NAME
+    assert catalog.list_directory(DEMO) == {}
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("demo_mode", [False, True])
+async def test_restored_guest_job_checks_final_commit_after_owner_moves_parent(
+    catalog, demo_mode
+):
+    catalog.ensure_demo_files()
+    parent = catalog.create_folder("/", "Started outside demo")
+    jobs = FakeMongoBackend()
+    registry = TransferRegistry(mongo=jobs.db.jobs, mongo_backend=jobs, demo_mode=True)
+    with write_policy(True):
+        record = await registry.create("uploading", total=3)
+    registry.close()
+    registry = TransferRegistry(
+        mongo=jobs.db.jobs, mongo_backend=jobs, demo_mode=demo_mode
+    )
+    record = registry.get(record.id)
+    entered, resume = asyncio.Event(), asyncio.Event()
+
+    async def commit(item):
+        entered.set()
+        await resume.wait()
+        destination = catalog.resolve_id(parent["id"])
+        await asyncio.to_thread(catalog.add_file, destination, "late.txt", 333, 3)
+        await registry.update(item.id, status=TransferStatus.COMPLETED)
+
+    try:
+        task = registry.spawn(record.id, commit)
+        await entered.wait()
+        catalog.move(path(parent), DEMO)
+        resume.set()
+        await task
+        assert record.status == (
+            TransferStatus.ERROR if demo_mode else TransferStatus.COMPLETED
+        )
+        assert len(catalog.list_directory(catalog.resolve_id(parent["id"]))) == int(
+            not demo_mode
+        )
+    finally:
+        resume.set()
+        await registry.shutdown()
+        registry.close()
+
+
+@pytest.fixture
+def visitor(tmp_path):
+    with auth_client(tmp_path) as (client, settings, runtime):
+        store = runtime.store
+        child = store.create_folder(DEMO, "Nested samples")
+        sample = store.add_file(path(child), "sample.txt", 333, 3)
+        outside = store.create_folder("/", "Visitor files")
+        store.create_share(path(sample), token_factory=token_factory(settings))
+        share_id = store.list_shares(path(sample))[0]["id"]
+        runtime.transfers.inspect_remote = AsyncMock()
+        assert sign_in(client, VISITOR).status_code == 200
+        try:
+            yield client, store, runtime, child, sample, outside, share_id
+        finally:
+            if hasattr(runtime.transfers, "uploads"):
+                runtime.transfers.uploads.close()
+
+
+@pytest.mark.parametrize(
+    "action",
+    [
+        "folder",
+        "rename",
+        "trash",
+        "delete",
+        "share-file",
+        "share-folder",
+        "share-new",
+        "share-update",
+        "share-revoke",
+        "share-revoke-path",
+        "download-link",
+        "star",
+        "folder-tree",
+        "upload-receipt",
+        "remote",
+        "move-in",
+        "move-out",
+        "bulk-trash",
+        "bulk-restore",
+        "bulk-delete",
+        "root-share",
+    ],
+)
+def test_direct_visitor_mutations_reject_before_catalog_or_job_changes(visitor, action):
+    client, store, runtime, child, sample, outside, share_id = visitor
+    sample_path, child_path, outside_path = path(sample), path(child), path(outside)
+    requests = {
+        "folder": ("POST", "/api/createNewFolder", {"path": child_path, "name": "No"}),
+        "rename": ("POST", "/api/renameFileFolder", {"path": DEMO, "name": "No"}),
+        "trash": ("POST", "/api/trashFileFolder", {"path": child_path, "trash": True}),
+        "delete": ("POST", "/api/deleteFileFolder", {"path": sample_path}),
+        "share-file": ("POST", "/api/getFileShareAuth", {"path": sample_path}),
+        "share-folder": ("POST", "/api/getFolderShareAuth", {"path": DEMO}),
+        "share-new": ("POST", "/api/v1/shares", {"path": sample_path}),
+        "share-update": (
+            "PATCH",
+            "/api/v1/shares",
+            {"share_id": share_id, "label": "No"},
+        ),
+        "share-revoke": ("DELETE", "/api/v1/shares", {"share_id": share_id}),
+        "share-revoke-path": ("DELETE", "/api/v1/shares", {"path": sample_path}),
+        "download-link": ("POST", "/api/v1/download-links", {"path": sample_path}),
+        "star": ("PATCH", "/api/v1/starred", {"path": sample_path, "starred": True}),
+        "folder-tree": (
+            "POST",
+            "/api/v1/folders/tree",
+            {
+                "destination": child_path,
+                "root_name": "No",
+                "folders": [["Nested"]],
+                "client_request_id": "forbidden-demo-folder-tree",
+            },
+        ),
+        "upload-receipt": (
+            "POST",
+            "/api/v1/uploads",
+            {"parent_id": child_path, "name": "No.txt", "total_size": 3},
+        ),
+        "remote": (
+            "POST",
+            "/api/startFileDownloadFromUrl",
+            {
+                "path": child_path,
+                "url": "https://example.com/no.bin",
+                "client_request_id": "forbidden-demo-url-upload",
+            },
+        ),
+        "move-in": (
+            "POST",
+            "/api/v1/nodes/move",
+            {"paths": [outside_path], "destination": child_path},
+        ),
+        "move-out": (
+            "POST",
+            "/api/v1/nodes/move",
+            {"paths": [sample_path], "destination": "/"},
+        ),
+        "bulk-trash": (
+            "POST",
+            "/api/v1/nodes/bulk",
+            {"paths": [outside_path, DEMO], "action": "trash"},
+        ),
+        "bulk-restore": (
+            "POST",
+            "/api/v1/nodes/bulk",
+            {"paths": [sample_path], "action": "restore"},
+        ),
+        "bulk-delete": (
+            "POST",
+            "/api/v1/nodes/bulk",
+            {"paths": [sample_path], "action": "delete"},
+        ),
+        "root-share": ("POST", "/api/getFolderShareAuth", {"path": "/"}),
+    }
+    method, address, payload = requests[action]
+    before = store.export()
+    response = client.request(method, address, json=payload, headers=ORIGIN)
+    assert response.status_code == 403, response.text
+    assert response.json()["code"] == "DEMO_FILES_READ_ONLY"
+    assert store.export() == before
+    assert runtime.transfers.registry.list() == []
+    runtime.transfers.inspect_remote.assert_not_called()
+
+
+def test_browser_upload_is_rejected_before_transfer_or_request_claim(visitor):
+    client, store, runtime, child, *_ = visitor
+    revision = store.revision
+    response = client.post(
+        "/api/upload",
+        data={
+            "path": path(child),
+            "client_request_id": "forbidden-demo-browser-upload",
+        },
+        files={"file": ("no.txt", b"abc", "text/plain")},
+        headers=ORIGIN,
+    )
+    assert response.status_code == 403
+    assert response.json()["code"] == "DEMO_FILES_READ_ONLY"
+    assert store.revision == revision
+    assert runtime.transfers.registry.list() == []
+
+
+def test_demo_contents_stay_readable_and_full_password_can_modify(visitor, monkeypatch):
+    client, store, _, child, sample, _, share_id = visitor
+    root = client.post("/api/getDirectory", json={"path": "/"}).json()["data"]
+    assert root["contents"][DEMO_FILES_ID]["read_only"]
+    assert root["contents"][DEMO_FILES_ID]["demo_files"]
+    directory = client.post("/api/getDirectory", json={"path": path(child)}).json()[
+        "data"
+    ]
+    assert directory["read_only"] and directory["contents"][sample["id"]]["read_only"]
+    assert client.get("/api/v1/search", params={"q": "sample"}).json()["items"][0][
+        "read_only"
+    ]
+    assert (
+        client.post("/api/v1/shares/link", json={"share_id": share_id}).status_code
+        == 200
+    )
+
+    async def original(**_kwargs):
+        return Response(b"abc", media_type="text/plain")
+
+    monkeypatch.setattr("tgdrive.web.app.stream_telegram_file", original)
+    download = client.get("/file", params={"path": path(sample), "download": True})
+    assert download.status_code == 200 and download.content == b"abc"
+    assert sign_in(client, ADMIN).status_code == 200
+    response = client.post(
+        "/api/createNewFolder",
+        json={"path": path(child), "name": "Owner changes"},
+        headers=ORIGIN,
+    )
+    assert response.status_code == 200
+    full_directory = client.post(
+        "/api/getDirectory", json={"path": path(child)}
+    ).json()["data"]
+    assert not full_directory.get("read_only", False)
+    assert any(
+        item["name"] == "Owner changes"
+        for item in store.list_directory(path(child)).values()
+    )
+
+
+@pytest.mark.parametrize("operation", ["append", "complete", "cancel"])
+def test_existing_full_access_upload_receipt_cannot_be_mutated_after_downgrade(
+    visitor, operation
+):
+    client, _, runtime, child, *_ = visitor
+    assert sign_in(client, ADMIN).status_code == 200
+    created = client.post(
+        "/api/v1/uploads",
+        json={"parent_id": path(child), "name": "owner.txt", "total_size": 3},
+    )
+    assert created.status_code == 201
+    address = "/api/v1/uploads/" + created.json()["id"]
+    assert sign_in(client, VISITOR).status_code == 200
+    before = runtime.transfers.uploads.get_unchecked(created.json()["id"])
+    if operation == "append":
+        response = client.patch(
+            address,
+            content=b"abc",
+            headers=ORIGIN
+            | {"Content-Type": "application/octet-stream", "Upload-Offset": "0"},
+        )
+    else:
+        response = client.post(address + "/" + operation, json={}, headers=ORIGIN)
+    assert response.status_code == 403
+    assert response.json()["code"] == "DEMO_FILES_READ_ONLY"
+    assert runtime.transfers.uploads.get_unchecked(created.json()["id"]) == before
+    assert client.get(address).status_code == 200
+    assert client.head(address).headers["upload-offset"] == "0"
+
+
+def test_owner_moving_upload_destination_into_demo_cannot_bypass_receipt_binding(
+    visitor,
+):
+    client, store, _, _, _, outside, _ = visitor
+    created = client.post(
+        "/api/v1/uploads",
+        json={"parent_id": path(outside), "name": "visitor.txt", "total_size": 3},
+    )
+    assert created.status_code == 201
+    store.move(path(outside), DEMO)
+    address = "/api/v1/uploads/" + created.json()["id"]
+    response = client.patch(
+        address,
+        content=b"abc",
+        headers=ORIGIN
+        | {"Content-Type": "application/octet-stream", "Upload-Offset": "0"},
+    )
+    assert response.status_code == 403
+    assert response.json()["code"] == "DEMO_FILES_READ_ONLY"
+
+
+@pytest.mark.parametrize("operation", ["retry", "cancel", "legacy-cancel"])
+def test_full_jobs_into_demo_cannot_be_retried_or_cancelled_by_visitor(
+    visitor, operation
+):
+    client, _, runtime, child, *_ = visitor
+    record = client.portal.call(
+        lambda: runtime.transfers.registry.create("uploading", total=3)
+    )
+    record.context.update(
+        kind="remote", destination=path(child), destination_id=child["id"]
+    )
+    runtime.transfers.retry_job = lambda _identity: pytest.fail(
+        "Protected job was retried"
+    )
+    runtime.transfers.cancel_job = lambda _identity: pytest.fail(
+        "Protected job was cancelled"
+    )
+    if operation == "legacy-cancel":
+        response = client.post(
+            "/api/cancelUpload", json={"id": record.id}, headers=ORIGIN
+        )
+    else:
+        response = client.post(
+            f"/api/v1/jobs/{record.id}/{operation}", json={}, headers=ORIGIN
+        )
+    assert response.status_code == 403
+    assert response.json()["code"] == "DEMO_FILES_READ_ONLY"
+    assert not record.context.get("cancel_requested")
diff --git a/tests/web/test_demo_mode.py b/tests/web/test_demo_mode.py
new file mode 100644
index 00000000..f2b1e0d6
--- /dev/null
+++ b/tests/web/test_demo_mode.py
@@ -0,0 +1,447 @@
+"""Public demo keeps drive features usable while owner management is read-only."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from fastapi.testclient import TestClient
+from pydantic import SecretStr
+
+from tests.core.test_config import settings_values
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.storage.mongo import bootstrap_values
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+ORIGIN = {"Origin": "https://testserver"}
+TOKEN = "654321:" + "y" * 30
+CHALLENGE = "a" * 32
+MANAGEMENT_REQUESTS = [
+    ("POST", "/api/v1/settings/thumbnails/rebuild", {"confirmed": True}),
+    ("POST", "/api/v1/settings/thumbnails/rebuild/cancel", {}),
+    ("PATCH", "/api/v1/settings", {"expected_revision": 0, "api_id": 99999}),
+    ("PATCH", "/api/v1/settings/uploads", {"uploads_per_bot": 2}),
+    ("PATCH", "/api/v1/settings/performance", {"timezone": "UTC"}),
+    ("PATCH", "/api/v1/settings/bot-mode", {"folder_path": "/"}),
+    ("POST", "/api/v1/settings/refresh", {}),
+    (
+        "POST",
+        "/api/v1/settings/premium-login/start",
+        {"expected_revision": 0, "phone": "+15555550100", "label": "Demo account"},
+    ),
+    (
+        "POST",
+        "/api/v1/settings/premium-login/verify",
+        {"challenge_id": CHALLENGE, "code": "12345"},
+    ),
+    ("DELETE", "/api/v1/settings/premium-login/" + CHALLENGE, None),
+    (
+        "POST",
+        "/api/v1/replica/configure",
+        {"channel_id": -100222333444, "bot_token": TOKEN, "independent_accounts": True},
+    ),
+    *[
+        ("POST", "/api/v1/replica/action", {"action": action})
+        for action in ("pause", "resume", "disable", "retry", "sync")
+    ],
+    ("POST", "/api/v1/replica/recover", {"activate": True}),
+    (
+        "POST",
+        "/api/v1/replica/recover",
+        {"source_channel": -100222333444, "bot_token": TOKEN, "key": "b" * 64},
+    ),
+    (
+        "POST",
+        "/api/v1/replica/recover",
+        {
+            "target_channel": -100222333444,
+            "target_bot_token": TOKEN,
+            "confirm_channel": "-100222333444",
+        },
+    ),
+    ("POST", "/api/v1/backup", {}),
+    ("GET", "/api/v1/replica/key", None),
+    ("GET", "/api/v1/backup/recovery-key", None),
+]
+
+
+@contextmanager
+def owner_client(tmp_path, *, demo_mode=True, root_path=""):
+    settings = make_settings(tmp_path).model_copy(update={"demo_mode": demo_mode})
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    runtime.pool = SimpleNamespace(
+        status=AsyncMock(return_value=()),
+        health=AsyncMock(return_value=None),
+        set_uploads_per_bot=AsyncMock(),
+    )
+    runtime.preloads = SimpleNamespace(
+        reconfigure=AsyncMock(),
+        snapshot=AsyncMock(return_value={"jobs": [], "cache": {"files": []}}),
+        prepare=AsyncMock(return_value={"id": "demo-preload", "state": "queued"}),
+        cancel=AsyncMock(),
+        clear=AsyncMock(),
+    )
+    try:
+        with pytest.MonkeyPatch.context() as monkeypatch:
+            register_test_backend(monkeypatch, settings, runtime.mongo)
+            with TestClient(
+                create_app(settings, runtime=runtime),
+                base_url="https://testserver",
+                root_path=root_path,
+            ) as client:
+                yield client, store, runtime, settings
+    finally:
+        if hasattr(runtime.transfers, "uploads"):
+            runtime.transfers.uploads.close()
+        runtime.transfers.registry.close()
+        store.close()
+
+
+@pytest.fixture
+def demo_owner(tmp_path):
+    with owner_client(tmp_path) as owner:
+        yield owner
+
+
+def test_demo_mode_defaults_off_and_is_loaded_from_environment(monkeypatch):
+    monkeypatch.delenv("DEMO_MODE", raising=False)
+    assert Settings(_env_file=None, **settings_values()).demo_mode is False
+    monkeypatch.setenv("DEMO_MODE", "true")
+    assert Settings(_env_file=None, **settings_values()).demo_mode is True
+    monkeypatch.setenv("DEMO_MODE", "false")
+    assert Settings(_env_file=None, **settings_values()).demo_mode is False
+
+
+@pytest.mark.parametrize("demo_mode", [False, True])
+def test_public_config_reports_deployment_demo_mode(tmp_path, demo_mode):
+    with owner_client(tmp_path, demo_mode=demo_mode) as (client, _, _, _):
+        response = client.get("/api/config")
+        assert response.status_code == 200
+        assert response.json()["demo_mode"] is demo_mode
+        access = client.get("/api/v1/session").json()
+        assert access["authenticated"] is False
+        if demo_mode:
+            assert access["demo_read_only"] is True
+            assert access["demo_admin"] is False
+
+
+@pytest.mark.parametrize("method,path,payload", MANAGEMENT_REQUESTS)
+def test_demo_rejects_direct_management_requests_before_any_side_effect(
+    demo_owner, monkeypatch, method, path, payload
+):
+    client, store, runtime, settings = demo_owner
+    forbidden = Mock(side_effect=AssertionError("Management service must not run"))
+    for name in (
+        "get_connection_manager",
+        "get_bot_settings",
+        "get_transfer_preferences",
+    ):
+        monkeypatch.setattr("tgdrive.settings.management_api." + name, forbidden)
+    monkeypatch.setattr(
+        "tgdrive.observability.performance_api.get_performance_settings", forbidden
+    )
+    runtime.replica = SimpleNamespace(blocked=False, recovery_kit=forbidden)
+    runtime.backup = SimpleNamespace(ensure_revision=forbidden)
+    client.app.state.premium_login_service = SimpleNamespace(
+        begin=forbidden, verify=forbidden, cancel=forbidden, close=AsyncMock()
+    )
+    settings.mongodb_backup_key = SecretStr("b" * 64)
+    runtime.mongo = object()
+    login(client)
+    revision = store.revision
+
+    response = client.request(method, path, json=payload, headers=ORIGIN)
+
+    assert response.status_code == 403, response.text
+    assert response.json()["code"] == "DEMO_MODE_READ_ONLY"
+    assert "read-only" in response.json()["detail"]
+    assert "b" * 64 not in response.text
+    assert TOKEN not in response.text
+    forbidden.assert_not_called()
+    assert store.revision == revision
+    assert settings.demo_mode is True
+    for filename in (
+        "telegram-settings.json",
+        "transfer-preferences.json",
+        "performance-preferences.json",
+        "bot-preferences.json",
+        "channel-activation.json",
+    ):
+        assert not (settings.resolved_data_dir / filename).exists()
+
+
+@pytest.mark.parametrize(
+    "method,path,payload",
+    [
+        ("PATCH", "/api/v1/settings/uploads", {"uploads_per_bot": 2}),
+        ("GET", "/api/v1/replica/key", None),
+        ("GET", "/api/v1/backup/recovery-key", None),
+    ],
+)
+def test_demo_management_still_requires_authentication(
+    demo_owner, method, path, payload
+):
+    client, _, _, _ = demo_owner
+    assert client.request(method, path, json=payload, headers=ORIGIN).status_code == 401
+
+
+def test_demo_preserves_same_origin_protection(demo_owner):
+    client, store, _, _ = demo_owner
+    login(client)
+    contents = store.list_directory("/")
+    response = client.post(
+        "/api/createNewFolder",
+        json={"path": "/", "name": "Cross-origin"},
+        headers={"Origin": "https://other.example"},
+    )
+    assert response.status_code == 403
+    assert store.list_directory("/") == contents
+
+
+def test_demo_setting_cannot_be_changed_through_the_settings_api(demo_owner):
+    client, _, _, settings = demo_owner
+    login(client)
+    for payload in (
+        {"expected_revision": 0, "demo_mode": False},
+        {"expected_revision": 0, "DEMO_MODE": False},
+    ):
+        response = client.patch("/api/v1/settings", json=payload, headers=ORIGIN)
+        assert response.status_code == 403
+        assert response.json()["code"] == "DEMO_MODE_READ_ONLY"
+    assert settings.demo_mode is True
+    assert client.get("/api/config?demo_mode=false").json()["demo_mode"] is True
+
+
+@pytest.mark.parametrize(
+    "method,path,payload",
+    [
+        ("PATCH", "/demo/api/v1/settings/uploads", {"uploads_per_bot": 2}),
+        ("POST", "/demo/api/v1/replica/action", {"action": "sync"}),
+        ("POST", "/demo/api/v1/backup", {}),
+        ("GET", "/demo/api/v1/replica/key", None),
+        ("GET", "/demo/api/v1/backup/recovery-key", None),
+    ],
+)
+def test_demo_guard_uses_matched_route_under_proxy_root_path(
+    tmp_path, method, path, payload
+):
+    with owner_client(tmp_path, root_path="/demo") as (client, _, runtime, settings):
+        login(client)
+        runtime.replica = SimpleNamespace(blocked=False)
+        runtime.mongo = object()
+        settings.mongodb_backup_key = SecretStr("b" * 64)
+        response = client.request(method, path, json=payload, headers=ORIGIN)
+        assert response.status_code == 403, response.text
+        assert response.json()["code"] == "DEMO_MODE_READ_ONLY"
+        assert "b" * 64 not in response.text
+
+
+@pytest.mark.parametrize(
+    "path",
+    [
+        "/api/v1/settings/uploads/",
+        "/api/v1/%73ettings/uploads",
+        "/api/v1/settings%2Fuploads",
+    ],
+)
+def test_demo_guard_survives_redirects_and_encoded_management_paths(demo_owner, path):
+    client, _, runtime, _ = demo_owner
+    login(client)
+    response = client.patch(path, json={"uploads_per_bot": 2}, headers=ORIGIN)
+    assert response.status_code == 403, response.text
+    assert response.json()["code"] == "DEMO_MODE_READ_ONLY"
+    runtime.pool.set_uploads_per_bot.assert_not_called()
+
+
+def test_demo_keeps_settings_status_and_sanitized_reports_readable(demo_owner):
+    client, _, runtime, _ = demo_owner
+    runtime.replica = SimpleNamespace(
+        blocked=False, status=Mock(return_value={"enabled": False, "state": "disabled"})
+    )
+    login(client)
+    for path in (
+        "/api/v1/settings",
+        "/api/v1/settings/uploads",
+        "/api/v1/settings/performance",
+        "/api/v1/settings/bot-mode",
+        "/api/v1/status",
+        "/api/v1/performance",
+        "/api/v1/replica",
+        "/api/v1/replica/report",
+        "/api/v1/preloads",
+    ):
+        response = client.get(path)
+        assert response.status_code == 200, (path, response.text)
+        assert TOKEN not in response.text
+    assert client.get("/api/v1/settings/uploads").json()["uploads_per_bot"] == 1
+    assert (
+        client.get("/api/v1/settings/performance").json()["timezone"] == "Asia/Kolkata"
+    )
+
+
+def test_normal_deployment_can_still_change_preferences_and_back_up(tmp_path):
+    with owner_client(tmp_path, demo_mode=False) as (client, store, runtime, _):
+        login(client)
+        changed = client.patch(
+            "/api/v1/settings/uploads", json={"uploads_per_bot": 2}, headers=ORIGIN
+        )
+        assert changed.status_code == 200
+        assert changed.json()["uploads_per_bot"] == 2
+        runtime.pool.set_uploads_per_bot.assert_awaited_with(2)
+        runtime.backup = SimpleNamespace(
+            ensure_revision=AsyncMock(),
+            snapshot_now=AsyncMock(),
+            protection_status=Mock(return_value={"state": "protected"}),
+        )
+        response = client.post("/api/v1/backup", json={}, headers=ORIGIN)
+        assert response.status_code == 200
+        runtime.backup.snapshot_now.assert_awaited_once_with(store)
+        runtime.backup.ensure_revision.assert_not_awaited()
+
+
+def test_demo_allows_file_crud_uploads_shares_and_preload_actions(demo_owner):
+    client, store, runtime, _ = demo_owner
+    login(client)
+    created = client.post(
+        "/api/createNewFolder",
+        json={"path": "/", "name": "Demo folder"},
+        headers=ORIGIN,
+    )
+    assert created.status_code == 200
+    folder = next(
+        item
+        for item in store.list_directory("/").values()
+        if item["name"] == "Demo folder"
+    )
+    path = "/" + folder["id"]
+    assert (
+        client.post(
+            "/api/renameFileFolder",
+            json={"path": path, "name": "Renamed"},
+            headers=ORIGIN,
+        ).status_code
+        == 200
+    )
+    assert store.get_directory(path)["name"] == "Renamed"
+    share = client.post("/api/v1/shares", json={"path": path}, headers=ORIGIN)
+    assert share.status_code == 201
+    assert client.get("/api/v1/shares").json()["shares"][0]["name"] == "Renamed"
+    assert (
+        client.request(
+            "DELETE", "/api/v1/shares", json={"path": path}, headers=ORIGIN
+        ).status_code
+        == 200
+    )
+    uploaded = client.post(
+        "/api/upload",
+        data={"path": "/"},
+        files={"file": ("demo.txt", b"abc", "text/plain")},
+        headers=ORIGIN,
+    )
+    assert uploaded.status_code == 200
+    assert runtime.transfers.registry.get(uploaded.json()["id"]).total == 3
+    receipt = client.post(
+        "/api/v1/uploads",
+        json={"name": "resumable.txt", "parent_id": "/", "total_size": 3},
+        headers=ORIGIN,
+    )
+    assert receipt.status_code == 201
+    upload_path = "/api/v1/uploads/" + receipt.json()["id"]
+    chunk = client.patch(
+        upload_path,
+        content=b"abc",
+        headers=ORIGIN
+        | {"Content-Type": "application/octet-stream", "Upload-Offset": "0"},
+    )
+    assert chunk.status_code == 204
+    assert client.head(upload_path).headers["upload-offset"] == "3"
+    file = store.add_file("/", "preload.txt", 777, 3)
+    prepared = client.post(
+        "/api/v1/preloads", json={"path": "/" + file["id"]}, headers=ORIGIN
+    )
+    assert prepared.status_code == 202
+    runtime.preloads.prepare.assert_awaited_once()
+    assert (
+        client.post(
+            "/api/v1/preloads/demo-preload/cancel", json={}, headers=ORIGIN
+        ).status_code
+        == 200
+    )
+    runtime.preloads.cancel.assert_awaited_once_with("demo-preload")
+    assert (
+        client.post("/api/v1/preloads/clear", json={}, headers=ORIGIN).status_code
+        == 200
+    )
+    runtime.preloads.clear.assert_awaited_once_with(None)
+    for trash in (True, False, True):
+        assert (
+            client.post(
+                "/api/trashFileFolder",
+                json={"path": path, "trash": trash},
+                headers=ORIGIN,
+            ).status_code
+            == 200
+        )
+    deleted = client.post("/api/deleteFileFolder", json={"path": path}, headers=ORIGIN)
+    assert deleted.status_code == 202
+
+    async def finish_deletion():
+        await runtime.transfers.registry.get(deleted.json()["id"]).task
+
+    client.portal.call(finish_deletion)
+    assert folder["id"] not in store.list_directory("/")
+    assert client.post("/api/logout", json={}, headers=ORIGIN).status_code == 200
+    access = client.get("/api/v1/session").json()
+    assert access["authenticated"] is False
+    assert access["demo_read_only"] is True
+    assert access["demo_admin"] is False
+
+
+@pytest.mark.parametrize("demo_mode", [False, True])
+def test_mongo_bootstrap_never_saves_demo_policy(demo_mode):
+    settings = Settings(_env_file=None, **settings_values(DEMO_MODE=demo_mode))
+    document = bootstrap_values(settings)
+    assert "DEMO_MODE" not in document
+    assert document["API_ID"] == settings.api_id
+    assert document["API_HASH"] == settings.api_hash.get_secret_value()
+    assert document["SESSION_SECRET"] == settings.session_secret.get_secret_value()
+
+
+@pytest.mark.parametrize("saved_mode", [False, True])
+@pytest.mark.parametrize("env_mode", [None, "true", "false"])
+def test_legacy_mongo_bootstrap_cannot_supply_demo_policy(
+    tmp_path, monkeypatch, saved_mode, env_mode
+):
+    document = settings_values(DEMO_MODE=saved_mode)
+    for key in (*document, "ADMIN_PASSWORD_HASH"):
+        monkeypatch.delenv(key, raising=False)
+    monkeypatch.setenv("MONGODB_URI", "mongodb://synthetic.invalid")
+    monkeypatch.setenv("MONGODB_DATABASE", "demo_policy_test")
+    monkeypatch.setenv("DATA_DIR", str(tmp_path))
+    monkeypatch.setenv("TGDRIVE_AUTO_SECRETS", "false")
+    if env_mode is not None:
+        monkeypatch.setenv("DEMO_MODE", env_mode)
+    collection = Mock()
+    collection.find_one.return_value = {"document": document}
+    backend = SimpleNamespace(db=SimpleNamespace(settings=collection))
+    configure = Mock(return_value=backend)
+    monkeypatch.setattr("tgdrive.storage.mongo.configure", configure)
+    monkeypatch.setattr(
+        "tgdrive.settings.managed_settings.read_document", lambda _dir: None
+    )
+
+    settings = Settings(_env_file=None)
+
+    assert settings.demo_mode is (env_mode == "true")
+    assert settings.api_id == document["API_ID"]
+    assert settings.api_hash.get_secret_value() == document["API_HASH"]
+    assert settings.session_secret.get_secret_value() == document["SESSION_SECRET"]
+    configure.assert_called_once_with(
+        tmp_path, "mongodb://synthetic.invalid", "demo_policy_test"
+    )
diff --git a/tests/web/test_demo_task_policy.py b/tests/web/test_demo_task_policy.py
new file mode 100644
index 00000000..2e2378a6
--- /dev/null
+++ b/tests/web/test_demo_task_policy.py
@@ -0,0 +1,66 @@
+"""Restricted demo jobs retain their write policy when recovered or resumed."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from tests.support.mongo_fixtures import FakeMongoBackend
+from tgdrive.storage.demo_files import restricted_writes, write_policy
+from tgdrive.transfers.tasks import TransferRegistry
+
+
+@pytest.mark.parametrize("enabled", [False, True])
+async def test_durable_demo_job_restores_policy_using_current_deployment(enabled):
+    backend = FakeMongoBackend()
+    registry = TransferRegistry(
+        mongo=backend.db.jobs, mongo_backend=backend, demo_mode=True
+    )
+    try:
+        with write_policy(True):
+            record = await registry.create("queued")
+        identity = record.id
+        saved = backend.db.jobs.find_one({"_id": identity})["data"]
+        assert saved["context"]["demo_read_only"] is True
+    finally:
+        registry.close()
+
+    recovered = TransferRegistry(
+        mongo=backend.db.jobs, mongo_backend=backend, demo_mode=enabled
+    )
+    observed = []
+
+    async def work(_record):
+        observed.append(restricted_writes.get())
+        observed.append(await asyncio.to_thread(restricted_writes.get))
+
+    try:
+        assert restricted_writes.get() is False
+        await recovered.spawn(identity, work)
+        assert observed == [enabled, enabled]
+        assert restricted_writes.get() is False
+    finally:
+        recovered.close()
+
+
+async def test_trusted_job_does_not_inherit_an_unrelated_visitor_policy():
+    registry = TransferRegistry(demo_mode=True)
+    record = await registry.create("queued")
+    observed = []
+
+    async def work(_record):
+        observed.append(restricted_writes.get())
+
+    with write_policy(True):
+        await registry.spawn(record.id, work)
+        assert restricted_writes.get() is True
+    assert observed == [False]
+    assert "demo_read_only" not in record.context
+
+
+async def test_disabled_demo_mode_does_not_mark_new_jobs():
+    registry = TransferRegistry(demo_mode=False)
+    with write_policy(True):
+        record = await registry.create("queued")
+    assert "demo_read_only" not in record.context
diff --git a/tests/web/test_folder_tree.py b/tests/web/test_folder_tree.py
new file mode 100644
index 00000000..d6a2b0d8
--- /dev/null
+++ b/tests/web/test_folder_tree.py
@@ -0,0 +1,382 @@
+from __future__ import annotations
+
+import copy
+import sqlite3
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+
+import pytest
+from fastapi.testclient import TestClient
+
+import tgdrive.storage.store as store_module
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tgdrive.core.errors import (
+    CorruptStoreError,
+    DuplicateNameError,
+    InvalidNameError,
+    InvalidPathError,
+    NotDirectoryError,
+    PersistenceError,
+    TrashedItemError,
+    ValidationError,
+)
+from tgdrive.storage.store import DriveStore, FolderTreeConflictError
+from tgdrive.web.app import create_app
+
+
+def prepare(store, *, request_id=None, destination="/", root="Photos", folders=None):
+    return store.prepare_folder_tree(
+        destination, root, folders or [], request_id or str(uuid.uuid4())
+    )
+
+
+def test_atomic_tree_returns_opaque_paths_and_recovers_lost_response(tmp_path):
+    database = tmp_path / "drive.sqlite3"
+    store = DriveStore.create(database)
+    request_id = str(uuid.uuid4())
+    folders = [["2025", "Trips"], ["2025"], ["Personal"]]
+    before = store.revision
+    first = prepare(store, request_id=request_id, folders=folders)
+    root = first["root"]
+    assert root["name"] == "Photos"
+    assert root["path"] == "/"
+    assert first["folders"][""] == "/" + root["id"]
+    assert set(first["folders"]) == {"", "2025", "2025/Trips", "Personal"}
+    for relative, path in first["folders"].items():
+        node = store.get_directory(path)
+        assert node["name"] == (relative.rsplit("/", 1)[-1] if relative else "Photos")
+    assert store.revision == before + 1
+    store.close()
+    recovered = DriveStore.load(database)
+    assert prepare(recovered, request_id=request_id, folders=folders[::-1]) == first
+    assert recovered.revision == before + 1
+    # Caller mutations cannot corrupt the durable replay result.
+    first["folders"]["2025"] = "/not-a-real-path"
+    assert (
+        prepare(recovered, request_id=request_id, folders=folders)["folders"]["2025"]
+        != first["folders"]["2025"]
+    )
+    recovered.close()
+
+
+def test_fresh_root_keeps_both_without_merging_or_overwriting():
+    store = DriveStore.create()
+    original = store.create_folder("/", "PHOTOS")
+    original_path = "/" + original["id"]
+    store.create_folder(original_path, "Untouched")
+    first = prepare(store, folders=[["Nested"]])
+    second = prepare(store, folders=[["Nested"]])
+    assert first["root"]["name"] == "Photos (1)"
+    assert second["root"]["name"] == "Photos (2)"
+    assert first["folders"][""] != second["folders"][""] != original_path
+    assert len(store.get_directory(original_path)["contents"]) == 1
+    assert (
+        next(iter(store.get_directory(original_path)["contents"].values()))["name"]
+        == "Untouched"
+    )
+    store.close()
+
+
+@pytest.mark.parametrize(
+    "folders",
+    [
+        [[".."]],
+        [["."]],
+        [["bad/name"]],
+        [["bad\\name"]],
+        [["/absolute"]],
+        [["leading "]],
+        [["\x00"]],
+        [["line\nfeed"]],
+        [["\ud800"]],
+        [[]],
+        [["Missing", "Child"]],
+        [["Straße"], ["STRASSE"]],
+        [["Résumé"], ["RE\u0301SUME\u0301"]],
+        [["Same"], ["Same"]],
+        [["x"] * 64],
+    ],
+)
+def test_invalid_manifest_never_creates_partial_folders(folders):
+    store = DriveStore.create()
+    before = store.export()
+    with pytest.raises((ValidationError, InvalidNameError, DuplicateNameError)):
+        prepare(store, folders=folders)
+    assert store.export() == before
+    store.close()
+
+
+@pytest.mark.parametrize("destination", ["relative", "/../x", "/a//b", "/a\\b"])
+def test_invalid_destination_is_rejected_before_writing(destination):
+    store = DriveStore.create()
+    before = store.export()
+    with pytest.raises(InvalidPathError):
+        prepare(store, destination=destination)
+    assert store.export() == before
+    store.close()
+
+
+def test_unicode_is_normalized_and_order_does_not_change_request_identity():
+    store = DriveStore.create()
+    request_id = str(uuid.uuid4())
+    first = prepare(
+        store,
+        request_id=request_id,
+        root="Re\u0301sume\u0301",
+        folders=[["Re\u0301sume\u0301"]],
+    )
+    second = prepare(store, request_id=request_id, root="Résumé", folders=[["Résumé"]])
+    assert first == second
+    assert set(first["folders"]) == {"", "Résumé"}
+    # Percent escapes are literal names; they are never decoded into traversal.
+    literal = prepare(store, root="%2e%2e", folders=[["%2f"]])
+    assert store.get_directory(literal["folders"]["%2f"])["name"] == "%2f"
+    store.close()
+
+
+def test_folder_and_absolute_depth_bounds_are_enforced_atomically(monkeypatch):
+    store = DriveStore.create()
+    first = prepare(store, folders=[[str(n)] for n in range(999)])
+    assert len(first["folders"]) == 1000
+    before = store.export()
+    with pytest.raises(ValidationError, match="1000"):
+        prepare(store, folders=[[str(n)] for n in range(1000)])
+    assert store.export() == before
+    deep = [["x"] * n for n in range(1, 64)]
+    result = prepare(store, folders=deep)
+    assert len(result["folders"]) == 64
+    monkeypatch.setattr(store_module, "MAX_TREE_DEPTH", 3)
+    before = store.export()
+    with pytest.raises(ValidationError, match="depth"):
+        prepare(store, destination=result["folders"]["x"], folders=[["a"], ["a", "b"]])
+    assert store.export() == before
+    with monkeypatch.context() as limited:
+        limited.setattr(store_module, "MAX_TREE_ITEMS", 2)
+        with pytest.raises(ValidationError, match="item count"):
+            prepare(store)
+    assert store.export() == before
+    store.close()
+
+
+def test_database_failure_rolls_back_every_node_and_idempotency_record(monkeypatch):
+    store = DriveStore.create()
+    before = store.export()
+    original = store._import_folder_preparation
+
+    def fail_after_creation(db, record):
+        original(db, record)
+        raise sqlite3.OperationalError("injected commit failure")
+
+    monkeypatch.setattr(store, "_import_folder_preparation", fail_after_creation)
+    with pytest.raises(PersistenceError, match="injected"):
+        prepare(store, folders=[["Child"], ["Child", "Nested"]])
+    assert store.export() == before
+    store.close()
+
+
+def test_concurrent_duplicate_request_commits_once(tmp_path):
+    database = tmp_path / "drive.sqlite3"
+    first = DriveStore.create(database)
+    second = DriveStore.load(database)
+    request_id = str(uuid.uuid4())
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        calls = [
+            executor.submit(prepare, store, request_id=request_id, folders=[["Child"]])
+            for store in (first, second)
+        ]
+        results = [call.result() for call in calls]
+    assert results[0] == results[1]
+    assert len(first.get_directory("/")["contents"]) == 1
+    assert first.revision == 2
+    first.close()
+    second.close()
+
+
+def test_request_id_cannot_prepare_different_tree():
+    store = DriveStore.create()
+    request_id = str(uuid.uuid4())
+    prepare(store, request_id=request_id, folders=[["Child"]])
+    before = store.export()
+    with pytest.raises(FolderTreeConflictError, match="different"):
+        prepare(store, request_id=request_id, folders=[["Other"]])
+    assert store.export() == before
+    store.close()
+
+
+@pytest.mark.parametrize(
+    "change", ["move_root", "move_child", "rename", "trash", "delete", "deleting"]
+)
+def test_changed_tree_replay_fails_without_silent_recreation(change):
+    store = DriveStore.create()
+    request_id = str(uuid.uuid4())
+    tree = prepare(store, request_id=request_id, folders=[["Child"]])
+    root = tree["folders"][""]
+    child = tree["folders"]["Child"]
+    if change == "move_root":
+        other = store.create_folder("/", "Other")
+        store.move(root, "/" + other["id"])
+    elif change == "move_child":
+        store.move(child, "/")
+    elif change == "rename":
+        store.rename(child, "Changed")
+    elif change == "trash":
+        store.set_trashed(root, True)
+    elif change == "deleting":
+        store.set_trashed(root, True)
+        store.begin_deletion(root)
+    else:
+        store.delete(root)
+    before = store.export()
+    with pytest.raises(FolderTreeConflictError, match="changed"):
+        prepare(store, request_id=request_id, folders=[["Child"]])
+    assert store.export() == before
+    # Tombstone results remain valid metadata after nodes are removed.
+    restored = DriveStore._from_payload(store.export())
+    assert restored.export() == store.export()
+    with pytest.raises(FolderTreeConflictError, match="changed"):
+        prepare(restored, request_id=request_id, folders=[["Child"]])
+    restored.close()
+    store.close()
+
+
+def test_portable_checkpoint_retains_idempotent_preparation():
+    store = DriveStore.create()
+    request_id = str(uuid.uuid4())
+    tree = prepare(store, request_id=request_id, folders=[["Child"]])
+    restored = DriveStore._from_payload(store.export())
+    assert prepare(restored, request_id=request_id, folders=[["Child"]]) == tree
+    corrupt = copy.deepcopy(store.export())
+    corrupt["folder_preparations"][0]["result"]["folders"]["Child"] = tree["folders"][
+        ""
+    ]
+    with pytest.raises(CorruptStoreError, match="ancestry"):
+        DriveStore._from_payload(corrupt)
+    restored.close()
+    store.close()
+
+
+@pytest.fixture
+def client(tmp_path):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    runtime = FakeRuntime(store)
+    app = create_app(settings, runtime=runtime)
+    with TestClient(app, base_url="https://testserver") as http:
+        yield http, store
+    runtime.transfers.registry.close()
+    store.close()
+
+
+def payload(**overrides):
+    return {
+        "destination": "/",
+        "root_name": "Photos",
+        "folders": [["Child"]],
+        "client_request_id": str(uuid.uuid4()),
+        **overrides,
+    }
+
+
+def test_tree_route_auth_body_schema_replay_and_conflict(client):
+    http, store = client
+    request = payload()
+    assert http.post("/api/v1/folders/tree", json=request).status_code == 401
+    login(http)
+    first = http.post("/api/v1/folders/tree", json=request)
+    assert first.status_code == 201
+    assert http.post("/api/v1/folders/tree", json=request).json() == first.json()
+    conflict = http.post("/api/v1/folders/tree", json=request | {"root_name": "Other"})
+    assert conflict.status_code == 409
+    assert conflict.json()["code"] == "FOLDER_TREE_CONFLICT"
+    bad = http.post("/api/v1/folders/tree", json=payload(folders=[[".."]]))
+    assert bad.status_code == 400
+    for invalid in (
+        payload(folders="Child"),
+        payload(folders=[[]]),
+        payload(root_name=12),
+        payload(extra="ignored?"),
+    ):
+        assert http.post("/api/v1/folders/tree", json=invalid).status_code == 422
+    # Verbatim whitespace reaches store validation; the API must not strip it.
+    assert (
+        http.post(
+            "/api/v1/folders/tree", json=payload(root_name=" leading")
+        ).status_code
+        == 400
+    )
+    oversized = payload(folders=[[str(n) + "x" * 100] for n in range(999)])
+    assert http.post("/api/v1/folders/tree", json=oversized).status_code == 413
+    assert len(store.get_directory("/")["contents"]) == 1
+
+
+def test_tree_inherits_existing_folder_share_without_new_credentials(client):
+    http, store = client
+    parent = store.create_folder("/", "Shared")
+    destination = "/" + parent["id"]
+    token = store.create_share(destination)
+    login(http)
+    response = http.post("/api/v1/folders/tree", json=payload(destination=destination))
+    assert response.status_code == 201
+    child_path = response.json()["folders"]["Child"]
+    assert store.authorize_directory(child_path, token) == destination
+    assert len(store.list_shares()) == 1
+    # A shared bearer token alone cannot mutate the tree.
+    http.cookies.clear()
+    denied = http.post(
+        "/api/v1/folders/tree",
+        json=payload(destination=destination),
+        headers={"Authorization": "Bearer " + token},
+    )
+    assert denied.status_code == 401
+
+
+@pytest.mark.parametrize("state", ["trashed", "deleting", "file"])
+def test_new_tree_rejects_invalid_or_hidden_destination_without_writing(state):
+    store = DriveStore.create()
+    if state == "file":
+        item = store.add_file("/", "file.txt", 123, 4)
+    else:
+        item = store.create_folder("/", "Destination")
+        store.set_trashed("/" + item["id"], True)
+        if state == "deleting":
+            store.begin_deletion("/" + item["id"])
+    before = store.export()
+    with pytest.raises((ValidationError, NotDirectoryError, TrashedItemError)):
+        prepare(store, destination="/" + item["id"], folders=[["Child"]])
+    assert store.export() == before
+    store.close()
+
+
+@pytest.mark.parametrize("bad_path", ["/", "/a/", "/wrong/parent/child"])
+def test_portable_tree_rejects_malformed_result_paths(bad_path):
+    store = DriveStore.create()
+    prepare(store, folders=[["Child"]])
+    corrupt = copy.deepcopy(store.export())
+    corrupt["folder_preparations"][0]["result"]["folders"]["Child"] = bad_path
+    with pytest.raises(CorruptStoreError, match="ancestry"):
+        DriveStore._from_payload(corrupt)
+    store.close()
+
+
+def test_existing_preparation_stays_replayable_after_files_are_uploaded():
+    store = DriveStore.create()
+    request_id = str(uuid.uuid4())
+    tree = prepare(store, request_id=request_id, folders=[["Child"]])
+    store.add_file(tree["folders"]["Child"], "photo.jpg", 123, 10)
+    before = store.revision
+    assert prepare(store, request_id=request_id, folders=[["Child"]]) == tree
+    assert store.revision == before
+    store.close()
+
+
+def test_route_detects_changed_tree_and_does_not_create_another_root(client):
+    http, store = client
+    login(http)
+    request = payload()
+    tree = http.post("/api/v1/folders/tree", json=request).json()
+    store.rename(tree["folders"]["Child"], "Changed")
+    before = store.export()
+    response = http.post("/api/v1/folders/tree", json=request)
+    assert response.status_code == 409
+    assert response.json()["code"] == "FOLDER_TREE_CONFLICT"
+    assert store.export() == before
diff --git a/tests/web/test_frontend_security.py b/tests/web/test_frontend_security.py
new file mode 100644
index 00000000..cebe7f3b
--- /dev/null
+++ b/tests/web/test_frontend_security.py
@@ -0,0 +1,106 @@
+"""Security checks target authored React sources and the production entry."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+WEBSITE = ROOT / "website"
+
+
+def test_authored_frontend_has_no_html_injection_or_dynamic_code_sinks() -> None:
+    sources = "\n".join(
+        path.read_text(encoding="utf-8")
+        for path in (WEBSITE / "src").rglob("*")
+        if path.suffix in {".ts", ".tsx"} and ".test." not in path.name
+    )
+    for forbidden in (
+        "dangerouslySetInnerHTML",
+        ".innerHTML",
+        "insertAdjacentHTML",
+        "eval(",
+        "document.write",
+    ):
+        assert forbidden not in sources
+
+
+def test_production_entry_and_player_have_no_inline_or_remote_active_content() -> None:
+    entries = [WEBSITE / "index.html", WEBSITE / "public" / "VideoPlayer.html"]
+    if (WEBSITE / "dist" / "index.html").exists():
+        entries.append(WEBSITE / "dist" / "index.html")
+    for path in entries:
+        html = path.read_text(encoding="utf-8")
+        assert not re.search(r"\son[a-z]+\s*=", html, re.IGNORECASE)
+        assert "<style" not in html.lower()
+        assert not re.search(r"<script(?![^>]+src=)[^>]*>", html, re.IGNORECASE)
+        assert not re.search(r"(?:src|href)=[\"']https?://", html, re.IGNORECASE)
+        ids = re.findall(r'\bid="([^"]+)"', html)
+        assert len(ids) == len(set(ids)), path
+
+
+def test_production_assets_are_local_and_content_addressed() -> None:
+    entry = WEBSITE / "dist" / "index.html"
+    if not entry.exists():
+        return  # Source packages build this artifact in the Docker frontend stage.
+    for asset in re.findall(r'(?:src|href)="(/assets/[^"]+)"', entry.read_text()):
+        assert re.search(r"-[A-Za-z0-9_-]+\.(?:js|css)$", asset)
+        assert (WEBSITE / "dist" / asset.lstrip("/")).is_file()
+
+
+def test_frontend_dependencies_are_locked() -> None:
+    package = json.loads((WEBSITE / "package.json").read_text())
+    lock = json.loads((WEBSITE / "package-lock.json").read_text())
+    assert lock["lockfileVersion"] == 3
+    assert lock["packages"][""]["dependencies"] == package["dependencies"]
+    manifest = json.loads((WEBSITE / "vendor/manifest.json").read_text())
+    assert manifest["schema_version"] == 1
+    assert set(manifest["packages"]) == {"movi-player", "pdfjs-dist"}
+    dependencies = package["dependencies"] | package["devDependencies"]
+    for name, version in dependencies.items():
+        if name not in manifest["packages"]:
+            assert re.fullmatch(r"\d+\.\d+\.\d+", version), version
+            continue
+        viewer = manifest["packages"][name]
+        vendored = viewer["vendored"]
+        assert version == "file:vendor/" + vendored["archive"]
+        archive = WEBSITE / version.removeprefix("file:")
+        assert archive.parent == WEBSITE / "vendor"
+        assert archive.suffix == ".tgz"
+        content = archive.read_bytes()
+        actual_integrity = "sha512-" + base64.b64encode(
+            hashlib.sha512(content).digest()
+        ).decode("ascii")
+        entry = lock["packages"]["node_modules/" + name]
+        assert entry["resolved"] == version
+        assert entry["version"] == vendored["version"]
+        assert entry["integrity"] == vendored["integrity"] == actual_integrity
+        assert hashlib.sha256(content).hexdigest() == vendored["sha256"]
+        recipe = ROOT / viewer["patch"]["recipe"]
+        assert (
+            hashlib.sha256(recipe.read_bytes()).hexdigest()
+            == viewer["patch"]["recipe_sha256"]
+        )
+    for hook in ("predev", "prebuild", "pretest", "dev", "build", "test"):
+        command = package["scripts"].get(hook, "")
+        assert "patch-movi-player.js" not in command
+        assert "patch-pdf-worker.js" not in command
+
+
+def test_frontend_text_is_clean_utf8() -> None:
+    suspicious = ("â€", "ðŸ", "�")
+    for base in (WEBSITE / "src", WEBSITE / "public"):
+        for path in base.rglob("*"):
+            if path.is_file() and path.suffix in {
+                ".html",
+                ".css",
+                ".js",
+                ".ts",
+                ".tsx",
+                ".svg",
+            }:
+                text = path.read_text(encoding="utf-8")
+                assert not any(marker in text for marker in suspicious), path
diff --git a/tests/web/test_frontend_suite.py b/tests/web/test_frontend_suite.py
new file mode 100644
index 00000000..15d6d3fa
--- /dev/null
+++ b/tests/web/test_frontend_suite.py
@@ -0,0 +1,28 @@
+"""Run the complete Vitest behavior suite when frontend tools are installed."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_frontend_behavior_suite() -> None:
+    node = shutil.which("node")
+    if not node or not (ROOT / "website/node_modules/vitest/vitest.mjs").exists():
+        pytest.skip(
+            "Install the locked frontend dependencies to run the complete Vitest suite"
+        )
+    result = subprocess.run(  # noqa: S603 - fixed, repository-owned test entry
+        [node, str(ROOT / "website/node_modules/vitest/vitest.mjs"), "run"],
+        cwd=ROOT / "website",
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=60,
+    )
+    assert result.returncode == 0, result.stdout + result.stderr
diff --git a/tests/web/test_http_guard.py b/tests/web/test_http_guard.py
new file mode 100644
index 00000000..1dc16111
--- /dev/null
+++ b/tests/web/test_http_guard.py
@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from tempfile import SpooledTemporaryFile
+from typing import Any
+
+import pytest
+import starlette.formparsers as formparsers
+from starlette.exceptions import HTTPException
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from tgdrive.core.security import SESSION_COOKIE, SessionManager
+from tgdrive.web.http_guard import (
+    SecurityHeadersMiddleware,
+    StreamConcurrencyMiddleware,
+    UploadGuardMiddleware,
+)
+
+
+async def invoke(
+    app: Any,
+    *,
+    headers: list[tuple[bytes, bytes]],
+    chunks: list[bytes],
+) -> tuple[list[dict[str, Any]], int]:
+    sent: list[dict[str, Any]] = []
+    reads = 0
+
+    async def receive() -> dict[str, Any]:
+        nonlocal reads
+        if reads >= len(chunks):
+            await asyncio.Event().wait()
+        index = reads
+        reads += 1
+        return {
+            "type": "http.request",
+            "body": chunks[index],
+            "more_body": index < len(chunks) - 1,
+        }
+
+    async def send(message: dict[str, Any]) -> None:
+        sent.append(message)
+
+    await app(
+        {
+            "type": "http",
+            "asgi": {"version": "3.0", "spec_version": "2.4"},
+            "method": "POST",
+            "path": "/api/upload",
+            "raw_path": b"/api/upload",
+            "query_string": b"",
+            "scheme": "https",
+            "server": ("testserver", 443),
+            "client": ("127.0.0.1", 1234),
+            "headers": headers,
+            "app": object(),
+        },
+        receive,
+        send,
+    )
+    return sent, reads
+
+
+def make_guard(app: Any, limit: int = 16) -> tuple[Any, list[tuple[bytes, bytes]]]:
+    sessions = SessionManager(b"s" * 48, 3600)
+    guard = UploadGuardMiddleware(
+        app, sessions=sessions, upload_limit=limit, max_concurrent=1
+    )
+    cookie = f"{SESSION_COOKIE}={sessions.create()}".encode()
+    return guard, [(b"cookie", cookie)]
+
+
+@pytest.mark.asyncio
+async def test_unauthenticated_body_is_never_read_or_parsed() -> None:
+    async def app(*_args: Any) -> None:
+        pytest.fail("Unauthenticated requests must not enter multipart parsing")
+
+    guard, _ = make_guard(app)
+    messages, reads = await invoke(
+        guard,
+        headers=[(b"content-type", b"multipart/form-data; boundary=test")],
+        chunks=[b"x" * (3 * 1024**2)],
+    )
+    assert messages[0]["status"] == 401
+    assert reads == 0
+
+
+@pytest.mark.asyncio
+async def test_chunked_multipart_limit_closes_previously_spooled_file(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    opened: list[Any] = []
+
+    def tracked_spool(*args: Any, **kwargs: Any) -> Any:
+        file = SpooledTemporaryFile(*args, **kwargs)  # noqa: SIM115 - parser owns it
+        opened.append(file)
+        return file
+
+    monkeypatch.setattr(formparsers, "SpooledTemporaryFile", tracked_spool)
+
+    async def app(scope: Any, receive: Any, send: Any) -> None:
+        request = Request(scope, receive)
+        try:
+            async with request.form():
+                pytest.fail("Oversized request reached the upload handler")
+        except HTTPException as exc:
+            await JSONResponse({"detail": str(exc)}, status_code=exc.status_code)(
+                scope, receive, send
+            )
+
+    guard, headers = make_guard(app)
+    headers.append((b"content-type", b"multipart/form-data; boundary=test"))
+    start = (
+        b'--test\r\nContent-Disposition: form-data; name="file"; '
+        b'filename="large.bin"\r\nContent-Type: application/octet-stream\r\n\r\n'
+    )
+    messages, _ = await invoke(
+        guard,
+        headers=headers,
+        chunks=[start + b"x" * 1024, b"x" * (1024**2), b"x" * (1024**2)],
+    )
+    assert messages[0]["status"] == 413
+    assert json.loads(messages[1]["body"])["detail"] == "Upload body is too large"
+    assert opened
+    assert all(file.closed for file in opened)
+
+
+@pytest.mark.asyncio
+async def test_declared_oversize_body_is_rejected_before_receive() -> None:
+    async def app(*_args: Any) -> None:
+        pytest.fail("Oversized requests must not reach the handler")
+
+    guard, headers = make_guard(app)
+    headers.append((b"content-length", b"99999999"))
+    messages, reads = await invoke(guard, headers=headers, chunks=[b"ignored"])
+    assert messages[0]["status"] == 413
+    assert reads == 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("length", [b"-1", b"not-a-number"])
+async def test_invalid_body_framing_is_rejected(length: bytes) -> None:
+    async def app(*_args: Any) -> None:
+        pytest.fail("Invalid framing must not reach the handler")
+
+    guard, headers = make_guard(app)
+    headers.append((b"content-length", length))
+    messages, reads = await invoke(guard, headers=headers, chunks=[b"ignored"])
+    assert messages[0]["status"] == 400
+    assert reads == 0
+
+
+@pytest.mark.asyncio
+async def test_stream_capacity_covers_body_and_releases_after_disconnect() -> None:
+    entered = asyncio.Queue()
+    finish = asyncio.Event()
+
+    async def stream(scope: Any, receive: Any, send: Any) -> None:
+        await entered.put(scope["client"])
+        if scope["client"] == "cancelled":
+            await asyncio.Event().wait()
+        await finish.wait()
+
+    guard = StreamConcurrencyMiddleware(stream, max_concurrent=1)
+
+    async def invoke_stream(label: str, path: str = "/file") -> None:
+        await guard(
+            {"type": "http", "method": "GET", "path": path, "client": label},
+            None,
+            None,
+        )
+
+    first = asyncio.create_task(invoke_stream("cancelled"))
+    assert await asyncio.wait_for(entered.get(), 1) == "cancelled"
+    second = asyncio.create_task(invoke_stream("waiting"))
+    await asyncio.sleep(0)
+    assert entered.empty()
+    # The file limit must not block health/auth/metadata requests.
+    unrelated = asyncio.create_task(invoke_stream("health", "/healthz"))
+    assert await asyncio.wait_for(entered.get(), 1) == "health"
+    first.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await first
+    assert await asyncio.wait_for(entered.get(), 1) == "waiting"
+    finish.set()
+    await asyncio.gather(second, unrelated)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("path", "status"),
+    [("/", 200), ("/file", 206), ("/api/missing", 404), ("/api/failure", 500)],
+)
+@pytest.mark.parametrize("advertise", [False, True])
+async def test_alt_svc_default_preserves_streaming_payload_and_file_headers(
+    path, status, advertise
+):
+    messages = []
+    payload = [b"first", b"second"]
+
+    async def app(scope, receive, send):
+        headers = [
+            (b"content-length", b"11"),
+            (b"content-range", b"bytes 5-15/50"),
+            (b"accept-ranges", b"bytes"),
+            (b"content-encoding", b"identity"),
+        ]
+        if advertise:
+            headers.extend(
+                [(b"alt-svc", b'h3=":443"; ma=86400'), (b"Alt-Svc", b'h3-29=":443"')]
+            )
+        await send(
+            {"type": "http.response.start", "status": status, "headers": headers}
+        )
+        for index, chunk in enumerate(payload):
+            await send(
+                {"type": "http.response.body", "body": chunk, "more_body": index == 0}
+            )
+            assert messages[-1]["body"] is chunk  # passed through immediately
+
+    middleware = SecurityHeadersMiddleware(app, secure=True)
+
+    async def send(value):
+        messages.append(value)
+
+    await middleware({"type": "http", "path": path}, None, send)
+    headers = dict(messages[0]["headers"])
+    assert messages[0]["status"] == status
+    assert headers[b"alt-svc"] == b"clear"
+    assert sum(name.lower() == b"alt-svc" for name, _ in messages[0]["headers"]) == 1
+    assert headers[b"content-length"] == b"11"
+    assert headers[b"content-range"] == b"bytes 5-15/50"
+    assert headers[b"accept-ranges"] == b"bytes"
+    assert headers[b"content-encoding"] == b"identity"
+    assert headers[b"x-content-type-options"] == b"nosniff"
+    assert (
+        headers[b"strict-transport-security"] == b"max-age=31536000; includeSubDomains"
+    )
+    assert b"default-src 'self'" in headers[b"content-security-policy"]
+    assert b"".join(value["body"] for value in messages[1:]) == b"firstsecond"
+
+
+@pytest.mark.asyncio
+async def test_alt_svc_policy_passes_non_http_scope_and_messages_unchanged():
+    scope = {"type": "websocket", "path": "/"}
+    accept = {"type": "websocket.accept", "headers": [(b"alt-svc", b"unchanged")]}
+    sent = []
+
+    async def app(actual_scope, receive, send):
+        assert actual_scope is scope
+        await send(accept)
+
+    async def send(message):
+        sent.append(message)
+
+    await SecurityHeadersMiddleware(app, secure=True)(scope, None, send)
+    assert sent == [accept] and sent[0] is accept
diff --git a/tests/web/test_management.py b/tests/web/test_management.py
new file mode 100644
index 00000000..77355e03
--- /dev/null
+++ b/tests/web/test_management.py
@@ -0,0 +1,1170 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import UTC, datetime
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi.testclient import TestClient
+from pydantic import SecretStr
+from pymongo.errors import ConnectionFailure
+from telethon import types
+from telethon.crypto import AuthKey
+from telethon.sessions import StringSession
+
+import tgdrive.settings.management as management_module
+from tests.support.app_fixtures import FakeRuntime, make_settings
+from tests.support.mongo_fixtures import register_test_backend
+from tgdrive.core.config import Settings
+from tgdrive.settings.managed_settings import (
+    ManagedClient,
+    ManagedDocument,
+    SettingsProblem,
+    read_document,
+    save_document,
+)
+from tgdrive.settings.management import (
+    ConnectionManager,
+    SettingsChange,
+    verify_connection,
+)
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.telegram.client_identity import IdentityCache
+from tgdrive.transfers.tasks import TransferStatus
+from tgdrive.transfers.uploads import ResumableUploads
+from tgdrive.web.app import create_app
+
+TOKEN = "123456:" + "x" * 30
+SECOND_TOKEN = "654321:" + "y" * 30
+
+
+@pytest.fixture
+def managed(tmp_path, monkeypatch):
+    settings = make_settings(tmp_path)
+    settings.resolved_cache_dir.mkdir(parents=True)
+    backend = register_test_backend(monkeypatch, settings)
+    store = MongoStore.create(backend)
+    runtime = FakeRuntime(store)
+    runtime.mongo = backend
+
+    async def verifier(_api_id, _api_hash, row, _channel):
+        return (
+            "storage-bot-" + row.credential.get_secret_value().split(":", 1)[0]
+            if row.kind == "bot"
+            else "premium-user-987654"
+        )
+
+    manager = ConnectionManager(settings, runtime, verifier=verifier)
+    runtime.connection_manager = manager
+    yield manager, runtime, settings, store
+    runtime.transfers.registry.close()
+    store.close()
+
+
+@pytest.mark.asyncio
+async def test_atomic_private_save_cas_and_secret_safe_snapshot(managed):
+    manager, _runtime, settings, _ = managed
+    snapshot = await manager.snapshot()
+    client = snapshot["clients"][0]
+    result = await manager.save(
+        SettingsChange.model_validate(
+            {
+                "expected_revision": 0,
+                "api_id": 99999,
+                "api_hash": "b" * 32,
+                "clients": [
+                    {
+                        "id": client["id"],
+                        "label": "Main bot",
+                        "kind": "bot",
+                        "enabled": True,
+                    }
+                ],
+            }
+        )
+    )
+    assert result["revision"] == 1
+    assert result["applied_revision"] == 0
+    assert result["restart_required"] and result["admission_paused"]
+    assert result["api_id"] == 99999
+    assert settings.api_id == 12345  # Running configuration never changes.
+    assert result["active_clients"][0]["label"] == "Storage bot 1"
+    text = json.dumps(result)
+    for secret in (TOKEN, "b" * 32, settings.session_secret.get_secret_value()):
+        assert secret not in text
+    assert _runtime.mongo.db.settings.find_one({"_id": "telegram"})["revision"] == 1
+    document = read_document(settings.resolved_data_dir)
+    assert document.api_hash.get_secret_value() == "b" * 32
+    assert document.clients[0].credential.get_secret_value() == TOKEN
+    with pytest.raises(SettingsProblem) as conflict:
+        await manager.save(SettingsChange(expected_revision=0, api_id=1000))
+    assert conflict.value.code == "SETTINGS_CONFLICT"
+    assert read_document(settings.resolved_data_dir).revision == 1
+    with pytest.raises(SettingsProblem) as pending:
+        manager.check_upload_allowed()
+    assert pending.value.code == "SETTINGS_RESTART_REQUIRED"
+
+
+@pytest.mark.asyncio
+async def test_failed_verification_preserves_previous_configuration(managed):
+    manager, _, settings, _ = managed
+    manager.verifier = AsyncMock(side_effect=RuntimeError(TOKEN))
+    with pytest.raises(SettingsProblem) as captured:
+        await manager.save(SettingsChange(expected_revision=0, api_id=12))
+    assert captured.value.code == "SETTINGS_PREFLIGHT_FAILED"
+    assert TOKEN not in str(captured.value)
+    assert read_document(settings.resolved_data_dir) is None
+
+
+@pytest.mark.asyncio
+async def test_no_enabled_bot_no_duplicate_accounts_no_unknown_identity(managed):
+    manager, _, settings, _ = managed
+    row = (await manager.snapshot())["clients"][0]
+    for clients in (
+        [{"id": row["id"], "label": "Bot", "kind": "bot", "enabled": False}],
+        [
+            {"label": "One", "kind": "bot", "credential": TOKEN},
+            {"label": "Two", "kind": "bot", "credential": TOKEN},
+        ],
+        [{"id": "not-saved", "label": "One", "kind": "bot", "credential": TOKEN}],
+    ):
+        with pytest.raises(SettingsProblem):
+            await manager.save(
+                SettingsChange.model_validate(
+                    {"expected_revision": 0, "clients": clients}
+                )
+            )
+    assert read_document(settings.resolved_data_dir) is None
+
+
+@pytest.mark.asyncio
+async def test_premium_private_import_preserves_existing_client_ids(managed):
+    manager, _, settings, _ = managed
+    initial = (await manager.snapshot())["clients"][0]["id"]
+    result = await manager.add_authenticated_session(0, "Premium", "synthetic-session")
+    assert [row["kind"] for row in result["clients"]] == ["bot", "user"]
+    assert result["clients"][0]["id"] == initial
+    assert "synthetic-session" not in json.dumps(result)
+    assert (
+        read_document(settings.resolved_data_dir)
+        .clients[1]
+        .credential.get_secret_value()
+        == "synthetic-session"
+    )
+    api_id, api_hash, revision = manager.login_api()
+    assert api_id == 12345 and api_hash.get_secret_value() == "a" * 32 and revision == 1
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("same_account", [True, False])
+async def test_pending_upload_allows_only_same_account_credential_repair(
+    managed, same_account
+):
+    manager, runtime, settings, _ = managed
+    row = (await manager.snapshot())["clients"][0]
+    record = await runtime.transfers.registry.create("failed")
+    record.status = TransferStatus.ERROR
+    record.context.update(sender="storage-bot-123456", random_id=123, send_started=True)
+    token = "123456:" + "z" * 30 if same_account else SECOND_TOKEN
+    change = SettingsChange.model_validate(
+        {
+            "expected_revision": 0,
+            "clients": [
+                {
+                    "id": row["id"],
+                    "label": row["label"],
+                    "kind": "bot",
+                    "credential": token,
+                }
+            ],
+        }
+    )
+    if same_account:
+        result = await manager.save(change)
+        assert result["restart_required"]
+        assert token not in json.dumps(result)
+        saved = read_document(settings.resolved_data_dir).clients[0]
+        assert saved.runtime_name == record.context["sender"]
+        assert saved.credential.get_secret_value() == token
+    else:
+        with pytest.raises(SettingsProblem, match="same Telegram account"):
+            await manager.save(change)
+        assert read_document(settings.resolved_data_dir) is None
+    assert record.context["random_id"] == 123
+    assert record.context["send_started"]
+
+
+@pytest.mark.asyncio
+async def test_refresh_restores_verified_live_channel_access(managed):
+    from telethon.errors import ChannelPrivateError
+
+    from tests.telegram.test_client_pool import FakeClient
+    from tgdrive.telegram.client_pool import ClientPool
+
+    manager, runtime, _, _ = managed
+    client = FakeClient("storage-bot-123456")
+    runtime.pool = ClientPool([client])
+    await runtime.pool.start()
+    try:
+        await runtime.pool.report_failure(client, ChannelPrivateError(request=None))
+        before = await manager.snapshot()
+        assert before["clients"][0]["error_code"] == "TELEGRAM_CHANNEL_ACCESS"
+        await manager.refresh_connections()
+        await asyncio.gather(*manager._check_tasks)
+        after = await manager.snapshot()
+        assert after["clients"][0]["healthy"]
+        assert after["clients"][0]["error"] is None
+    finally:
+        await manager.close()
+        await runtime.pool.stop()
+
+
+@pytest.mark.asyncio
+async def test_busy_rechecked_after_network_verification(managed):
+    manager, runtime, settings, _ = managed
+    entered = asyncio.Event()
+    resume = asyncio.Event()
+    original = manager.verifier
+
+    async def verifier(*arguments):
+        entered.set()
+        await resume.wait()
+        return await original(*arguments)
+
+    manager.verifier = verifier
+    task = asyncio.create_task(
+        manager.save(SettingsChange(expected_revision=0, api_id=123))
+    )
+    await entered.wait()
+    await runtime.transfers.registry.create("uploading")
+    resume.set()
+    with pytest.raises(SettingsProblem) as captured:
+        await task
+    assert captured.value.code == "SETTINGS_BUSY"
+    assert read_document(settings.resolved_data_dir) is None
+
+
+@pytest.mark.asyncio
+async def test_failed_ambiguous_job_also_blocks_removing_its_sender(managed):
+    manager, runtime, _, _ = managed
+    job = await runtime.transfers.registry.create("uploading")
+    job.status = TransferStatus.ERROR
+    job.context.update(sender="storage-bot-123456", send_started=True)
+    with pytest.raises(SettingsProblem) as captured:
+        await manager.save(SettingsChange(expected_revision=0, api_id=1))
+    assert captured.value.code == "SETTINGS_BUSY"
+
+
+@pytest.mark.asyncio
+async def test_catalog_stats_include_inherited_trash_and_live_client_health(managed):
+    manager, runtime, _, store = managed
+    folder = store.create_folder("/", "Folder")
+    store.add_file("/", "visible.bin", 101, 7)
+    folder_path = "/" + folder["id"]
+    store.add_file(folder_path, "trashed.bin", 102, 13)
+    store.set_trashed(folder_path, True)
+    runtime.pool = SimpleNamespace(
+        status=AsyncMock(
+            return_value=(
+                SimpleNamespace(
+                    name="storage-bot-123456",
+                    started=True,
+                    connected=True,
+                    healthy=True,
+                    active_leases=2,
+                    last_error_type=None,
+                ),
+            )
+        )
+    )
+    snapshot = await manager.snapshot()
+    assert snapshot["stats"] | {} == {
+        **snapshot["stats"],
+        "files": 1,
+        "folders": 0,
+        "total_bytes": 7,
+        "trashed_files": 1,
+        "trashed_bytes": 13,
+    }
+    assert snapshot["clients"][0]["connected"] is True
+    assert snapshot["clients"][0]["active_leases"] == 2
+    assert snapshot["clients"][0]["premium"] is False
+
+
+def document(revision=1):
+    return ManagedDocument(
+        revision=revision,
+        api_id=333,
+        api_hash=SecretStr("b" * 32),
+        clients=[
+            ManagedClient(
+                id="saved-bot",
+                label="Saved bot",
+                kind="bot",
+                credential=SecretStr(SECOND_TOKEN),
+            )
+        ],
+    )
+
+
+def test_restart_loads_managed_overrides_before_invalid_environment(
+    tmp_path, monkeypatch
+):
+    monkeypatch.chdir(tmp_path)
+    data = tmp_path / "private"
+    register_test_backend(monkeypatch, data)
+    save_document(data, document(), 0)
+    monkeypatch.setenv("MONGODB_URI", "mongodb://synthetic.invalid")
+    monkeypatch.setenv("DATA_DIR", str(data))
+    monkeypatch.setenv("API_ID", "invalid-old-env")
+    monkeypatch.setenv("API_HASH", "invalid-old-hash")
+    monkeypatch.setenv("BOT_TOKENS", "invalid-old-token")
+    monkeypatch.setenv("STORAGE_CHANNEL", "-1001234567890")
+    monkeypatch.setenv("ADMIN_PASSWORD", "correct horse battery staple")
+    monkeypatch.setenv("SESSION_SECRET", "s" * 48)
+    settings = Settings(_env_file=None)
+    assert settings.api_id == 333 and settings.bot_tokens == (SECOND_TOKEN,)
+    assert settings.managed_revision == 1
+    assert settings.managed_client_ids == ("saved-bot",)
+    assert settings.managed_client_labels == ("Saved bot",)
+
+
+@pytest.mark.parametrize("saved_main_state", [None, "disabled", "removed", "rotated"])
+def test_main_token_seeds_only_before_connections_are_managed(
+    tmp_path, monkeypatch, saved_main_state
+):
+    monkeypatch.chdir(tmp_path)
+    data = tmp_path / "private"
+    register_test_backend(monkeypatch, data)
+    expected_token = TOKEN
+    if saved_main_state is not None:
+        saved = document()
+        expected_token = SECOND_TOKEN
+        if saved_main_state == "disabled":
+            saved.clients.append(
+                ManagedClient(
+                    id="main-bot",
+                    label="Main bot",
+                    kind="bot",
+                    enabled=False,
+                    credential=SecretStr(TOKEN),
+                )
+            )
+        elif saved_main_state == "rotated":
+            expected_token = "123456:" + "z" * 30
+            saved.clients[0].id = "main-bot"
+            saved.clients[0].credential = SecretStr(expected_token)
+        save_document(data, saved, 0)
+    monkeypatch.delenv("BOT_TOKENS", raising=False)
+    for name, value in {
+        "MONGODB_URI": "mongodb://synthetic.invalid",
+        "DATA_DIR": str(data),
+        "API_ID": "12345",
+        "API_HASH": "a" * 32,
+        "MAIN_BOT_TOKEN": TOKEN,
+        "TELEGRAM_ADMIN_IDS": "123",
+        "STORAGE_CHANNEL": "-1001234567890",
+        "ADMIN_PASSWORD": "correct horse battery staple",
+        "SESSION_SECRET": "s" * 48,
+    }.items():
+        monkeypatch.setenv(name, value)
+
+    applied = Settings(_env_file=None)
+    assert applied.bot_tokens == (expected_token,)
+    assert applied.bot_tokens_csv.get_secret_value() == expected_token
+    assert applied.main_bot_token_value == TOKEN
+    assert applied.managed_revision == (0 if saved_main_state is None else 1)
+
+
+@pytest.mark.parametrize("damage", ["document", "unavailable"])
+def test_invalid_or_unavailable_mongo_settings_never_fall_back_to_environment(
+    tmp_path, monkeypatch, damage
+):
+    data = tmp_path / "data"
+    backend = register_test_backend(monkeypatch, data)
+    save_document(data, document(), 0)
+    backend._settings_cached = False
+    collection = backend.db.settings
+    if damage == "document":
+        collection.replace_one(
+            {"_id": "telegram"},
+            {
+                "_id": "telegram",
+                "revision": 1,
+                "document": {"api_hash": "synthetic-secret"},
+            },
+        )
+    else:
+
+        def unavailable(_query):
+            raise ConnectionFailure("synthetic-secret")
+
+        monkeypatch.setattr(collection, "find_one", unavailable)
+    expected = SettingsProblem if damage == "document" else DatabaseUnavailable
+    with pytest.raises(expected) as captured:
+        read_document(data)
+    assert "synthetic-secret" not in str(captured.value)
+    assert collection.rows  # Rejected configuration is preserved.
+
+
+def test_store_cas_atomic_write_and_no_catalog_secret_export(managed):
+    _, _, settings, store = managed
+    save_document(settings.resolved_data_dir, document(), 0)
+    with pytest.raises(SettingsProblem):
+        save_document(settings.resolved_data_dir, document(2), 0)
+    assert read_document(settings.resolved_data_dir).revision == 1
+    assert SECOND_TOKEN not in json.dumps(store.export())
+
+
+def test_owner_only_api_omits_secret_inputs_and_preserves_unsaved_on_invalid(managed):
+    manager, runtime, settings, _ = managed
+    app = create_app(settings, runtime=runtime)
+    with TestClient(app, base_url="https://testserver") as client:
+        assert client.get("/api/v1/settings").status_code == 401
+        assert (
+            client.patch("/api/v1/settings", json={"expected_revision": 0}).status_code
+            == 401
+        )
+        assert (
+            client.post(
+                "/api/checkPassword", json={"pass": "correct horse battery staple"}
+            ).status_code
+            == 200
+        )
+        result = client.get("/api/v1/settings")
+        assert result.status_code == 200 and TOKEN not in result.text
+        bad = client.patch(
+            "/api/v1/settings",
+            json={
+                "expected_revision": 0,
+                "api_hash": "wrong-secret",
+                "storage_channel": -1009,
+            },
+        )
+        assert bad.status_code == 422 and "wrong-secret" not in bad.text
+        result = client.patch(
+            "/api/v1/settings", json={"expected_revision": 0, "api_id": 67890}
+        )
+        assert result.status_code == 200 and result.json()["restart_required"]
+        assert TOKEN not in result.text
+        assert manager.restart_required
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("case", ["unprotected", "conflict", "receipt"])
+async def test_pending_work_and_recovery_conflict_block_settings(managed, case):
+    manager, runtime, settings, store = managed
+    protection = {
+        "state": "protected",
+        "metadata_revision": store.revision,
+        "protected_revision": store.revision,
+    }
+    runtime.backup = SimpleNamespace(protection_status=lambda _: protection)
+    uploads = None
+    if case == "unprotected":
+        protection.update(state="pending", protected_revision=0)
+    elif case == "conflict":
+        protection.update(state="error", recovery_required=True)
+    else:
+        uploads = ResumableUploads(settings, runtime.transfers)
+        uploads.create("pending.bin", "/", 3)
+    try:
+        with pytest.raises(SettingsProblem) as captured:
+            await manager.save(SettingsChange(expected_revision=0, api_id=1))
+        assert captured.value.code == "SETTINGS_BUSY"
+        assert read_document(settings.resolved_data_dir) is None
+    finally:
+        if uploads is not None:
+            uploads.close()
+
+
+@pytest.mark.asyncio
+async def test_clean_confirmed_watermark_can_repair_broken_old_credentials(managed):
+    manager, runtime, _, store = managed
+    runtime.backup = SimpleNamespace(
+        protection_status=lambda _: {
+            "state": "error",
+            "metadata_revision": store.revision,
+            "protected_revision": store.revision,
+            "error": "Old connection unavailable",
+        }
+    )
+    result = await manager.save(SettingsChange(expected_revision=0, api_id=123))
+    assert result["restart_required"]
+    assert result["recovery"]["state"] == "error"  # No false protection claim.
+
+
+@pytest.mark.asyncio
+async def test_replaced_account_is_not_shown_connected_before_restart(managed):
+    manager, runtime, _, _ = managed
+    runtime.pool = SimpleNamespace(
+        status=AsyncMock(
+            return_value=(
+                SimpleNamespace(
+                    name="storage-bot-123456",
+                    started=True,
+                    connected=True,
+                    healthy=True,
+                    active_leases=0,
+                    last_error_type=None,
+                ),
+            )
+        )
+    )
+    row = (await manager.snapshot())["clients"][0]
+    result = await manager.save(
+        SettingsChange.model_validate(
+            {
+                "expected_revision": 0,
+                "clients": [
+                    {
+                        "id": row["id"],
+                        "label": "Replacement",
+                        "kind": "bot",
+                        "credential": SECOND_TOKEN,
+                    }
+                ],
+            }
+        )
+    )
+    assert result["clients"][0]["connected"] is None
+    assert not result["clients"][0]["healthy"]
+    assert result["active_clients"][0]["connected"] is True
+
+
+class NativeProbe:
+    def __init__(
+        self, *, bot=True, premium=False, authorized=True, rights=True, identity=123456
+    ):
+        self.account = SimpleNamespace(id=identity, bot=bot, premium=premium)
+        self.authorized = authorized
+        self.rights = rights
+        self.connect = AsyncMock()
+        self.disconnect = AsyncMock()
+        self.sign_in = AsyncMock()
+        self.get_me = AsyncMock(return_value=self.account)
+        self.is_user_authorized = AsyncMock(return_value=authorized)
+        self.get_input_entity = AsyncMock(
+            return_value=types.InputPeerChannel(1234567890, 123)
+        )
+        self.calls = []
+
+    async def __call__(self, request):
+        self.calls.append(request)
+        return SimpleNamespace(
+            chats=[
+                types.Channel(
+                    id=1234567890,
+                    title="Private test",
+                    photo=types.ChatPhotoEmpty(),
+                    date=datetime.now(UTC),
+                    broadcast=True,
+                    admin_rights=types.ChatAdminRights(
+                        post_messages=self.rights,
+                        edit_messages=self.rights,
+                        delete_messages=self.rights,
+                    ),
+                )
+            ]
+        )
+
+
+def fake_session():
+    session = StringSession()
+    session.set_dc(2, "149.154.167.51", 443)
+    session.auth_key = AuthKey(data=b"x" * 256)
+    return session.save()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("kind", ["bot", "user"])
+async def test_real_preflight_contract_is_memory_only_checks_getme_and_channel(
+    monkeypatch, kind, tmp_path
+):
+    native = NativeProbe(bot=kind == "bot", premium=kind == "user")
+    native.account.first_name = "Telegram Name"
+    native.account.username = "telegram_name"
+    constructors = []
+
+    def constructor(session, api_id, api_hash, **options):
+        constructors.append((session, api_id, api_hash, options))
+        return native
+
+    monkeypatch.setattr(management_module, "TelegramClient", constructor)
+    row = ManagedClient(
+        id="test-account",
+        label="Test",
+        kind=kind,
+        credential=SecretStr(TOKEN if kind == "bot" else fake_session()),
+    )
+    register_test_backend(monkeypatch, tmp_path)
+    cache = IdentityCache(tmp_path)
+    result = await verify_connection(
+        12345, "a" * 32, row, -1001234567890, identity_cache=cache
+    )
+    assert result == ("storage-bot-123456" if kind == "bot" else "premium-user-123456")
+    assert cache.read(result) == {
+        "display_name": "Telegram Name",
+        "username": "telegram_name",
+    }
+    assert isinstance(constructors[0][0], StringSession)
+    assert constructors[0][3]["receive_updates"] is False
+    assert constructors[0][3]["flood_sleep_threshold"] == 0
+    assert constructors[0][3]["base_logger"].propagate is False
+    native.disconnect.assert_awaited_once()
+    native.get_me.assert_awaited_once()
+    assert (
+        len(native.calls) == 1
+        and native.calls[0].__class__.__name__ == "GetFullChannelRequest"
+    )
+    if kind == "bot":
+        native.sign_in.assert_awaited_once_with(bot_token=TOKEN)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "case", ["nonpremium", "expired", "wrong-bot", "rights", "network"]
+)
+async def test_preflight_failure_never_echoes_secret_and_always_disconnects(
+    monkeypatch, case
+):
+    user = case in {"nonpremium", "expired"}
+    native = NativeProbe(
+        bot=not user,
+        premium=False,
+        authorized=case != "expired",
+        rights=case != "rights",
+        identity=654321 if case == "wrong-bot" else 123456,
+    )
+    if case == "network":
+        native.connect.side_effect = RuntimeError(TOKEN)
+    monkeypatch.setattr(
+        management_module, "TelegramClient", lambda *_args, **_kwargs: native
+    )
+    row = ManagedClient(
+        id="test-account",
+        label="Test",
+        kind="user" if user else "bot",
+        credential=SecretStr(fake_session() if user else TOKEN),
+    )
+    with pytest.raises(SettingsProblem) as captured:
+        await verify_connection(12345, "a" * 32, row, -1001234567890)
+    assert TOKEN not in str(captured.value)
+    native.disconnect.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_restart_applies_enabled_rows_and_removal_cannot_resurrect_environment(
+    tmp_path, monkeypatch
+):
+    monkeypatch.chdir(tmp_path)
+    data = tmp_path / "data"
+    backend = register_test_backend(monkeypatch, data)
+    candidate = document()
+    candidate.clients.append(
+        ManagedClient(
+            id="disabled-bot",
+            label="Disabled",
+            kind="bot",
+            enabled=False,
+            credential=SecretStr(TOKEN),
+        )
+    )
+    save_document(data, candidate, 0)
+    monkeypatch.setenv("MONGODB_URI", "mongodb://synthetic.invalid")
+    monkeypatch.setenv("DATA_DIR", str(data))
+    monkeypatch.setenv("BOT_TOKENS", TOKEN)
+    monkeypatch.setenv("STORAGE_CHANNEL", "-1001234567890")
+    monkeypatch.setenv("ADMIN_PASSWORD", "correct horse battery staple")
+    monkeypatch.setenv("SESSION_SECRET", "s" * 48)
+    applied = Settings(_env_file=None)
+    assert applied.bot_tokens == (SECOND_TOKEN,)
+    runtime = SimpleNamespace(store=None, pool=None, mongo=backend)
+    manager = ConnectionManager(applied, runtime)
+    result = await manager.snapshot()
+    assert result["applied_revision"] == result["revision"] == 1
+    assert not result["restart_required"]
+    assert len(result["clients"]) == 2
+    assert len(result["active_clients"]) == 1
+
+
+@pytest.mark.asyncio
+async def test_disabling_expired_bot_does_not_reverify_disabled_credentials(managed):
+    manager, _, _, _ = managed
+    row = (await manager.snapshot())["clients"][0]
+    verified = []
+
+    async def verifier(_api_id, _api_hash, candidate, _channel):
+        verified.append(candidate.id)
+        assert candidate.credential.get_secret_value() == SECOND_TOKEN
+        return "storage-bot-654321"
+
+    manager.verifier = verifier
+    result = await manager.save(
+        SettingsChange.model_validate(
+            {
+                "expected_revision": 0,
+                "clients": [
+                    {
+                        "id": row["id"],
+                        "label": "Expired",
+                        "kind": "bot",
+                        "enabled": False,
+                    },
+                    {"label": "Replacement", "kind": "bot", "credential": SECOND_TOKEN},
+                ],
+            }
+        )
+    )
+    assert len(verified) == 1
+    assert result["clients"][0]["enabled"] is False
+    assert result["clients"][1]["enabled"] is True
+
+
+@pytest.mark.asyncio
+async def test_concurrent_managers_cas_after_candidate_verification(managed):
+    first, runtime, settings, _ = managed
+    entered = 0
+    both = asyncio.Event()
+
+    async def verifier(*_args):
+        nonlocal entered
+        entered += 1
+        if entered == 2:
+            both.set()
+        await both.wait()
+        return "storage-bot-123456"
+
+    first.verifier = verifier
+    second = ConnectionManager(settings, runtime, verifier=verifier)
+    results = await asyncio.gather(
+        first.save(SettingsChange(expected_revision=0, api_id=1)),
+        second.save(SettingsChange(expected_revision=0, api_id=2)),
+        return_exceptions=True,
+    )
+    assert sum(isinstance(result, dict) for result in results) == 1
+    failures = [result for result in results if isinstance(result, SettingsProblem)]
+    assert len(failures) == 1 and failures[0].code == "SETTINGS_CONFLICT"
+    assert read_document(settings.resolved_data_dir).revision == 1
+
+
+@pytest.mark.asyncio
+async def test_cancelled_preflight_drains_all_probe_tasks_and_never_saves(managed):
+    manager, _, settings, _ = managed
+    entered = 0
+    closed = 0
+    both = asyncio.Event()
+
+    async def verifier(*_args):
+        nonlocal entered, closed
+        entered += 1
+        if entered == 2:
+            both.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            closed += 1
+
+    manager.verifier = verifier
+    task = asyncio.create_task(
+        manager.save(
+            SettingsChange.model_validate(
+                {
+                    "expected_revision": 0,
+                    "clients": [
+                        {"label": "One", "kind": "bot", "credential": TOKEN},
+                        {"label": "Two", "kind": "bot", "credential": SECOND_TOKEN},
+                    ],
+                }
+            )
+        )
+    )
+    await both.wait()
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert closed == 2
+    assert read_document(settings.resolved_data_dir) is None
+
+
+@pytest.mark.asyncio
+async def test_inflight_bot_import_blocks_credentials_commit(managed):
+    manager, runtime, settings, _ = managed
+    runtime.bot_mode = SimpleNamespace(active_imports=1)
+    with pytest.raises(SettingsProblem) as captured:
+        await manager.save(SettingsChange(expected_revision=0, api_id=222))
+    assert captured.value.code == "SETTINGS_BUSY"
+    assert read_document(settings.resolved_data_dir) is None
+
+
+@pytest.mark.asyncio
+async def test_removing_premium_preserves_bot_multipart_logical_limit(managed):
+    manager, _, settings, _ = managed
+    manager.settings = settings.model_copy(
+        update={
+            "max_file_size": 3000 * 1024**2,
+            "string_sessions_csv": SecretStr("synthetic-premium"),
+        }
+    )
+    result = await manager.save(SettingsChange(expected_revision=0, api_id=123))
+    assert result["restart_required"]
+    assert manager.settings.upload_limit == 3000 * 1024**2
+    assert read_document(settings.resolved_data_dir) is not None
+
+
+async def test_login_api_rejects_busy_before_phone_code_request(managed):
+    manager, runtime, _, _ = managed
+    await runtime.transfers.registry.create("uploading")
+    with pytest.raises(SettingsProblem) as captured:
+        manager.login_api()
+    assert captured.value.code == "SETTINGS_BUSY"
+
+
+@pytest.mark.asyncio
+async def test_stale_completed_receipt_does_not_block_connection_changes(managed):
+    manager, runtime, settings, _ = managed
+    uploads = ResumableUploads(settings, runtime.transfers)
+    try:
+        receipt = uploads.create("finished.bin", "/", 3)
+        record = await runtime.transfers.registry.create(
+            "uploading", transfer_id=receipt["id"]
+        )
+        record.status = TransferStatus.COMPLETED
+        result = await manager.save(SettingsChange(expected_revision=0, api_id=123))
+        assert result["restart_required"]
+        assert result["stats"]["staging_reserved_bytes"] == 0
+    finally:
+        uploads.close()
+
+
+@pytest.mark.asyncio
+async def test_cancellation_while_collecting_health_happens_before_session_commit(
+    managed,
+):
+    from tests.telegram.test_premium_login import LoginClient
+    from tgdrive.settings.premium_login import PremiumLoginService
+
+    manager, runtime, settings, _ = managed
+    entered = asyncio.Event()
+
+    async def blocked_status():
+        entered.set()
+        await asyncio.Event().wait()
+
+    runtime.pool = SimpleNamespace(status=blocked_status)
+    client = LoginClient()
+    service = PremiumLoginService(
+        manager.login_api,
+        manager.add_authenticated_session,
+        client_factory=lambda *_: client,
+    )
+    task = None
+    try:
+        identity = (await service.begin("owner", 0, "+919876543210", "Premium"))[
+            "challenge_id"
+        ]
+        task = asyncio.create_task(service.verify("owner", identity, code="12345"))
+        await entered.wait()
+        assert read_document(settings.resolved_data_dir) is None
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await task
+        assert client.logged_out  # Not committed: the disposable login is revoked.
+        assert read_document(settings.resolved_data_dir) is None
+    finally:
+        await service.close()
+
+
+@pytest.mark.asyncio
+async def test_post_commit_mongodb_reply_loss_is_resolved_by_private_probe(
+    managed, monkeypatch
+):
+    manager, runtime, _, _ = managed
+    backend = runtime.mongo
+    collection = backend.db.settings
+    original = collection.replace_one
+
+    def lose_reply(*args, **kwargs):
+        original(*args, **kwargs)
+        backend._settings_cached = False
+        raise ConnectionFailure("synthetic lost commit response")
+
+    monkeypatch.setattr(collection, "replace_one", lose_reply)
+    with pytest.raises(ConnectionFailure):
+        await manager.add_authenticated_session(
+            0, "Premium", "committed-private-session"
+        )
+    assert manager.session_is_saved("committed-private-session") is True
+    assert manager.session_is_saved("not-committed") is False
+
+    def unavailable(_query):
+        raise ConnectionFailure("synthetic unavailable settings")
+
+    backend._settings_cached = False
+    monkeypatch.setattr(collection, "find_one", unavailable)
+    assert manager.session_is_saved("committed-private-session") is None
+
+
+@pytest.mark.asyncio
+async def test_cancellation_after_commit_never_revokes_saved_session(
+    managed, monkeypatch
+):
+    from tests.telegram.test_premium_login import SESSION, LoginClient
+    from tgdrive.settings.premium_login import PremiumLoginService
+
+    manager, _, _, _ = managed
+    original = management_module.save_document
+    loop = asyncio.get_running_loop()
+    task = asyncio.current_task()
+
+    def cancel_after_commit(*arguments):
+        original(*arguments)
+        loop.call_soon_threadsafe(task.cancel)
+
+    monkeypatch.setattr(management_module, "save_document", cancel_after_commit)
+    client = LoginClient()
+
+    async def disconnect():
+        await asyncio.sleep(0)
+        client.disconnected = True
+
+    client.disconnect = disconnect
+    service = PremiumLoginService(
+        manager.login_api,
+        manager.add_authenticated_session,
+        client_factory=lambda *_: client,
+        is_session_saved=manager.session_is_saved,
+    )
+    try:
+        identity = (await service.begin("owner", 0, "+919876543210", "Premium"))[
+            "challenge_id"
+        ]
+        with pytest.raises(asyncio.CancelledError):
+            await service.verify("owner", identity, code="12345")
+        assert manager.session_is_saved(SESSION) is True
+        assert not client.logged_out
+    finally:
+        await service.close()
+
+
+async def test_cached_names_are_read_only_and_hidden_for_replacement_account(managed):
+    manager, runtime, _, _ = managed
+    old_name = "storage-bot-123456"
+    manager.identity_cache.write(
+        old_name, {"display_name": "Actual Bot", "username": "actual_bot"}
+    )
+    runtime.pool = SimpleNamespace(
+        status=AsyncMock(
+            return_value=(
+                SimpleNamespace(
+                    name=old_name, started=True, healthy=True, connected=True
+                ),
+            )
+        ),
+    )
+    before = await manager.snapshot()
+    assert before["clients"][0]["display_name"] == "Actual Bot"
+    assert before["clients"][0]["username"] == "actual_bot"
+    assert before["clients"][0]["label"] == "Storage bot 1"
+    result = await manager.save(
+        SettingsChange.model_validate(
+            {
+                "expected_revision": 0,
+                "clients": [
+                    {
+                        "id": before["clients"][0]["id"],
+                        "label": "Replacement",
+                        "kind": "bot",
+                        "credential": SECOND_TOKEN,
+                    }
+                ],
+            }
+        )
+    )
+    assert result["clients"][0]["display_name"] is None
+    assert result["clients"][0]["username"] is None
+
+
+def test_refresh_names_requires_owner_and_same_origin_without_saving_configuration(
+    managed,
+):
+    from tests.support.app_fixtures import login
+
+    manager, runtime, settings, _ = managed
+    manager.verifier = AsyncMock(return_value="storage-bot-123456")
+    runtime.pool = SimpleNamespace(status=AsyncMock(return_value=()))
+    with TestClient(
+        create_app(settings, runtime=runtime), base_url="https://testserver"
+    ) as client:
+        route = "/api/v1/settings/refresh"
+        assert client.post(route, json={}).status_code == 401
+        login(client)
+        assert (
+            client.post(
+                route, json={}, headers={"Origin": "https://other.example"}
+            ).status_code
+            == 403
+        )
+        assert manager.verifier.call_count == 0
+        response = client.post(route, json={})
+        assert response.status_code == 202
+        assert response.headers["cache-control"] == "no-store"
+        assert response.json()["revision"] == 0
+        assert response.json()["restart_required"] is False
+        assert TOKEN not in response.text
+
+        async def completed_checks():
+            await asyncio.gather(*manager._check_tasks)
+
+        # The endpoint accepts background work; a GET need not complete it.
+        client.portal.call(completed_checks)
+        client.get("/api/v1/settings")
+        assert manager.verifier.call_count == 1
+        assert read_document(settings.resolved_data_dir) is None
+
+
+@pytest.mark.asyncio
+async def test_refresh_checks_all_enabled_saved_clients_bounded_and_isolates_failure(
+    managed,
+):
+    manager, runtime, _, _ = managed
+    rows = []
+    for index in range(5):
+        rows.append(
+            ManagedClient(
+                id=f"bot-{index}",
+                label=f"Bot {index}",
+                kind="bot",
+                enabled=index != 4,
+                credential=SecretStr(f"{123450 + index}:" + "x" * 30),
+            )
+        )
+    manager.active = rows
+    runtime.pool = SimpleNamespace(status=AsyncMock(return_value=()))
+    release = asyncio.Event()
+    both_entered = asyncio.Event()
+    entered = 0
+    peak = 0
+    calls = []
+
+    async def verify(_id, _hash, row, _channel):
+        nonlocal entered, peak
+        calls.append(row.id)
+        entered += 1
+        peak = max(peak, entered)
+        if entered == 2:
+            both_entered.set()
+        try:
+            await release.wait()
+            if row.id == "bot-1":
+                raise SettingsProblem("Storage Channel permission is missing")
+            return "storage-bot-" + row.credential.get_secret_value().split(":")[0]
+        finally:
+            entered -= 1
+
+    manager.verifier = verify
+    first = await manager.refresh_connections()
+    assert any(
+        row.get("connection_check") in {"queued", "checking"}
+        for row in first["clients"]
+    )
+    await manager.refresh_connections()
+    await asyncio.wait_for(both_entered.wait(), 2)
+    assert peak == 2
+    release.set()
+    await asyncio.gather(*manager._check_tasks)
+    result = await manager.snapshot()
+    assert sorted(calls) == ["bot-0", "bot-1", "bot-2", "bot-3"]
+    assert peak == 2
+    assert result["clients"][1]["connection_check"] == "failed"
+    assert (
+        result["clients"][1]["connection_check_error"]
+        == "Storage Channel permission is missing"
+    )
+    assert result["clients"][0]["connection_check"] == "passed"
+    assert "connection_check" not in result["clients"][4]
+    assert result["revision"] == 0
+    assert not result["restart_required"]
+
+
+@pytest.mark.asyncio
+async def test_refresh_cancels_on_close_and_hides_results_after_configuration_change(
+    managed,
+):
+    manager, _, _, _ = managed
+    entered = asyncio.Event()
+    cancelled = asyncio.Event()
+
+    async def verify(*_args):
+        entered.set()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            cancelled.set()
+
+    manager.verifier = verify
+    await manager.refresh_connections()
+    await entered.wait()
+    await manager.close()
+    assert cancelled.is_set()
+    assert not manager._check_tasks
+    manager._checks_revision = 99
+    assert "connection_check" not in (await manager.snapshot())["clients"][0]
+
+
+@pytest.mark.asyncio
+async def test_refresh_preserves_flood_wait_and_never_exposes_raw_error(managed):
+    manager, runtime, _, _ = managed
+    runtime.pool = SimpleNamespace(
+        status=AsyncMock(return_value=()), defer_client=AsyncMock()
+    )
+    problem = SettingsProblem("Telegram temporarily limited verification")
+    problem.retry_after = 120
+    manager.verifier = AsyncMock(side_effect=problem)
+    await manager.refresh_connections()
+    for _ in range(100):
+        if runtime.pool.defer_client.await_count:
+            break
+        await asyncio.sleep(0.01)
+    row = (await manager.snapshot())["clients"][0]
+    assert row["connection_check"] == "waiting"
+    deadline = row["connection_retry_at"]
+    assert manager.identity_cache.retry_at("storage-bot-123456") == deadline
+    runtime.pool.defer_client.assert_awaited_once_with("storage-bot-123456", deadline)
+    assert manager.verifier.await_count == 1
+    await manager.close()
+    manager._refresh_not_before = 0
+    manager.verifier = AsyncMock(side_effect=RuntimeError("secret-token"))
+    # Do not sleep through a persisted wait in this separate error-sanitization check.
+    manager.identity_cache.retry_at = lambda _name: 0
+    await manager.refresh_connections()
+    await asyncio.gather(*manager._check_tasks)
+    result = await manager.snapshot()
+    assert result["clients"][0]["connection_check"] == "failed"
+    assert "secret-token" not in json.dumps(result)
+
+
+@pytest.mark.asyncio
+async def test_refresh_obeys_existing_transfer_pool_wait_before_network_probe(managed):
+    import time
+
+    manager, runtime, _, _ = managed
+    deadline = time.time() + 300
+    runtime.pool = SimpleNamespace(
+        status=AsyncMock(return_value=()),
+        account_retry_at=AsyncMock(return_value=deadline),
+    )
+    manager.verifier = AsyncMock()
+    await manager.refresh_connections()
+    for _ in range(100):
+        if runtime.pool.account_retry_at.await_count:
+            break
+        await asyncio.sleep(0.001)
+    result = await manager.snapshot()
+    assert result["clients"][0]["connection_check"] == "waiting"
+    assert result["clients"][0]["connection_retry_at"] == deadline
+    manager.verifier.assert_not_awaited()
+    await manager.close()
diff --git a/tests/web/test_management_admission.py b/tests/web/test_management_admission.py
new file mode 100644
index 00000000..95e2f46d
--- /dev/null
+++ b/tests/web/test_management_admission.py
@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from io import BytesIO
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+from fastapi import UploadFile
+from fastapi.testclient import TestClient
+
+import tgdrive.transfers.manager as transfer_module
+from tests.support.app_fixtures import FakeRuntime, make_settings
+from tests.transfers.test_transfers import make_manager
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+
+@pytest.mark.asyncio
+async def test_settings_saved_during_async_multipart_admission_never_create_a_job(
+    tmp_path,
+    monkeypatch,
+):
+    manager, store, transport, pool = await make_manager(tmp_path)
+    blocked = False
+
+    async def changed_during_health(*_args):
+        nonlocal blocked
+        blocked = True
+        return 1024
+
+    def check():
+        if blocked:
+            raise SettingsProblem(
+                "Restart required",
+                code="SETTINGS_RESTART_REQUIRED",
+                status=409,
+            )
+
+    manager._check_upload_allowed = check
+    monkeypatch.setattr(transfer_module, "current_upload_limit", changed_during_health)
+    upload = UploadFile(BytesIO(b"hello"), size=5, filename="hello.txt")
+    try:
+        with pytest.raises(SettingsProblem):
+            await manager.receive_browser_upload(upload, "/")
+        assert upload.file.closed
+        assert manager.registry.list() == []
+        assert store.get_directory("/")["contents"] == {}
+        assert not transport.started_upload.is_set()
+    finally:
+        manager.registry.close()
+        store.close()
+        await pool.stop()
+
+
+def test_restart_required_rejects_remote_start_without_source_inspection(tmp_path):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create(tmp_path / "drive.json")
+    runtime = FakeRuntime(store)
+    runtime.connection_manager = SimpleNamespace(
+        restart_required=True, close=AsyncMock()
+    )
+
+    runtime.transfers.inspect_remote = AsyncMock(
+        side_effect=AssertionError("start must not contact the source")
+    )
+    app = create_app(settings, runtime=runtime)
+    try:
+        with TestClient(app, base_url="https://testserver") as client:
+            client.post(
+                "/api/checkPassword",
+                json={
+                    "pass": settings.admin_password.get_secret_value(),
+                },
+            )
+            result = client.post(
+                "/api/startFileDownloadFromUrl",
+                json={
+                    "url": "https://example.com/source.bin",
+                    "path": "/",
+                },
+            )
+            assert result.status_code == 409
+            assert result.json()["code"] == "SETTINGS_RESTART_REQUIRED"
+            runtime.transfers.inspect_remote.assert_not_awaited()
+            assert runtime.transfers.remote_requests == []
+            assert runtime.transfers.registry.list() == []
+    finally:
+        store.close()
diff --git a/tests/web/test_multi_shares.py b/tests/web/test_multi_shares.py
new file mode 100644
index 00000000..2647a056
--- /dev/null
+++ b/tests/web/test_multi_shares.py
@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+from pydantic import SecretStr
+
+import tests.support.app_fixtures as fixtures
+import tests.web.test_share_update_api as share_update_fixtures
+from tgdrive.core.errors import ValidationError
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.share_links import token_factory
+
+app_client = fixtures.app_client
+share_client = share_update_fixtures.share_client
+
+
+@pytest.mark.parametrize("kind", ["file", "folder"])
+def test_same_item_copy_edit_and_revoke_preserve_other_links(share_client, kind):
+    client, store, _ = share_client
+    if kind == "folder":
+        node = store.create_folder("/", "Client assets")
+        path = "/" + node["id"]
+        child = store.add_file(path, "design.pdf", 12, 42)
+        file_path = path + "/" + child["id"]
+    else:
+        node = store.add_file("/", "design.pdf", 12, 42)
+        path = file_path = "/" + node["id"]
+
+    links = []
+    for label, days in (("Client review", 1), ("Team reference", 30)):
+        response = client.post(
+            "/api/v1/shares",
+            json={"path": path, "label": label, "expires_in_days": days},
+        )
+        assert response.status_code == 201
+        links.append(response.json())
+    first, second = links
+    assert first["id"] != second["id"] and first["auth"] != second["auth"]
+    rows = {row["id"]: row for row in client.get("/api/v1/shares").json()["shares"]}
+    other_before = rows[second["id"]]
+    assert rows[first["id"]]["node_id"] == other_before["node_id"] == node["id"]
+    assert rows[first["id"]]["expires_at"] != other_before["expires_at"]
+    assert rows[first["id"]]["label"] == "Client review"
+    assert other_before["label"] == "Team reference"
+    assert all(rows[link["id"]]["copyable"] for link in links)
+
+    before_copy = store.export()
+    for link in links:
+        response = client.post("/api/v1/shares/link", json={"share_id": link["id"]})
+        assert response.status_code == 200
+        assert response.json()["auth"] == link["auth"]
+    assert store.export() == before_copy
+
+    assert (
+        client.patch(
+            "/api/v1/shares",
+            json={"share_id": first["id"], "label": "Final review", "expires_at": None},
+        ).status_code
+        == 200
+    )
+    edited = {row["id"]: row for row in client.get("/api/v1/shares").json()["shares"]}
+    assert edited[first["id"]]["label"] == "Final review"
+    assert edited[first["id"]]["expires_at"] is None
+    assert edited[second["id"]] == other_before
+    assert all(store.authorize_file(file_path, link["auth"]) for link in links)
+
+    assert (
+        client.request(
+            "DELETE", "/api/v1/shares", json={"share_id": first["id"]}
+        ).status_code
+        == 200
+    )
+    assert not store.authorize_file(file_path, first["auth"])
+    assert store.authorize_file(file_path, second["auth"])
+    remaining = {
+        row["id"]: row for row in client.get("/api/v1/shares").json()["shares"]
+    }
+    assert first["id"] not in remaining
+    assert remaining[second["id"]] == other_before
+    assert (
+        client.post("/api/v1/shares/link", json={"share_id": second["id"]}).json()[
+            "auth"
+        ]
+        == second["auth"]
+    )
+
+
+@pytest.mark.parametrize("kind", ["file", "folder"])
+@pytest.mark.parametrize("unavailable", ["random", "changed-secret", "expired"])
+def test_uncopyable_and_expired_links_never_mint_or_replace_links(
+    share_client, monkeypatch, kind, unavailable
+):
+    client, store, _ = share_client
+    if kind == "folder":
+        node = store.create_folder("/", "Recipient files")
+        path = "/" + node["id"]
+        child = store.add_file(path, "notes.txt", 12, 42)
+        file_path = path + "/" + child["id"]
+    else:
+        node = store.add_file("/", "notes.txt", 12, 42)
+        path = file_path = "/" + node["id"]
+    current_settings = client.app.state.settings
+    original_factory = token_factory(current_settings)
+    factory = (
+        None
+        if unavailable == "random"
+        else token_factory(
+            current_settings.model_copy(
+                update={"session_secret": SecretStr("previous-owner-secret-" * 3)}
+            )
+        )
+        if unavailable == "changed-secret"
+        else original_factory
+    )
+    old_token = store.create_share(path, token_factory=factory, label="Recipient")
+    old_row = store.list_shares(path, token_factory=original_factory)[0]
+    surviving_response = client.post(
+        "/api/v1/shares",
+        json={"path": path, "label": "Independent recipient", "expires_in_days": None},
+    )
+    assert surviving_response.status_code == 201
+    surviving = surviving_response.json()
+    if unavailable == "expired":
+        later = (
+            (
+                datetime.fromisoformat(old_row["expires_at"].replace("Z", "+00:00"))
+                + timedelta(seconds=1)
+            )
+            .isoformat(timespec="seconds")
+            .replace("+00:00", "Z")
+        )
+        monkeypatch.setattr("tgdrive.storage.store._utc_now", lambda: later)
+        monkeypatch.setattr("tgdrive.storage.mongo_store._utc_now", lambda: later)
+
+    before = store.export()
+    response = client.post("/api/v1/shares/link", json={"share_id": old_row["id"]})
+    assert response.status_code == (410 if unavailable == "expired" else 409)
+    if unavailable != "expired":
+        assert response.json()["detail"] == (
+            "The original link URL is unavailable. Existing copies still "
+            "work until this link expires or is revoked."
+        )
+    assert store.export() == before
+    assert store.authorize_file(file_path, old_token) == (unavailable != "expired")
+    assert store.authorize_file(file_path, surviving["auth"])
+    assert (
+        client.post("/api/v1/shares/link", json={"share_id": surviving["id"]}).json()[
+            "auth"
+        ]
+        == surviving["auth"]
+    )
+    assert store.export() == before
+
+
+@pytest.mark.asyncio
+async def test_showcase_seeds_named_copyable_links_with_distinct_expiries(tmp_path):
+    import asyncio
+
+    from tests.support.showcase_data import seed
+
+    async def load_cache(_key, _size, loader):
+        return await loader()
+
+    store = DriveStore.create()
+    settings = fixtures.make_settings(tmp_path)
+    transfers = fixtures.FakeTransfers()
+    runtime = SimpleNamespace(
+        store=store,
+        payloads={113: b"Synthetic PDF content"},
+        transfers=transfers,
+        preloads=SimpleNamespace(
+            cache=SimpleNamespace(
+                register_file=Mock(), get=load_cache, flush=AsyncMock()
+            )
+        ),
+    )
+    try:
+        await seed(runtime, settings)
+        factory = token_factory(settings)
+        rows = store.list_shares(token_factory=factory)
+        assert {row["label"] for row in rows} == {"Project review", "Design handoff"}
+        assert len({row["expires_at"] for row in rows}) == 2
+        assert all(row["copyable"] for row in rows)
+        assert all(
+            store.authorize_file(row["path"], factory(row["id"])) for row in rows
+        )
+    finally:
+        task = getattr(runtime, "showcase_task", None)
+        if task is not None:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+        transfers.registry.close()
+        store.close()
+
+
+def test_independent_links_copy_edit_revoke_and_restore(app_client):
+    client, store, _, settings = app_client
+    fixtures.login(client)
+    folder = store.create_folder("/", "Shared")
+    path = "/" + folder["id"]
+    file = store.add_file(path, "book.epub", 10, 42)
+    file_path = path + "/" + file["id"]
+    first = client.post(
+        "/api/v1/shares", json={"path": path, "label": "Alex", "expires_in_days": 1}
+    ).json()
+    second = client.post(
+        "/api/v1/shares",
+        json={"path": path, "label": "Design team", "expires_in_days": 30},
+    ).json()
+    assert first["auth"] != second["auth"] and first["id"] != second["id"]
+    assert store.authorize_file(file_path, first["auth"])
+    assert store.authorize_file(file_path, second["auth"])
+    assert client.post("/api/v1/shares/link", json={"path": path}).status_code == 409
+    copied = client.post("/api/v1/shares/link", json={"share_id": first["id"]})
+    assert copied.json()["auth"] == first["auth"]
+    expiry = (datetime.now(UTC) + timedelta(days=90)).isoformat()
+    assert (
+        client.patch(
+            "/api/v1/shares",
+            json={
+                "share_id": first["id"],
+                "label": "Alex review",
+                "expires_at": expiry,
+            },
+        ).status_code
+        == 200
+    )
+    rows = client.get("/api/v1/shares").json()["shares"]
+    assert next(r for r in rows if r["id"] == first["id"])["label"] == "Alex review"
+    assert next(r for r in rows if r["id"] == second["id"])["label"] == "Design team"
+    restored = DriveStore._from_payload(store.export())
+    try:
+        assert restored.authorize_file(file_path, first["auth"])
+        assert restored.authorize_file(file_path, second["auth"])
+        assert restored.list_shares(token_factory=token_factory(settings))[0][
+            "copyable"
+        ]
+    finally:
+        restored.close()
+    assert (
+        client.request(
+            "DELETE", "/api/v1/shares", json={"share_id": first["id"]}
+        ).status_code
+        == 200
+    )
+    assert not store.authorize_file(file_path, first["auth"])
+    assert store.authorize_file(file_path, second["auth"])
+    assert (
+        client.post("/api/v1/shares/link", json={"share_id": first["id"]}).status_code
+        == 410
+    )
+    store.set_trashed(path, True)
+    assert not store.authorize_file(file_path, second["auth"])
+
+
+def test_custom_expiry_labels_authorization_and_download_link_scope(app_client):
+    client, store, _, _ = app_client
+    file = store.add_file("/", "report.pdf", 11, 10)
+    path = "/" + file["id"]
+    assert client.post("/api/v1/shares", json={"path": path}).status_code == 401
+    fixtures.login(client)
+    expiry = (datetime.now(UTC) + timedelta(hours=2)).isoformat()
+    response = client.post(
+        "/api/v1/shares", json={"path": path, "label": "Pat", "expires_at": expiry}
+    )
+    assert response.status_code == 201
+    personal = response.json()
+    download = client.post("/api/v1/download-links", json={"path": path})
+    assert download.status_code == 200
+    assert personal["auth"] not in download.json()["url"]
+    assert (
+        client.post("/api/v1/download-links", json={"path": path}).json()["url"]
+        == download.json()["url"]
+    )
+    assert store.authorize_file(path, personal["auth"])
+    assert (
+        client.post(
+            "/api/v1/shares", json={"path": path, "label": "x" * 81}
+        ).status_code
+        == 422
+    )
+    assert (
+        client.post(
+            "/api/v1/shares", json={"path": path, "expires_at": "2000-01-01T00:00:00Z"}
+        ).status_code
+        == 400
+    )
+    assert (
+        client.post(
+            "/api/v1/shares", json={"path": path, "expires_at": "2035-01-01T00:00:00"}
+        ).status_code
+        == 400
+    )
+    assert client.request("DELETE", "/api/v1/shares", json={}).status_code == 422
+    client.post("/api/logout")
+    assert (
+        client.patch(
+            "/api/v1/shares", json={"share_id": personal["id"], "label": "stolen"}
+        ).status_code
+        == 401
+    )
+
+
+def test_invalid_labels_and_legacy_rotation_are_explicit():
+    store = DriveStore.create()
+    folder = store.create_folder("/", "Share")
+    path = "/" + folder["id"]
+    first = store.create_share(path)
+    second = store.create_share(path)
+    with pytest.raises(ValidationError):
+        store.create_share(path, label="x\x00y")
+    replacement = store.create_share(path, replace_existing=True)
+    assert not store.authorize_directory(path, first)
+    assert not store.authorize_directory(path, second)
+    assert store.authorize_directory(path, replacement) == path
diff --git a/tests/web/test_rename.py b/tests/web/test_rename.py
new file mode 100644
index 00000000..7d7290e5
--- /dev/null
+++ b/tests/web/test_rename.py
@@ -0,0 +1,124 @@
+"""File renames preserve extensions in both catalog implementations."""
+
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+
+from tgdrive.core.errors import InvalidNameError
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.storage.store import ROOT_ID, SCHEMA_VERSION, DriveStore
+
+
+@pytest.fixture(params=["sqlite", "mongodb"])
+def store(request, monkeypatch):
+    if request.param == "sqlite":
+        instance = DriveStore.create()
+    else:
+        # Keep MongoDB's actual transaction and rename behavior; replace only
+        # loading/index setup and cloud persistence for these domain checks.
+        def load(instance):
+            instance._committed = {
+                "metadata": {
+                    "schema_version": SCHEMA_VERSION,
+                    "drive_id": "rename-test",
+                    "revision": 1,
+                    "backed_up_revision": 1,
+                    "generation": 0,
+                    "storage_channel_id": None,
+                },
+                "nodes": {ROOT_ID: MongoStore._node(ROOT_ID, None, "/", "folder")},
+                "shares": {},
+                "operations": {},
+                "deletions": {},
+                "preparations": {},
+            }
+
+        monkeypatch.setattr(MongoStore, "_reload", load)
+        monkeypatch.setattr(MongoStore, "_indexes", Mock())
+        monkeypatch.setattr(MongoStore, "_commit", Mock())
+        instance = MongoStore(SimpleNamespace(check_owner=Mock()))
+    try:
+        yield instance
+    finally:
+        instance.close()
+
+
+@pytest.mark.parametrize(
+    ("original", "renamed"),
+    [
+        ("earth.mp4", "earth"),
+        ("earth.mp4", "earth.pdf"),
+        ("earth.mp4", "earth.mp4.exe"),
+        ("earth.mp4", "earth."),
+        ("earth.mp4", ".mp4"),
+        ("archive.tar.gz", "archive.tar"),
+        (".config.json", ".config"),
+        ("image.svg", "image.\u017fvg"),
+        ("file.ss", "file.\u00df"),
+    ],
+)
+def test_file_extension_change_is_rejected_without_mutation(store, original, renamed):
+    item = store.add_file("/", original, 123, 456)
+    path = "/" + item["id"]
+    before = store.export()
+    revision = store.revision
+    if isinstance(store, MongoStore):
+        store._commit.reset_mock()
+
+    with pytest.raises(InvalidNameError, match="extension cannot be changed"):
+        store.rename(path, renamed)
+
+    assert store.export() == before
+    assert store.revision == revision
+    assert store.get_file(path)["name"] == original
+    if isinstance(store, MongoStore):
+        store._commit.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    ("original", "renamed"),
+    [
+        ("earth.mp4", "planet.mp4"),
+        ("earth.mp4", "EARTH.MP4"),
+        ("earth.MP4", "planet.mp4"),
+        ("earth.mp4", "earth.final.mp4"),
+        ("archive.tar.gz", "backup.gz"),
+        (".config.json", ".settings.json"),
+        ("README", "NOTES"),
+        ("earth", "earth.mp4"),
+        (".env", ".env.local"),
+        (".env", "settings"),
+        ("trailing.", "repaired.txt"),
+    ],
+)
+def test_file_rename_preserves_metadata_and_accepts_supported_names(
+    store, original, renamed
+):
+    item = store.add_file("/", original, 123, 456)
+    path = "/" + item["id"]
+    before = store.get_file(path)
+    revision = store.revision
+
+    assert store.rename(path, renamed)["name"] == renamed
+    assert store.get_file(path) == before | {"name": renamed}
+    assert store.revision == revision + 1
+
+
+def test_unchanged_file_name_does_not_bump_revision(store):
+    item = store.add_file("/", "earth.mp4", 123, 456)
+    before = store.export()
+
+    assert store.rename("/" + item["id"], "earth.mp4")["name"] == "earth.mp4"
+    assert store.export() == before
+
+
+@pytest.mark.parametrize("renamed", ["archive", "archive.zip"])
+def test_folder_rename_can_change_or_remove_suffix(store, renamed):
+    item = store.create_folder("/", "photos.mp4")
+    path = "/" + item["id"]
+    child = store.add_file(path, "earth.mp4", 123, 456)
+
+    assert store.rename(path, renamed)["name"] == renamed
+    assert store.get_directory(path)["name"] == renamed
+    assert store.get_file(path + "/" + child["id"])["name"] == "earth.mp4"
diff --git a/tests/web/test_scoped_search.py b/tests/web/test_scoped_search.py
new file mode 100644
index 00000000..494b7823
--- /dev/null
+++ b/tests/web/test_scoped_search.py
@@ -0,0 +1,53 @@
+"""Search contexts must never broaden a Trash or owner-only listing."""
+
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tgdrive.storage.store import DriveStore
+from tgdrive.web.app import create_app
+
+
+def test_trash_search_is_owner_only_and_does_not_include_active_or_hidden_children(
+    tmp_path,
+):
+    store = DriveStore.create(tmp_path / "drive.sqlite3")
+    active = store.add_file("/", "résumé active.txt", 1, 10)
+    source = store.create_folder("/", "書庫")
+    nested_source = store.create_folder("/" + source["id"], "Reference")
+    nested_path = "/" + source["id"] + "/" + nested_source["id"]
+    deleted = store.add_file(nested_path, "résumé deleted.txt", 2, 10)
+    folder = store.create_folder("/", "Old documents")
+    child = store.add_file("/" + folder["id"], "résumé child.txt", 3, 10)
+    store.set_trashed(nested_path + "/" + deleted["id"], True)
+    store.set_trashed("/" + folder["id"], True)
+    runtime = FakeRuntime(store)
+    try:
+        with TestClient(
+            create_app(make_settings(tmp_path), runtime=runtime),
+            base_url="https://testserver",
+        ) as client:
+            assert (
+                client.get("/api/v1/trash", params={"q": "résumé"}).status_code == 401
+            )
+            login(client)
+            result = client.get("/api/v1/trash", params={"q": "RE\u0301SUME\u0301"})
+            assert result.status_code == 200
+            assert result.headers["cache-control"] == "no-store"
+            contents = result.json()["data"]["contents"]
+            assert set(contents) == {deleted["id"]}
+            assert contents[deleted["id"]]["parent_names"] == ["書庫", "Reference"]
+            assert contents[deleted["id"]]["path"] == nested_path
+            assert active["id"] not in result.text and child["id"] not in result.text
+            assert len(client.get("/api/v1/trash").json()["data"]["contents"]) == 2
+            assert (
+                client.get("/api/v1/trash", params={"q": "x" * 256}).status_code == 422
+            )
+            assert (
+                client.get("/api/v1/trash", params={"q": "missing"}).json()["data"][
+                    "contents"
+                ]
+                == {}
+            )
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
diff --git a/tests/web/test_search.py b/tests/web/test_search.py
new file mode 100644
index 00000000..6fe5832b
--- /dev/null
+++ b/tests/web/test_search.py
@@ -0,0 +1,353 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from threading import local
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, make_settings
+from tgdrive.core.errors import ValidationError
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.storage.store import MAX_SEARCH_OFFSET, DriveStore
+from tgdrive.web.app import create_app
+
+
+@pytest.fixture
+def store():
+    result = DriveStore.create()
+    yield result
+    result.close()
+
+
+@pytest.fixture
+def search_client(tmp_path):
+    settings = make_settings(tmp_path)
+    store = DriveStore.create()
+    runtime = FakeRuntime(store)
+    app = create_app(settings, runtime=runtime)
+    with TestClient(app, base_url="https://testserver") as client:
+        yield client, store, runtime
+    store.close()
+    runtime.transfers.registry.close()
+
+
+def full(record):
+    return record["path"].rstrip("/") + "/" + record["id"]
+
+
+def owner(client):
+    assert (
+        client.post(
+            "/api/checkPassword", json={"pass": "correct horse battery staple"}
+        ).status_code
+        == 200
+    )
+
+
+@pytest.mark.parametrize(
+    ("name", "query"),
+    [
+        ("Straße.txt", "STRASSE"),
+        ("Café.txt", "CAFE\u0301"),
+        ("План.txt", "ПЛАН"),
+        ("κόσμος.txt", "ΚΌΣΜΟΣ"),
+        ("100% ready.txt", "%"),
+        ("under_score.txt", "_"),
+        ("literal[?]*.txt", "[?]*"),
+        ("payload' OR 1=1 --.txt", "' OR 1=1 --"),
+    ],
+)
+def test_unicode_normalized_casefold_and_sql_special_characters_are_literal(
+    store, name, query
+):
+    match = store.add_file("/", name, 1, 3)
+    store.add_file("/", "Unrelated plain file.txt", 2, 4)
+    page = store.search_page(query)
+    assert [row["id"] for row in page["items"]] == [match["id"]]
+    assert page["items"][0]["parent_names"] == []
+    assert not page["has_more"] and page["next_offset"] is None
+
+
+def test_filename_only_search_prunes_entire_trash_branch_and_builds_human_parents(
+    store,
+):
+    parent = store.create_folder("/", "Projects")
+    nested = store.create_folder(full(parent), "Café reports")
+    live = store.add_file(full(nested), "Quarterly report.csv", 1, 3)
+    trash = store.create_folder("/", "Old report folder")
+    hidden = store.add_file(full(trash), "Quarterly report private.csv", 2, 4)
+    deeper = store.create_folder(full(trash), "Nested report folder")
+    store.add_file(full(deeper), "report deep.txt", 3, 5)
+    store.set_trashed(full(trash), True)
+    page = store.search_page("report")
+    assert {row["id"] for row in page["items"]} == {nested["id"], live["id"]}
+    result = next(row for row in page["items"] if row["id"] == live["id"])
+    assert result["parent_names"] == ["Projects", "Café reports"]
+    assert result["path"] == full(nested)
+    assert {row["id"] for row in store.search_page("Projects")["items"]} == {
+        parent["id"]
+    }
+    assert hidden["id"] in store.search("report", include_trashed=True)
+
+
+def search_implementation(store, implementation):
+    if implementation == "sqlite":
+        return store
+    # Mongo search reads its consistent catalog cache. Exercise that real read
+    # path without requiring a running MongoDB service for ordering unit tests.
+    reader = object.__new__(MongoStore)
+    reader._local = local()
+    reader._closed = False
+    with store._transaction() as db:
+        reader._committed = {
+            "nodes": {row["id"]: dict(row) for row in db.execute("SELECT * FROM nodes")}
+        }
+    return reader
+
+
+@pytest.mark.parametrize("implementation", ["sqlite", "mongo-cache"])
+def test_sort_and_pagination_apply_globally_with_deterministic_ties(
+    store, implementation
+):
+    folder = store.create_folder("/", "z report folder")
+    records = [
+        store.add_file("/", name, index + 1, size)
+        for index, (name, size) in enumerate(
+            [
+                ("z report.txt", 1),
+                ("a report.txt", 100),
+                ("m report.txt", 100),
+            ]
+        )
+    ]
+    with store._transaction(write=True) as db:
+        for index, row in enumerate(records):
+            timestamp = datetime(2020 + index, 1, 1, tzinfo=UTC).isoformat()
+            db.execute(
+                "UPDATE nodes SET upload_date=? WHERE id=?", (timestamp, row["id"])
+            )
+    target = search_implementation(store, implementation)
+    expected = {
+        ("name", None): [1, 2, 0],
+        ("name", "asc"): [1, 2, 0],
+        ("name", "desc"): [0, 2, 1],
+        ("size", None): [1, 2, 0],
+        ("size", "desc"): [1, 2, 0],
+        ("size", "asc"): [0, 1, 2],
+        ("date", None): [2, 1, 0],
+        ("date", "desc"): [2, 1, 0],
+        ("date", "asc"): [0, 1, 2],
+    }
+    for (sort, order), indices in expected.items():
+        identities = [folder["id"], *[records[index]["id"] for index in indices]]
+        first = target.search_page("report", limit=2, sort=sort, order=order)
+        assert first["has_more"] and first["next_offset"] == 2
+        second = target.search_page(
+            "report", offset=first["next_offset"], limit=2, sort=sort, order=order
+        )
+        assert not second["has_more"] and second["next_offset"] is None
+        assert [row["id"] for row in first["items"] + second["items"]] == identities
+    assert target.search_page("report", offset=MAX_SEARCH_OFFSET)["items"] == []
+
+
+@pytest.mark.parametrize("implementation", ["sqlite", "mongo-cache"])
+@pytest.mark.parametrize("sort", ["name", "date", "size"])
+@pytest.mark.parametrize("order", ["asc", "desc"])
+def test_equal_search_keys_keep_stable_id_order_and_hidden_branches_stay_hidden(
+    store, implementation, sort, order
+):
+    parents = [store.create_folder("/", name) for name in ("One", "Two", "Private")]
+    records = [
+        store.add_file(full(parent), "report.txt", index + 1, 10)
+        for index, parent in enumerate(parents)
+    ]
+    store.set_trashed(full(parents[2]), True)
+    with store._transaction(write=True) as db:
+        db.execute("UPDATE nodes SET upload_date='2025-01-01T00:00:00Z'")
+    target = search_implementation(store, implementation)
+    pages = [
+        target.search_page("report", sort=sort, order=order, limit=1, offset=offset)
+        for offset in range(2)
+    ]
+    assert [page["items"][0]["id"] for page in pages] == sorted(
+        row["id"] for row in records[:2]
+    )
+    assert pages[0]["has_more"] and not pages[1]["has_more"]
+
+
+@pytest.mark.parametrize("implementation", ["sqlite", "mongo-cache"])
+def test_trash_lists_human_parent_names_without_hidden_children(store, implementation):
+    parent = store.create_folder("/", "Books")
+    nested = store.create_folder(full(parent), "Reference")
+    root_file = store.add_file("/", "root-deleted.txt", 1, 10)
+    nested_file = store.add_file(full(nested), "nested-deleted.txt", 2, 10)
+    hidden = store.add_file(full(nested), "active.txt", 3, 10)
+    trashed_folder = store.create_folder(full(parent), "Old")
+    child = store.add_file(full(trashed_folder), "hidden-deleted.txt", 4, 10)
+    for row in (root_file, nested_file, trashed_folder, child):
+        store.set_trashed(full(row), True)
+    target = search_implementation(store, implementation)
+    items = target.list_trash()
+    assert set(items) == {root_file["id"], nested_file["id"], trashed_folder["id"]}
+    assert items[root_file["id"]]["parent_names"] == []
+    assert items[nested_file["id"]]["parent_names"] == ["Books", "Reference"]
+    assert items[nested_file["id"]]["path"] == full(nested)
+    assert items[trashed_folder["id"]]["parent_names"] == ["Books"]
+    assert hidden["id"] not in items and child["id"] not in items
+    assert list(target.list_trash("nested")) == [nested_file["id"]]
+
+
+def test_search_has_one_data_query_instead_of_per_result_ancestry_queries(
+    store, monkeypatch
+):
+    folder = store.create_folder("/", "Nested")
+    for index in range(40):
+        store.add_file(full(folder), f"Report {index:02d}.txt", index + 1, index)
+
+    def forbidden(*_args, **_kwargs):
+        raise AssertionError("Search must not resolve ancestry per result")
+
+    monkeypatch.setattr(store, "_path_for_id", forbidden)
+    monkeypatch.setattr(store, "_resolve", forbidden)
+    statements = []
+    store._db.set_trace_callback(statements.append)
+    try:
+        page = store.search_page("report", limit=10)
+    finally:
+        store._db.set_trace_callback(None)
+    assert len(page["items"]) == 10 and page["has_more"]
+    assert len(statements) == 3  # BEGIN, one recursive read, COMMIT.
+
+
+@pytest.mark.parametrize(
+    ("query", "options"),
+    [
+        ("", {}),
+        ("   ", {}),
+        ("x" * 256, {}),
+        ("a\x00b", {}),
+        ("a\nb", {}),
+        ("file", {"offset": -1}),
+        ("file", {"offset": MAX_SEARCH_OFFSET + 1}),
+        ("file", {"limit": 0}),
+        ("file", {"limit": 501}),
+        ("file", {"limit": True}),
+        ("file", {"sort": "name; DROP TABLE nodes"}),
+        ("file", {"order": "ASC"}),
+        ("file", {"order": "desc; DROP TABLE nodes"}),
+        ("file", {"order": []}),
+    ],
+)
+def test_search_validates_query_pagination_and_sort(store, query, options):
+    with pytest.raises(ValidationError):
+        store.search_page(query, **options)
+
+
+def test_api_owner_only_search_does_not_accept_public_share_tokens(search_client):
+    client, store, _ = search_client
+    shared = store.create_folder("/", "Public")
+    public = store.add_file(full(shared), "report shared.txt", 1, 3)
+    private = store.add_file("/", "report private.txt", 2, 4)
+    token = store.create_share(full(shared))
+    assert (
+        client.get("/api/v1/search", params={"q": "report", "auth": token}).status_code
+        == 401
+    )
+    denied = client.post(
+        "/api/getDirectory", json={"path": "/search_report", "auth": token}
+    )
+    assert denied.status_code == 401
+    assert "report private" not in denied.text
+    owner(client)
+    response = client.get("/api/v1/search", params={"q": "REPORT", "limit": 1})
+    assert (
+        response.status_code == 200 and response.headers["cache-control"] == "no-store"
+    )
+    first = response.json()
+    assert first["has_more"] and first["next_offset"] == 1
+    second = client.get(
+        "/api/v1/search", params={"q": "REPORT", "offset": 1, "limit": 1}
+    ).json()
+    assert {item["id"] for item in first["items"] + second["items"]} == {
+        public["id"],
+        private["id"],
+    }
+    assert not second["has_more"]
+    assert "message_id" not in str(first)
+
+
+@pytest.mark.parametrize(
+    "parameters",
+    [
+        {"q": ""},
+        {"q": " "},
+        {"q": "x" * 256},
+        {"q": "a\x00b"},
+        {"q": "report", "limit": 201},
+        {"q": "report", "offset": -1},
+        {"q": "report", "sort": "modified"},
+        {"q": "report", "order": "ascending"},
+    ],
+)
+def test_api_rejects_invalid_search_inputs(search_client, parameters):
+    client, _, _ = search_client
+    owner(client)
+    assert client.get("/api/v1/search", params=parameters).status_code == 422
+
+
+def test_api_direction_applies_before_offset_pagination(search_client):
+    client, store, _ = search_client
+    folder = store.create_folder("/", "a report folder")
+    first = store.add_file("/", "a report.txt", 1, 10)
+    last = store.add_file("/", "z report.txt", 2, 20)
+    owner(client)
+    for sort in ("name", "size"):
+        response = client.get(
+            "/api/v1/search",
+            params={"q": "report", "sort": sort, "order": "desc", "limit": 2},
+        )
+        assert response.status_code == 200
+        page = response.json()
+        assert [item["id"] for item in page["items"]] == [folder["id"], last["id"]]
+        response = client.get(
+            "/api/v1/search",
+            params={
+                "q": "report",
+                "sort": sort,
+                "order": "desc",
+                "limit": 2,
+                "offset": page["next_offset"],
+            },
+        )
+        assert response.status_code == 200
+        assert [item["id"] for item in response.json()["items"]] == [first["id"]]
+
+
+def test_legacy_search_is_bounded_and_exposes_more_results_instead_of_fake_total(
+    search_client,
+):
+    client, store, _ = search_client
+    for index in range(502):
+        store.add_file("/", f"Report {index:03d}.txt", index + 1, index)
+    owner(client)
+    response = client.post("/api/getDirectory", json={"path": "/search_Report"})
+    assert response.status_code == 200
+    data = response.json()["data"]
+    assert len(data["contents"]) == 500
+    assert data["search"] == {"query": "Report", "has_more": True, "next_offset": 500}
+    assert "total" not in data["search"]
+    assert len(store.search("report")) == 500
+
+
+def test_search_remains_readable_while_restart_required(search_client):
+    client, store, runtime = search_client
+    store.add_file("/", "report.txt", 1, 3)
+    owner(client)
+    from types import SimpleNamespace
+    from unittest.mock import AsyncMock
+
+    runtime.connection_manager = SimpleNamespace(
+        restart_required=True, close=AsyncMock()
+    )
+    assert client.get("/api/v1/search", params={"q": "report"}).status_code == 200
diff --git a/tests/web/test_security.py b/tests/web/test_security.py
new file mode 100644
index 00000000..033970ce
--- /dev/null
+++ b/tests/web/test_security.py
@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import pytest
+
+from tgdrive.core.security import (
+    InvalidSession,
+    LoginLimiter,
+    SessionManager,
+    safe_name,
+    verify_password,
+)
+
+
+def test_session_round_trip_and_expiry() -> None:
+    manager = SessionManager(b"k" * 32, ttl_seconds=300)
+    token = manager.create(now=1_000)
+
+    payload = manager.verify(token, now=1_299)
+    assert payload["iat"] == 1_000
+
+    with pytest.raises(InvalidSession, match="expired"):
+        manager.verify(token, now=1_300)
+    with pytest.raises(InvalidSession, match="expired"):
+        manager.verify(token, now=1_301)
+
+
+def test_session_rejects_tampering_and_malformed_data() -> None:
+    manager = SessionManager(b"k" * 32, ttl_seconds=300)
+    token = manager.create(now=1_000)
+    payload, signature = token.split(".")
+
+    with pytest.raises(InvalidSession):
+        manager.verify(f"{payload}x.{signature}", now=1_001)
+    with pytest.raises(InvalidSession):
+        manager.verify("not-a-session", now=1_001)
+
+
+def test_login_limiter_is_a_sliding_window() -> None:
+    limiter = LoginLimiter(attempts=2, window_seconds=10)
+
+    limiter.failure("client", now=1.0)
+    assert limiter.check("client", now=2.0).allowed
+    limiter.failure("client", now=2.0)
+    decision = limiter.check("client", now=3.0)
+    assert not decision.allowed
+    assert decision.retry_after == 8
+    assert limiter.check("client", now=12.1).allowed
+
+
+def test_success_clears_login_failures() -> None:
+    limiter = LoginLimiter(attempts=1, window_seconds=10)
+    limiter.failure("client", now=1.0)
+    limiter.success("client")
+    assert limiter.check("client", now=2.0).allowed
+
+
+def test_login_limiter_bounds_unique_client_state() -> None:
+    limiter = LoginLimiter(attempts=1, window_seconds=10, max_clients=2)
+    limiter.failure("first", now=1.0)
+    limiter.failure("second", now=1.0)
+    limiter.failure("third", now=1.0)
+
+    assert limiter.check("first", now=2.0).allowed
+
+
+def test_safe_name_removes_paths_controls_and_dangerous_empty_names() -> None:
+    assert safe_name("../../folder\\report.txt") == "report.txt"
+    assert safe_name("\r\n") == "file"
+    assert safe_name("..") == "file"
+    assert safe_name(" report + 100%.txt ") == "report + 100%.txt"
+
+
+def test_password_comparison() -> None:
+    assert verify_password("secret", "secret")
+    assert not verify_password("secret", "other")
+
+
+def test_mongodb_sessions_support_concurrent_range_checks_and_logins():
+    from concurrent.futures import ThreadPoolExecutor
+    from threading import Barrier, RLock
+    from types import SimpleNamespace
+
+    class Sessions:
+        """Thread-safe MongoDB collection double; no external database is used."""
+
+        def __init__(self):
+            self.rows = {}
+            self.lock = RLock()
+
+        def find(self, query):
+            with self.lock:
+                return [
+                    dict(row)
+                    for row in self.rows.values()
+                    if row["expires"] > query["expires"]["$gt"]
+                ]
+
+        def insert_one(self, row):
+            with self.lock:
+                self.rows[row["_id"]] = dict(row)
+
+        def delete_one(self, query):
+            with self.lock:
+                self.rows.pop(query["_id"], None)
+
+        def delete_many(self, query):
+            with self.lock:
+                for identity in [
+                    key
+                    for key, row in self.rows.items()
+                    if row["expires"] <= query["expires"]["$lte"]
+                ]:
+                    del self.rows[identity]
+
+    collection = Sessions()
+    backend = SimpleNamespace(
+        db=SimpleNamespace(sessions=collection),
+        write=lambda target, method, *args: getattr(target, method)(*args),
+    )
+
+    manager = SessionManager(b"k" * 32, ttl_seconds=300, mongo_backend=backend)
+    existing = manager.create(now=1_000)
+    start = Barrier(16)
+
+    def check_and_login(_worker):
+        start.wait(timeout=10)
+        for _ in range(40):
+            assert manager.verify(existing, now=1_001)["iat"] == 1_000
+            token = manager.create(now=1_001)
+            assert manager.verify(token, now=1_002)["iat"] == 1_001
+            manager.revoke(token)
+            with pytest.raises(InvalidSession, match="revoked"):
+                manager.verify(token, now=1_002)
+
+    try:
+        with ThreadPoolExecutor(max_workers=16) as workers:
+            list(workers.map(check_and_login, range(16)))
+        manager.revoke(existing)
+        with pytest.raises(InvalidSession, match="revoked"):
+            manager.verify(existing, now=1_002)
+    finally:
+        manager.close()
diff --git a/tests/web/test_share_update_api.py b/tests/web/test_share_update_api.py
new file mode 100644
index 00000000..7fc6ddd3
--- /dev/null
+++ b/tests/web/test_share_update_api.py
@@ -0,0 +1,170 @@
+"""Partial share edits preserve expiry and concurrent edits in both catalogs."""
+
+from concurrent.futures import ThreadPoolExecutor
+from datetime import UTC, datetime, timedelta
+from threading import Barrier
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+from fastapi.testclient import TestClient
+
+from tests.support.app_fixtures import FakeRuntime, login, make_settings
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.storage.store import ROOT_ID, SCHEMA_VERSION, DriveStore
+from tgdrive.web.app import create_app
+
+
+@pytest.fixture(params=["sqlite", "mongo-cache"])
+def share_client(request, tmp_path, monkeypatch):
+    if request.param == "sqlite":
+        store = DriveStore.create()
+    else:
+        # Exercise MongoStore's real transaction lock and share operations;
+        # replace only cloud loading/indexes/persistence, with no network access.
+        def load(instance):
+            instance._committed = {
+                "metadata": {
+                    "schema_version": SCHEMA_VERSION,
+                    "drive_id": "share-update-test",
+                    "revision": 1,
+                    "backed_up_revision": 1,
+                    "generation": 0,
+                    "storage_channel_id": None,
+                },
+                "nodes": {ROOT_ID: MongoStore._node(ROOT_ID, None, "/", "folder")},
+                "shares": {},
+                "operations": {},
+                "deletions": {},
+                "preparations": {},
+            }
+
+        monkeypatch.setattr(MongoStore, "_reload", load)
+        monkeypatch.setattr(MongoStore, "_indexes", Mock())
+        monkeypatch.setattr(MongoStore, "_commit", Mock())
+        store = MongoStore(SimpleNamespace(check_owner=Mock()))
+    runtime = FakeRuntime(store)
+    try:
+        app = create_app(make_settings(tmp_path), runtime=runtime)
+        with TestClient(app, base_url="https://testserver") as client:
+            login(client)
+            node = store.add_file("/", "shared.txt", 123, 4)
+            made = client.post(
+                "/api/v1/shares",
+                json={
+                    "path": "/" + node["id"],
+                    "label": "Recipient",
+                    "expires_in_days": 1,
+                },
+            )
+            assert made.status_code == 201
+            yield client, store, made.json()
+    finally:
+        runtime.transfers.registry.close()
+        store.close()
+
+
+def current_share(client, share_id):
+    response = client.get("/api/v1/shares")
+    assert response.status_code == 200
+    return next(row for row in response.json()["shares"] if row["id"] == share_id)
+
+
+def test_label_only_edit_preserves_expiry_and_eventual_access_denial(
+    share_client, monkeypatch
+):
+    client, _, share = share_client
+    edited = client.patch(
+        "/api/v1/shares", json={"share_id": share["id"], "label": "Renamed"}
+    )
+    assert edited.status_code == 200
+    current = current_share(client, share["id"])
+    assert current["label"] == "Renamed"
+    assert current["expires_at"] == share["expires_at"]
+
+    after_expiry = (
+        (
+            datetime.fromisoformat(share["expires_at"].replace("Z", "+00:00"))
+            + timedelta(seconds=1)
+        )
+        .isoformat(timespec="seconds")
+        .replace("+00:00", "Z")
+    )
+    monkeypatch.setattr("tgdrive.storage.store._utc_now", lambda: after_expiry)
+    monkeypatch.setattr("tgdrive.storage.mongo_store._utc_now", lambda: after_expiry)
+    denied = client.head("/file", params={"path": share["path"], "auth": share["auth"]})
+    assert denied.status_code == 403
+
+
+@pytest.mark.parametrize("never", [False, True])
+def test_expiry_only_edit_preserves_label_and_explicit_null_removes_expiry(
+    share_client, never
+):
+    client, _, share = share_client
+    expiry = None if never else (datetime.now(UTC) + timedelta(days=30)).isoformat()
+    edited = client.patch(
+        "/api/v1/shares", json={"share_id": share["id"], "expires_at": expiry}
+    )
+    assert edited.status_code == 200
+    current = current_share(client, share["id"])
+    assert current["label"] == "Recipient"
+    if never:
+        assert current["expires_at"] is None
+    else:
+        assert current["expires_at"] == (
+            datetime.fromisoformat(expiry)
+            .isoformat(timespec="seconds")
+            .replace("+00:00", "Z")
+        )
+
+
+def test_explicit_empty_label_clears_only_the_label(share_client):
+    client, _, share = share_client
+    edited = client.patch("/api/v1/shares", json={"share_id": share["id"], "label": ""})
+    assert edited.status_code == 200
+    current = current_share(client, share["id"])
+    assert current["label"] == ""
+    assert current["expires_at"] == share["expires_at"]
+
+
+def test_omitting_both_fields_does_not_change_share_or_revision(share_client):
+    client, store, share = share_client
+    before = current_share(client, share["id"])
+    revision = store.revision
+    assert (
+        client.patch("/api/v1/shares", json={"share_id": share["id"]}).status_code
+        == 200
+    )
+    assert current_share(client, share["id"]) == before
+    assert store.revision == revision
+
+
+def test_concurrent_label_and_expiry_edits_preserve_both_changes(
+    share_client, monkeypatch
+):
+    client, store, share = share_client
+    ready = Barrier(2)
+    update = store.update_share
+
+    def together(share_id, **changes):
+        # Both requests reach the store before either writes. Merging old values
+        # in the route would overwrite one request's change at this point.
+        ready.wait(timeout=5)
+        return update(share_id, **changes)
+
+    monkeypatch.setattr(store, "update_share", together)
+    expiry = (datetime.now(UTC) + timedelta(days=30)).isoformat(timespec="seconds")
+    patches = [{"label": "Renamed"}, {"expires_at": expiry}]
+    with ThreadPoolExecutor(max_workers=2) as workers:
+        results = list(
+            workers.map(
+                lambda patch: client.patch(
+                    "/api/v1/shares", json={"share_id": share["id"], **patch}
+                ),
+                patches,
+            )
+        )
+    assert [result.status_code for result in results] == [200, 200]
+    current = current_share(client, share["id"])
+    assert current["label"] == "Renamed"
+    assert current["expires_at"] == expiry.replace("+00:00", "Z")
diff --git a/tests/web/test_starred.py b/tests/web/test_starred.py
new file mode 100644
index 00000000..eefd66a1
--- /dev/null
+++ b/tests/web/test_starred.py
@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import pytest
+
+import tests.support.app_fixtures as fixtures
+from tgdrive.core.errors import ValidationError
+from tgdrive.storage.store import DriveStore
+
+app_client = fixtures.app_client
+
+
+def check_starred(store):
+    folder = store.create_folder("/", "Projects")
+    parent = "/" + folder["id"]
+    file = store.add_file(parent, "Report.pdf", 901, 20)
+    target = parent + "/" + file["id"]
+    store.set_starred(parent, True)
+    store.set_starred(target, True)
+    assert set(store.list_starred()) == {folder["id"], file["id"]}
+    assert store.list_starred("REPORT")[file["id"]]["parent_names"] == ["Projects"]
+    revision = store.revision
+    store.set_starred(target, True)
+    assert store.revision == revision
+    store.rename(target, "Revised.pdf")
+    destination = store.create_folder("/", "Destination")
+    store.move(target, "/" + destination["id"])
+    row = store.list_starred()[file["id"]]
+    assert row["name"] == "Revised.pdf" and row["parent_names"] == ["Destination"]
+    clone = DriveStore._from_payload(store.export())
+    try:
+        assert set(clone.list_starred()) == {folder["id"], file["id"]}
+    finally:
+        clone.close()
+    store.set_trashed("/" + destination["id"], True)
+    assert file["id"] not in store.list_starred()
+    store.set_trashed("/" + destination["id"], False)
+    assert file["id"] in store.list_starred()
+    store.set_starred(store.resolve_id(file["id"]), False)
+    assert set(store.list_starred()) == {folder["id"]}
+    with pytest.raises(ValidationError):
+        store.set_starred(parent, 1)
+
+
+def test_starred_survives_paths_backup_and_reopen(tmp_path):
+    path = tmp_path / "drive.sqlite3"
+    store = DriveStore.create(path)
+    check_starred(store)
+    expected = store.export()
+    store.close()
+    reopened = DriveStore.load(path)
+    assert reopened.export() == expected
+    reopened.close()
+
+
+def test_starred_api_owner_only_and_strict_boolean(app_client):
+    client, store, _, _ = app_client
+    folder = store.create_folder("/", "Star me")
+    path = "/" + folder["id"]
+    assert client.get("/api/v1/starred").status_code == 401
+    fixtures.login(client)
+    assert (
+        client.patch(
+            "/api/v1/starred", json={"path": path, "starred": True}
+        ).status_code
+        == 200
+    )
+    assert folder["id"] in client.get("/api/v1/starred").json()["data"]["contents"]
+    assert client.get("/api/v1/starred?q=missing").json()["data"]["contents"] == {}
+    assert (
+        client.patch("/api/v1/starred", json={"path": path, "starred": 1}).status_code
+        == 422
+    )
+    assert (
+        client.patch(
+            "/api/v1/starred", json={"path": path, "starred": False}
+        ).status_code
+        == 200
+    )
+    assert client.get("/api/v1/starred").json()["data"]["contents"] == {}
diff --git a/tests/web/test_startup_configuration.py b/tests/web/test_startup_configuration.py
new file mode 100644
index 00000000..e16d8828
--- /dev/null
+++ b/tests/web/test_startup_configuration.py
@@ -0,0 +1,33 @@
+"""Startup failures must name the fix without disclosing private inputs."""
+
+import logging
+
+import pytest
+from pydantic import ValidationError
+
+import tgdrive.web.app as application
+from tgdrive.storage.mongo import DatabaseUnavailable
+
+
+@pytest.mark.parametrize("database_failure", [False, True])
+def test_configuration_failure_is_logged_before_the_app_is_created(
+    monkeypatch, caplog, database_failure
+):
+    error = (
+        DatabaseUnavailable("MongoDB is unavailable. Check database access.")
+        if database_failure
+        else ValidationError.from_exception_data(
+            "Settings",
+            [{"type": "missing", "loc": ("MONGODB_URI",), "input": {}}],
+            hide_input=True,
+        )
+    )
+
+    def fail():
+        raise error
+
+    monkeypatch.setattr(application, "configure_logging", lambda *_args: None)
+    monkeypatch.setattr(application, "get_settings", fail)
+    with caplog.at_level(logging.ERROR), pytest.raises(RuntimeError):
+        application.create_app()
+    assert "MongoDB" in caplog.text or "MONGODB_URI" in caplog.text
diff --git a/tgdrive/__init__.py b/tgdrive/__init__.py
new file mode 100755
index 00000000..59ed74b8
--- /dev/null
+++ b/tgdrive/__init__.py
@@ -0,0 +1,7 @@
+"""TGDrive application package."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "2.0.0"
diff --git a/tgdrive/core/__init__.py b/tgdrive/core/__init__.py
new file mode 100644
index 00000000..76b0cce3
--- /dev/null
+++ b/tgdrive/core/__init__.py
@@ -0,0 +1 @@
+"""Application configuration, lifecycle, security, and shared errors."""
diff --git a/tgdrive/core/config.py b/tgdrive/core/config.py
new file mode 100644
index 00000000..fc7c944e
--- /dev/null
+++ b/tgdrive/core/config.py
@@ -0,0 +1,529 @@
+"""Typed, fail-fast application configuration."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from collections.abc import Mapping
+from functools import lru_cache
+from pathlib import Path
+
+from argon2 import Type, extract_parameters
+from argon2.exceptions import InvalidHashError
+from pydantic import Field, SecretStr, ValidationInfo, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_BOT_TOKEN_RE = re.compile(r"^[1-9][0-9]{4,14}:[A-Za-z0-9_-]{20,}$")
+# Conservative document cap in binary MiB; new uploads use it for every account.
+_DEFAULT_BOT_LIMIT = 2000 * 1024**2
+_DEPLOYMENT_ONLY_SETTINGS = frozenset(
+    {"DEMO_MODE", "DEMO_ADMIN_PASSWORD", "DEMO_ADMIN_PASSWORD_HASH"}
+)
+
+
+def _csv(value: str) -> tuple[str, ...]:
+    return tuple(part.strip() for part in value.split(",") if part.strip())
+
+
+def _should_restore_setting(name: str, configured: Mapping[str, object]) -> bool:
+    """Fill a missing setting without replacing deployment access policy.
+
+    A configured plaintext owner password also takes precedence over a saved
+    password hash, so credential rotation cannot revive the previous password.
+    """
+    if name in _DEPLOYMENT_ONLY_SETTINGS:
+        return False
+    if configured.get(name) not in (None, ""):
+        return False
+    return not (name == "ADMIN_PASSWORD_HASH" and configured.get("ADMIN_PASSWORD"))
+
+
+class Settings(BaseSettings):
+    """Validated deployment configuration and saved Telegram connections.
+
+    Explicit constructor values take priority. Saved connection settings precede
+    environment variables and ``.env``; recovery settings fill missing values.
+    Secret values are represented by :class:`~pydantic.SecretStr`, which keeps
+    accidental logging and validation errors from exposing credentials.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+        validate_default=True,
+        hide_input_in_errors=True,
+    )
+
+    mongodb_uri: SecretStr = Field(alias="MONGODB_URI")
+    mongodb_database: str = Field(
+        default="tgdrive", alias="MONGODB_DATABASE", pattern=r"^[A-Za-z0-9_-]{1,63}$"
+    )
+    mongodb_backup_seconds: int = Field(
+        default=3600, alias="MONGODB_BACKUP_SECONDS", ge=60, le=604800
+    )
+    mongodb_backup_key: SecretStr | None = Field(
+        default=None, alias="MONGODB_BACKUP_KEY"
+    )
+
+    @field_validator("mongodb_backup_key")
+    @classmethod
+    def valid_backup_key(cls, value):
+        if value is not None and not re.fullmatch(
+            r"[0-9a-fA-F]{64}", value.get_secret_value()
+        ):
+            raise ValueError(
+                "MONGODB_BACKUP_KEY must contain 64 hexadecimal characters"
+            )
+        return value
+
+    @field_validator("mongodb_uri")
+    @classmethod
+    def valid_mongodb_uri(cls, value):
+        raw = value.get_secret_value().strip()
+        if not raw.startswith(("mongodb://", "mongodb+srv://")):
+            raise ValueError("MONGODB_URI must be a MongoDB connection string")
+        return SecretStr(raw)
+
+    api_id: int = Field(alias="API_ID", gt=0)
+    api_hash: SecretStr = Field(alias="API_HASH")
+    bot_tokens_csv: SecretStr = Field(default=SecretStr(""), alias="BOT_TOKENS")
+    storage_channel: int = Field(alias="STORAGE_CHANNEL", lt=0)
+    admin_password: SecretStr = Field(default=SecretStr(""), alias="ADMIN_PASSWORD")
+    demo_admin_password: SecretStr | None = Field(
+        default=None, alias="DEMO_ADMIN_PASSWORD"
+    )
+    demo_admin_password_hash: SecretStr | None = Field(
+        default=None, alias="DEMO_ADMIN_PASSWORD_HASH"
+    )
+    session_secret: SecretStr = Field(alias="SESSION_SECRET")
+
+    string_sessions_csv: SecretStr = Field(
+        default=SecretStr(""), alias="STRING_SESSIONS"
+    )
+    main_bot_token: SecretStr | None = Field(default=None, alias="MAIN_BOT_TOKEN")
+    public_url: str | None = Field(default=None, alias="PUBLIC_URL")
+
+    @field_validator("public_url")
+    @classmethod
+    def valid_public_url(cls, value):
+        from tgdrive.settings.bot_settings import BotUploadPreferences
+
+        return BotUploadPreferences(site_url=value).site_url if value else None
+
+    telegram_admin_ids_csv: str = Field(default="", alias="TELEGRAM_ADMIN_IDS")
+
+    sleep_threshold: int = Field(default=60, alias="SLEEP_THRESHOLD", ge=0, le=3600)
+    max_file_size: int | None = Field(default=None, alias="MAX_FILE_SIZE", gt=0)
+    cache_dir: Path = Field(default=Path("cache"), alias="CACHE_DIR")
+    data_dir: Path = Field(default=Path("data"), alias="DATA_DIR")
+    log_level: str = Field(default="INFO", alias="LOG_LEVEL")
+
+    session_ttl_seconds: int = Field(
+        default=86400, alias="SESSION_TTL_SECONDS", ge=300, le=2592000
+    )
+    cookie_secure: bool = Field(default=True, alias="COOKIE_SECURE")
+    demo_mode: bool = Field(default=False, alias="DEMO_MODE")
+    allow_private_remote_urls: bool = Field(
+        default=False, alias="ALLOW_PRIVATE_REMOTE_URLS"
+    )
+    remote_connect_timeout: float = Field(
+        default=20.0, alias="REMOTE_CONNECT_TIMEOUT", gt=0, le=300
+    )
+    remote_download_concurrency: int = Field(
+        default=2, alias="REMOTE_DOWNLOAD_CONCURRENCY", ge=1, le=8
+    )
+    remote_read_timeout: float = Field(
+        default=120.0, alias="REMOTE_READ_TIMEOUT", gt=0, le=3600
+    )
+    remote_total_timeout: float = Field(
+        default=21600.0, alias="REMOTE_TOTAL_TIMEOUT", gt=0, le=86400
+    )
+    remote_max_redirects: int = Field(
+        default=5, alias="REMOTE_MAX_REDIRECTS", ge=0, le=20
+    )
+    transfer_ttl_seconds: int = Field(
+        default=3600, alias="TRANSFER_TTL_SECONDS", ge=60, le=86400
+    )
+    max_concurrent_transfers: int = Field(
+        default=2, alias="MAX_CONCURRENT_TRANSFERS", ge=1, le=32
+    )
+
+    telegram_uploads_per_bot: int = Field(
+        default=1, alias="TELEGRAM_UPLOADS_PER_BOT", ge=1, le=4
+    )
+
+    telegram_upload_pipeline: int = Field(
+        default=4, alias="TELEGRAM_UPLOAD_PIPELINE", ge=1, le=16
+    )
+    telegram_request_limit: int = Field(
+        default=8, alias="TELEGRAM_REQUEST_LIMIT", ge=1, le=32
+    )
+    telegram_parts_per_second: int = Field(
+        default=48, alias="TELEGRAM_PARTS_PER_SECOND", ge=1, le=128
+    )
+    telegram_media_per_bot: int = Field(
+        default=3, alias="TELEGRAM_MEDIA_PER_BOT", ge=1, le=16
+    )
+    telegram_max_queue: int = Field(
+        default=256, alias="TELEGRAM_MAX_QUEUE", ge=1, le=4096
+    )
+    upload_split_mib: int = Field(default=2000, alias="UPLOAD_SPLIT_MIB", ge=0, le=2000)
+    cache_memory_bytes: int = Field(
+        default=256 * 1024**2, alias="CACHE_MEMORY_BYTES", ge=0, le=8 * 1024**3
+    )
+    cache_disk_bytes: int = Field(
+        default=10 * 1024**3, alias="CACHE_DISK_BYTES", ge=0, le=2 * 1024**4
+    )
+    cache_min_free_bytes: int = Field(
+        default=1024**3, alias="CACHE_MIN_FREE_BYTES", ge=0, le=2 * 1024**4
+    )
+    cache_ttl_seconds: int = Field(
+        default=86400, alias="CACHE_TTL_SECONDS", ge=60, le=2678400
+    )
+    auto_preload: bool = Field(default=True, alias="AUTO_PRELOAD")
+    preload_max_jobs: int = Field(default=2, alias="PRELOAD_MAX_JOBS", ge=1, le=8)
+    timezone: str = Field(default="Asia/Kolkata", alias="TIMEZONE")
+
+    @field_validator("timezone")
+    @classmethod
+    def valid_timezone(cls, value: str) -> str:
+        from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+        try:
+            ZoneInfo(value)
+        except (ValueError, ZoneInfoNotFoundError) as exc:
+            raise ValueError("Use a valid IANA timezone, such as Asia/Kolkata") from exc
+        return value
+
+    staging_budget_bytes: int = Field(
+        default=16 * 1024**3, alias="STAGING_BUDGET_BYTES", gt=0
+    )
+    min_free_bytes: int = Field(default=1024**3, alias="MIN_FREE_BYTES", ge=0)
+    upload_session_ttl_seconds: int = Field(
+        default=86400, alias="UPLOAD_SESSION_TTL_SECONDS", ge=60
+    )
+    max_concurrent_streams: int = Field(
+        default=4, alias="MAX_CONCURRENT_STREAMS", ge=1, le=64
+    )
+    admin_password_hash: SecretStr | None = Field(
+        default=None, alias="ADMIN_PASSWORD_HASH"
+    )
+
+    # Internal startup provenance is never exported as configuration or backup.
+    managed_revision: int = Field(default=0, exclude=True, ge=0)
+    managed_client_ids: tuple[str, ...] = Field(default=(), exclude=True)
+    managed_client_labels: tuple[str, ...] = Field(default=(), exclude=True)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls,
+        init_settings,
+        env_settings,
+        dotenv_settings,
+        file_secret_settings,
+    ):
+        def managed_source():
+            from tgdrive.settings.managed_settings import read_document
+
+            explicit = init_settings()
+            credential_fields = {
+                "API_ID",
+                "API_HASH",
+                "BOT_TOKENS",
+                "MAIN_BOT_TOKEN",
+                "STRING_SESSIONS",
+            }
+            # Explicit injected configurations remain isolated (tests/embedding).
+            if credential_fields.intersection(explicit):
+                return {}
+            base = {**dotenv_settings(), **env_settings(), **explicit}
+            directory = Path(base.get("DATA_DIR", "data")).expanduser().resolve()
+            bootstrap = {}
+            uri = base.get("MONGODB_URI")
+            if not uri:
+                # Let the required field produce a redacted configuration error.
+                return {}
+            from tgdrive.replication.replica_bootstrap import load_bootstrap
+            from tgdrive.storage.mongo import DatabaseUnavailable, configure
+
+            recovery_bootstrap = load_bootstrap(
+                directory,
+                mongodb_uri=uri,
+                mongodb_database=str(base.get("MONGODB_DATABASE", "tgdrive")),
+            )
+            backend = configure(
+                directory,
+                uri.get_secret_value() if isinstance(uri, SecretStr) else str(uri),
+                str(base.get("MONGODB_DATABASE", "tgdrive")),
+            )
+            try:
+                row = backend.db.settings.find_one({"_id": "bootstrap"})
+            except Exception:
+                raise DatabaseUnavailable(
+                    "MongoDB is unavailable. Check MONGODB_URI, authentication, "
+                    "read permissions and network access."
+                ) from None
+            # Recovery copies fill missing values; they must never conceal an
+            # explicit credential rotation or channel/database mismatch.
+            saved = {
+                **(recovery_bootstrap or {}),
+                **(row["document"] if row else {}),
+            }
+            bootstrap = {
+                key: value
+                for key, value in saved.items()
+                if _should_restore_setting(key, base)
+            }
+            if os.environ.get("TGDRIVE_AUTO_SECRETS") == "true":
+                from tgdrive.core.deployment import SECRET_FIELDS, installation_secrets
+
+                known = {}
+                for key in SECRET_FIELDS:
+                    value = base.get(key) or bootstrap.get(key)
+                    if value:
+                        known[key] = (
+                            value.get_secret_value()
+                            if isinstance(value, SecretStr)
+                            else str(value)
+                        )
+                existing = bool(
+                    recovery_bootstrap is not None
+                    or (directory / "mongodb-drive.json").exists()
+                    or row is not None
+                    or (
+                        not all(known.get(key) for key in SECRET_FIELDS)
+                        and backend.db.catalog.find_one({"_id": "catalog"})
+                    )
+                )
+                bootstrap = {
+                    **bootstrap,
+                    **installation_secrets(directory, known, existing_drive=existing),
+                }
+            document = read_document(directory)
+            if document is None:
+                return bootstrap
+            rows = [
+                row
+                for kind in ("bot", "user")
+                for row in document.clients
+                if row.kind == kind and row.enabled
+            ]
+            return {
+                **bootstrap,
+                "API_ID": document.api_id,
+                "API_HASH": document.api_hash,
+                "BOT_TOKENS": ",".join(
+                    row.credential.get_secret_value()
+                    for row in rows
+                    if row.kind == "bot"
+                ),
+                "STRING_SESSIONS": ",".join(
+                    row.credential.get_secret_value()
+                    for row in rows
+                    if row.kind == "user"
+                ),
+                "managed_revision": document.revision,
+                "managed_client_ids": tuple(row.id for row in rows),
+                "managed_client_labels": tuple(row.label for row in rows),
+            }
+
+        return (
+            init_settings,
+            managed_source,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+    @field_validator("max_file_size", mode="before")
+    @classmethod
+    def optional_file_size(cls, value):
+        return None if value in ("", None) else value
+
+    @field_validator(
+        "admin_password_hash",
+        "mongodb_backup_key",
+        "demo_admin_password",
+        "demo_admin_password_hash",
+        mode="before",
+    )
+    @classmethod
+    def optional_password_hash(cls, value):
+        raw = value.get_secret_value() if isinstance(value, SecretStr) else value
+        return (
+            None if raw is None or (isinstance(raw, str) and not raw.strip()) else value
+        )
+
+    @field_validator("api_hash")
+    @classmethod
+    def validate_api_hash(cls, value: SecretStr) -> SecretStr:
+        raw = value.get_secret_value().strip()
+        if not re.fullmatch(r"[0-9a-fA-F]{32}", raw):
+            raise ValueError("API hash must contain exactly 32 hexadecimal characters")
+        return SecretStr(raw)
+
+    @field_validator("admin_password", "session_secret", "demo_admin_password")
+    @classmethod
+    def validate_non_empty_secret(
+        cls, value: SecretStr | None, info: ValidationInfo
+    ) -> SecretStr | None:
+        if value is None:
+            return None
+        raw = value.get_secret_value().strip()
+        if raw.startswith("<"):
+            raise ValueError("Replace the example placeholder with a generated secret")
+        if info.field_name == "admin_password" and not raw:
+            return SecretStr("")
+        minimum = (
+            12 if info.field_name in {"admin_password", "demo_admin_password"} else 32
+        )
+        if len(raw) < minimum:
+            label = info.field_name.replace("_", " ")
+            raise ValueError(f"{label} must contain at least {minimum} characters")
+        return SecretStr(raw)
+
+    @field_validator("log_level")
+    @classmethod
+    def validate_log_level(cls, value: str) -> str:
+        normalized = value.strip().upper()
+        if normalized not in {"DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"}:
+            raise ValueError("must be DEBUG, INFO, WARNING, ERROR, or CRITICAL")
+        return normalized
+
+    @field_validator("telegram_admin_ids_csv")
+    @classmethod
+    def validate_admin_ids(cls, value: str) -> str:
+        for raw_id in _csv(value):
+            if not raw_id.isdecimal() or int(raw_id) <= 0:
+                raise ValueError("must be a comma-separated list of positive integers")
+        return value
+
+    @model_validator(mode="after")
+    def validate_related_settings(self) -> Settings:
+        if (
+            not self.admin_password.get_secret_value()
+            and self.admin_password_hash is None
+        ):
+            raise ValueError("ADMIN_PASSWORD or ADMIN_PASSWORD_HASH is required")
+        for name in ("admin_password_hash", "demo_admin_password_hash"):
+            encoded = getattr(self, name)
+            if encoded is None:
+                continue
+            label = name.upper()
+            try:
+                parameters = extract_parameters(encoded.get_secret_value())
+                if parameters.type is not Type.ID:
+                    raise ValueError(f"{label} must use Argon2id")
+                if parameters.memory_cost < 19456 or parameters.time_cost < 2:
+                    raise ValueError(f"{label} is below the supported security floor")
+                if (
+                    parameters.memory_cost > 262144
+                    or parameters.time_cost > 10
+                    or parameters.parallelism > 16
+                ):
+                    raise ValueError(
+                        f"{label} exceeds supported login costs "
+                        "(256 MiB memory, 10 iterations, 16 lanes); generate a new "
+                        "Argon2id hash or configure ADMIN_PASSWORD instead"
+                    )
+            except InvalidHashError as exc:
+                raise ValueError(f"{label} must be a valid Argon2id hash") from exc
+        if self.demo_mode:
+            from tgdrive.core.security import verify_password
+
+            owner = self.admin_password_hash or self.admin_password
+            demo = self.demo_admin_password_hash or self.demo_admin_password
+            collision = bool(demo and demo == owner)
+            if demo and self.demo_admin_password_hash is None:
+                collision = verify_password(
+                    demo.get_secret_value(), owner.get_secret_value()
+                )
+            elif demo and self.admin_password_hash is None:
+                collision = verify_password(
+                    owner.get_secret_value(), demo.get_secret_value()
+                )
+            if collision:
+                raise ValueError(
+                    "Demo administrator password must differ from the regular password"
+                )
+        token = self.main_bot_token_value
+        if token:
+            if not _BOT_TOKEN_RE.fullmatch(token):
+                raise ValueError("MAIN_BOT_TOKEN is not a valid Telegram bot token")
+            if not self.telegram_admin_ids:
+                raise ValueError(
+                    "TELEGRAM_ADMIN_IDS is required when MAIN_BOT_TOKEN is set"
+                )
+            # Seed new installations without reviving a saved, removed connection.
+            if not self.bot_tokens and not self.managed_revision:
+                self.bot_tokens_csv = SecretStr(token)
+        if not self.bot_tokens:
+            raise ValueError(
+                "At least one storage bot is required; "
+                "set MAIN_BOT_TOKEN for a new deployment"
+            )
+        if len(set(self.bot_tokens)) != len(self.bot_tokens):
+            raise ValueError("BOT_TOKENS must not repeat a storage bot")
+        if len(set(self.string_sessions)) != len(self.string_sessions):
+            raise ValueError("STRING_SESSIONS must not repeat an account session")
+        invalid_tokens = [
+            token for token in self.bot_tokens if not _BOT_TOKEN_RE.fullmatch(token)
+        ]
+        if invalid_tokens:
+            raise ValueError("BOT_TOKENS contains an invalid Telegram bot token")
+        return self
+
+    @property
+    def bot_tokens(self) -> tuple[str, ...]:
+        return _csv(self.bot_tokens_csv.get_secret_value())
+
+    @property
+    def string_sessions(self) -> tuple[str, ...]:
+        return _csv(self.string_sessions_csv.get_secret_value())
+
+    @property
+    def telegram_admin_ids(self) -> tuple[int, ...]:
+        return tuple(int(value) for value in _csv(self.telegram_admin_ids_csv))
+
+    @property
+    def main_bot_token_value(self) -> str | None:
+        if self.main_bot_token is None:
+            return None
+        value = self.main_bot_token.get_secret_value().strip()
+        return value or None
+
+    @property
+    def bot_upload_limit(self) -> int:
+        return _DEFAULT_BOT_LIMIT
+
+    @property
+    def upload_limit(self) -> int:
+        """Logical file ceiling; Telegram message limits apply to individual parts."""
+        return min(
+            self.staging_budget_bytes,
+            self.max_file_size or self.staging_budget_bytes,
+            self.bot_upload_limit * 4096,
+        )
+
+    @property
+    def session_key(self) -> bytes:
+        return hashlib.sha256(self.session_secret.get_secret_value().encode()).digest()
+
+    @property
+    def resolved_cache_dir(self) -> Path:
+        return self.cache_dir.expanduser().resolve()
+
+    @property
+    def resolved_data_dir(self) -> Path:
+        return self.data_dir.expanduser().resolve()
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Return the process-wide validated settings instance."""
+
+    return Settings()  # type: ignore[call-arg]
diff --git a/tgdrive/core/deployment.py b/tgdrive/core/deployment.py
new file mode 100644
index 00000000..4e3bd3be
--- /dev/null
+++ b/tgdrive/core/deployment.py
@@ -0,0 +1,97 @@
+"""Container defaults that survive restarts without exposing deployment secrets."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import os
+import re
+import secrets
+import stat
+from pathlib import Path
+
+SECRET_FIELDS = ("SESSION_SECRET", "MONGODB_BACKUP_KEY")
+
+
+def installation_secrets(
+    directory: Path, known: dict[str, str], *, existing_drive: bool
+) -> dict[str, str]:
+    """Reuse saved keys; generate missing keys only for an uninitialized drive."""
+    if all(known.get(key) for key in SECRET_FIELDS):
+        return known
+    if directory in (Path(directory.anchor), Path.home()):
+        raise ValueError("Use a dedicated DATA_DIR for generated deployment secrets")
+    directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+    lock = os.open(
+        directory / ".deployment-secrets.lock",
+        os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW,
+        0o600,
+    )
+    try:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        path = directory / "deployment-secrets.json"
+        try:
+            descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+        except FileNotFoundError:
+            saved = {}
+        else:
+            try:
+                info = os.fstat(descriptor)
+                if (
+                    not stat.S_ISREG(info.st_mode)
+                    or info.st_size > 4096
+                    or info.st_mode & 0o077
+                ):
+                    raise ValueError
+                with os.fdopen(descriptor, "r", closefd=False) as source:
+                    saved = json.load(source)
+                if not isinstance(saved, dict) or set(saved) != set(SECRET_FIELDS):
+                    raise ValueError
+                if (
+                    not isinstance(saved["SESSION_SECRET"], str)
+                    or len(saved["SESSION_SECRET"]) < 32
+                    or not isinstance(saved["MONGODB_BACKUP_KEY"], str)
+                    or not re.fullmatch(r"[0-9a-fA-F]{64}", saved["MONGODB_BACKUP_KEY"])
+                ):
+                    raise ValueError
+            except ValueError, TypeError:
+                raise ValueError(
+                    "Preserve deployment-secrets.json and repair its contents or "
+                    "0600 permissions; saved keys were not replaced"
+                ) from None
+            finally:
+                os.close(descriptor)
+        values = {**saved, **known}
+        missing = [key for key in SECRET_FIELDS if not values.get(key)]
+        if not missing:
+            return values
+        if existing_drive:
+            raise ValueError(
+                "Existing drive is missing deployment keys. Supply the original "
+                + ", ".join(missing)
+                + "; existing keys were not regenerated"
+            )
+        for key in missing:
+            values[key] = (
+                secrets.token_hex(32)
+                if key == "MONGODB_BACKUP_KEY"
+                else secrets.token_urlsafe(48)
+            )
+        temporary = directory / (".deployment-secrets-" + secrets.token_hex(16))
+        descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        try:
+            with os.fdopen(descriptor, "w") as target:
+                json.dump(values, target)
+                target.flush()
+                os.fsync(target.fileno())
+            os.replace(temporary, path)
+            parent = os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
+            try:
+                os.fsync(parent)
+            finally:
+                os.close(parent)
+        finally:
+            temporary.unlink(missing_ok=True)
+        return values
+    finally:
+        os.close(lock)
diff --git a/tgdrive/core/errors.py b/tgdrive/core/errors.py
new file mode 100644
index 00000000..700f4ca8
--- /dev/null
+++ b/tgdrive/core/errors.py
@@ -0,0 +1,59 @@
+"""Domain exceptions for TGDrive's metadata layer."""
+
+from __future__ import annotations
+
+
+class DriveError(Exception):
+    """Base class for metadata failures that callers may safely handle."""
+
+
+class ValidationError(DriveError, ValueError):
+    """Stored or user-supplied metadata failed validation."""
+
+
+class InvalidNameError(ValidationError):
+    """An item name is unsafe or outside the supported limits."""
+
+
+class InvalidPathError(ValidationError):
+    """An ID path is malformed or contains traversal syntax."""
+
+
+class RootMutationError(InvalidPathError):
+    """An operation attempted to rename, trash, or delete the root."""
+
+
+class DuplicateNameError(ValidationError):
+    """A sibling already has the requested case-insensitive name."""
+
+
+class NotFoundError(DriveError, LookupError):
+    """The requested item or path does not exist."""
+
+
+class NotDirectoryError(DriveError):
+    """A path component or requested item is not a folder."""
+
+
+class NotFileError(DriveError):
+    """The requested item is not a file."""
+
+
+class TrashedItemError(DriveError):
+    """The requested item is hidden by its own or an ancestor's trash state."""
+
+
+class CorruptStoreError(DriveError):
+    """A metadata file is malformed or internally inconsistent."""
+
+
+class UnsupportedSchemaError(CorruptStoreError):
+    """The metadata schema version is not supported by this implementation."""
+
+
+class PersistenceError(DriveError):
+    """An atomic metadata write could not be completed."""
+
+
+class InvalidRevisionError(DriveError, ValueError):
+    """A backup acknowledgement references an impossible revision."""
diff --git a/tgdrive/core/logging.py b/tgdrive/core/logging.py
new file mode 100644
index 00000000..6e7aab73
--- /dev/null
+++ b/tgdrive/core/logging.py
@@ -0,0 +1,96 @@
+"""Centralized logging configuration with conservative secret redaction."""
+
+from __future__ import annotations
+
+import logging
+import re
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+_SECRET_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"(?i)mongodb(?:\+srv)?://[^\s\"']+"), "[REDACTED_MONGODB_URI]"),
+    (re.compile(r"\b\d{5,15}:[A-Za-z0-9_-]{20,}\b"), "[REDACTED]"),
+    (
+        re.compile(
+            r"(?i)(mongodb[_-]?backup[_-]?key|x-tgdrive-recovery-key)"
+            r"\s*[=:]\s*[^\s,]+"
+        ),
+        "[REDACTED]",
+    ),
+    (
+        re.compile(r"(?i)(password|api[_-]?hash|session[_-]?secret)\s*[=:]\s*[^\s,]+"),
+        "[REDACTED]",
+    ),
+    (
+        re.compile(r"(?i)([?&](?:auth|token|access_token)=)[^&\s\"']+"),
+        r"\1[REDACTED]",
+    ),
+    (
+        re.compile(r"(?i)(\b(?:authorization|cookie)\s*:\s*)[^\r\n]+"),
+        r"\1[REDACTED]",
+    ),
+)
+
+
+def _redact(message: str) -> str:
+    for pattern, replacement in _SECRET_PATTERNS:
+        message = pattern.sub(replacement, message)
+    return message
+
+
+class RedactingFormatter(logging.Formatter):
+    """Redact the rendered traceback as well as the ordinary log message."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        return _redact(super().format(record))
+
+
+class RedactingFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = _redact(record.getMessage())
+        record.args = ()
+        return True
+
+
+def configure_logging(level: str = "INFO", log_file: Path | None = None) -> None:
+    """Configure the root logger once for console and optional rotated file output."""
+
+    root = logging.getLogger()
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+        handler.close()
+    root.setLevel(level)
+    # Share URLs contain bearer credentials.  Uvicorn formats access records on
+    # its own handler, outside the root redaction filter, so disable that unsafe
+    # raw-query log at the source.
+    logging.getLogger("uvicorn.access").disabled = True
+    # Telethon's routine update/difference messages can dominate a busy drive's
+    # logs. Keep provider warnings/errors visible; DEBUG deliberately restores
+    # its connection/update diagnostics for a short troubleshooting session.
+    diagnostic_level = (
+        logging.NOTSET
+        if root.level == logging.DEBUG
+        else max(root.level, logging.WARNING)
+    )
+    logging.getLogger("telethon").setLevel(diagnostic_level)
+    logging.getLogger("httpx").setLevel(diagnostic_level)
+    logging.getLogger("httpcore").setLevel(diagnostic_level)
+    formatter = RedactingFormatter(
+        "%(asctime)s %(levelname)s %(name)s: %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%S%z",
+    )
+    redact = RedactingFilter()
+
+    console = logging.StreamHandler()
+    console.setFormatter(formatter)
+    console.addFilter(redact)
+    root.addHandler(console)
+
+    if log_file is not None:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        handler = RotatingFileHandler(
+            log_file, maxBytes=2 * 1024 * 1024, backupCount=3, encoding="utf-8"
+        )
+        handler.setFormatter(formatter)
+        handler.addFilter(redact)
+        root.addHandler(handler)
diff --git a/tgdrive/core/runtime.py b/tgdrive/core/runtime.py
new file mode 100644
index 00000000..4ef44bb4
--- /dev/null
+++ b/tgdrive/core/runtime.py
@@ -0,0 +1,497 @@
+"""Application lifecycle orchestration and graceful shutdown."""
+
+from __future__ import annotations
+
+import asyncio
+import fcntl
+import logging
+import time
+from pathlib import Path
+
+from tgdrive.core.config import Settings
+from tgdrive.recovery.backup import RecoveryConflict
+from tgdrive.recovery.mongo_backup import MongoProtection
+from tgdrive.settings.bot_settings import get_bot_settings
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.bot_mode import BotMode
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.clients import build_bot_mode_client, build_client_pool
+from tgdrive.transfers.manager import TransferManager, restore_telegram_cooldowns
+from tgdrive.transfers.remote import RemoteClient, RemoteTimeouts
+from tgdrive.transfers.tasks import TransferRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class Runtime:
+    def __init__(
+        self,
+        settings: Settings,
+        *,
+        pool: ClientPool | None = None,
+    ) -> None:
+        self.settings = settings
+        from tgdrive.storage.mongo import for_settings
+
+        self.mongo = for_settings(settings)
+        self.pool = pool or build_client_pool(settings)
+        self.backup = MongoProtection(settings, self.pool, self.mongo)
+        self.remote = RemoteClient(
+            download_concurrency=settings.remote_download_concurrency,
+            max_bytes=settings.upload_limit,
+            min_free_bytes=settings.min_free_bytes,
+            max_redirects=settings.remote_max_redirects,
+            allow_private=settings.allow_private_remote_urls,
+            timeouts=RemoteTimeouts(
+                connect=settings.remote_connect_timeout,
+                read=settings.remote_read_timeout,
+                total=settings.remote_total_timeout,
+            ),
+        )
+        self.registry = TransferRegistry(ttl_seconds=settings.transfer_ttl_seconds)
+        self.store: DriveStore | None = None
+        self.transfers: TransferManager | None = None
+        self.bot_mode: BotMode | None = None
+        self.ready = False
+        self._owner_lock = None
+        self._mongo_acquired = False
+        self._reconnector = None
+        self._channel_check_lock = asyncio.Lock()
+        self._channel_verified_until = 0.0
+        self.storage_channel_error: str | None = None
+
+    async def start(self) -> None:
+        if self.ready:
+            return
+        self._prepare_runtime_directories()
+        try:
+            self._owner_lock = (
+                self.settings.resolved_data_dir / ".instance.lock"
+            ).open("a")
+            try:
+                fcntl.flock(self._owner_lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError as exc:
+                self._owner_lock.close()
+                self._owner_lock = None
+                raise RuntimeError(
+                    "Another TGDrive instance owns this data directory"
+                ) from exc
+            from tgdrive.core.errors import CorruptStoreError
+            from tgdrive.recovery.backup import BackupError
+            from tgdrive.replication.replica import ChannelReplica
+            from tgdrive.replication.replica_activation import (
+                ActivationError,
+                apply_activation,
+            )
+            from tgdrive.storage.mongo import (
+                initialize_if_empty,
+                record_drive_open,
+            )
+
+            # Database configuration, connectivity and ownership are startup
+            # requirements, including when recovery metadata is available.
+            logger.info("Checking MongoDB connectivity")
+            await asyncio.to_thread(self.mongo.ping)
+            logger.info("Acquiring MongoDB drive ownership")
+            await asyncio.to_thread(self.mongo.acquire)
+            self._mongo_acquired = True
+            logger.info("Checking MongoDB transaction support and write permissions")
+            await asyncio.to_thread(self.mongo.transaction, self.mongo.fence)
+
+            try:
+                if getattr(self, "_activation_unavailable", False):
+                    raise ActivationError("Recovery activation requires review")
+                await asyncio.to_thread(apply_activation, self.settings, self.mongo)
+                created = await asyncio.to_thread(
+                    initialize_if_empty, self.settings, self.mongo
+                )
+                logger.info(
+                    "Created a new MongoDB drive from deployment configuration"
+                    if created
+                    else "Opening the existing MongoDB drive"
+                )
+                self.store = await self.backup.restore()
+                await asyncio.to_thread(record_drive_open, self.settings, self.store)
+            except (
+                ActivationError,
+                BackupError,
+                CorruptStoreError,
+                ValueError,
+            ):
+                self.recovery_only = True
+                self.replica = ChannelReplica(self.settings, self)
+                self.replica.report(
+                    "error",
+                    "The MongoDB catalog is unavailable or requires explicit recovery. "
+                    "Existing data has been preserved; normal file operations "
+                    "are stopped.",
+                )
+                self.replica.start()
+                logger.warning(
+                    "Catalog unavailable: owner web recovery is available; "
+                    "file writers are stopped"
+                )
+                return
+            self.recovery_only = False
+            self.replica = ChannelReplica(self.settings, self)
+            if self.replica.journal.get("activation"):
+                self.replica.journal.set("activation", None)
+                self.replica.journal.set("recovery", None)
+                self.replica.journal.set("candidate", None)
+                self.replica.journal.set("job", None)
+                self.replica.journal.set("config", {})
+                self.replica.update(phase="disabled", protected_revision=0, error=None)
+            original_lineage = getattr(self.backup, "verify_lineage", None)
+
+            async def protected_lineage(store):
+                if self.replica.blocked:
+                    from tgdrive.settings.managed_settings import SettingsProblem
+
+                    raise SettingsProblem(
+                        "Channel recovery has paused Telegram changes.", status=409
+                    )
+                await self._verify_storage_channel()
+                if original_lineage is not None:
+                    await original_lineage(store)
+
+            self.backup.verify_lineage = protected_lineage
+            self.registry = TransferRegistry(
+                ttl_seconds=self.settings.transfer_ttl_seconds,
+                mongo=self.mongo.db.jobs,
+                mongo_backend=self.mongo,
+            )
+            from tgdrive.settings.transfer_preferences import get_transfer_preferences
+
+            await get_transfer_preferences(self.settings, self).initialize()
+            from tgdrive.settings.performance_preferences import (
+                get_performance_settings,
+            )
+
+            await get_performance_settings(self.settings, self).initialize()
+            check_binding = getattr(self.backup, "check_local_binding", None)
+            if check_binding is not None:
+                try:
+                    check_binding(self.store)
+                except RecoveryConflict:
+                    logger.warning(
+                        "Storage-channel configuration conflicts with local state"
+                    )
+            await restore_telegram_cooldowns(self.pool, self.registry.list())
+            restore_publication = getattr(
+                self.backup, "restore_publication_cooldown", None
+            )
+            if callable(restore_publication):
+                await restore_publication()
+            connected = False
+            try:
+                await self.pool.start()
+                connected = True
+            except Exception as exc:
+                logger.warning(
+                    "Telegram unavailable during startup: %s; metadata stays available",
+                    type(exc).__name__,
+                )
+            lineage_ready = False
+            if connected:
+                try:
+                    # Clean local copies can still be older than a remote pin.
+                    # Verify before resuming any Telegram side effects.
+                    await self._verify_storage_channel()
+                    await self.backup.backup(self.store)
+                    lineage_ready = True
+                except RecoveryConflict:
+                    logger.warning(
+                        "Recovery conflict: metadata stays available; "
+                        "Telegram mutation recovery is paused"
+                    )
+                except Exception:
+                    logger.warning(
+                        "Initial channel verification failed; the saved catalog "
+                        "remains available and transfer recovery waits for repair"
+                    )
+
+            async def ensure_backup(required_revision: int) -> int:
+                await self._verify_storage_channel()
+                return await self.backup.ensure_revision(self.store, required_revision)
+
+            async def ensure_lineage() -> None:
+                await self.backup.verify_lineage(self.store)
+
+            self.transfers = TransferManager(
+                settings=self.settings,
+                pool=self.pool,
+                store=self.store,
+                remote=self.remote,
+                registry=self.registry,
+                ensure_backup=ensure_backup,
+                ensure_lineage=ensure_lineage,
+                ensure_channel=self._verify_storage_channel,
+                check_upload_allowed=self._check_upload_allowed,
+            )
+            self.transfers._ensure_replica = self.replica.before_mutation
+            if self.replica.blocked:
+                lineage_ready = False
+            if lineage_ready:
+                try:
+                    await self.transfers.recover()
+                except Exception:
+                    lineage_ready = False
+                    logger.warning(
+                        "Durable transfers are waiting for verified protection; "
+                        "owner metadata and backup controls remain available"
+                    )
+            bot_client = build_bot_mode_client(self.settings) if lineage_ready else None
+            if bot_client is not None:
+                bot_client.bind_send_gate(self.pool.pace_send, self.pool.defer_channel)
+                self.bot_mode = BotMode(
+                    client=bot_client,
+                    settings=self.settings,
+                    store=self.store,
+                    folder_settings=get_bot_settings(self.settings, self),
+                    before_write=self._check_bot_upload_allowed,
+                    before_delete=lambda: self.backup.verify_lineage(self.store),
+                )
+                await self.bot_mode.start()
+            self.backup.start(self.store)
+            self.replica.start()
+            self.ready = True
+            if not lineage_ready:
+                self._reconnector = asyncio.create_task(
+                    self._reconnect(), name="telegram-reconnect"
+                )
+            logger.info("TGDrive runtime is ready")
+        except DatabaseUnavailable as exc:
+            logger.error(
+                "TGDrive startup rejected: %s Correct the MongoDB configuration "
+                "or database access, then restart the deployment.",
+                exc,
+            )
+            await self._cleanup_failed_start()
+            raise
+        except Exception:
+            logger.exception("TGDrive startup failed")
+            await self._cleanup_failed_start()
+            raise
+
+    def _check_upload_allowed(self) -> None:
+        if getattr(self, "replica", None) is not None and self.replica.blocked:
+            from tgdrive.settings.managed_settings import SettingsProblem
+
+            raise SettingsProblem(
+                "Finish or disable channel recovery before uploading.", status=409
+            )
+        self.backup.check_upload_allowed(self.store)
+        manager = getattr(self, "connection_manager", None)
+        if manager is not None:
+            manager.check_upload_allowed()
+
+    async def _check_bot_upload_allowed(self) -> None:
+        self._check_upload_allowed()
+        await self._verify_storage_channel()
+
+    async def _reconnect(self) -> None:
+        while self.ready:
+            try:
+                await self.pool.start()
+                await self._verify_storage_channel()
+                await self.backup.backup(self.store)
+                if self.transfers is not None:
+                    await self.transfers.recover()
+                logger.info("Telegram connection and catalog lineage verified")
+                if self.bot_mode is None:
+                    client = build_bot_mode_client(self.settings)
+                    if client is not None:
+                        client.bind_send_gate(
+                            self.pool.pace_send, self.pool.defer_channel
+                        )
+                        self.bot_mode = BotMode(
+                            client=client,
+                            settings=self.settings,
+                            store=self.store,
+                            folder_settings=get_bot_settings(self.settings, self),
+                            before_write=self._check_bot_upload_allowed,
+                            before_delete=lambda: self.backup.verify_lineage(
+                                self.store
+                            ),
+                        )
+                        await self.bot_mode.start()
+                return
+            except Exception:
+                await asyncio.sleep(30)
+
+    async def _verify_storage_channel(self) -> None:
+        """Recheck Telegram-side changes before resuming durable mutations."""
+        if time.monotonic() < self._channel_verified_until:
+            return
+        # Pool adapters may implement only the lifecycle protocol (e.g. an
+        # externally supplied transport); production Telethon adapters probe.
+        status = getattr(self.pool, "status", None)
+        if not callable(status):
+            return
+        async with self._channel_check_lock:
+            if time.monotonic() < self._channel_verified_until:
+                return
+            from tgdrive.settings.managed_settings import SettingsProblem
+
+            for row in await status():
+                if row.kind != "bot" or not row.healthy:
+                    continue
+                async with self.pool.lease(client_name=row.name) as client:
+                    probe = getattr(client, "storage_channel_problem", None)
+                    if not callable(probe):
+                        continue
+                    try:
+                        async with asyncio.timeout(30):
+                            problem = await probe(
+                                self.settings.storage_channel,
+                                require_pin=False,
+                            )
+                    except Exception:
+                        self.storage_channel_error = (
+                            "Telegram storage channel could not be verified. "
+                            "Check the network, channel membership "
+                            "and bot permissions, "
+                            "then retry or restart TGDrive."
+                        )
+                        raise ConnectionError(self.storage_channel_error) from None
+                    if problem is not None:
+                        self.storage_channel_error = problem[1]
+                        raise SettingsProblem(problem[1], code=problem[0], status=409)
+            self.storage_channel_error = None
+            # Bound Telegram requests for concurrent uploads. Failed checks are
+            # never cached, so fixing channel settings takes effect on retry.
+            self._channel_verified_until = time.monotonic() + 30
+
+    async def _close_media_resources(self) -> list[BaseException]:
+        manager = getattr(self, "preloads", None)
+        resource = (
+            manager
+            if manager is not None
+            else getattr(self.pool, "_media_read_cache", None)
+        )
+        if resource is not None:
+            try:
+                await resource.close()
+            except Exception as exc:
+                logger.exception("Failed to stop disposable media resources")
+                return [exc]
+        return []
+
+    async def stop(self) -> list[BaseException]:
+        self.ready = False
+        if self._reconnector is not None:
+            self._reconnector.cancel()
+            await asyncio.gather(self._reconnector, return_exceptions=True)
+            self._reconnector = None
+        failures: list[BaseException] = []
+        failures.extend(await self._close_media_resources())
+        if self.bot_mode is not None:
+            try:
+                await self.bot_mode.stop()
+            except Exception as exc:
+                logger.exception("Failed to stop bot mode")
+                failures.append(exc)
+        if self.transfers is not None:
+            try:
+                await self.transfers.close()
+            except Exception as exc:
+                logger.exception("Failed to stop transfer manager")
+                failures.append(exc)
+        else:
+            await self.remote.close()
+        if getattr(self, "replica", None) is not None:
+            await self.replica.close()
+        if self.store is not None:
+            try:
+                await self.backup.stop(self.store)
+            except Exception as exc:
+                logger.exception("Final metadata backup failed")
+                failures.append(exc)
+        try:
+            stop_failures = await self.pool.stop(drain_timeout=20)
+            failures.extend(error for _, error in stop_failures)
+        except Exception as exc:
+            logger.exception("Failed to stop Telegram client pool")
+            failures.append(exc)
+        closers = [self.registry]
+        if self.transfers is not None and hasattr(self.transfers, "uploads"):
+            closers.append(self.transfers.uploads)
+        if self.bot_mode is not None:
+            closers.append(self.bot_mode)
+        if self.store is not None:
+            closers.append(self.store)
+        try:
+            for resource in closers:
+                try:
+                    resource.close()
+                except Exception as exc:
+                    logger.exception("Failed to close local persistence")
+                    failures.append(exc)
+        finally:
+            self._release_owner_lock()
+        if failures:
+            logger.error("Shutdown completed with %s error(s)", len(failures))
+        else:
+            logger.info("TGDrive runtime stopped cleanly")
+        return failures
+
+    def _release_owner_lock(self) -> None:
+        if self._mongo_acquired:
+            self.mongo.release()
+            self._mongo_acquired = False
+        if self._owner_lock is not None:
+            self._owner_lock.close()
+            self._owner_lock = None
+
+    async def _cleanup_failed_start(self) -> None:
+        if getattr(self, "replica", None) is not None:
+            await self.replica.close()
+        if self.bot_mode is not None:
+            try:
+                await self.bot_mode.stop()
+            except Exception:
+                logger.exception("Bot-mode cleanup after failed startup failed")
+            finally:
+                self.bot_mode.close()
+        try:
+            await self.remote.close()
+        except Exception:
+            logger.exception("Remote-client cleanup after failed startup failed")
+        await self._close_media_resources()
+        try:
+            await self.pool.stop(drain_timeout=10)
+        except Exception:
+            logger.exception("Client-pool cleanup after failed startup failed")
+        try:
+            if self.transfers is not None:
+                await self.transfers.close()
+                self.transfers.uploads.close()
+            self.registry.close()
+            if self.store is not None:
+                self.store.close()
+        finally:
+            self._release_owner_lock()
+
+    def _prepare_runtime_directories(self) -> None:
+        cache_dir = self.settings.resolved_cache_dir
+        data_dir = self.settings.resolved_data_dir
+        self._validate_runtime_path(cache_dir, "CACHE_DIR")
+        self._validate_runtime_path(data_dir, "DATA_DIR")
+        if cache_dir.is_relative_to(data_dir) or data_dir.is_relative_to(cache_dir):
+            raise ValueError("CACHE_DIR and DATA_DIR must not overlap")
+        cleanup_paths = [cache_dir / name for name in ("uploads", "remote")]
+        for cleanup_path in cleanup_paths:
+            resolved = cleanup_path.resolve()
+            if resolved == cache_dir or not resolved.is_relative_to(cache_dir):
+                raise ValueError("CACHE_DIR cleanup paths must stay inside CACHE_DIR")
+        data_dir.mkdir(parents=True, exist_ok=True)
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        # Staged bytes belong to durable jobs and must survive restart.
+
+    @staticmethod
+    def _validate_runtime_path(path: Path, name: str) -> None:
+        if path == Path(path.anchor) or path == Path.home().resolve():
+            raise ValueError(
+                f"{name} cannot be a filesystem root or the home directory"
+            )
diff --git a/tgdrive/core/security.py b/tgdrive/core/security.py
new file mode 100644
index 00000000..4bb10300
--- /dev/null
+++ b/tgdrive/core/security.py
@@ -0,0 +1,276 @@
+"""Authentication, request throttling, and untrusted-name helpers."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+import unicodedata
+from collections import OrderedDict, deque
+from dataclasses import dataclass
+from typing import Final
+
+from argon2 import PasswordHasher
+from argon2.exceptions import VerificationError
+from pymongo.errors import PyMongoError
+
+SESSION_COOKIE: Final = "tgdrive_session"
+_TOKEN_VERSION: Final = 1
+
+
+def credential_session_key(key: bytes, credential: str) -> bytes:
+    """Invalidate browser sessions when the configured owner credential changes.
+
+    Derive from the configured value, rather than a freshly salted login hash,
+    so ordinary restarts preserve sessions. Share-link keys stay independent.
+    """
+
+    return hmac.new(
+        key, b"tgdrive/owner-session/v1\0" + credential.encode(), hashlib.sha256
+    ).digest()
+
+
+def demo_admin_session_key(key: bytes, credential: str) -> bytes:
+    """Keep demo administrator sessions independent of ordinary owner sessions."""
+
+    return hmac.new(
+        key, b"tgdrive/demo-admin-session/v1\0" + credential.encode(), hashlib.sha256
+    ).digest()
+
+
+class InvalidSession(ValueError):
+    """Raised when a session token is invalid or expired."""
+
+
+def _b64encode(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).rstrip(b"=").decode("ascii")
+
+
+def _b64decode(value: str) -> bytes:
+    padding = "=" * (-len(value) % 4)
+    return base64.urlsafe_b64decode(value + padding)
+
+
+class SessionManager:
+    """Create and verify compact HMAC-authenticated admin sessions."""
+
+    def __init__(
+        self,
+        key: bytes,
+        ttl_seconds: int,
+        *,
+        mongo_backend=None,
+        demo_admin_key: bytes | None = None,
+    ) -> None:
+        if len(key) < 32:
+            raise ValueError("session key must contain at least 32 bytes")
+        if demo_admin_key is not None and len(demo_admin_key) < 32:
+            raise ValueError(
+                "demo administrator session key must contain at least 32 bytes"
+            )
+        self._key = key
+        self._demo_admin_key = demo_admin_key
+        self._ttl_seconds = ttl_seconds
+        from tgdrive.storage.mongo import DatabaseUnavailable
+
+        self._mongo_backend = mongo_backend
+        self._mongo = mongo_backend.db.sessions if mongo_backend is not None else None
+        try:
+            self._mongo_sessions = (
+                {
+                    row["_id"]: row["expires"]
+                    for row in self._mongo.find({"expires": {"$gt": int(time.time())}})
+                }
+                if self._mongo is not None
+                else {}
+            )
+        except PyMongoError:
+            raise DatabaseUnavailable(
+                "MongoDB is unavailable. Restore database access, then restart "
+                "TGDrive. Owner sign-in requires the configured database."
+            ) from None
+
+    def close(self) -> None:
+        """The shared MongoDB backend owns its connection lifecycle."""
+
+    def revoke(self, token: str) -> None:
+        if self._mongo is not None:
+            digest = hashlib.sha256(token.encode()).hexdigest()
+            self._mongo_backend.write(self._mongo, "delete_one", {"_id": digest})
+            self._mongo_sessions.pop(digest, None)
+            return
+
+    def create(self, *, now: int | None = None, demo_admin: bool = False) -> str:
+        if demo_admin and self._demo_admin_key is None:
+            raise ValueError("Demo administrator sign-in is not configured")
+        issued_at = int(time.time() if now is None else now)
+        payload = {
+            "v": _TOKEN_VERSION,
+            "iat": issued_at,
+            "exp": issued_at + self._ttl_seconds,
+            "nonce": secrets.token_urlsafe(18),
+        }
+        if demo_admin:
+            payload["demo_admin"] = True
+        encoded = _b64encode(
+            json.dumps(payload, separators=(",", ":"), sort_keys=True).encode()
+        )
+        signature = _b64encode(
+            hmac.new(
+                self._demo_admin_key if demo_admin else self._key,
+                encoded.encode("ascii"),
+                hashlib.sha256,
+            ).digest()
+        )
+        token = f"{encoded}.{signature}"
+        if self._mongo is not None:
+            self._mongo_backend.write(
+                self._mongo, "delete_many", {"expires": {"$lte": issued_at}}
+            )
+            self._mongo_backend.write(
+                self._mongo,
+                "insert_one",
+                {
+                    "_id": hashlib.sha256(token.encode()).hexdigest(),
+                    "expires": payload["exp"],
+                },
+            )
+            self._mongo_sessions[hashlib.sha256(token.encode()).hexdigest()] = payload[
+                "exp"
+            ]
+        return token
+
+    def verify(self, token: str, *, now: int | None = None) -> dict[str, int | str]:
+        try:
+            encoded, supplied_signature = token.split(".", 1)
+            expected_signature = _b64encode(
+                hmac.new(self._key, encoded.encode("ascii"), hashlib.sha256).digest()
+            )
+            ordinary_signature = hmac.compare_digest(
+                supplied_signature, expected_signature
+            )
+            administrator_signature = False
+            if self._demo_admin_key is not None:
+                administrator_signature = hmac.compare_digest(
+                    supplied_signature,
+                    _b64encode(
+                        hmac.new(
+                            self._demo_admin_key,
+                            encoded.encode("ascii"),
+                            hashlib.sha256,
+                        ).digest()
+                    ),
+                )
+            if not (ordinary_signature or administrator_signature):
+                raise InvalidSession("invalid session signature")
+            payload = json.loads(_b64decode(encoded))
+            if not isinstance(payload, dict):
+                raise InvalidSession("malformed session")
+            elevated = payload.get("demo_admin") is True
+            if not (administrator_signature if elevated else ordinary_signature):
+                raise InvalidSession("invalid session capability signature")
+            current_time = int(time.time() if now is None else now)
+            if payload.get("v") != _TOKEN_VERSION:
+                raise InvalidSession("unsupported session version")
+            if (
+                not isinstance(payload.get("exp"), int)
+                or payload["exp"] <= current_time
+            ):
+                raise InvalidSession("session expired")
+            if (
+                not isinstance(payload.get("iat"), int)
+                or payload["iat"] > current_time + 60
+            ):
+                raise InvalidSession("invalid session timestamp")
+            if not isinstance(payload.get("nonce"), str):
+                raise InvalidSession("invalid session nonce")
+            if (
+                self._mongo is not None
+                and self._mongo_sessions.get(
+                    hashlib.sha256(token.encode()).hexdigest(), 0
+                )
+                <= current_time
+            ):
+                raise InvalidSession("Session was revoked")
+            return payload
+        except InvalidSession:
+            raise
+        except (ValueError, TypeError, KeyError, json.JSONDecodeError) as exc:
+            raise InvalidSession("malformed session") from exc
+
+
+@dataclass(frozen=True, slots=True)
+class LoginDecision:
+    allowed: bool
+    retry_after: int = 0
+
+
+class LoginLimiter:
+    """Small in-memory sliding-window limiter for password attempts."""
+
+    def __init__(
+        self,
+        attempts: int = 5,
+        window_seconds: int = 300,
+        max_clients: int = 10_000,
+    ) -> None:
+        if attempts <= 0 or window_seconds <= 0 or max_clients <= 0:
+            raise ValueError("login limiter settings must be positive")
+        self._attempts = attempts
+        self._window = window_seconds
+        self._max_clients = max_clients
+        self._failures: OrderedDict[str, deque[float]] = OrderedDict()
+
+    def check(self, key: str, *, now: float | None = None) -> LoginDecision:
+        current = time.monotonic() if now is None else now
+        failures = self._failures.get(key)
+        if failures is None:
+            if len(self._failures) >= self._max_clients:
+                self._failures.popitem(last=False)
+            failures = deque()
+            self._failures[key] = failures
+        else:
+            self._failures.move_to_end(key)
+        while failures and failures[0] <= current - self._window:
+            failures.popleft()
+        if len(failures) < self._attempts:
+            return LoginDecision(True)
+        retry_after = max(1, int(self._window - (current - failures[0])))
+        return LoginDecision(False, retry_after)
+
+    def failure(self, key: str, *, now: float | None = None) -> None:
+        current = time.monotonic() if now is None else now
+        self.check(key, now=current)
+        self._failures[key].append(current)
+
+    def success(self, key: str) -> None:
+        self._failures.pop(key, None)
+
+
+def verify_password(candidate: str, expected: str) -> bool:
+    """Compare passwords without content-dependent early exits."""
+
+    if expected.startswith("$argon2id$"):
+        try:
+            return PasswordHasher().verify(expected, candidate)
+        except VerificationError:
+            return False
+    return hmac.compare_digest(candidate.encode("utf-8"), expected.encode("utf-8"))
+
+
+def safe_name(value: str | None, *, fallback: str = "file") -> str:
+    """Normalize an untrusted display/file name without interpreting it as a path."""
+
+    raw = (value or "").replace("\\", "/").rsplit("/", 1)[-1]
+    normalized = unicodedata.normalize("NFC", raw).strip()
+    normalized = "".join(
+        char for char in normalized if unicodedata.category(char) != "Cc"
+    )
+    normalized = normalized.strip(". ")
+    if normalized in {"", ".", ".."}:
+        normalized = fallback
+    # Telegram and common filesystems become unreliable with very long names.
+    return normalized[:240]
diff --git a/tgdrive/media/__init__.py b/tgdrive/media/__init__.py
new file mode 100644
index 00000000..b249caf6
--- /dev/null
+++ b/tgdrive/media/__init__.py
@@ -0,0 +1 @@
+"""Streaming, shared media caching, previews, and isolated media workers."""
diff --git a/tgdrive/media/book_worker.py b/tgdrive/media/book_worker.py
new file mode 100644
index 00000000..ad8ed891
--- /dev/null
+++ b/tgdrive/media/book_worker.py
@@ -0,0 +1,855 @@
+"""Isolated, bounded archive parsing. Never extract a book onto the filesystem."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import posixpath
+import re
+import struct
+import sys
+from collections import OrderedDict
+from html.parser import HTMLParser
+from urllib.parse import unquote, urlsplit
+from zipfile import ZipFile
+
+from defusedxml import ElementTree as ET
+
+BLOCK = 1024 * 1024
+MAX_READ = 32 * BLOCK
+MAX_ENTRY = 16 * BLOCK
+MAX_PAGE = 64 * BLOCK
+MAX_PAGE_READ = 96 * BLOCK
+MAX_TEXT = 2 * BLOCK
+MAX_ENTRIES = 10000
+MAX_IMAGE_PIXELS = 16_000_000
+MAX_IMAGE_EDGE = 32768
+IMAGES = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif"}
+
+
+class BookError(ValueError):
+    pass
+
+
+def safe_name(name):
+    if (
+        not isinstance(name, str)
+        or not name
+        or len(name) > 1024
+        or name.startswith("/")
+        or "\\" in name
+        or any(ord(c) < 32 for c in name)
+    ):
+        raise BookError("This book contains an invalid resource path.")
+    if any(p in {"..", "."} for p in name.split("/")):
+        raise BookError("This book contains an unsafe resource path.")
+    return name
+
+
+def local_ref(base, value):
+    if not isinstance(value, str) or len(value) > 2048:
+        return None
+    url = urlsplit(value)
+    if url.scheme or url.netloc or value.startswith(("/", "\\")):
+        return None
+    path = (
+        posixpath.normpath(posixpath.join(posixpath.dirname(base), unquote(url.path)))
+        if url.path
+        else base
+    )
+    try:
+        safe_name(path)
+    except BookError:
+        return None
+    return path + ("#" + unquote(url.fragment) if url.fragment else "")
+
+
+class RemoteFile(io.RawIOBase):
+    def __init__(self, size, fetch, *, maximum=MAX_READ):
+        self.size, self.fetch, self.pos = size, fetch, 0
+        self.maximum = maximum
+        self.cache = OrderedDict()
+        self.used = 0
+        self.failure = None
+
+    def readable(self):
+        return True
+
+    def seekable(self):
+        return True
+
+    def tell(self):
+        return self.pos
+
+    def seek(self, offset, whence=0):
+        value = (
+            offset
+            if whence == 0
+            else self.pos + offset
+            if whence == 1
+            else self.size + offset
+            if whence == 2
+            else -1
+        )
+        if not 0 <= value <= self.size:
+            raise BookError("The book requests an invalid byte range.")
+        self.pos = value
+        return value
+
+    def read(self, amount=-1):
+        if amount is None or amount < 0:
+            amount = self.size - self.pos
+        if amount > self.maximum:
+            raise BookError(
+                "This book needs too much data for a selective preview. "
+                "Download it instead."
+            )
+        end = min(self.size, self.pos + amount)
+        output = bytearray()
+        while self.pos < end:
+            block = self.pos // BLOCK
+            if block not in self.cache:
+                count = min(BLOCK, self.size - block * BLOCK)
+                if self.used + count > self.maximum:
+                    raise BookError(
+                        f"This archive needs more than {self.maximum // BLOCK} MiB "
+                        "to read this page. "
+                        "Download it instead."
+                    )
+                data = self.fetch(block * BLOCK, count)
+                if len(data) != count:
+                    raise BookError("The book ended before its declared length.")
+                self.used += count
+                self.cache[block] = data
+                while len(self.cache) > 4:
+                    self.cache.popitem(last=False)
+            self.cache.move_to_end(block)
+            chunk = self.cache[block][
+                self.pos % BLOCK : min(BLOCK, end - block * BLOCK)
+            ]
+            output.extend(chunk)
+            self.pos += len(chunk)
+        return bytes(output)
+
+    def readinto(self, target):
+        data = self.read(len(target))
+        target[: len(data)] = data
+        return len(data)
+
+
+class SafeRarSource:
+    # ctypes callbacks must return an error sentinel instead of raising across C.
+    def __init__(self, source):
+        self.source = source
+
+    def seekable(self):
+        return True
+
+    def seek(self, *args):
+        try:
+            return self.source.seek(*args)
+        except Exception as exc:
+            self.source.failure = exc
+            return self.source.pos
+
+    def tell(self):
+        return self.source.pos
+
+    def readinto(self, target):
+        if self.source.failure:
+            return 0
+        try:
+            return self.source.readinto(target)
+        except Exception as exc:
+            self.source.failure = exc
+            return 0
+
+
+def open_zip(source):
+    # Bound the directory before ZipFile allocates one object per entry.
+    tail_size = min(source.size, 65557)
+    source.seek(source.size - tail_size)
+    tail = source.read(tail_size)
+    at = tail.rfind(b"PK\x05\x06")
+    if at < 0 or len(tail) - at < 22:
+        raise BookError("This is not a readable ZIP book.")
+    _, disk, cd_disk, disk_count, count, length, offset, comment = struct.unpack_from(
+        "<4s4H2LH", tail, at
+    )
+    if at + 22 + comment != len(tail) or disk or cd_disk or disk_count != count:
+        raise BookError("Split-volume ZIP books are not supported.")
+    if count == 65535 or length == 0xFFFFFFFF or offset == 0xFFFFFFFF:
+        position = source.size - tail_size + at
+        if position < 20:
+            raise BookError("Invalid ZIP64 book.")
+        source.seek(position - 20)
+        locator = source.read(20)
+        signature, disk, zip64_at, disks = struct.unpack("<4sLQL", locator)
+        if signature != b"PK\x06\x07" or disk or disks != 1:
+            raise BookError("Split-volume books are not supported.")
+        source.seek(zip64_at)
+        record = struct.unpack("<4sQ2H2L4Q", source.read(56))
+        if (
+            record[0] != b"PK\x06\x06"
+            or record[4]
+            or record[5]
+            or record[6] != record[7]
+        ):
+            raise BookError("Invalid ZIP64 directory.")
+        count, length, offset = record[7:10]
+    if count > MAX_ENTRIES or length > 2 * BLOCK or offset + length > source.size:
+        raise BookError("This book has too many resources for the reader.")
+    archive = ZipFile(source)
+    names = set()
+    for entry in archive.infolist():
+        if entry.is_dir():
+            continue
+        safe_name(entry.filename)
+        if entry.filename in names or entry.flag_bits & 1:
+            archive.close()
+            raise BookError("Duplicate or encrypted book resources are not supported.")
+        names.add(entry.filename)
+    return archive
+
+
+def zip_bytes(archive, name, maximum=MAX_TEXT):
+    safe_name(name)
+    try:
+        entry = archive.getinfo(name)
+    except KeyError as exc:
+        raise BookError("This book resource is missing.") from exc
+    if entry.file_size > maximum:
+        raise BookError(
+            f"This resource exceeds the {maximum // BLOCK} MiB preview limit."
+        )
+    if entry.compress_type not in {0, 8}:
+        raise BookError("This resource uses an unsupported ZIP compression method.")
+    if entry.file_size > max(1, entry.compress_size) * 1000:
+        raise BookError("This resource has an excessive compression ratio.")
+    with archive.open(entry) as stream:
+        data = stream.read(maximum + 1)
+    if len(data) > maximum:
+        raise BookError("This page is too large to preview.")
+    return data
+
+
+def xml(data):
+    if b"<!DOCTYPE" in data.upper() or b"<!ENTITY" in data.upper():
+        raise BookError("Books with XML entity declarations are not supported.")
+    return ET.fromstring(data)
+
+
+def natural(name):
+    return [int(x) if x.isdigit() else x.casefold() for x in re.split(r"(\d+)", name)]
+
+
+def image_type(data):
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if data.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if data.startswith((b"GIF87a", b"GIF89a")):
+        return "image/gif"
+    if data.startswith(b"RIFF") and data[8:12] == b"WEBP":
+        return "image/webp"
+    if data[4:8] == b"ftyp" and data[8:12] in {b"avif", b"avis"}:
+        return "image/avif"
+    raise BookError("This page is not a supported image.")
+
+
+def image_dimensions(data, mime):
+    """Read bounded raster headers only; never allocate decoded pixels."""
+    if mime == "image/png":
+        if len(data) < 33 or data[8:16] != b"\x00\x00\x00\rIHDR":
+            raise ValueError
+        dimensions = [struct.unpack_from(">II", data, 16)]
+        position = 33
+        for _ in range(MAX_ENTRIES):
+            if position + 12 > len(data):
+                raise ValueError
+            length, kind = struct.unpack_from(">I4s", data, position)
+            if position + length + 12 > len(data):
+                raise ValueError
+            if kind == b"fcTL":
+                if length != 26:
+                    raise ValueError
+                width, height, left, top = struct.unpack_from(
+                    ">IIII", data, position + 12
+                )
+                dimensions.extend(((width, height), (left + width, top + height)))
+            if kind == b"IEND":
+                return dimensions
+            position += length + 12
+        raise ValueError
+    if mime == "image/gif":
+        if len(data) < 13:
+            raise ValueError
+        dimensions = [struct.unpack_from("<HH", data, 6)]
+        position = 13 + (3 * (2 << (data[10] & 7)) if data[10] & 0x80 else 0)
+        for _ in range(MAX_ENTRIES):
+            if position >= len(data):
+                raise ValueError
+            kind = data[position]
+            position += 1
+            if kind == 0x3B:
+                return dimensions
+            if kind == 0x2C:
+                if position + 9 > len(data):
+                    raise ValueError
+                left, top, width, height = struct.unpack_from("<HHHH", data, position)
+                dimensions.extend(((width, height), (left + width, top + height)))
+                packed = data[position + 8]
+                position += 10 + (3 * (2 << (packed & 7)) if packed & 0x80 else 0)
+            elif kind == 0x21:
+                position += 1
+            else:
+                raise ValueError
+            for _ in range(MAX_ENTRIES):
+                if position >= len(data):
+                    raise ValueError
+                length = data[position]
+                position += length + 1
+                if not length:
+                    break
+            else:
+                raise ValueError
+        raise ValueError
+    if mime == "image/jpeg":
+        position = 2
+        for _ in range(MAX_ENTRIES):
+            if position + 4 > min(len(data), BLOCK) or data[position] != 0xFF:
+                raise ValueError
+            while position < min(len(data), BLOCK) and data[position] == 0xFF:
+                position += 1
+            if position + 3 > min(len(data), BLOCK):
+                raise ValueError
+            marker = data[position]
+            position += 1
+            if marker == 0x01:
+                continue
+            if marker in {0xD9, 0xDA}:
+                raise ValueError
+            length = int.from_bytes(data[position : position + 2], "big")
+            if length < 2 or position + length > len(data):
+                raise ValueError
+            if marker in {
+                0xC0,
+                0xC1,
+                0xC2,
+                0xC3,
+                0xC5,
+                0xC6,
+                0xC7,
+                0xC9,
+                0xCA,
+                0xCB,
+                0xCD,
+                0xCE,
+                0xCF,
+            }:
+                if length < 8:
+                    raise ValueError
+                height, width = struct.unpack_from(">HH", data, position + 3)
+                return [(width, height)]
+            position += length
+        raise ValueError
+    if mime == "image/webp":
+        end = int.from_bytes(data[4:8], "little") + 8
+        if end > len(data) or end < 20:
+            raise ValueError
+        pending = [(12, end)]
+        dimensions = []
+        count = 0
+        while pending:
+            position, end = pending.pop()
+            while position < end:
+                count += 1
+                if count > MAX_ENTRIES or position + 8 > end:
+                    raise ValueError
+                kind = data[position : position + 4]
+                length = int.from_bytes(data[position + 4 : position + 8], "little")
+                start = position + 8
+                if start + length > end:
+                    raise ValueError
+                if kind == b"VP8X" and length >= 10:
+                    dimensions.append(
+                        tuple(
+                            int.from_bytes(
+                                data[start + offset : start + offset + 3], "little"
+                            )
+                            + 1
+                            for offset in (4, 7)
+                        )
+                    )
+                elif kind == b"VP8 " and length >= 10:
+                    if data[start + 3 : start + 6] != b"\x9d\x01\x2a":
+                        raise ValueError
+                    dimensions.append(
+                        tuple(
+                            value & 0x3FFF
+                            for value in struct.unpack_from("<HH", data, start + 6)
+                        )
+                    )
+                elif kind == b"VP8L" and length >= 5 and data[start] == 0x2F:
+                    bits = int.from_bytes(data[start + 1 : start + 5], "little")
+                    dimensions.append(
+                        ((bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1)
+                    )
+                elif kind == b"ANMF" and length >= 16:
+                    left, top, width, height = (
+                        int.from_bytes(
+                            data[start + offset : start + offset + 3], "little"
+                        )
+                        for offset in (0, 3, 6, 9)
+                    )
+                    dimensions.extend(
+                        (
+                            (width + 1, height + 1),
+                            (left * 2 + width + 1, top * 2 + height + 1),
+                        )
+                    )
+                    pending.append((start + 16, start + length))
+                position = start + length + (length & 1)
+        return dimensions
+    if mime == "image/avif":
+        # Visit only dimension-bearing HEIF properties and AV1 sample entries.
+        containers = {
+            b"meta": 4,
+            b"iprp": 0,
+            b"ipco": 0,
+            b"moov": 0,
+            b"trak": 0,
+            b"mdia": 0,
+            b"minf": 0,
+            b"stbl": 0,
+            b"stsd": 8,
+        }
+        pending = [(0, len(data), 0)]
+        dimensions = []
+        count = 0
+        while pending:
+            position, end, depth = pending.pop()
+            while position < end:
+                count += 1
+                if count > MAX_ENTRIES or depth > 8 or position + 8 > end:
+                    raise ValueError
+                length, kind = struct.unpack_from(">I4s", data, position)
+                header = 8
+                if length == 1:
+                    if position + 16 > end:
+                        raise ValueError
+                    length = struct.unpack_from(">Q", data, position + 8)[0]
+                    header = 16
+                elif length == 0:
+                    length = end - position
+                if length < header or position + length > end:
+                    raise ValueError
+                start, stop = position + header, position + length
+                if kind == b"ispe":
+                    if stop - start < 12:
+                        raise ValueError
+                    dimensions.append(struct.unpack_from(">II", data, start + 4))
+                elif kind == b"av01":
+                    if stop - start < 78:
+                        raise ValueError
+                    dimensions.append(struct.unpack_from(">HH", data, start + 24))
+                elif kind in containers:
+                    child = start + containers[kind]
+                    if child > stop:
+                        raise ValueError
+                    pending.append((child, stop, depth + 1))
+                position = stop
+        return dimensions
+    raise ValueError
+
+
+def image_result(data, *, raw_images):
+    mime = image_type(data)
+    try:
+        dimensions = image_dimensions(data, mime)
+        if not dimensions or any(
+            not width or not height for width, height in dimensions
+        ):
+            raise ValueError
+    except ValueError, struct.error, IndexError:
+        raise BookError(
+            "This page has invalid or overly complex image dimensions. "
+            "Download the original to open it in another reader."
+        ) from None
+    if any(
+        width > MAX_IMAGE_EDGE
+        or height > MAX_IMAGE_EDGE
+        or width * height > MAX_IMAGE_PIXELS
+        for width, height in dimensions
+    ):
+        raise BookError(
+            "This page exceeds the 16 million pixel or 32768-pixel edge limit. "
+            "Download the original to open it in another reader."
+        )
+    return {
+        "kind": "image",
+        "mime": mime,
+        **(
+            {"content": data}
+            if raw_images
+            else {"data": base64.b64encode(data).decode()}
+        ),
+    }
+
+
+class ChapterParser(HTMLParser):
+    allowed = frozenset(
+        [
+            "p",
+            "div",
+            "span",
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "h5",
+            "h6",
+            "strong",
+            "b",
+            "em",
+            "i",
+            "u",
+            "s",
+            "a",
+            "img",
+            "ul",
+            "ol",
+            "li",
+            "blockquote",
+            "pre",
+            "code",
+            "br",
+            "hr",
+            "table",
+            "thead",
+            "tbody",
+            "tr",
+            "th",
+            "td",
+            "caption",
+            "dl",
+            "dt",
+            "dd",
+            "sup",
+            "sub",
+            "figure",
+            "figcaption",
+            "section",
+            "article",
+        ]
+    )
+    blocked = frozenset(
+        [
+            "script",
+            "style",
+            "iframe",
+            "object",
+            "embed",
+            "form",
+            "audio",
+            "video",
+            "svg",
+            "math",
+            "template",
+            "head",
+        ]
+    )
+
+    def __init__(self, base):
+        super().__init__(convert_charrefs=True)
+        self.base = base
+        self.root = []
+        self.stack = [("", self.root)]
+        self.hidden = 0
+        self.nodes = 0
+
+    def handle_starttag(self, tag, attrs):
+        if tag in self.blocked:
+            self.hidden += 1
+        if self.hidden or tag not in self.allowed:
+            return
+        self.nodes += 1
+        if self.nodes > 20000 or len(self.stack) > 100:
+            raise BookError("This chapter is too complex to preview.")
+        attrs = dict(attrs)
+        node = {"tag": tag, "children": []}
+        if attrs.get("id") and len(attrs["id"]) <= 128:
+            node["id"] = attrs["id"]
+        if tag == "a":
+            node["href"] = local_ref(self.base, attrs.get("href", ""))
+        if tag == "img":
+            node["src"] = local_ref(self.base, attrs.get("src", ""))
+            node["alt"] = (attrs.get("alt") or "")[:500]
+        self.stack[-1][1].append(node)
+        if tag not in {"img", "br", "hr"}:
+            self.stack.append((tag, node["children"]))
+
+    def handle_startendtag(self, tag, attrs):
+        self.handle_starttag(tag, attrs)
+        if tag not in {"img", "br", "hr"}:
+            self.handle_endtag(tag)
+
+    def handle_endtag(self, tag):
+        if tag in self.blocked and self.hidden:
+            self.hidden -= 1
+            return
+        if self.hidden:
+            return
+        for i in range(len(self.stack) - 1, 0, -1):
+            if self.stack[i][0] == tag:
+                self.stack = self.stack[:i]
+                break
+
+    def handle_data(self, data):
+        if not self.hidden and data:
+            self.nodes += 1
+            if self.nodes > 20000:
+                raise BookError("This chapter is too complex to preview.")
+            self.stack[-1][1].append(data)
+
+
+def epub_index(archive):
+    if "META-INF/encryption.xml" in archive.namelist():
+        raise BookError(
+            "Encrypted EPUB resources are not supported. Use an authorized reading app."
+        )
+    container = xml(zip_bytes(archive, "META-INF/container.xml"))
+    rootfile = next(
+        (
+            n.get("full-path")
+            for n in container.iter()
+            if n.tag.rsplit("}", 1)[-1] == "rootfile"
+        ),
+        None,
+    )
+    if not rootfile:
+        raise BookError("The EPUB package is missing.")
+    package = xml(zip_bytes(archive, rootfile))
+    manifest = {}
+    title = ""
+    for node in package.iter():
+        tag = node.tag.rsplit("}", 1)[-1]
+        if tag == "title" and not title:
+            title = (node.text or "")[:300]
+        if tag == "item" and node.get("id") and node.get("href"):
+            name = local_ref(rootfile, node.get("href"))
+            if name:
+                manifest[node.get("id")] = (
+                    name.split("#")[0],
+                    node.get("media-type"),
+                    node.get("properties", ""),
+                )
+    labels = {}
+    for name, _mime, properties in manifest.values():
+        if "nav" in properties.split():
+            nav = xml(zip_bytes(archive, name))
+            for link in nav.iter():
+                if link.tag.rsplit("}", 1)[-1] == "a":
+                    target = local_ref(name, link.get("href", ""))
+                    if target:
+                        labels.setdefault(
+                            target.split("#")[0],
+                            " ".join(link.itertext()).strip()[:200],
+                        )
+    entries = []
+    for node in package.iter():
+        if (
+            node.tag.rsplit("}", 1)[-1] == "itemref"
+            and node.get("linear", "yes") != "no"
+        ):
+            item = manifest.get(node.get("idref"))
+            if item and item[1] in {"application/xhtml+xml", "text/html"}:
+                name = item[0]
+                entries.append(
+                    {
+                        "name": name,
+                        "label": labels.get(name) or posixpath.basename(name),
+                    }
+                )
+    if not entries or len(entries) > 5000:
+        raise BookError("This EPUB has no supported reading order.")
+    return {"kind": "epub", "title": title, "entries": entries}
+
+
+def read_book(source, fmt, entry=None, *, raw_images=False):
+    image_limit = MAX_PAGE if raw_images else MAX_ENTRY
+    if fmt in {"epub", "cbz"}:
+        with open_zip(source) as archive:
+            if entry is None:
+                if fmt == "epub":
+                    return epub_index(archive)
+                pages = sorted(
+                    (
+                        n
+                        for n in archive.namelist()
+                        if posixpath.splitext(n)[1].lower() in IMAGES
+                        and not n.startswith("__MACOSX/")
+                    ),
+                    key=natural,
+                )
+                if not pages:
+                    raise BookError("This comic has no supported image pages.")
+                return {
+                    "kind": "comic",
+                    "entries": [
+                        {"name": n, "label": "Page " + str(i + 1)}
+                        for i, n in enumerate(pages)
+                    ],
+                }
+            data = zip_bytes(
+                archive,
+                entry,
+                MAX_TEXT
+                if posixpath.splitext(entry)[1].lower() in {".html", ".xhtml", ".htm"}
+                else image_limit,
+            )
+            if fmt == "epub" and posixpath.splitext(entry)[1].lower() in {
+                ".html",
+                ".xhtml",
+                ".htm",
+            }:
+                parser = ChapterParser(entry)
+                parser.feed(data.decode("utf-8-sig", errors="replace"))
+                parser.close()
+                return {"kind": "chapter", "nodes": parser.root}
+            return image_result(data, raw_images=raw_images)
+    if fmt != "cbr":
+        raise BookError("Unsupported reading format.")
+    source.seek(0)
+    if not source.read(8).startswith(b"Rar!\x1a\x07"):
+        raise BookError("This is not a readable RAR comic.")
+    source.seek(0)
+    try:
+        import libarchive
+    except (ImportError, OSError, AttributeError) as exc:
+        raise BookError(
+            "CBR support needs libarchive. "
+            "Use the TGDrive Docker image or install libarchive."
+        ) from exc
+    pages = []
+    with libarchive.stream_reader(
+        SafeRarSource(source), filter_name="none", block_size=65536
+    ) as archive:
+        for i, member in enumerate(archive):
+            if source.failure:
+                raise source.failure
+            if i >= MAX_ENTRIES:
+                raise BookError("This comic has too many resources.")
+            name = str(member.pathname)
+            safe_name(name)
+            if not member.isfile or posixpath.splitext(name)[1].lower() not in IMAGES:
+                continue
+            if entry is None:
+                if name in pages:
+                    raise BookError("This comic contains duplicate page names.")
+                pages.append(name)
+            elif name == entry:
+                if member.size is None or member.size > image_limit:
+                    raise BookError("This page is too large to preview.")
+                output = bytearray()
+                for block in member.get_blocks():
+                    output.extend(block)
+                    if source.failure:
+                        raise source.failure
+                    if len(output) > image_limit:
+                        raise BookError("This page is too large to preview.")
+                data = bytes(output)
+                return image_result(data, raw_images=raw_images)
+    if source.failure:
+        raise source.failure
+    if entry is not None:
+        raise BookError("This comic page is missing.")
+    if not pages:
+        raise BookError("This comic has no supported image pages.")
+    return {
+        "kind": "comic",
+        "entries": [
+            {"name": n, "label": "Page " + str(i + 1)}
+            for i, n in enumerate(sorted(pages, key=natural))
+        ],
+    }
+
+
+def run():
+    try:
+        import resource
+
+        resource.setrlimit(resource.RLIMIT_AS, (384 * BLOCK, 384 * BLOCK))
+        resource.setrlimit(resource.RLIMIT_CPU, (10, 10))
+        resource.setrlimit(resource.RLIMIT_FSIZE, (0, 0))
+    except ImportError:
+        pass
+    request = json.loads(sys.stdin.readline())
+
+    def fetch(offset, length):
+        print(json.dumps({"read": [offset, length]}), flush=True)
+        reply = json.loads(sys.stdin.readline())
+        return base64.b64decode(reply["data"], validate=True)
+
+    try:
+        # The larger budget applies only to a selected original raster page.
+        # Indexes, text and thumbnail extraction retain their smaller limits.
+        raw_images = bool(request.get("raw_images")) and not request.get("thumbnail")
+        raster = (
+            raw_images
+            and posixpath.splitext(request.get("entry") or "")[1].lower() in IMAGES
+        )
+        source = RemoteFile(
+            request["size"], fetch, maximum=MAX_PAGE_READ if raster else MAX_READ
+        )
+        if request.get("thumbnail") and request["format"] in {
+            "epub",
+            "cbz",
+            "docx",
+            "pptx",
+            "xlsx",
+            "odt",
+            "odp",
+            "ods",
+        }:
+            from tgdrive.media.thumbnail_worker import archive_cover_from_source
+
+            cover = archive_cover_from_source(source, "." + request["format"])
+            result = (
+                {"kind": "missing"}
+                if cover is None
+                else {
+                    "kind": "image",
+                    "mime": image_type(cover[0]),
+                    "data": base64.b64encode(cover[0]).decode(),
+                }
+            )
+        else:
+            result = read_book(
+                source, request["format"], request.get("entry"), raw_images=raw_images
+            )
+        if result.get("kind") == "image" and "content" in result:
+            content = result.pop("content")
+            print(
+                json.dumps({"image": {"mime": result["mime"], "length": len(content)}}),
+                flush=True,
+            )
+            sys.stdout.buffer.write(content)
+            sys.stdout.buffer.flush()
+        else:
+            print(json.dumps({"result": result}), flush=True)
+    except Exception as exc:
+        message = (
+            str(exc)
+            if isinstance(exc, BookError)
+            else (
+                "This book is damaged, encrypted or uses an unsupported feature. "
+                "Download it to open in a dedicated reader."
+            )
+        )
+        print(json.dumps({"error": message[:500]}), flush=True)
+
+
+if __name__ == "__main__":
+    run()
diff --git a/tgdrive/media/books.py b/tgdrive/media/books.py
new file mode 100644
index 00000000..56267cd5
--- /dev/null
+++ b/tgdrive/media/books.py
@@ -0,0 +1,284 @@
+"""Authorized, selective book reads through a resource-limited parser process."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import json
+import os
+import sys
+import time
+from collections import OrderedDict
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path, PurePath
+
+from fastapi import HTTPException
+
+from tgdrive.media.logical_media import PartLease, part_ranges
+from tgdrive.media.media_reader import stream_pooled_media
+from tgdrive.media.previews import lease_media
+from tgdrive.media.ranges import ByteRange, plan_telegram_chunks
+from tgdrive.storage.file_parts import validate_parts
+
+BLOCK = 1024 * 1024
+MAX_READ = 32 * BLOCK
+MAX_OUTPUT = 24 * BLOCK
+MAX_PAGE = 64 * BLOCK
+MAX_PAGE_READ = 96 * BLOCK
+RASTER_TYPES = {"image/png", "image/jpeg", "image/gif", "image/webp", "image/avif"}
+PROJECT_ROOT = str(Path(__file__).resolve().parents[2])
+
+
+async def read_range(pool, channel, data, start, count, authorize, *, background=False):
+    await authorize()
+    selection = ByteRange(start, start + count - 1, data["size"], is_partial=True)
+    result = bytearray()
+    if data.get("parts") is not None:
+        parts = validate_parts(
+            data["parts"], size=data["size"], message_id=data["message_id"]
+        )
+        for part, interval in part_ranges(parts, selection):
+            lease = await PartLease(
+                pool, channel, part, authorize=authorize, background=background
+            ).open()
+            stream = lease.read(interval)
+            try:
+                async for block in stream:
+                    result.extend(block)
+            finally:
+                await stream.aclose()
+                await lease.close()
+    else:
+        async with lease_media(
+            pool, channel, data["message_id"], background=background
+        ) as (
+            client,
+            message,
+            media,
+        ):
+            if media.file_size != data["size"]:
+                raise HTTPException(409, "The stored book changed. Reopen it.")
+            plan = plan_telegram_chunks(selection)
+            stream = stream_pooled_media(
+                pool,
+                client,
+                message,
+                channel=channel,
+                offset=plan.offset // plan.chunk_size,
+                limit=plan.part_count,
+                authorize=authorize,
+                background=background,
+            )
+            try:
+                index = 0
+                async for block in stream:
+                    first = plan.first_part_cut if index == 0 else 0
+                    last = (
+                        plan.last_part_cut
+                        if index == plan.part_count - 1
+                        else len(block)
+                    )
+                    result.extend(block[first:last])
+                    index += 1
+                    if index >= plan.part_count:
+                        break
+            finally:
+                await stream.aclose()
+    if len(result) != count:
+        raise HTTPException(
+            409, "The book ended early. Reopen it or download the original."
+        )
+    await authorize()
+    return bytes(result)
+
+
+async def parse_book(data, fetch, entry=None, *, thumbnail=False, raw_images=False):
+    fmt = PurePath(data["name"]).suffix.lower().lstrip(".")
+    if fmt not in (
+        {"epub", "cbz", "cbr", "docx", "pptx", "xlsx", "odt", "odp", "ods"}
+        if thumbnail
+        else {"epub", "cbz", "cbr"}
+    ):
+        raise HTTPException(415, "This file is not an EPUB, CBZ or CBR book.")
+    # Deliberately do not pass Telegram credentials, owner secrets or inherited
+    # application environment into a parser handling untrusted archive bytes.
+    environment = {
+        "PATH": os.defpath,
+        "LANG": "C.UTF-8",
+        "PYTHONPATH": PROJECT_ROOT,
+    }
+    if os.environ.get("LIBARCHIVE"):
+        environment["LIBARCHIVE"] = os.environ["LIBARCHIVE"]
+    process = await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-m",
+        "tgdrive.media.book_worker",
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.DEVNULL,
+        env=environment,
+        limit=MAX_OUTPUT,
+    )
+    raster = (
+        raw_images
+        and not thumbnail
+        and PurePath(entry or "").suffix.lower()
+        in {".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif"}
+    )
+    maximum = MAX_PAGE_READ if raster else MAX_READ
+    total = 0
+    try:
+        async with asyncio.timeout(45):
+            process.stdin.write(
+                json.dumps(
+                    {
+                        "size": data["size"],
+                        "format": fmt,
+                        "entry": entry,
+                        "thumbnail": thumbnail,
+                        "raw_images": raw_images,
+                    }
+                ).encode()
+                + b"\n"
+            )
+            await process.stdin.drain()
+            while True:
+                line = await process.stdout.readline()
+                if not line or len(line) > MAX_OUTPUT:
+                    raise HTTPException(
+                        422,
+                        "The book exceeds the reader limits or is damaged. "
+                        "Download it instead.",
+                    )
+                message = json.loads(line)
+                if "read" in message:
+                    start, count = message["read"]
+                    if (
+                        type(start) is not int
+                        or type(count) is not int
+                        or start < 0
+                        or not 0 < count <= BLOCK
+                        or start + count > data["size"]
+                        or total + count > maximum
+                    ):
+                        raise HTTPException(
+                            422,
+                            "This book needs too much data for a selective preview. "
+                            "Download it instead.",
+                        )
+                    total += count
+                    content = await fetch(start, count)
+                    process.stdin.write(
+                        json.dumps(
+                            {"data": base64.b64encode(content).decode()}
+                        ).encode()
+                        + b"\n"
+                    )
+                    await process.stdin.drain()
+                elif isinstance(message.get("image"), dict):
+                    image = message["image"]
+                    length, mime = image.get("length"), image.get("mime")
+                    if (
+                        not raster
+                        or type(length) is not int
+                        or not 0 < length <= MAX_PAGE
+                        or mime not in RASTER_TYPES
+                    ):
+                        raise HTTPException(422, "The book returned an invalid image.")
+                    content = await process.stdout.readexactly(length)
+                    return {"kind": "image", "mime": mime, "content": content}
+                elif "error" in message:
+                    raise HTTPException(422, str(message["error"])[:500])
+                elif isinstance(message.get("result"), dict):
+                    return message["result"]
+                else:
+                    raise HTTPException(422, "The book could not be read.")
+    except TimeoutError as exc:
+        raise HTTPException(
+            422, "This book took too long to read. Download it in a dedicated reader."
+        ) from exc
+    except (
+        ValueError,
+        KeyError,
+        BrokenPipeError,
+        ConnectionResetError,
+        asyncio.IncompleteReadError,
+    ) as exc:
+        raise HTTPException(
+            422, "This book could not be read. Download the original instead."
+        ) from exc
+    finally:
+        if process.returncode is None:
+            with suppress(ProcessLookupError):
+                process.kill()
+        await asyncio.shield(process.wait())
+        if process.stdin:
+            process.stdin.close()
+
+
+class BookCache:
+    """Bounded original-byte/metadata reuse; authorization stays in the route."""
+
+    def __init__(self, *, maximum=64 * BLOCK, entries=16, ttl=300):
+        self.maximum, self.entries, self.ttl = maximum, entries, ttl
+        self.bytes = 0
+        self.items = OrderedDict()
+        self.locks = {}
+
+    @staticmethod
+    def key(data, entry):
+        source = {key: data.get(key) for key in ("message_id", "size", "parts", "name")}
+        return hashlib.sha256(
+            json.dumps([source, entry], sort_keys=True).encode()
+        ).hexdigest()
+
+    def get(self, key):
+        now = time.monotonic()
+        for stale, (expires, content, _mime, _etag) in list(self.items.items()):
+            if expires <= now:
+                self.bytes -= len(content)
+                del self.items[stale]
+        result = self.items.get(key)
+        if result is not None:
+            self.items.move_to_end(key)
+            return result[1:]
+        return None
+
+    def put(self, key, result):
+        mime = (
+            result.get("mime") if result.get("kind") == "image" else "application/json"
+        )
+        content = (
+            result["content"]
+            if result.get("kind") == "image"
+            else json.dumps(result).encode()
+        )
+        etag = '"' + hashlib.sha256(content).hexdigest() + '"'
+        if len(content) <= self.maximum:
+            previous = self.items.pop(key, None)
+            if previous:
+                self.bytes -= len(previous[1])
+            while self.items and (
+                self.bytes + len(content) > self.maximum
+                or len(self.items) >= self.entries
+            ):
+                _, old = self.items.popitem(last=False)
+                self.bytes -= len(old[1])
+            self.items[key] = (time.monotonic() + self.ttl, content, mime, etag)
+            self.bytes += len(content)
+        return content, mime, etag
+
+    @asynccontextmanager
+    async def hold(self, key):
+        lock, users = self.locks.get(key, (asyncio.Lock(), 0))
+        self.locks[key] = lock, users + 1
+        try:
+            async with lock:
+                yield
+        finally:
+            remaining = self.locks[key][1] - 1
+            if remaining:
+                self.locks[key] = lock, remaining
+            else:
+                del self.locks[key]
diff --git a/tgdrive/media/generated_thumbnails.py b/tgdrive/media/generated_thumbnails.py
new file mode 100644
index 00000000..825bb62f
--- /dev/null
+++ b/tgdrive/media/generated_thumbnails.py
@@ -0,0 +1,430 @@
+"""Small derivatives from staged uploads or complete verified local cache data."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import secrets
+import shutil
+import signal
+import stat
+import sys
+import tempfile
+import time
+import weakref
+from collections import OrderedDict
+from contextlib import suppress
+from pathlib import Path
+
+MAX_BYTES = 64 * 1024
+DISK_BYTES = 128 * 1024**2
+MAX_ENTRIES = 4096
+_slots = weakref.WeakKeyDictionary()
+_background_slots = weakref.WeakKeyDictionary()
+PROJECT_ROOT = str(Path(__file__).resolve().parents[2])
+SUPPORTED = {
+    ".cbr",
+    ".docx",
+    ".pptx",
+    ".xlsx",
+    ".odt",
+    ".odp",
+    ".ods",
+    ".mp3",
+    ".flac",
+    ".m4a",
+    ".ogg",
+    ".opus",
+    ".wav",
+    ".aac",
+    ".epub",
+    ".cbz",
+    ".jpg",
+    ".jpeg",
+    ".png",
+    ".webp",
+    ".gif",
+    ".bmp",
+    ".tif",
+    ".tiff",
+    ".mp4",
+    ".m4v",
+    ".mov",
+    ".avif",
+    ".mkv",
+    ".webm",
+    ".avi",
+    ".wmv",
+    ".asf",
+    ".mpeg",
+    ".mpg",
+    ".pdf",
+}
+REPAIR_SOURCE_BYTES = 128 * 1024**2
+REPAIR_SECONDS = 8
+NATIVE_ADMISSION_SECONDS = 2
+
+
+class ThumbnailRendererBusy(Exception):
+    """No native renderer was admitted; the source has not failed to decode."""
+
+
+async def _finish_owned(task):
+    interrupted = False
+    while not task.done():
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            interrupted = True
+        except BaseException:
+            break
+    if interrupted:
+        # Opening a source can create an fd/path even after cancellation. Return
+        # its result to the owner so it can clean up before propagating the stop.
+        with suppress(BaseException):
+            return task.result(), True
+        return None, True
+    return task.result(), False
+
+
+async def _owned_task(task):
+    result, interrupted = await _finish_owned(task)
+    if interrupted:
+        raise asyncio.CancelledError
+    return result
+
+
+async def _owned_disk_call(function, *args, **kwargs):
+    return await _owned_task(
+        asyncio.create_task(asyncio.to_thread(function, *args, **kwargs))
+    )
+
+
+class CachedThumbnailRepair:
+    """One bounded local repair; missing bytes never initiate Telegram reads."""
+
+    def __init__(self, directory: Path):
+        self.directory = directory
+        self._slot = asyncio.Lock()
+        self._attempts = weakref.WeakKeyDictionary()
+
+    async def start(self):
+        with suppress(OSError):
+            await _owned_disk_call(self._cleanup_stale_sources)
+
+    def _cleanup_stale_sources(self):
+        if self.directory.is_symlink():
+            return
+        try:
+            import fcntl
+        except ImportError:
+            fcntl = None
+        for path in self.directory.glob(".repair-*.source"):
+            token = path.name.removeprefix(".repair-").removesuffix(".source")
+            if len(token) != 32 or any(c not in "0123456789abcdef" for c in token):
+                continue
+            try:
+                descriptor = os.open(path, os.O_RDWR | getattr(os, "O_NOFOLLOW", 0))
+                with os.fdopen(descriptor, "r+b") as previous:
+                    info = os.fstat(previous.fileno())
+                    if not stat.S_ISREG(info.st_mode) or (
+                        hasattr(os, "getuid") and info.st_uid != os.getuid()
+                    ):
+                        continue
+                    if fcntl is not None:
+                        # An active renderer holds this lock through native
+                        # decoding. A crash releases it without running cleanup.
+                        try:
+                            fcntl.flock(previous, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                        except BlockingIOError:
+                            continue
+                    elif info.st_mtime > time.time() - 60:
+                        continue
+                    path.unlink(missing_ok=True)
+            except OSError:
+                continue
+
+    def _open_source(self, size, reserve):
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        if self.directory.is_symlink():
+            raise OSError("Thumbnail directory must not be a symbolic link")
+        self._cleanup_stale_sources()
+        if shutil.disk_usage(self.directory).free < size + reserve:
+            raise OSError("Insufficient temporary thumbnail space")
+        path = self.directory / (".repair-" + secrets.token_hex(16) + ".source")
+        descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_RDWR, 0o600)
+        output = os.fdopen(descriptor, "w+b")
+        try:
+            import fcntl
+
+            fcntl.flock(output, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except ImportError:
+            pass
+        except BaseException:
+            self._cleanup_source(output, path)
+            raise
+        return output, path
+
+    @staticmethod
+    def _cleanup_source(output, path):
+        try:
+            output.close()
+        finally:
+            path.unlink(missing_ok=True)
+
+    async def get(self, cache, *, source, name, version, authorize):
+        from tgdrive.media.media_reader import CachedSourceUnavailable
+        from tgdrive.media.thumbnails import ThumbnailBusy
+
+        if (
+            version is None
+            or Path(name).suffix.lower() not in SUPPORTED
+            or not 0 < source["size"] <= REPAIR_SOURCE_BYTES
+        ):
+            return None
+        attempts = self._attempts.setdefault(cache, OrderedDict())
+        if attempts.get(version.file_id) == version.revision:
+            return None
+        # Optional work never forms another long queue behind the sole renderer.
+        deadline = asyncio.get_running_loop().time() + REPAIR_SECONDS
+        try:
+            await asyncio.wait_for(self._slot.acquire(), timeout=0.05)
+        except TimeoutError as exc:
+            raise ThumbnailBusy from exc
+        output = path = None
+        rendering = False
+        rendered = False
+
+        def remember_failure():
+            attempts[version.file_id] = version.revision
+            attempts.move_to_end(version.file_id)
+            while len(attempts) > MAX_ENTRIES:
+                attempts.popitem(last=False)
+
+        def native_started():
+            nonlocal rendering
+            rendering = True
+
+        try:
+            if attempts.get(version.file_id) == version.revision:
+                return None
+            async with asyncio.timeout_at(deadline):
+                written = 0
+                async for block in cache.cached_file_blocks(
+                    **source,
+                    version=version,
+                    max_bytes=REPAIR_SOURCE_BYTES,
+                    authorize=authorize,
+                ):
+                    if output is None:
+                        opening = asyncio.create_task(
+                            asyncio.to_thread(
+                                self._open_source,
+                                source["size"],
+                                max(64 * 1024**2, cache.policy.min_free_bytes),
+                            )
+                        )
+                        opened, interrupted = await _finish_owned(opening)
+                        if opened is not None:
+                            output, path = opened
+                        if interrupted:
+                            raise asyncio.CancelledError
+                    count = await _owned_disk_call(output.write, block)
+                    if count != len(block):
+                        raise CachedSourceUnavailable
+                    written += count
+                if output is None or written != source["size"]:
+                    raise CachedSourceUnavailable
+                await _owned_disk_call(output.flush)
+                if await _owned_disk_call(lambda: path.stat().st_size) != written:
+                    raise CachedSourceUnavailable
+                authorize()
+                cover = await generate(
+                    path, name, raise_busy=True, on_start=native_started
+                )
+                rendered = True
+                authorize()
+                if cache.cached_source_version(**source) != version:
+                    raise CachedSourceUnavailable
+                if cover:
+                    await _owned_disk_call(
+                        save,
+                        self.directory,
+                        source["channel_id"],
+                        source["message_id"],
+                        cover,
+                    )
+                    authorize()
+                    if cache.cached_source_version(**source) != version:
+                        raise CachedSourceUnavailable
+                elif rendering:
+                    remember_failure()
+                else:
+                    # A transient spawn failure never tested this source.
+                    raise ThumbnailRendererBusy
+                return cover
+        except asyncio.CancelledError:
+            # A disconnected request can retry; an unsuccessful completed
+            # repair stays suppressed until this file receives new cached data.
+            if attempts.get(version.file_id) == version.revision:
+                attempts.pop(version.file_id, None)
+            raise
+        except CachedSourceUnavailable as exc:
+            if cache.cached_source_version(**source) != version:
+                raise ThumbnailBusy from exc
+            return None
+        except ThumbnailRendererBusy as exc:
+            raise ThumbnailBusy from exc
+        except TimeoutError as exc:
+            if rendering and not rendered:
+                remember_failure()
+                return None
+            raise ThumbnailBusy from exc
+        except OSError as exc:
+            raise ThumbnailBusy from exc
+        except ValueError:
+            return None
+        except BaseException:
+            # Authorization/catalog failures belong to this request, not to
+            # the immutable source's ability to render for another viewer.
+            if attempts.get(version.file_id) == version.revision:
+                attempts.pop(version.file_id, None)
+            raise
+        finally:
+            try:
+                if output is not None:
+                    with suppress(OSError):
+                        await _owned_disk_call(self._cleanup_source, output, path)
+            finally:
+                self._slot.release()
+
+
+async def generate(
+    path: Path,
+    name: str,
+    *,
+    raise_busy=False,
+    on_start=None,
+    background=False,
+    remote_url=None,
+    source_size=None,
+) -> bytes | None:
+    suffix = Path(name).suffix.lower()
+    if suffix not in SUPPORTED:
+        return None
+    slots = _background_slots if background else _slots
+    slot = slots.setdefault(asyncio.get_running_loop(), asyncio.Semaphore(1))
+    try:
+        await asyncio.wait_for(slot.acquire(), timeout=NATIVE_ADMISSION_SECONDS)
+    except TimeoutError as exc:
+        if raise_busy:
+            raise ThumbnailRendererBusy from exc
+        return None
+    try:
+        process = None
+        try:
+            async with asyncio.timeout(120 if remote_url else 12):
+                opening = asyncio.create_task(
+                    asyncio.create_subprocess_exec(
+                        sys.executable,
+                        "-m",
+                        "tgdrive.media.thumbnail_worker",
+                        remote_url or str(await asyncio.to_thread(path.resolve)),
+                        suffix,
+                        *(
+                            ["remote", str(source_size)]
+                            if remote_url
+                            else ["background"]
+                            if background
+                            else []
+                        ),
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.DEVNULL,
+                        start_new_session=os.name == "posix",
+                        env={
+                            "PATH": os.defpath,
+                            "LANG": "C.UTF-8",
+                            "PYTHONPATH": PROJECT_ROOT,
+                        },
+                    )
+                )
+                process, interrupted = await _finish_owned(opening)
+                if interrupted:
+                    raise asyncio.CancelledError
+                if on_start is not None:
+                    on_start()
+                content = bytearray()
+                while block := await process.stdout.read(8192):
+                    content.extend(block)
+                    if len(content) > MAX_BYTES:
+                        return None
+                data = bytes(content)
+                await process.wait()
+                if process.returncode == 0 and data.startswith(b"\xff\xd8\xff"):
+                    return data
+        except OSError, TimeoutError:
+            pass
+        finally:
+            if process is not None:
+                with suppress(ProcessLookupError):
+                    if os.name == "posix":
+                        os.killpg(process.pid, signal.SIGKILL)
+                    elif process.returncode is None:
+                        process.kill()
+                await _owned_task(asyncio.create_task(process.wait()))
+    finally:
+        slot.release()
+    return None
+
+
+def location(directory: Path, channel: int, message: int) -> Path:
+    identity = hashlib.sha256(f"{channel}:{message}".encode()).hexdigest()
+    return directory / (identity + ".jpg")
+
+
+def read(directory: Path, channel: int, message: int) -> bytes | None:
+    path = location(directory, channel, message)
+    try:
+        if path.is_symlink() or path.stat().st_size > MAX_BYTES:
+            return None
+        with path.open("rb") as source:
+            data = source.read(MAX_BYTES + 1)
+        return (
+            data
+            if 0 < len(data) <= MAX_BYTES and data.startswith(b"\xff\xd8\xff")
+            else None
+        )
+    except OSError:
+        return None
+
+
+def save(directory: Path, channel: int, message: int, data: bytes) -> None:
+    if not 0 < len(data) <= MAX_BYTES or not data.startswith(b"\xff\xd8\xff"):
+        return
+    directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+    if shutil.disk_usage(directory).free < 64 * 1024**2:
+        return
+    descriptor, temporary = tempfile.mkstemp(dir=directory, prefix=".thumbnail-")
+    try:
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(data)
+        os.replace(temporary, location(directory, channel, message))
+    finally:
+        with suppress(FileNotFoundError):
+            os.unlink(temporary)
+    # Disposable cache: bounded independently of original media budgets.
+    entries = []
+    for path in directory.glob("*.jpg"):
+        try:
+            if len(path.stem) == 64 and not path.is_symlink():
+                entries.append((path.stat().st_mtime, path, path.stat().st_size))
+        except FileNotFoundError:
+            continue
+    total = sum(row[2] for row in entries)
+    for index, (_, path, size) in enumerate(sorted(entries)):
+        if total <= DISK_BYTES and len(entries) - index <= MAX_ENTRIES:
+            break
+        with suppress(FileNotFoundError):
+            path.unlink()
+        total -= size
diff --git a/tgdrive/media/logical_media.py b/tgdrive/media/logical_media.py
new file mode 100644
index 00000000..689d7712
--- /dev/null
+++ b/tgdrive/media/logical_media.py
@@ -0,0 +1,222 @@
+"""Bounded logical reads across immutable Telegram document parts."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+from telethon.errors import FloodWaitError, RPCError
+
+from tgdrive.media.media_metadata import get_message
+from tgdrive.media.ranges import ByteRange, plan_telegram_chunks
+from tgdrive.media.streaming import TelegramFileNotFound, _media_from_message
+
+
+def part_ranges(
+    parts: list[dict[str, Any]],
+    selected: ByteRange,
+) -> list[tuple[dict[str, Any], ByteRange]]:
+    spans = []
+    for part in parts:
+        start = max(selected.start, part["offset"])
+        end = min(selected.end, part["offset"] + part["size"] - 1)
+        if start <= end:
+            spans.append(
+                (
+                    part,
+                    ByteRange(
+                        start - part["offset"],
+                        end - part["offset"],
+                        part["size"],
+                        is_partial=True,
+                    ),
+                )
+            )
+    if sum(interval.length for _, interval in spans) != selected.length:
+        raise TelegramFileNotFound("Stored file parts do not cover this byte range")
+    return spans
+
+
+class PartLease:
+    """One selected part, with owned release even if HTTP cancellation repeats."""
+
+    def __init__(
+        self,
+        pool: Any,
+        channel: int,
+        part: dict[str, Any],
+        *,
+        authorize=None,
+        request_id=None,
+        background=False,
+    ):
+        self.pool, self.channel, self.part = pool, channel, part
+        self.authorize, self.request_id = authorize, request_id
+        self.background = background
+        self.lease: Any = None
+        self.client: Any = None
+        self.message: Any = None
+        self._release_task: asyncio.Task | None = None
+
+    async def _fetch(self) -> None:
+        if self.authorize is not None:
+            await self.authorize()
+        self.message = await get_message(
+            self.client, self.channel, self.part["message_id"]
+        )
+        media = _media_from_message(self.message)
+        if (
+            self.message is None
+            or getattr(self.message, "empty", False)
+            or media is None
+        ):
+            raise TelegramFileNotFound("A stored file part is missing from Telegram")
+        actual = getattr(media, "file_size", None)
+        if type(actual) is not int or actual != self.part["size"]:
+            raise TelegramFileNotFound("A stored file part has changed size")
+        if "document_id" in self.part:
+            native = getattr(self.message, "native", self.message)
+            document_id = getattr(getattr(native, "document", None), "id", None)
+            if document_id != self.part["document_id"]:
+                raise TelegramFileNotFound(
+                    "A stored file part was replaced in Telegram"
+                )
+
+    async def _acquire(self, *, prefer_premium: bool = False) -> None:
+        priority = {"priority": "preload", "download": True} if self.background else {}
+        lease = self.pool.lease(
+            prefer_premium=prefer_premium, respect_cooldown=True, **priority
+        )
+        client = await lease.__aenter__()
+        # A context that never yielded owns no client lease to release.
+        self.lease, self.client = lease, client
+        self._release_task = None
+
+    async def open(self) -> PartLease:
+        await self._acquire(prefer_premium=True)
+        try:
+            for attempt in range(3):
+                try:
+                    await self._fetch()
+                    break
+                except (OSError, RPCError, ValueError) as error:
+                    problem = await self.pool.report_failure(self.client, error)
+                    if isinstance(error, FloodWaitError):
+                        await self.pool.defer_client(
+                            self.client.name,
+                            time.time() + max(1, error.seconds),
+                        )
+                    elif problem is None and self.pool.kind_of(self.client) != "user":
+                        raise
+                    if attempt == 2:
+                        if problem is not None:
+                            raise problem from None
+                        raise
+                    await self.close()
+                    self.lease = None
+                    await self._acquire()
+            from tgdrive.telegram.clients import _block_identity
+
+            if _block_identity(self.message, 0) is not None:
+                await self.close()
+            return self
+        except BaseException:
+            await self.close()
+            raise
+
+    async def close(self) -> None:
+        if self.lease is None:
+            return
+        if self._release_task is None:
+            self._release_task = asyncio.create_task(
+                self.lease.__aexit__(None, None, None),
+            )
+        interrupted = False
+        while not self._release_task.done():
+            try:
+                await asyncio.shield(self._release_task)
+            except asyncio.CancelledError:
+                interrupted = True
+        self._release_task.result()
+        if interrupted:
+            raise asyncio.CancelledError
+
+    async def read(
+        self, selected: ByteRange, *, authorize=None, request_id=None
+    ) -> AsyncIterator[bytes]:
+        plan = plan_telegram_chunks(selected)
+        from tgdrive.media.media_reader import stream_pooled_media
+
+        iterator = stream_pooled_media(
+            self.pool,
+            self.client,
+            self.message,
+            channel=self.channel,
+            limit=plan.part_count,
+            offset=plan.offset // plan.chunk_size,
+            authorize=authorize or self.authorize,
+            request_id=request_id or self.request_id,
+            background=self.background,
+        )
+        emitted = 0
+        count = 0
+        whole_part = selected.start == 0 and selected.length == self.part["size"]
+        digest = hashlib.sha256() if whole_part else None
+        try:
+            async for chunk in iterator:
+                if count >= plan.part_count:
+                    break
+                cut_start = plan.first_part_cut if count == 0 else 0
+                cut_end = (
+                    plan.last_part_cut if count == plan.part_count - 1 else len(chunk)
+                )
+                selected_bytes = chunk[cut_start:cut_end]
+                count += 1
+                emitted += len(selected_bytes)
+                if digest is not None:
+                    digest.update(selected_bytes)
+                if count == plan.part_count:
+                    if emitted != selected.length:
+                        raise OSError(
+                            "Telegram file part ended before its declared length"
+                        )
+                    if digest is not None and digest.hexdigest() != self.part["sha256"]:
+                        # Withhold the last block so an incorrect full part can never
+                        # satisfy Content-Length and appear to download successfully.
+                        raise OSError("Telegram file part failed its checksum")
+                if selected_bytes:
+                    yield selected_bytes
+            if emitted != selected.length:
+                raise OSError("Telegram file part ended before its declared length")
+        finally:
+            await iterator.aclose()
+
+
+async def read_logical_prefix(
+    *,
+    pool: Any,
+    channel_id: int,
+    parts: list[dict[str, Any]],
+    size: int,
+    limit: int,
+) -> bytes:
+    """Fetch only a bounded prefix, including tiny parts crossing that prefix."""
+    if not 0 < limit <= 1024 * 1024:
+        raise ValueError("Logical prefix limit must be between 1 byte and 1 MiB")
+    selection = ByteRange(0, min(size, limit) - 1, size, is_partial=False)
+    output = bytearray()
+    for part, interval in part_ranges(parts, selection):
+        lease = await PartLease(pool, channel_id, part).open()
+        iterator = lease.read(interval)
+        try:
+            async for chunk in iterator:
+                output.extend(chunk)
+        finally:
+            try:
+                await iterator.aclose()
+            finally:
+                await lease.close()
+    return bytes(output)
diff --git a/tgdrive/media/media_cache.py b/tgdrive/media/media_cache.py
new file mode 100644
index 00000000..4d5ebcc4
--- /dev/null
+++ b/tgdrive/media/media_cache.py
@@ -0,0 +1,281 @@
+"""Private bounded disk cache for immutable, already-authorized media blocks."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import os
+import secrets
+import shutil
+import threading
+import time
+from collections import OrderedDict
+from contextlib import suppress
+from pathlib import Path
+
+
+class DiskMediaCache:
+    """Disposable bytes with scan-resistant probation/protected retention."""
+
+    def __init__(
+        self,
+        directory: Path,
+        *,
+        max_bytes=512 * 1024**2,
+        ttl=86400,
+        max_entries=None,
+        min_free_bytes=0,
+        protected_fraction=0.75,
+    ):
+        self.directory = Path(directory)
+        self.max_bytes, self.ttl = max_bytes, ttl
+        self.min_free_bytes = min_free_bytes
+        self.protected_fraction = protected_fraction
+        self._explicit_max_entries = max_entries
+        self.max_entries = max_entries or self._entry_limit(max_bytes)
+        self._lock = threading.Lock()
+        self._entries = None
+        self._protected = OrderedDict()
+        self._protected_bytes = 0
+        self._probation = OrderedDict()
+        self._size = 0
+        self._hits = self._misses = self._evictions = self._write_failures = 0
+
+    @staticmethod
+    def _entry_limit(budget):
+        return max(1024, math.ceil(budget / 1024**2) + 32)
+
+    @staticmethod
+    def _key(identity):
+        return hashlib.sha256(repr(identity).encode()).hexdigest()
+
+    def _remove(self, key):
+        if self._entries is not None:
+            item = self._entries.pop(key, None)
+            if item:
+                self._size -= item[0]
+        if key in self._protected:
+            self._protected.pop(key)
+            self._protected_bytes -= item[0] if item else 0
+        self._probation.pop(key, None)
+        (self.directory / (key + ".block")).unlink(missing_ok=True)
+
+    def _prepare(self):
+        if self._entries is not None:
+            return
+        if self.directory.is_symlink():
+            raise OSError("Media cache directory must not be a symbolic link")
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.directory.chmod(0o700)
+        rows = []
+        now = time.time()
+        for path in self.directory.iterdir():
+            if path.suffix == ".tmp":
+                path.unlink(missing_ok=True)
+            elif path.suffix == ".block":
+                stat = path.lstat()
+                if path.is_symlink() or stat.st_mtime + self.ttl <= now:
+                    path.unlink(missing_ok=True)
+                else:
+                    rows.append((path.stem, stat.st_size, stat.st_mtime))
+        self._entries = OrderedDict(
+            (key, (size, touched))
+            for key, size, touched in sorted(rows, key=lambda row: row[2])
+        )
+        self._probation = OrderedDict.fromkeys(self._entries)
+        self._size = sum(size for size, _ in self._entries.values())
+        self._trim()
+
+    def _demote(self):
+        ceiling = self.max_bytes * self.protected_fraction
+        while self._protected and self._protected_bytes > ceiling:
+            key, _ = self._protected.popitem(last=False)
+            self._protected_bytes -= self._entries[key][0]
+            self._probation[key] = None
+
+    def _victim(self):
+        return (
+            next(iter(self._probation))
+            if self._probation
+            else next(iter(self._protected))
+        )
+
+    def _trim(self, incoming=0, incoming_entries=0):
+        now = time.time()
+        while self._entries:
+            key = next(iter(self._entries))
+            _, touched = self._entries[key]
+            if touched + self.ttl <= now:
+                self._remove(key)
+            else:
+                break
+        self._demote()
+        while self._entries and (
+            self._size + incoming > self.max_bytes
+            or len(self._entries) + incoming_entries > self.max_entries
+        ):
+            self._remove(self._victim())
+            self._evictions += 1
+
+    def read(self, identity, expected):
+        try:
+            with self._lock:
+                self._prepare()
+                key = self._key(identity)
+                item = self._entries.get(key)
+                if item is None:
+                    self._misses += 1
+                    return None
+                path = self.directory / (key + ".block")
+                if (
+                    item[0] != expected + 32
+                    or item[1] + self.ttl <= time.time()
+                    or path.is_symlink()
+                ):
+                    self._remove(key)
+                    self._misses += 1
+                    return None
+                with path.open("rb") as handle:
+                    payload = handle.read(expected + 33)
+                digest, data = payload[:32], payload[32:]
+                if len(data) != expected or hashlib.sha256(data).digest() != digest:
+                    self._remove(key)
+                    self._misses += 1
+                    return None
+                now = time.time()
+                self._entries[key] = (item[0], now)
+                self._entries.move_to_end(key)
+                if key not in self._protected:
+                    self._protected_bytes += item[0]
+                self._protected[key] = None
+                self._probation.pop(key, None)
+                self._protected.move_to_end(key)
+                self._demote()
+                os.utime(path, (now, now), follow_symlinks=False)
+                self._hits += 1
+                return data
+        except OSError:
+            return None
+
+    def write(self, identity, data):
+        if not data or len(data) + 32 > self.max_bytes:
+            return False
+        temporary = None
+        try:
+            with self._lock:
+                self._prepare()
+                key = self._key(identity)
+                self._remove(key)
+                size = len(data) + 32
+                self._trim(size, 1)
+                while (
+                    self._entries
+                    and shutil.disk_usage(self.directory).free
+                    < self.min_free_bytes + size
+                ):
+                    self._remove(self._victim())
+                    self._evictions += 1
+                if shutil.disk_usage(self.directory).free < self.min_free_bytes + size:
+                    return False
+                temporary = self.directory / (secrets.token_hex(16) + ".tmp")
+                fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+                with os.fdopen(fd, "wb") as handle:
+                    handle.write(hashlib.sha256(data).digest() + data)
+                temporary.replace(self.directory / (key + ".block"))
+                self._entries[key] = (size, time.time())
+                self._probation[key] = None
+                self._size += size
+                return True
+        except OSError:
+            self._write_failures += 1
+            return False
+        finally:
+            if temporary is not None:
+                with suppress(OSError):
+                    temporary.unlink(missing_ok=True)
+
+    def reconfigure(self, *, max_bytes, ttl, min_free_bytes, protected_fraction):
+        with self._lock:
+            self.max_bytes, self.ttl = max_bytes, ttl
+            self.min_free_bytes, self.protected_fraction = (
+                min_free_bytes,
+                protected_fraction,
+            )
+            self.max_entries = self._explicit_max_entries or self._entry_limit(
+                max_bytes
+            )
+            try:
+                self._prepare()
+                self._trim()
+            except OSError:
+                pass
+
+    def promote(self, identity):
+        """Explicit owner preparation counts as reuse, after a verified fill."""
+        with self._lock:
+            try:
+                self._prepare()
+                key = self._key(identity)
+                item = self._entries.get(key)
+                if item is not None:
+                    if key not in self._protected:
+                        self._protected_bytes += item[0]
+                    self._protected[key] = None
+                    self._protected.move_to_end(key)
+                    self._probation.pop(key, None)
+                    self._demote()
+            except OSError:
+                pass
+
+    def clear(self, identities=None):
+        with self._lock:
+            try:
+                self._prepare()
+                keys = (
+                    list(self._entries)
+                    if identities is None
+                    else [self._key(identity) for identity in identities]
+                )
+                for key in keys:
+                    self._remove(key)
+            except OSError:
+                pass
+
+    def ready(self, identities):
+        """Inventory only; actual reads still verify length and checksum."""
+        with self._lock:
+            try:
+                self._prepare()
+                self._trim()
+                return [
+                    identity
+                    for identity in identities
+                    if self._key(identity) in self._entries
+                    and (self.directory / (self._key(identity) + ".block")).is_file()
+                ]
+            except OSError:
+                return []
+
+    def snapshot(self):
+        with self._lock:
+            available = True
+            try:
+                self._prepare()
+                self._trim()
+                free = shutil.disk_usage(self.directory).free
+            except OSError:
+                available, free = False, None
+            return {
+                "available": available,
+                "bytes": self._size,
+                "max_bytes": self.max_bytes,
+                "entries": len(self._entries or ()),
+                "max_entries": self.max_entries,
+                "protected_entries": len(self._protected),
+                "free_bytes": free,
+                "min_free_bytes": self.min_free_bytes,
+                "hits": self._hits,
+                "misses": self._misses,
+                "evictions": self._evictions,
+                "write_failures": self._write_failures,
+            }
diff --git a/tgdrive/media/media_metadata.py b/tgdrive/media/media_metadata.py
new file mode 100644
index 00000000..2b634f0c
--- /dev/null
+++ b/tgdrive/media/media_metadata.py
@@ -0,0 +1,82 @@
+"""Concurrent-only Telegram metadata coalescing, never an authorization cache."""
+
+from __future__ import annotations
+
+import asyncio
+import weakref
+from dataclasses import dataclass, field
+from typing import Any
+
+from tgdrive.media.media_scheduler import (
+    MediaPriorityScope,
+    effective_priority,
+    media_priority,
+)
+
+
+@dataclass
+class _Flight:
+    task: asyncio.Task[Any]
+    priority: MediaPriorityScope
+    waiters: int = 0
+    abandoned: bool = False
+    done: asyncio.Event = field(default_factory=asyncio.Event)
+
+
+_FLIGHTS: weakref.WeakKeyDictionary = weakref.WeakKeyDictionary()
+
+
+async def get_message(client: Any, channel: int, message_id: int) -> Any:
+    loop = asyncio.get_running_loop()
+    flights = _FLIGHTS.setdefault(loop, {})
+    key = (id(client), channel, message_id)
+    flight = flights.get(key)
+    while flight is not None and flight.abandoned:
+        await flight.done.wait()
+        flight = flights.get(key)
+    if flight is None:
+        from tgdrive.telegram.client_pool import MediaQueueFull
+
+        pool = getattr(client, "_identity_pool", None)
+        maximum = getattr(pool, "_max_media_queue", 256)
+        if len(flights) >= maximum:
+            raise MediaQueueFull(retry_after=1)
+        inherited = media_priority.get()
+        priority = (
+            inherited
+            if isinstance(inherited, MediaPriorityScope)
+            else MediaPriorityScope(inherited)
+        )
+        token = media_priority.set(priority)
+        try:
+            task = asyncio.create_task(
+                client.get_messages(channel, message_ids=message_id)
+            )
+        finally:
+            media_priority.reset(token)
+        flight = _Flight(task, priority)
+        flights[key] = flight
+
+        def completed(_task):
+            if flights.get(key) is flight:
+                flights.pop(key, None)
+            flight.done.set()
+
+        task.add_done_callback(completed)
+    flight.waiters += 1
+    try:
+        if effective_priority(media_priority.get()) == "demand":
+            await flight.priority.promote()
+        return await asyncio.shield(flight.task)
+    finally:
+        flight.waiters -= 1
+        if not flight.waiters and not flight.task.done():
+            flight.abandoned = True
+            flight.task.cancel()
+            while not flight.task.done():
+                try:
+                    await asyncio.shield(flight.task)
+                except asyncio.CancelledError:
+                    continue
+                except Exception:
+                    break
diff --git a/tgdrive/media/media_policy.py b/tgdrive/media/media_policy.py
new file mode 100644
index 00000000..03df5e80
--- /dev/null
+++ b/tgdrive/media/media_policy.py
@@ -0,0 +1,74 @@
+"""Instance-wide limits for disposable media bytes and speculative work."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Sequence
+from dataclasses import asdict, dataclass
+
+MIB = 1024**2
+
+
+@dataclass(frozen=True, slots=True)
+class MediaCachePolicy:
+    """Shared byte budgets and scheduling limits for reads and preparation."""
+
+    disk_max_bytes: int = 512 * MIB
+    memory_max_bytes: int = 64 * MIB
+    min_free_bytes: int = 1024 * MIB
+    ttl_seconds: float = 86400
+    memory_ttl_seconds: float = 600
+    protected_fraction: float = 0.75
+    max_background_jobs: int = 2
+    background_blocks: int = 2
+    max_file_fraction: float = 0.5
+    read_ahead_blocks: int = 32
+    scratch_max_bytes: int = 32 * MIB
+    auto_preload: bool = False
+
+    def __post_init__(self) -> None:
+        for name in (
+            "disk_max_bytes",
+            "memory_max_bytes",
+            "min_free_bytes",
+            "scratch_max_bytes",
+        ):
+            value = getattr(self, name)
+            if type(value) is not int or value < 0:
+                raise ValueError(f"{name} must be a nonnegative integer")
+        for name in ("ttl_seconds", "memory_ttl_seconds"):
+            if not math.isfinite(getattr(self, name)) or getattr(self, name) <= 0:
+                raise ValueError(f"{name} must be finite and positive")
+        if not 0 <= self.protected_fraction < 1:
+            raise ValueError("protected_fraction must be between zero and one")
+        if not 0 < self.max_file_fraction <= 1:
+            raise ValueError("max_file_fraction must be positive and at most one")
+        for name, ceiling in (
+            ("max_background_jobs", 8),
+            ("background_blocks", 8),
+            ("read_ahead_blocks", 64),
+        ):
+            value = getattr(self, name)
+            if type(value) is not int or not 1 <= value <= ceiling:
+                raise ValueError(f"{name} must be between 1 and {ceiling}")
+
+    def as_dict(self) -> dict[str, int | float | bool]:
+        """Return an independent snapshot for preferences and status responses."""
+        return asdict(self)
+
+
+def merge_ranges(ranges: Iterable[Sequence[int]]) -> list[list[int]]:
+    """Return sorted half-open intervals, joining overlaps and adjacent ranges.
+
+    Empty or reversed intervals are omitted. The returned lists do not alias the
+    input, allowing callers to update cache readiness without changing its source.
+    """
+    result: list[list[int]] = []
+    for start, end in sorted(ranges):
+        if end <= start:
+            continue
+        if result and start <= result[-1][1]:
+            result[-1][1] = max(result[-1][1], end)
+        else:
+            result.append([start, end])
+    return result
diff --git a/tgdrive/media/media_reader.py b/tgdrive/media/media_reader.py
new file mode 100644
index 00000000..094e61ff
--- /dev/null
+++ b/tgdrive/media/media_reader.py
@@ -0,0 +1,1209 @@
+"""Ordered, bounded read-ahead across healthy Telegram accounts."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import math
+import os
+import secrets
+import time
+from collections.abc import AsyncIterator
+from contextlib import suppress
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from telethon.errors import FloodPremiumWaitError, FloodWaitError, RPCError
+
+from tgdrive.media.media_cache import DiskMediaCache
+from tgdrive.media.media_policy import MediaCachePolicy, merge_ranges
+from tgdrive.media.media_scheduler import MediaPriorityScope
+from tgdrive.telegram.clients import _block_identity, _BlockCache
+
+BLOCK = 1024**2
+READ_AHEAD = 32  # MiB per response, including currently requested windows.
+
+
+class CachedSourceUnavailable(Exception):
+    """A cache-only derivative must stop rather than fetch missing payloads."""
+
+
+@dataclass(frozen=True)
+class CachedSourceVersion:
+    file_id: str
+    revision: int
+    generation: int
+
+    @property
+    def data_revision(self):
+        # Registering metadata/HEAD alone must not invalidate a cached miss.
+        return (self.file_id, self.revision) if self.revision else None
+
+
+class _AdaptiveReadAhead:
+    """Size a response pipeline from demonstrated delivery, not codec bitrate.
+
+    Consumer advancement includes HTTP backpressure and waits for the next
+    source block. Sampling over time avoids treating an immediate cache burst as
+    an unlimited consumer. Source latency supplies the horizon needed to overlap
+    Telegram reads; policy, account capacity and scratch remain separate caps.
+    """
+
+    def __init__(self, maximum, *, clock=None):
+        self.maximum = max(1, maximum)
+        self.window = min(2, self.maximum)
+        self.clock = clock or time.monotonic
+        self._sample_at = self.clock()
+        self._last_consumed_at = self._sample_at
+        self._sample_bytes = 0
+        self._rate = None
+        self._latency = None
+
+    def observe_fetch(self, elapsed):
+        elapsed = max(0.001, elapsed)
+        self._latency = (
+            elapsed if self._latency is None else self._latency * 0.75 + elapsed * 0.25
+        )
+
+    def consumed(self, size, *, consumer_seconds=None):
+        self._sample_bytes += size
+        now = self.clock()
+        if consumer_seconds is None:
+            consumer_seconds = now - self._last_consumed_at
+        self._last_consumed_at = now
+        elapsed = now - self._sample_at
+        if elapsed < 0.1:
+            return
+        rate = self._sample_bytes / elapsed
+        if consumer_seconds >= 0.1:
+            # A paused send must not inherit the fast bytes accumulated just
+            # before it. Source waits are measured separately by the caller.
+            rate = min(rate, size / consumer_seconds)
+        # Slow consumers reduce speculation promptly. Sustained faster delivery
+        # must demonstrate itself over successive samples before using more RAM.
+        self._rate = (
+            rate
+            if self._rate is None or rate < self._rate
+            else min(self._rate * 2, self._rate * 0.5 + rate * 0.5)
+        )
+        horizon = max(0.25, 2 * (self._latency or 0))
+        target = min(self.maximum, max(2, 1 + math.ceil(self._rate * horizon / BLOCK)))
+        self.window = min(target, max(2, self.window * 2))
+        self._sample_bytes = 0
+        self._sample_at = now
+
+    @property
+    def idle_seconds(self):
+        return max(1.0, 3 * (self._latency or 0))
+
+    def idle(self):
+        # No consumer progress: retain only the yielded head. Its speculative
+        # neighbours are disposable; a later advancement starts a fresh probe.
+        self.window = 1
+        self._rate = None
+        self._sample_at = self.clock()
+        self._last_consumed_at = self._sample_at
+        self._sample_bytes = 0
+
+
+class _ScratchBudget:
+    """Global MiB reservations with FIFO heads and reclaimable read-ahead.
+
+    An awaited or yielded head stays owned until its consumer advances or closes.
+    Speculative frames can be reclaimed from a suspended reader when a new head
+    needs space. In-flight frames release only after their cancellation cleanup.
+    """
+
+    def __init__(self, maximum):
+        self.limit = max(2, maximum // BLOCK)
+        self.used = self.peak = self.waiters = 0
+        self.changed = asyncio.Event()
+        self._heads = []
+        self._streams = set()
+
+    def try_acquire(self):
+        if self.waiters or self.used >= self.limit:
+            return False
+        self.used += 1
+        self.peak = max(self.peak, self.used)
+        return True
+
+    async def acquire(self):
+        ticket = object()
+        self._heads.append(ticket)
+        self.waiters += 1
+        try:
+            while True:
+                self.changed.clear()
+                if self._heads[0] is ticket:
+                    if self.used >= self.limit:
+                        # Prefer the largest speculative window and reclaim its
+                        # farthest block. Never revoke its awaited/yielded head.
+                        streams = sorted(
+                            self._streams,
+                            key=lambda stream: stream.speculative_count,
+                            reverse=True,
+                        )
+                        for stream in streams:
+                            if stream.reclaim_one():
+                                break
+                    if self.used < self.limit:
+                        self.used += 1
+                        self.peak = max(self.peak, self.used)
+                        return
+                await self.changed.wait()
+        finally:
+            self._heads.remove(ticket)
+            self.waiters -= 1
+            self.changed.set()
+
+    def release(self):
+        if self.used <= 0:
+            raise RuntimeError("Media scratch reservation underflow")
+        self.used -= 1
+        self.changed.set()
+
+    def resize(self, maximum):
+        self.limit = max(2, maximum // BLOCK)
+        self.changed.set()
+
+
+class _StreamFrames:
+    """Own stream tasks independently of a suspended generator's consumer."""
+
+    def __init__(self, scratch, read):
+        self.scratch, self.read = scratch, read
+        self.frames = {}
+        self.retiring = set()
+        scratch._streams.add(self)
+
+    @property
+    def speculative_count(self):
+        return sum(not frame.head for frame in self.frames.values())
+
+    def schedule(self, index, *, head=False):
+        try:
+            task = asyncio.create_task(self.read(index))
+        except BaseException:
+            self.scratch.release()
+            raise
+        frame = _StreamFrame(self, index, task, head)
+        self.frames[index] = frame
+        return frame
+
+    def reclaim_one(self):
+        for index in sorted(self.frames, reverse=True):
+            frame = self.frames[index]
+            if not frame.head:
+                self.retire(frame)
+                return True
+        return False
+
+    def trim(self, index, quota):
+        for following in sorted(self.frames, reverse=True):
+            frame = self.frames[following]
+            if not frame.head and (
+                following >= index + quota or len(self.frames) > quota
+            ):
+                self.retire(frame)
+
+    def release(self, frame):
+        if self.frames.get(frame.index) is frame:
+            del self.frames[frame.index]
+        frame.task = None
+        if not frame.released:
+            frame.released = True
+            self.scratch.release()
+
+    def retire(self, frame):
+        self.frames.pop(frame.index, None)
+        task = frame.task
+        if task.done():
+            frame.finish(task)
+        else:
+            self.retiring.add(frame)
+            task.add_done_callback(frame.finish)
+            task.cancel()
+
+    async def close(self):
+        self.scratch._streams.discard(self)
+        for frame in list(self.frames.values()):
+            self.retire(frame)
+        interrupted = False
+        if self.retiring:
+            cleanup = asyncio.gather(
+                *(frame.task for frame in self.retiring), return_exceptions=True
+            )
+            while not cleanup.done():
+                try:
+                    await asyncio.shield(cleanup)
+                except asyncio.CancelledError:
+                    interrupted = True
+            cleanup.result()
+        if interrupted:
+            raise asyncio.CancelledError
+
+
+class _StreamFrame:
+    def __init__(self, owner, index, task, head):
+        self.owner, self.index, self.task = owner, index, task
+        self.head, self.released = head, False
+
+    def finish(self, task):
+        # Consume speculative errors without making them escape a different
+        # request. The original reader retries that offset if it needs it later.
+        with suppress(BaseException):
+            task.result()
+        self.owner.retiring.discard(self)
+        self.owner.release(self)
+
+
+class _PayloadCache(_BlockCache):
+    """Shared-flight cache whose protected segment survives one-time scans."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.protected = {}
+        self.protected_fraction = 0.75
+
+    def _hit(self, key):
+        data = super()._hit(key)
+        self.protected = {k: None for k in self.protected if k in self.entries}
+        if data is not None:
+            self.entries[key] = (self.clock() + self.ttl, data)
+            self.protected.pop(key, None)
+            self.protected[key] = None
+            self._demote()
+        return data
+
+    def _demote(self):
+        size = sum(
+            len(self.entries[key][1]) for key in self.protected if key in self.entries
+        )
+        while self.protected and size > self.max_bytes * self.protected_fraction:
+            key = next(iter(self.protected))
+            self.protected.pop(key)
+            size -= len(self.entries[key][1])
+
+    def trim(self):
+        self._demote()
+        while self.entries and (
+            self.bytes_used > self.max_bytes or len(self.entries) > self.max_entries
+        ):
+            key = next(
+                (key for key in self.entries if key not in self.protected),
+                next(iter(self.entries)),
+            )
+            _, data = self.entries.pop(key)
+            self.bytes_used -= len(data)
+            self.protected.pop(key, None)
+
+    def _put(self, key, data):
+        if not data or len(data) > self.max_bytes:
+            return
+        old = self.entries.pop(key, None)
+        if old:
+            self.bytes_used -= len(old[1])
+        self.entries[key] = (self.clock() + self.ttl, data)
+        self.bytes_used += len(data)
+        # Evict old probation before the newly admitted payload, keeping hot bytes.
+        self.trim()
+
+
+def _effective_memory(configured):
+    """Clamp retained bytes to a quarter of available host/container memory."""
+    limits = [configured]
+    try:
+        fields = dict(
+            line.split(":", 1)
+            for line in Path("/proc/meminfo").read_text().splitlines()
+        )
+        limits.append(int(fields["MemAvailable"].split()[0]) * 1024 // 4)
+    except OSError, ValueError, KeyError:
+        pass
+    try:
+        maximum = Path("/sys/fs/cgroup/memory.max").read_text().strip()
+        if maximum != "max":
+            current = int(Path("/sys/fs/cgroup/memory.current").read_text())
+            limits.append(max(0, int(maximum) - current) // 4)
+    except OSError, ValueError:
+        pass
+    return max(0, min(limits))
+
+
+class MediaReadCache:
+    def __init__(self, directory=None, policy=None, *, clock=None):
+        self.policy = policy or MediaCachePolicy()
+        self._capacity_clock = clock or time.monotonic
+        self._last_capacity_check = self._capacity_clock()
+        self.deferred_writes = policy is not None
+        self.effective_memory_bytes = _effective_memory(self.policy.memory_max_bytes)
+        self.scratch = _ScratchBudget(_effective_memory(self.policy.scratch_max_bytes))
+        self._active_streams = 0
+        self.memory = _PayloadCache(
+            max_bytes=max(1, self.effective_memory_bytes),
+            max_entries=max(256, self.effective_memory_bytes // BLOCK + 32),
+            ttl=self.policy.memory_ttl_seconds,
+            read_slots=self.scratch.limit,
+        )
+        # This resizable gate is independent of retained payloads; every real
+        # pooled load also owns one global scratch frame. Reconfigure the same
+        # gate object so old waiters/releases cannot inflate a new semaphore.
+        self.memory._slots = _ScratchBudget(self.scratch.limit * BLOCK)
+        self.memory.max_bytes = self.effective_memory_bytes
+        self.memory.protected_fraction = self.policy.protected_fraction
+        self.directory = Path(directory) if directory is not None else None
+        self.disk = (
+            DiskMediaCache(
+                self.directory,
+                max_bytes=self.policy.disk_max_bytes,
+                ttl=self.policy.ttl_seconds,
+                min_free_bytes=self.policy.min_free_bytes,
+                protected_fraction=self.policy.protected_fraction,
+            )
+            if directory is not None
+            else None
+        )
+        self._demand_idle = asyncio.Event()
+        self._demand_idle.set()
+        self._background_slots = asyncio.Semaphore(2)
+        self._foreground = {}
+        self._fill_priorities = {}
+        self._active_keys = {}
+        self._pending = {}
+        self._hot_keys = set()
+        self._pending_bytes = 0
+        self._writer = None
+        self._flush_lock = asyncio.Lock()
+        self._index_lock = asyncio.Lock()
+        self._generation = 0
+        self._closed = False
+        self._files = {}
+        self._blocks = {}
+        self._file_lookup = {}
+        self._prune_lock = asyncio.Lock()
+        self._hits = self._misses = 0
+        self._index_dirty = False
+        self._load_index()
+        self._data_revision = max(
+            (row.get("_data_revision", 0) for row in self._files.values()), default=0
+        )
+
+    def _refresh_capacity(self, *, force=False):
+        now = self._capacity_clock()
+        if not force and now - self._last_capacity_check < 5:
+            return
+        self._last_capacity_check = now
+        self.effective_memory_bytes = _effective_memory(self.policy.memory_max_bytes)
+        maximum = _effective_memory(self.policy.scratch_max_bytes)
+        self.scratch.resize(maximum)
+        self.memory._slots.resize(maximum)
+        self.memory.max_entries = max(256, self.effective_memory_bytes // BLOCK + 32)
+        self._adjust_memory()
+
+    def _load_index(self):
+        if self.directory is None:
+            return
+        try:
+            path = self.directory / "inventory.json"
+            index_limit = max(16 * BLOCK, min(128 * BLOCK, self.disk.max_entries * 512))
+            if path.is_symlink() or path.stat().st_size > index_limit:
+                return
+            value = json.loads(path.read_text())
+            for row in value.get("files", []):
+                if not (
+                    isinstance(row, dict)
+                    and isinstance(row.get("id"), str)
+                    and isinstance(row.get("name"), str)
+                    and type(row.get("message_id")) is int
+                    and type(row.get("size")) is int
+                    and row["size"] >= 0
+                    and isinstance(row.get("channel_id"), (int, type(None)))
+                    and isinstance(row.get("parts"), list)
+                    and isinstance(row.get("_representations", {}), dict)
+                ):
+                    raise ValueError("Invalid disposable cache index")
+                if row["parts"]:
+                    from tgdrive.storage.file_parts import validate_parts
+
+                    row["parts"] = validate_parts(
+                        row["parts"], size=row["size"], message_id=row["message_id"]
+                    )
+                downloaded = row.get("last_download", 0)
+                row["last_download"] = (
+                    downloaded
+                    if type(downloaded) in (int, float)
+                    and math.isfinite(downloaded)
+                    and downloaded >= 0
+                    else 0
+                )
+                revision = row.get("_data_revision", 0)
+                row["_data_revision"] = (
+                    revision if type(revision) is int and revision >= 0 else 0
+                )
+                self._files[row["id"]] = row
+            for row in value.get("blocks", []):
+                key = tuple(row["key"])
+                if not (
+                    len(key) in (6, 7)
+                    and all(isinstance(v, (str, int, type(None))) for v in key)
+                    and row["file_id"] in self._files
+                    and type(row["start"]) is int
+                    and type(row["end"]) is int
+                    and 0
+                    <= row["start"]
+                    < row["end"]
+                    <= self._files[row["file_id"]]["size"]
+                ):
+                    raise ValueError("Invalid disposable cache block index")
+                self._blocks[key] = {
+                    "file_id": row["file_id"],
+                    "start": row["start"],
+                    "end": row["end"],
+                }
+            for row in self._files.values():
+                self._bind_file(row)
+        except (
+            OSError,
+            ValueError,
+            KeyError,
+            TypeError,
+            AttributeError,
+            RecursionError,
+        ):
+            self._files, self._blocks = {}, {}
+            self._file_lookup = {}
+
+    def _bind_file(self, row):
+        parts = row["parts"] or [
+            {"message_id": row["message_id"], "offset": 0, "size": row["size"]}
+        ]
+        for part in parts:
+            self._file_lookup[(row["channel_id"], part["message_id"], part["size"])] = (
+                row["id"],
+                part["offset"],
+            )
+
+    @staticmethod
+    def _file_identity(channel_id, message_id, size, parts, representation=None):
+        value = (
+            channel_id,
+            message_id,
+            size,
+            [(p["message_id"], p["offset"], p["size"]) for p in (parts or [])],
+        )
+        if representation is not None:
+            value += (representation,)
+        return hashlib.sha256(repr(value).encode()).hexdigest()[:24]
+
+    def register_file(
+        self, *, channel_id, message_id, size, name="", parts=None, representation=None
+    ):
+        identity = self._file_identity(
+            channel_id, message_id, size, parts, representation
+        )
+        row = self._files.get(identity, {})
+        self._files[identity] = {
+            "id": identity,
+            "name": name or row.get("name", ""),
+            "channel_id": channel_id,
+            "message_id": message_id,
+            "size": size,
+            "parts": parts or [],
+            "last_access": time.time(),
+            "last_download": row.get("last_download", 0),
+            "_data_revision": row.get("_data_revision", 0),
+            "_representations": row.get("_representations", {}),
+        }
+        self._bind_file(self._files[identity])
+        if len(self._files) > max(1024, len(self._blocks)) + 64:
+            owners = {block["file_id"] for block in self._blocks.values()}
+            keep = owners | set(list(self._files)[-1024:])
+            self._files = {key: row for key, row in self._files.items() if key in keep}
+            self._file_lookup = {
+                key: value
+                for key, value in self._file_lookup.items()
+                if value[0] in keep
+            }
+        self._index_dirty = True
+        return identity
+
+    def cached_source_version(self, *, channel_id, message_id, size, parts=None):
+        identity = self._file_identity(channel_id, message_id, size, parts)
+        row = self._files.get(identity)
+        if row is None:
+            return None
+        return CachedSourceVersion(
+            identity, row.get("_data_revision", 0), self._generation
+        )
+
+    async def cached_file_blocks(
+        self,
+        *,
+        channel_id,
+        message_id,
+        size,
+        parts=None,
+        version,
+        max_bytes,
+        authorize=None,
+    ):
+        """Yield a complete original from retained blocks; never start/join origin I/O.
+
+        Readiness is checked before the first yield, then actual disk reads verify
+        every digest. Eviction, clearing or source replacement aborts the copy.
+        """
+        from tgdrive.storage.file_parts import validate_parts
+
+        def current():
+            if authorize is not None:
+                authorize()
+            if (
+                self._closed
+                or version is None
+                or self.cached_source_version(
+                    channel_id=channel_id,
+                    message_id=message_id,
+                    size=size,
+                    parts=parts,
+                )
+                != version
+            ):
+                raise CachedSourceUnavailable
+
+        current()
+        if not 0 < size <= max_bytes:
+            raise CachedSourceUnavailable
+        documents = (
+            validate_parts(parts, size=size, message_id=message_id)
+            if parts
+            else [{"message_id": message_id, "offset": 0, "size": size}]
+        )
+        row = self._files[version.file_id]
+        plan = []
+        for part in documents:
+            representation = row.get("_representations", {}).get(
+                str(part["message_id"])
+            )
+            if (
+                not isinstance(representation, (list, tuple))
+                or len(representation) not in (3, 4)
+                or not all(
+                    isinstance(value, (str, int, type(None)))
+                    for value in representation
+                )
+                or representation[-1] != part["size"]
+            ):
+                raise CachedSourceUnavailable
+            blocks = []
+            for index in range(math.ceil(part["size"] / BLOCK)):
+                expected = min(BLOCK, part["size"] - index * BLOCK)
+                key = (channel_id, part["message_id"], *representation, index)
+                start = part["offset"] + index * BLOCK
+                if self._blocks.get(key) != {
+                    "file_id": version.file_id,
+                    "start": start,
+                    "end": start + expected,
+                }:
+                    raise CachedSourceUnavailable
+                blocks.append((key, expected))
+            plan.append((part, blocks))
+        keys = [key for _, blocks in plan for key, _ in blocks]
+        disk_keys = (
+            set(await asyncio.to_thread(self.disk.ready, keys))
+            if self.disk is not None
+            else set()
+        )
+        current()
+        # Expire RAM hits here as well; an old inventory entry is not proof that
+        # the complete original is still retained.
+        if any(
+            key not in self._pending
+            and self.memory._hit(key) is None
+            and key not in disk_keys
+            for key in keys
+        ):
+            raise CachedSourceUnavailable
+        for part, blocks in plan:
+            checksum = hashlib.sha256()
+            for key, expected in blocks:
+                current()
+                payload = self._pending.get(key)
+                if payload is None:
+                    payload = self.memory._hit(key)
+                if payload is None and self.disk is not None:
+                    payload = await asyncio.to_thread(self.disk.read, key, expected)
+                current()
+                if payload is None or len(payload) != expected:
+                    raise CachedSourceUnavailable
+                checksum.update(payload)
+                yield payload
+                current()
+            if part.get("sha256") and checksum.hexdigest() != part["sha256"]:
+                raise CachedSourceUnavailable
+
+    def register_block(self, key, expected):
+        channel, message_id = key[0], key[1]
+        owner = None
+        logical_offset = 0
+        binding = self._file_lookup.get((channel, message_id, key[-2]))
+        if binding is not None:
+            owner = self._files.get(binding[0])
+            logical_offset = binding[1]
+        representation = list(key[2:-1])
+        if owner is not None:
+            previous = owner.get("_representations", {}).get(str(message_id))
+            if previous is not None and previous != representation:
+                identity = self.register_file(
+                    channel_id=channel,
+                    message_id=message_id,
+                    size=key[-2],
+                    name=owner["name"],
+                    representation=representation,
+                )
+                owner, logical_offset = self._files[identity], 0
+        if owner is None:
+            identity = self.register_file(
+                channel_id=channel, message_id=message_id, size=key[-2]
+            )
+            owner = self._files[identity]
+        owner.setdefault("_representations", {})[str(message_id)] = representation
+        self._blocks[key] = {
+            "file_id": owner["id"],
+            "start": logical_offset + key[-1] * BLOCK,
+            "end": logical_offset + key[-1] * BLOCK + expected,
+        }
+        self._index_dirty = True
+
+    async def get(self, key, expected, remote, *, background=False, retain_hot=False):
+        self._refresh_capacity()
+        bound = (
+            self.memory.max_entries
+            + (self.disk.max_entries if self.disk is not None else 0)
+            + 128
+        )
+        if len(self._blocks) > bound:
+            async with self._prune_lock:
+                memory_keys = (
+                    set(self.memory.entries)
+                    | set(self._pending)
+                    | set(self.memory.flights)
+                    | set(self._active_keys)
+                )
+                disk_keys = (
+                    set(await asyncio.to_thread(self.disk.ready, list(self._blocks)))
+                    if self.disk is not None
+                    else set()
+                )
+                self._blocks = {
+                    key: value
+                    for key, value in self._blocks.items()
+                    if key in memory_keys or key in disk_keys
+                }
+        self.register_block(key, expected)
+        self._active_keys[key] = self._active_keys.get(key, 0) + 1
+        if retain_hot:
+            self._hot_keys.add(key)
+        priority_scope = self._fill_priorities.setdefault(
+            key, MediaPriorityScope("preload" if background else "demand")
+        )
+        if not background:
+            self._foreground[key] = self._foreground.get(key, 0) + 1
+            self._demand_idle.clear()
+
+        async def load():
+            if key in self._pending:
+                return self._pending[key]
+            if self.disk is not None:
+                payload = await asyncio.to_thread(self.disk.read, key, expected)
+                if payload is not None:
+                    return payload
+            generation = self._generation
+            payload = await remote()
+            if len(payload) != expected:
+                raise OSError("Telegram read ended before the declared block length")
+            if generation == self._generation:
+                block = self._blocks.get(key)
+                owner = self._files.get(block["file_id"]) if block else None
+                if owner is not None:
+                    owner["last_download"] = time.time()
+                    self._data_revision += 1
+                    owner["_data_revision"] = self._data_revision
+                    self._index_dirty = True
+            if (
+                generation == self._generation
+                and self.disk is not None
+                and self.policy.disk_max_bytes > 0
+                and not self._closed
+            ):
+                budget = min(16 * BLOCK, self.effective_memory_bytes // 4)
+                if (
+                    self.deferred_writes
+                    and self._pending_bytes + len(payload) <= budget
+                ):
+                    self._pending[key] = payload
+                    self._pending_bytes += len(payload)
+                    self._adjust_memory()
+                    if self._writer is None or self._writer.done():
+                        self._writer = asyncio.create_task(self._drain_writes())
+                else:
+                    await asyncio.to_thread(self.disk.write, key, payload)
+                    if key in self._hot_keys:
+                        await asyncio.to_thread(self.disk.promote, key)
+                        self._hot_keys.discard(key)
+                    self._index_dirty = True
+            return payload
+
+        generation = self._generation
+        try:
+            if not background:
+                await priority_scope.promote()
+            if self.memory._hit(key) is not None or key in self._pending:
+                self._hits += 1
+            else:
+                self._misses += 1
+            if background:
+                # Reserve most shared fill slots for demand. Waiting speculative
+                # work must never occupy all slots needed to unblock foreground.
+                async with self._background_slots:
+                    await self._demand_idle.wait()
+                    payload = await self.memory.get(key, expected, load)
+            else:
+                payload = await self.memory.get(key, expected, load)
+            if generation != self._generation:
+                old = self.memory.entries.pop(key, None)
+                if old:
+                    self.memory.bytes_used -= len(old[1])
+                self.memory.protected.pop(key, None)
+            elif retain_hot:
+                self.memory._hit(key)
+                if key not in self._pending:
+                    if self.disk is not None:
+                        await asyncio.to_thread(self.disk.promote, key)
+                    self._hot_keys.discard(key)
+            return payload
+        finally:
+            active = self._active_keys.get(key, 1) - 1
+            if active:
+                self._active_keys[key] = active
+            else:
+                self._active_keys.pop(key, None)
+                self._fill_priorities.pop(key, None)
+            if key not in self._pending:
+                self._hot_keys.discard(key)
+            if not background:
+                count = self._foreground.get(key, 1) - 1
+                if count:
+                    self._foreground[key] = count
+                else:
+                    self._foreground.pop(key, None)
+                if not self._foreground:
+                    self._demand_idle.set()
+
+    def _adjust_memory(self):
+        self.memory.max_bytes = max(
+            0, self.effective_memory_bytes - self._pending_bytes
+        )
+        self.memory.trim()
+
+    async def _drain_writes(self):
+        while True:
+            while self._pending:
+                key = next(iter(self._pending))
+                payload = self._pending[key]
+                await asyncio.to_thread(self.disk.write, key, payload)
+                if key in self._hot_keys:
+                    await asyncio.to_thread(self.disk.promote, key)
+                    self._hot_keys.discard(key)
+                self._pending.pop(key, None)
+                self._pending_bytes -= len(payload)
+                self._adjust_memory()
+            await self._persist_index()
+            if not self._pending:
+                return
+
+    async def flush(self):
+        async with self._flush_lock:
+            await self._flush()
+
+    async def _flush(self):
+        if self._writer is not None:
+            await asyncio.shield(self._writer)
+        await self._persist_index()
+
+    async def _persist_index(self):
+        async with self._index_lock:
+            await self._persist_index_locked()
+
+    async def _persist_index_locked(self):
+        if self.disk is not None and self._index_dirty:
+            # Clear before yielding so registrations/downloads arriving during
+            # the write keep their own dirty flag and get a subsequent snapshot.
+            self._index_dirty = False
+            written = False
+            try:
+                disk_keys = set(
+                    await asyncio.to_thread(self.disk.ready, list(self._blocks))
+                )
+                blocks = [
+                    {"key": key, **row}
+                    for key, row in self._blocks.items()
+                    if key in disk_keys
+                ]
+                owners = {row["file_id"] for row in blocks}
+                value = {
+                    "files": [row for key, row in self._files.items() if key in owners],
+                    "blocks": blocks,
+                }
+                await asyncio.to_thread(self._write_index, value)
+                written = True
+            except OSError:
+                pass
+            finally:
+                if not written:
+                    self._index_dirty = True
+
+    def _write_index(self, value):
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        path = self.directory / "inventory.json"
+        temporary = self.directory / (secrets.token_hex(16) + ".tmp")
+        try:
+            fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(fd, "w") as handle:
+                json.dump(value, handle, separators=(",", ":"))
+            temporary.replace(path)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    async def reconfigure(self, policy):
+        await self.flush()
+        self.policy = policy
+        self.memory.ttl = policy.memory_ttl_seconds
+        self.memory.protected_fraction = policy.protected_fraction
+        self._refresh_capacity(force=True)
+        if self.disk is not None:
+            await asyncio.to_thread(
+                self.disk.reconfigure,
+                max_bytes=policy.disk_max_bytes,
+                ttl=policy.ttl_seconds,
+                min_free_bytes=policy.min_free_bytes,
+                protected_fraction=policy.protected_fraction,
+            )
+
+    async def clear(self, file_id=None):
+        self._generation += 1
+        await self.flush()
+        keys = [
+            key
+            for key, row in self._blocks.items()
+            if file_id is None or row["file_id"] == file_id
+        ]
+        if self.disk is not None:
+            await asyncio.to_thread(self.disk.clear, None if file_id is None else keys)
+        for key in keys:
+            old = self.memory.entries.pop(key, None)
+            if old:
+                self.memory.bytes_used -= len(old[1])
+            self.memory.protected.pop(key, None)
+            self._hot_keys.discard(key)
+            self._blocks.pop(key, None)
+        if file_id is None:
+            self._files.clear()
+            self._file_lookup.clear()
+        else:
+            self._files.pop(file_id, None)
+            self._file_lookup = {
+                key: value
+                for key, value in self._file_lookup.items()
+                if value[0] != file_id
+            }
+        self._index_dirty = True
+        await self.flush()
+
+    async def snapshot(self):
+        self._refresh_capacity()
+        self.memory._hit(())  # Expire idle RAM entries before reporting readiness.
+        disk = (
+            await asyncio.to_thread(self.disk.snapshot)
+            if self.disk is not None
+            else {"available": False, "bytes": 0, "max_bytes": 0}
+        )
+        disk_keys = (
+            set(await asyncio.to_thread(self.disk.ready, list(self._blocks)))
+            if self.disk is not None
+            else set()
+        )
+        memory_keys = set(self.memory.entries) | set(self._pending)
+        grouped = {}
+        for key, block in self._blocks.items():
+            memory_ranges, disk_ranges = grouped.setdefault(block["file_id"], ([], []))
+            interval = (block["start"], block["end"])
+            if key in memory_keys:
+                memory_ranges.append(interval)
+            if key in disk_keys:
+                disk_ranges.append(interval)
+        files = []
+        for identity, row in self._files.items():
+            memory_ranges, disk_ranges = grouped.get(identity, ([], []))
+            ready = merge_ranges(memory_ranges + disk_ranges)
+            if ready:
+                files.append(
+                    {
+                        k: v
+                        for k, v in row.items()
+                        if k != "parts" and not k.startswith("_")
+                    }
+                    | {
+                        "ready_ranges": ready,
+                        "memory_ranges": merge_ranges(memory_ranges),
+                        "disk_ranges": merge_ranges(disk_ranges),
+                        "ready_bytes": sum(end - start for start, end in ready),
+                        "complete": ready == [[0, row["size"]]],
+                    }
+                )
+        files.sort(key=lambda row: (-row.get("last_download", 0), row["id"]))
+        # Missing/evicted blocks must not grow an unbounded metadata registry.
+        live = (
+            memory_keys | disk_keys | set(self.memory.flights) | set(self._active_keys)
+        )
+        self._blocks = {key: row for key, row in self._blocks.items() if key in live}
+        return {
+            "policy": self.policy.as_dict(),
+            "memory": {
+                "bytes": self.memory.bytes_used + self._pending_bytes,
+                "max_bytes": self.policy.memory_max_bytes,
+                "effective_max_bytes": self.effective_memory_bytes,
+                "entries": len(memory_keys),
+                "hits": self._hits,
+                "misses": self._misses,
+                "active_fills": self.memory._slots.used,
+                "max_fills": self.memory._slots.limit,
+            },
+            "disk": disk,
+            "files": files,
+            "pending_writes": len(self._pending),
+            "scratch": {
+                "bytes": self.scratch.used * BLOCK,
+                "max_bytes": self.scratch.limit * BLOCK,
+                "configured_max_bytes": self.policy.scratch_max_bytes,
+                "peak_bytes": self.scratch.peak * BLOCK,
+                "waiting_heads": self.scratch.waiters,
+                "active_streams": self._active_streams,
+            },
+        }
+
+    async def close(self):
+        self._closed = True
+        await self.flush()
+
+
+async def stream_pooled_media(
+    pool: Any,
+    client: Any,
+    message: Any,
+    *,
+    channel: int,
+    limit: int,
+    offset: int,
+    background: bool = False,
+    authorize=None,
+    request_id: str | None = None,
+    retain_hot: bool = False,
+) -> AsyncIterator[bytes]:
+    """Authorization and initial message validation precede every cache read.
+
+    Each worker binds the same document through its own account. Content keys
+    include channel, message, immutable document/rendition, size and block index.
+    Cached payloads are shared across clients; Telegram access hashes are not.
+    """
+    if limit <= 0:
+        return
+    if authorize is not None:
+        await authorize()
+    identity = _block_identity(message, offset)
+    if identity is None or not callable(getattr(pool, "download_capacity", None)):
+        iterator = client.stream_media(message, limit=limit, offset=offset)
+        try:
+            async for data in iterator:
+                if authorize is not None:
+                    await authorize()
+                yield data
+        finally:
+            await iterator.aclose()
+        return
+
+    request_id = request_id or f"read-{secrets.token_urlsafe(12)}"
+    if pool._media_read_cache is None:
+        pool._media_read_cache = MediaReadCache(pool.media_cache_dir)
+    cache = pool._media_read_cache
+    cache._refresh_capacity()
+    source = getattr(message, "native", message)
+    message_id = source.id
+    quality = getattr(message, "variant_id", None)
+    bindings = {id(client): message}
+    locks: dict[int, asyncio.Lock] = {}
+
+    async def bind(account):
+        key = id(account)
+        async with locks.setdefault(key, asyncio.Lock()):
+            if key not in bindings:
+                from tgdrive.media.media_metadata import get_message
+
+                fresh = await get_message(account, channel, message_id)
+                if fresh is None:
+                    raise FileNotFoundError("Stored Telegram message was removed")
+                if quality is not None:
+                    fresh = account.select_media_variant(fresh, quality)
+                if _block_identity(fresh, offset) != identity:
+                    raise FileNotFoundError("Stored Telegram media changed")
+                bindings[key] = fresh
+            return bindings[key]
+
+    async def fetch_remote(index):
+        from tgdrive.media.media_scheduler import media_priority
+
+        for attempt in range(3):
+            kwargs = {
+                "download": True,
+                "allow_users": True,
+                "prefer_premium": True,
+                "priority": media_priority.get(),
+            }
+            if request_id is not None:
+                kwargs["request_id"] = request_id
+            async with pool.lease(**kwargs) as account:
+                try:
+                    bound = await bind(account)
+                    options = {"limit": 1, "offset": index}
+                    if getattr(account, "supports_uncached_media", False):
+                        options["use_cache"] = False
+                    iterator = account.stream_media(bound, **options)
+                    started = controller.clock()
+                    try:
+                        data = await anext(iterator, b"")
+                        block = _block_identity(bound, index)
+                        if block is None or len(data) != block[1]:
+                            # Validate inside account failover, before the cache
+                            # sees any bytes. Empty EOF is a failed read too.
+                            raise OSError(
+                                "Telegram read ended before the declared block length"
+                            )
+                        controller.observe_fetch(controller.clock() - started)
+                        return data
+                    finally:
+                        await iterator.aclose()
+                except (FloodWaitError, FloodPremiumWaitError) as error:
+                    await pool.defer_client(
+                        account.name, time.time() + max(1, error.seconds)
+                    )
+                    if attempt == 2:
+                        raise
+                except (OSError, RPCError) as error:
+                    problem = await pool.report_failure(account, error)
+                    if attempt == 2:
+                        if problem is not None:
+                            raise problem from None
+                        raise
+                    # A temporary failure should not monopolize the next window.
+                    bindings.pop(id(account), None)
+                    await pool.defer_client(account.name, time.time() + 2)
+        raise OSError("No Telegram account could read this block")
+
+    async def remote(index):
+        from tgdrive.media.media_scheduler import media_priority
+
+        block = _block_identity(message, index)
+        scope = cache._fill_priorities.get(block[0]) if block is not None else None
+        token = media_priority.set(scope or ("preload" if background else "demand"))
+        try:
+            return await fetch_remote(index)
+        finally:
+            media_priority.reset(token)
+
+    async def read(index):
+        block = _block_identity(message, index)
+        if block is None:
+            raise OSError("Telegram block lies outside the validated media")
+        key, expected = block
+        return await cache.get(
+            key,
+            expected,
+            lambda: remote(index),
+            background=background,
+            retain_hot=retain_hot,
+        )
+
+    end = offset + limit
+    scratch = cache.scratch
+    maximum = (
+        cache.policy.background_blocks if background else cache.policy.read_ahead_blocks
+    )
+    controller = _AdaptiveReadAhead(
+        min(
+            maximum,
+            max(4, await pool.download_capacity() * 4),
+            limit,
+        )
+    )
+    frames = _StreamFrames(scratch, read)
+
+    def refill(index):
+        quota = min(
+            controller.window, max(1, scratch.limit // max(1, cache._active_streams))
+        )
+        frames.trim(index, quota)
+        for following in range(index + 1, min(end, index + quota)):
+            if len(frames.frames) >= quota:
+                break
+            if following in frames.frames:
+                continue
+            if not scratch.try_acquire():
+                break
+            frames.schedule(following)
+
+    cache._active_streams += 1
+    data = frame = None
+    idle_timer = None
+
+    def idle(index):
+        controller.idle()
+        frames.trim(index, 1)
+
+    try:
+        for index in range(offset, end):
+            frame = frames.frames.get(index)
+            if frame is None:
+                await scratch.acquire()
+                frame = frames.schedule(index, head=True)
+            else:
+                frame.head = True
+            refill(index)
+            data = await frame.task
+            if authorize is not None:
+                await authorize()
+            idle_timer = asyncio.get_running_loop().call_later(
+                controller.idle_seconds, idle, index
+            )
+            yielded_at = controller.clock()
+            yield data
+            idle_timer.cancel()
+            idle_timer = None
+            controller.consumed(
+                len(data), consumer_seconds=controller.clock() - yielded_at
+            )
+            # A suspended consumer owns exactly its yielded head, plus only
+            # reclaimable read-ahead. Drop our payload references before freeing
+            # the reservation so a new head cannot exceed the aggregate bound.
+            data = None
+            frames.release(frame)
+            frame = None
+    finally:
+        if idle_timer is not None:
+            idle_timer.cancel()
+        del data, frame
+        try:
+            await frames.close()
+        finally:
+            cache._active_streams -= 1
diff --git a/tgdrive/media/media_scheduler.py b/tgdrive/media/media_scheduler.py
new file mode 100644
index 00000000..43414212
--- /dev/null
+++ b/tgdrive/media/media_scheduler.py
@@ -0,0 +1,240 @@
+"""Bounded account-wide admission for Telegram media RPCs.
+
+Priority applies to work which has not started. Running requests are never
+cancelled to admit newer work. Estimates describe recent observations only.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections import deque
+from collections.abc import Callable
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Literal
+
+MediaPriority = Literal["demand", "preload"]
+
+
+class MediaPriorityScope:
+    """Let foreground subscribers promote one shared fill without restarting it."""
+
+    def __init__(self, priority: MediaPriority):
+        self.priority = priority
+        self._conditions: list[asyncio.Condition] = []
+        self._updates: list[Callable[[], None]] = []
+
+    def subscribe(self, condition: asyncio.Condition, on_promote=None):
+        self._conditions.append(condition)
+        if on_promote is not None:
+            self._updates.append(on_promote)
+
+        def unsubscribe():
+            self._conditions.remove(condition)
+            if on_promote is not None:
+                self._updates.remove(on_promote)
+
+        return unsubscribe
+
+    async def promote(self):
+        if self.priority == "demand":
+            return
+        self.priority = "demand"
+        for update in self._updates:
+            update()
+        for condition in set(self._conditions):
+            async with condition:
+                condition.notify_all()
+
+
+def effective_priority(value: MediaPriority | MediaPriorityScope) -> MediaPriority:
+    return value.priority if isinstance(value, MediaPriorityScope) else value
+
+
+media_priority: ContextVar[MediaPriority | MediaPriorityScope] = ContextVar(
+    "media_priority", default="demand"
+)
+
+
+@dataclass(slots=True)
+class _Request:
+    number: int
+    priority: MediaPriority | MediaPriorityScope
+    queued_at: float
+
+
+class MediaScheduler:
+    """Share concurrency, rate and flood feedback across one account's transfers."""
+
+    def __init__(self, *, limit: int = 8, rate: float = 48) -> None:
+        self.configure(limit=limit, rate=rate)
+        self.active = 0
+        self.completed = 0
+        self.failed = 0
+        self.floods = 0
+        self.bytes = 0
+        self.upload_bytes = 0
+        self.download_bytes = 0
+        self._sequence = 0
+        self._condition = asyncio.Condition()
+        self._waiting: list[_Request] = []
+        self._next_request = 0.0
+        self._cooldown = 0.0
+        self._durations: deque[float] = deque(maxlen=128)
+        self._history: deque[dict] = deque(maxlen=120)
+        self._last_sample = 0.0
+        self._successes = 0
+
+    def configure(self, *, limit: int, rate: float) -> None:
+        if type(limit) is not int or not 1 <= limit <= 32:
+            raise ValueError("Telegram request limit must be between 1 and 32")
+        if not 1 <= rate <= 512:
+            raise ValueError("Telegram request rate must be between 1 and 512")
+        self.limit = limit
+        self.rate = float(rate)
+        self.effective_limit = limit
+        self.effective_rate = float(rate)
+
+    async def flood(self, seconds: float) -> None:
+        async with self._condition:
+            self.floods += 1
+            self._successes = 0
+            self.effective_limit = max(1, self.effective_limit // 2)
+            self.effective_rate = max(1.0, self.effective_rate / 2)
+            self._cooldown = max(self._cooldown, time.monotonic() + seconds)
+            self._condition.notify_all()
+
+    def record_bytes(self, amount: int, *, upload: bool = False) -> None:
+        self.bytes += amount
+        if upload:
+            self.upload_bytes += amount
+        else:
+            self.download_bytes += amount
+
+    @asynccontextmanager
+    async def request(self):
+        queued_at = time.monotonic()
+        async with self._condition:
+            self._sequence += 1
+            ticket = _Request(self._sequence, media_priority.get(), queued_at)
+            self._waiting.append(ticket)
+
+            def promote_waiter():
+                self._sequence += 1
+                ticket.number = self._sequence
+
+            unsubscribe = (
+                ticket.priority.subscribe(self._condition, promote_waiter)
+                if isinstance(ticket.priority, MediaPriorityScope)
+                else None
+            )
+            try:
+                while True:
+                    now = time.monotonic()
+                    first = min(
+                        self._waiting,
+                        key=lambda item: (
+                            effective_priority(item.priority) == "preload",
+                            item.number,
+                        ),
+                    )
+                    deadline = max(self._cooldown, self._next_request)
+                    if (
+                        first is ticket
+                        and self.active < self.effective_limit
+                        and deadline <= now
+                    ):
+                        self._waiting.remove(ticket)
+                        self.active += 1
+                        self._next_request = now + 1 / self.effective_rate
+                        self._condition.notify_all()
+                        break
+                    delay = max(0.001, deadline - now) if deadline > now else None
+                    try:
+                        if delay is None:
+                            await self._condition.wait()
+                        else:
+                            await asyncio.wait_for(self._condition.wait(), delay)
+                    except TimeoutError:
+                        pass
+            except BaseException:
+                self._waiting.remove(ticket)
+                self._condition.notify_all()
+                raise
+            finally:
+                if unsubscribe is not None:
+                    unsubscribe()
+        started = time.monotonic()
+        succeeded = False
+        try:
+            yield
+            succeeded = True
+        finally:
+            async with self._condition:
+                self.active -= 1
+                if succeeded:
+                    self.completed += 1
+                    self._successes += 1
+                    self._durations.append(time.monotonic() - started)
+                    if self._successes >= 32:
+                        self._successes = 0
+                        self.effective_limit = min(self.limit, self.effective_limit + 1)
+                        self.effective_rate = min(self.rate, self.effective_rate + 1)
+                else:
+                    self.failed += 1
+                self._condition.notify_all()
+
+    def snapshot(self) -> dict:
+        now = time.monotonic()
+        mean = sum(self._durations) / len(self._durations) if self._durations else None
+        waiting = sorted(
+            self._waiting,
+            key=lambda item: (
+                effective_priority(item.priority) == "preload",
+                item.number,
+            ),
+        )
+        queue = []
+        for position, ticket in enumerate(waiting, 1):
+            estimated = None
+            if mean is not None:
+                estimated = max(0.0, self._cooldown - now) + max(
+                    (position - 1) / self.effective_rate,
+                    ((self.active + position - 1) // self.effective_limit) * mean,
+                )
+            queue.append(
+                dict(
+                    position=position,
+                    priority=effective_priority(ticket.priority),
+                    waiting_seconds=round(now - ticket.queued_at, 3),
+                    estimated_wait_seconds=estimated,
+                )
+            )
+        sample = dict(
+            at=time.time(),
+            active=self.active,
+            queued=len(queue),
+            completed=self.completed,
+            failed=self.failed,
+            floods=self.floods,
+            bytes=self.bytes,
+            upload_bytes=self.upload_bytes,
+            download_bytes=self.download_bytes,
+        )
+        if now - self._last_sample >= 1:
+            self._history.append(sample)
+            self._last_sample = now
+        return dict(
+            **sample,
+            configured_limit=self.limit,
+            effective_limit=self.effective_limit,
+            configured_parts_per_second=self.rate,
+            effective_parts_per_second=self.effective_rate,
+            cooldown_seconds=max(0.0, self._cooldown - now),
+            mean_request_seconds=mean,
+            estimates=True,
+            queue=queue[:128],
+            history=list(self._history),
+        )
diff --git a/tgdrive/media/multipart_streaming.py b/tgdrive/media/multipart_streaming.py
new file mode 100644
index 00000000..ee2729ed
--- /dev/null
+++ b/tgdrive/media/multipart_streaming.py
@@ -0,0 +1,191 @@
+"""HTTP ranges over one logical file backed by multiple Telegram messages."""
+
+from __future__ import annotations
+
+import mimetypes
+from collections.abc import AsyncIterator
+from typing import Any
+
+from fastapi import Request
+from fastapi.responses import Response
+
+from tgdrive.media.logical_media import PartLease, part_ranges
+from tgdrive.media.ranges import MalformedRange, RangeNotSatisfiable, parse_byte_range
+from tgdrive.media.streaming import (
+    PDF_PREVIEW_BYTES,
+    TelegramVariantNotFound,
+    _ActivityBody,
+    _content_disposition,
+    _is_playback_request,
+    _not_modified,
+    _observe_media_request,
+    _prime_response,
+    _request_range,
+    media_etag,
+)
+from tgdrive.storage.file_parts import validate_parts
+
+
+async def stream_multipart_file(
+    *,
+    pool: Any,
+    channel_id: int,
+    message_id: int,
+    file_name: str,
+    expected_size: int,
+    parts: list[dict[str, Any]],
+    request: Request,
+    download: bool = False,
+    preview: bool = False,
+    quality: str | None = None,
+    authorize=None,
+    request_id: str | None = None,
+    request_status=None,
+) -> Response:
+    if authorize is not None:
+        await authorize()
+    manifest = validate_parts(parts, size=expected_size, message_id=message_id)
+    if quality not in (None, "", "original") and not download:
+        raise TelegramVariantNotFound("Separate file parts have no alternate rendition")
+    etag = media_etag(channel_id, message_id, expected_size, parts=manifest)
+    try:
+        selected = parse_byte_range(_request_range(request, etag), expected_size)
+    except MalformedRange as error:
+        return Response(
+            status_code=400, content=str(error), headers={"Accept-Ranges": "bytes"}
+        )
+    except RangeNotSatisfiable as error:
+        return Response(
+            status_code=416,
+            headers={
+                "Accept-Ranges": "bytes",
+                "Content-Range": error.content_range,
+            },
+        )
+    mime_type = mimetypes.guess_type(file_name)[0] or "application/octet-stream"
+    if (
+        preview
+        and not download
+        and mime_type == "application/pdf"
+        and expected_size > PDF_PREVIEW_BYTES
+    ):
+        return Response(status_code=413, content="PDF preview limit is 256 MiB")
+    spans = part_ranges(manifest, selected)
+    first = await PartLease(
+        pool, channel_id, spans[0][0], authorize=authorize, request_id=request_id
+    ).open()
+    if _not_modified(request, etag):
+        try:
+            if authorize is not None:
+                await authorize()
+        finally:
+            await first.close()
+        return Response(
+            status_code=304,
+            headers={"ETag": etag, "Cache-Control": "private, no-store, no-transform"},
+        )
+    activity = _observe_media_request(
+        pool,
+        channel_id=channel_id,
+        message_id=message_id,
+        size=expected_size,
+        name=file_name,
+        parts=manifest,
+        request=request,
+        start=selected.start,
+        end=selected.end + 1,
+        allow_preload=_is_playback_request(
+            request, mime_type, download=download, preview=preview
+        ),
+        authorize=authorize,
+        request_id=request_id,
+    )
+    headers = {
+        "Accept-Ranges": "bytes",
+        "Content-Length": str(selected.length),
+        "Content-Encoding": "identity",
+        "Content-Disposition": _content_disposition(
+            file_name, mime_type, download=download, preview=preview
+        ),
+        "X-Content-Type-Options": "nosniff",
+        "Referrer-Policy": "no-referrer",
+        "Content-Security-Policy": "sandbox; default-src 'none'",
+        "Cache-Control": "private, no-store, no-transform",
+        "ETag": etag,
+    }
+    # Retain the original streamer's safe document policy for passive media.
+    from tgdrive.media.streaming import _SAFE_INLINE_IMAGE_TYPES
+
+    if (
+        mime_type.startswith(("audio/", "video/"))
+        or mime_type in _SAFE_INLINE_IMAGE_TYPES
+    ) and not download:
+        headers["Content-Security-Policy"] = (
+            "default-src 'none'; media-src 'self' blob:; img-src 'self' data:; "
+            "style-src 'unsafe-inline'; frame-ancestors 'self'"
+        )
+    elif preview and mime_type == "application/pdf" and not download:
+        headers["X-Frame-Options"] = "SAMEORIGIN"
+        headers["Content-Security-Policy"] = (
+            "sandbox; default-src 'none'; frame-ancestors 'self'"
+        )
+    if selected.content_range is not None:
+        headers["Content-Range"] = selected.content_range
+    status = 206 if selected.is_partial else 200
+    if request.method == "HEAD":
+        try:
+            if authorize is not None:
+                await authorize()
+        finally:
+            await first.close()
+        return Response(status_code=status, media_type=mime_type, headers=headers)
+
+    async def body() -> AsyncIterator[bytes]:
+        emitted = 0
+        try:
+            for index, (part, interval) in enumerate(spans):
+                lease = (
+                    first
+                    if index == 0
+                    else await PartLease(
+                        pool,
+                        channel_id,
+                        part,
+                        authorize=authorize,
+                        request_id=request_id,
+                    ).open()
+                )
+                iterator = lease.read(interval)
+                try:
+                    async for chunk in iterator:
+                        emitted += len(chunk)
+                        yield chunk
+                        if activity is not None:
+                            tracked_body.delivered(
+                                channel_id=channel_id,
+                                message_id=message_id,
+                                offset=selected.start + emitted - len(chunk),
+                                length=len(chunk),
+                            )
+                finally:
+                    try:
+                        await iterator.aclose()
+                    finally:
+                        await lease.close()
+            if emitted != selected.length:
+                raise OSError(
+                    "Logical Telegram stream ended before its declared length"
+                )
+        finally:
+            await first.close()
+
+    tracked_body = _ActivityBody(body(), activity)
+    return await _prime_response(
+        tracked_body,
+        release=first.close,
+        status=status,
+        mime_type=mime_type,
+        headers=headers,
+        authorize=authorize,
+        request_status=request_status,
+    )
diff --git a/tgdrive/media/preloading.py b/tgdrive/media/preloading.py
new file mode 100644
index 00000000..4b8a4438
--- /dev/null
+++ b/tgdrive/media/preloading.py
@@ -0,0 +1,809 @@
+"""Bounded, cancellable preparation sharing the ordinary media block cache.
+
+Authorization remains the caller's responsibility. A caller may supply a fresh
+authorization callback, which is checked before work and before every block.
+No HEAD request or metadata-only observation starts a bulk download.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import math
+import secrets
+import time
+from collections import OrderedDict
+
+from tgdrive.media.media_policy import MediaCachePolicy
+from tgdrive.media.media_reader import BLOCK, MediaReadCache, stream_pooled_media
+from tgdrive.storage.file_parts import validate_parts
+from tgdrive.telegram.clients import _block_identity
+
+PLAYBACK_RANGE_GRACE_SECONDS = 5.0
+
+
+class PreloadCapacityError(ValueError):
+    pass
+
+
+def _cache_footprint(size, parts, start, end):
+    """Count retained Telegram blocks, including partial boundary blocks."""
+    payload_bytes = block_count = 0
+    for part in parts or [{"offset": 0, "size": size}]:
+        lo = max(0, start - part["offset"])
+        hi = min(part["size"], end - part["offset"])
+        if hi <= lo:
+            continue
+        first = lo // BLOCK
+        final = (hi + BLOCK - 1) // BLOCK
+        payload_bytes += min(part["size"], final * BLOCK) - first * BLOCK
+        block_count += final - first
+    return payload_bytes, block_count
+
+
+class PreloadManager:
+    def __init__(self, pool, *, policy=None, clock=None):
+        self.pool = pool
+        self.policy = policy or MediaCachePolicy()
+        if pool._media_read_cache is None:
+            pool._media_read_cache = MediaReadCache(pool.media_cache_dir, self.policy)
+        self.cache = pool._media_read_cache
+        self._jobs = OrderedDict()
+        self._tasks = {}
+        self._observed = OrderedDict()
+        self._auto_tasks = {}
+        self._viewer_timers = {}
+        self._closed = False
+        self._condition = asyncio.Condition()
+        self._admission_lock = asyncio.Lock()
+        self._active = 0
+        self._clock = clock or time.monotonic
+        pool._preload_manager = self
+
+    def register_file(self, **kwargs):
+        return self.cache.register_file(**kwargs)
+
+    def observe(
+        self,
+        *,
+        channel_id,
+        message_id,
+        size,
+        name="",
+        parts=None,
+        start=0,
+        end=None,
+        method="GET",
+        authorize=None,
+        request_id=None,
+        media_rate=None,
+        allow_full=True,
+    ):
+        """Record a request; only delivered sequential bytes can trigger warming."""
+        identity = self.register_file(
+            channel_id=channel_id,
+            message_id=message_id,
+            size=size,
+            name=name,
+            parts=parts,
+        )
+        if method != "GET" or self._closed or not self.policy.auto_preload:
+            return identity
+        row = self._observed.get(identity)
+        if row is None:
+            row = {
+                "channel_id": channel_id,
+                "message_id": message_id,
+                "size": size,
+                "name": name,
+                "parts": parts,
+                "last_auto": float("-inf"),
+                "last_auto_mode": None,
+                "last_auto_range": None,
+                "authorize": authorize,
+                "requests": 0,
+                "viewers": {},
+                "runs": [],
+                "hot_until": 0,
+                "fill_rate": 0.0,
+            }
+            self._observed[identity] = row
+        row["authorize"] = authorize
+        row["requests"] += 1
+        viewer = self._get_viewer(row, request_id)
+        viewer["authorize"] = authorize
+        viewer["allow_full"] = allow_full
+        if (
+            type(media_rate) in (int, float)
+            and math.isfinite(media_rate)
+            and media_rate > 0
+        ):
+            viewer["media_rate"] = media_rate
+        self._observed.move_to_end(identity)
+        # Observations do not retain payloads; bound idle request metadata too.
+        while len(self._observed) > 1024:
+            self._observed.popitem(last=False)
+        return identity
+
+    @staticmethod
+    def _viewer():
+        return {
+            "last_end": None,
+            "sequential": 0,
+            "run_start": 0,
+            "run": None,
+            "at": None,
+            "sample_at": None,
+            "sample_bytes": 0,
+            "rate": 0.0,
+            "media_rate": None,
+            "authorize": None,
+            "allow_full": True,
+            "active": 0,
+            "warm_until": 0.0,
+        }
+
+    def _get_viewer(self, row, request_id):
+        viewers = row["viewers"]
+        key = request_id or "default"
+        viewer = viewers.pop(key, None)
+        if viewer is None:
+            viewer = self._viewer()
+        viewer["last_seen"] = self._clock()
+        viewers[key] = viewer
+        self._prune_viewers(row, keep=key)
+        return viewer
+
+    def _prune_viewers(self, row, *, keep=None):
+        # Viewer IDs are request observations, not permanent analytics. Keep
+        # recent range/replay continuity without retaining every past visitor.
+        # Active HTTP consumers stay tracked even beyond the idle-history cap.
+        viewers = row["viewers"]
+        cutoff = self._clock() - 600
+        for key, viewer in list(viewers.items()):
+            if (
+                key != keep
+                and not self._viewer_active(viewer)
+                and (viewer.get("last_seen", 0) < cutoff or len(viewers) > 128)
+            ):
+                viewers.pop(key)
+
+    def _viewer_active(self, viewer):
+        return bool(viewer["active"] or viewer["warm_until"] > self._clock())
+
+    def _cancel_viewer_timer(self, file_id, request_id):
+        timer = self._viewer_timers.pop((file_id, request_id), None)
+        if timer is not None:
+            timer.cancel()
+
+    def _expire_viewer(self, file_id, request_id):
+        self._viewer_timers.pop((file_id, request_id), None)
+        row = self._observed.get(file_id)
+        viewer = row["viewers"].get(request_id) if row is not None else None
+        if viewer is not None and not viewer["active"]:
+            viewer["warm_until"] = 0.0
+            self.finished(file_id, request_id)
+
+    def begin(self, file_id, request_id):
+        row = self._observed.get(file_id)
+        if row is not None:
+            viewer = self._get_viewer(row, request_id)
+            self._cancel_viewer_timer(file_id, request_id or "default")
+            viewer["warm_until"] = 0.0
+            viewer["active"] += 1
+            return row
+        return None
+
+    def finished(self, file_id, request_id, *, completed=False, observation=None):
+        row = self._observed.get(file_id)
+        if row is None or (observation is not None and row is not observation):
+            return
+        viewer = row["viewers"].get(request_id or "default")
+        if viewer is not None:
+            viewer["active"] = max(0, viewer["active"] - 1)
+            viewer["last_seen"] = self._clock()
+            if not viewer["active"]:
+                self._cancel_viewer_timer(file_id, request_id or "default")
+                viewer["warm_until"] = (
+                    self._clock() + PLAYBACK_RANGE_GRACE_SECONDS if completed else 0.0
+                )
+                if completed:
+                    # A completed finite HTTP range is not a closed player.
+                    # Retain only a short, bounded bridge to its next range.
+                    key = (file_id, request_id or "default")
+                    self._viewer_timers[key] = asyncio.get_running_loop().call_later(
+                        PLAYBACK_RANGE_GRACE_SECONDS, self._expire_viewer, *key
+                    )
+        self._prune_viewers(row)
+        any_active = any(self._viewer_active(item) for item in row["viewers"].values())
+        existing = self._existing(file_id)
+        if (
+            existing is not None
+            and existing["mode"] == "auto"
+            and existing["target_bytes"] < existing["size"]
+            and (
+                not any_active
+                or (
+                    existing.get("viewer_id") == (request_id or "default")
+                    and (viewer is None or not self._viewer_active(viewer))
+                )
+            )
+        ):
+            task = self._tasks.get(existing["id"])
+            if task is not None:
+                task.cancel()
+        if not any_active and row["hot_until"] <= self._clock():
+            task = self._auto_tasks.get(file_id)
+            if task is not None:
+                task.cancel()
+
+    def delivered(
+        self,
+        *,
+        channel_id,
+        message_id,
+        offset,
+        length,
+        request_id=None,
+        observation=None,
+    ):
+        if not self.policy.auto_preload or self._closed:
+            return
+        for identity, row in list(self._observed.items()):
+            if row["channel_id"] != channel_id or (
+                observation is not None and row is not observation
+            ):
+                continue
+            logical_offset = offset
+            if row["parts"]:
+                part = next(
+                    (p for p in row["parts"] if p["message_id"] == message_id), None
+                )
+                if part is None:
+                    continue
+                logical_offset += part["offset"]
+            elif row["message_id"] != message_id:
+                continue
+            viewer_id = request_id or "default"
+            viewer = self._get_viewer(row, viewer_id)
+            now = self._clock()
+            if viewer["last_end"] == logical_offset:
+                viewer["sequential"] += length
+                if viewer["at"] is not None and now - viewer["at"] > 30:
+                    viewer["rate"] = 0.0
+                    viewer["sample_at"] = now
+                    viewer["sample_bytes"] = 0
+                else:
+                    viewer["sample_bytes"] += length
+                    elapsed = now - viewer["sample_at"]
+                    # Aggregate short bursts over a real sample interval instead
+                    # of mistaking each cached yield for the media's bitrate.
+                    if elapsed >= 0.05:
+                        rate = viewer["sample_bytes"] / elapsed
+                        viewer["rate"] = (
+                            rate
+                            if not viewer["rate"]
+                            else 0.75 * viewer["rate"] + 0.25 * rate
+                        )
+                        viewer["sample_at"] = now
+                        viewer["sample_bytes"] = 0
+            else:
+                viewer["rate"] = 0.0
+                viewer["sample_at"] = now
+                viewer["sample_bytes"] = 0
+                viewer["sequential"] = length
+                viewer["run_start"] = logical_offset
+                viewer["run"] = None
+                # A distant seek abandons only speculative ahead work; shared
+                # fill subscribers belonging to other viewers remain alive.
+                existing = self._existing(identity)
+                if (
+                    existing is not None
+                    and existing["mode"] == "auto"
+                    and existing["target_bytes"] < existing["size"]
+                    and existing.get("viewer_id") == viewer_id
+                    and not existing["start"] <= logical_offset < existing["end"]
+                ):
+                    task = self._tasks.get(existing["id"])
+                    if task is not None:
+                        task.cancel()
+            viewer["at"] = now
+            viewer["last_end"] = logical_offset + length
+            rate = viewer["media_rate"] or viewer["rate"]
+            qualification = (
+                max(BLOCK, int(min(BLOCK, viewer["media_rate"]) * 4))
+                if viewer["media_rate"]
+                else 4 * BLOCK
+            )
+            if viewer["sequential"] < qualification:
+                continue
+            row["runs"] = [run for run in row["runs"] if now - run["at"] <= 600]
+            run = viewer["run"]
+            if run is None:
+                run = {
+                    "viewer": viewer_id,
+                    "start": viewer["run_start"],
+                    "end": viewer["last_end"],
+                    "at": now,
+                    "allow_full": viewer["allow_full"],
+                }
+                row["runs"].append(run)
+                row["runs"] = row["runs"][-32:]
+                viewer["run"] = run
+            else:
+                run.update(end=viewer["last_end"], at=now)
+            if viewer["allow_full"] and any(
+                previous["allow_full"]
+                and previous["viewer"] != viewer_id
+                and min(previous["end"], run["end"])
+                - max(previous["start"], run["start"])
+                >= qualification
+                for previous in row["runs"]
+            ):
+                row["hot_until"] = now + 600
+            hot = row["hot_until"] > now
+            promote = hot and row["last_auto_mode"] != "full"
+            previous_range = row["last_auto_range"]
+            renew = (
+                row["last_auto_mode"] == "ahead"
+                and previous_range is not None
+                and (
+                    viewer["last_end"] < previous_range[0]
+                    or (
+                        previous_range[1] < row["size"]
+                        and viewer["last_end"]
+                        >= previous_range[1]
+                        - (previous_range[1] - previous_range[0]) // 2
+                    )
+                )
+            )
+            # Renew as playback consumes the warmed window. A fixed cooldown
+            # alone leaves fast readers without ahead bytes for up to 30s.
+            if now - row["last_auto"] < 30 and not (promote or renew):
+                continue
+            existing = self._existing(identity)
+            if existing is not None:
+                if (
+                    not promote
+                    or existing["mode"] != "auto"
+                    or existing["target_bytes"] == existing["size"]
+                ):
+                    continue
+                task = self._tasks.get(existing["id"])
+                if task is not None:
+                    existing["state"] = "cancelled"
+                    task.cancel()
+            if identity in self._auto_tasks:
+                if not promote:
+                    continue
+                self._auto_tasks[identity].cancel()
+            if len(self._auto_tasks) >= self.policy.max_background_jobs:
+                continue
+            row["last_auto"] = now
+            row["last_auto_range"] = None
+            context = dict(row) | {
+                "last_end": viewer["last_end"],
+                "rate": rate,
+                "viewer_id": viewer_id,
+                "authorize": viewer["authorize"],
+                "hot": hot,
+            }
+            task = asyncio.create_task(self._auto(identity, context))
+            self._auto_tasks[identity] = task
+
+            def completed(done, key=identity):
+                if self._auto_tasks.get(key) is done:
+                    self._auto_tasks.pop(key, None)
+
+            task.add_done_callback(completed)
+
+    def _ahead_window(self, capacity, consumption_rate, fill_rate=0):
+        seconds = 16 if fill_rate and fill_rate < consumption_rate else 8
+        bounded_rate = min(consumption_rate, 128 * BLOCK / seconds)
+        desired = max(BLOCK, math.ceil(bounded_rate * seconds / BLOCK) * BLOCK)
+        return min(128 * BLOCK, int(capacity * 0.25), desired)
+
+    async def _auto(self, identity, row):
+        try:
+            capacity = await self._capacity()
+            current = self._observed.get(identity)
+            viewer = (
+                current["viewers"].get(row["viewer_id"])
+                if current is not None
+                else None
+            )
+            if viewer is not None:
+                # Capacity inspection yields; playback may have advanced since
+                # the delivery that scheduled this work.
+                row = row | {
+                    "last_end": viewer["last_end"],
+                    "rate": viewer["media_rate"] or viewer["rate"],
+                    "authorize": viewer["authorize"],
+                }
+            full_bytes, full_blocks = _cache_footprint(
+                row["size"], row["parts"], 0, row["size"]
+            )
+            full = (
+                row["hot"]
+                and full_bytes + full_blocks * 32
+                <= capacity * self.policy.max_file_fraction
+            )
+            start = 0 if full else row["last_end"]
+            ahead = self._ahead_window(
+                capacity, row["rate"], current["fill_rate"] if current else 0
+            )
+            if not full and (
+                ahead < BLOCK
+                or current is None
+                or viewer is None
+                or not self._viewer_active(viewer)
+            ):
+                return
+            end = row["size"] if full else min(row["size"], start + ahead)
+            if end > start:
+                job = await self.prepare(
+                    channel_id=row["channel_id"],
+                    message_id=row["message_id"],
+                    size=row["size"],
+                    name=row["name"],
+                    parts=row["parts"],
+                    authorize=row["authorize"],
+                    mode="auto",
+                    start=start,
+                    end=end,
+                    viewer_id=row["viewer_id"],
+                )
+                if current is not None:
+                    current["last_auto_mode"] = "full" if full else "ahead"
+                    current["last_auto_range"] = (job["start"], job["end"])
+        except Exception:
+            # Speculation is best effort and cannot fail an active response.
+            return
+
+    def _existing(self, identity):
+        return next(
+            (
+                row
+                for row in self._jobs.values()
+                if row["file_id"] == identity
+                and row["state"] in {"queued", "preparing"}
+            ),
+            None,
+        )
+
+    async def _capacity(self):
+        snapshot = await self.cache.snapshot()
+        disk = snapshot["disk"]
+        disk_capacity = 0
+        if disk["available"] and disk.get("free_bytes") is not None:
+            disk_capacity = min(
+                self.policy.disk_max_bytes,
+                max(0, disk["free_bytes"] + disk["bytes"] - self.policy.min_free_bytes),
+            )
+        # The layers duplicate hot bytes, so adding their limits would overpromise
+        # whole-file retention when the object fits neither individual tier.
+        return max(disk_capacity, self.cache.effective_memory_bytes)
+
+    async def prepare(
+        self,
+        *,
+        channel_id,
+        message_id,
+        size,
+        name="",
+        parts=None,
+        authorize=None,
+        mode="manual",
+        start=0,
+        end=None,
+        viewer_id=None,
+    ):
+        if self._closed:
+            raise ValueError("Media preparation is stopped")
+        if type(size) is not int or size <= 0:
+            raise ValueError("A nonempty file is required")
+        if parts is not None:
+            parts = validate_parts(parts, size=size, message_id=message_id)
+        end = size if end is None else end
+        if not 0 <= start < end <= size:
+            raise ValueError("Preparation range is outside the file")
+        if authorize is not None:
+            await authorize()
+        # Capacity checks yield to disk I/O. Serialize job admission so two
+        # simultaneous preparations cannot create duplicate jobs/reservations.
+        async with self._admission_lock:
+            identity = self.register_file(
+                channel_id=channel_id,
+                message_id=message_id,
+                size=size,
+                name=name,
+                parts=parts,
+            )
+            existing = self._existing(identity)
+            if existing is not None:
+                if mode == "manual" and existing["mode"] == "auto":
+                    await self.cancel(existing["id"])
+                else:
+                    return dict(existing)
+            capacity = await self._capacity()
+            if self._closed:
+                raise ValueError("Media preparation is stopped")
+            if mode == "auto" and end - start < size:
+                observation = self._observed.get(identity)
+                viewer = (
+                    observation["viewers"].get(viewer_id or "default")
+                    if observation is not None
+                    else None
+                )
+                if viewer is None or not self._viewer_active(viewer):
+                    # Its viewer can leave while admission waits for the lock,
+                    # authorization or disk capacity. Hot whole-file work may
+                    # outlive a viewer; speculative ahead work may not.
+                    raise ValueError("Automatic read-ahead has no active viewer")
+                if not start <= viewer["last_end"] < end:
+                    raise ValueError("Playback moved beyond this read-ahead range")
+            # RAM stores payloads directly; only disk entries need digest prefixes.
+            retained_bytes, blocks = _cache_footprint(size, parts, start, end)
+            overhead = (
+                blocks * 32 if capacity > self.cache.effective_memory_bytes else 0
+            )
+            if retained_bytes + overhead > capacity:
+                raise PreloadCapacityError(
+                    "This preparation exceeds the available cache budget; "
+                    "increase the budget or free space"
+                )
+            reserved = sum(
+                job["reservation_bytes"] + job.get("reservation_overhead", 0)
+                for job in self._jobs.values()
+                if job["state"] in {"queued", "preparing"}
+            )
+            if reserved + retained_bytes + overhead > capacity:
+                raise PreloadCapacityError(
+                    "Active preparations have reserved the available cache budget; "
+                    "try again later"
+                )
+            pending = sum(
+                row["state"] in {"queued", "preparing"} for row in self._jobs.values()
+            )
+            if pending >= self.policy.max_background_jobs * 4:
+                raise PreloadCapacityError(
+                    "The preparation queue is full; try again later"
+                )
+            job_id = secrets.token_urlsafe(12)
+            row = {
+                "id": job_id,
+                "file_id": identity,
+                "name": name,
+                "state": "queued",
+                "mode": mode,
+                "viewer_id": viewer_id,
+                "bytes_done": 0,
+                "size": size,
+                "target_bytes": end - start,
+                "reservation_bytes": retained_bytes,
+                "reservation_overhead": overhead,
+                "start": start,
+                "end": end,
+                "created_at": time.time(),
+                "error": None,
+            }
+            self._jobs[job_id] = row
+            # Keep bounded completed history without forgetting active work.
+            for old in list(self._jobs):
+                if len(self._jobs) <= 128:
+                    break
+                if self._jobs[old]["state"] not in {"queued", "preparing"}:
+                    self._jobs.pop(old)
+            task = asyncio.create_task(
+                self._run(row, channel_id, message_id, size, parts, authorize)
+            )
+            self._tasks[job_id] = task
+
+            def completed(done, key=job_id):
+                if done.cancelled() and row["state"] in {"queued", "preparing"}:
+                    row["state"] = "cancelled"
+                    row["finished_at"] = time.time()
+                self._tasks.pop(key, None)
+
+            task.add_done_callback(completed)
+            return dict(row)
+
+    async def _run(self, row, channel_id, message_id, size, parts, authorize):
+        acquired = False
+        try:
+            async with self._condition:
+                await self._condition.wait_for(
+                    lambda: (
+                        self._active < self.policy.max_background_jobs or self._closed
+                    )
+                )
+                if self._closed:
+                    raise asyncio.CancelledError
+                self._active += 1
+                acquired = True
+            row["state"] = "preparing"
+            previous_fill = self._clock()
+            fill_bytes = 0
+            manifest = parts or [{"message_id": message_id, "offset": 0, "size": size}]
+            for part in manifest:
+                lo, hi = (
+                    max(row["start"], part["offset"]),
+                    min(row["end"], part["offset"] + part["size"]),
+                )
+                if hi <= lo:
+                    continue
+                if authorize is not None:
+                    await authorize()
+                async with self.pool.lease(
+                    priority="preload", respect_cooldown=True
+                ) as client:
+                    from tgdrive.media.media_metadata import get_message
+                    from tgdrive.media.media_scheduler import media_priority
+
+                    token = media_priority.set("preload")
+                    try:
+                        message = await get_message(
+                            client, channel_id, part["message_id"]
+                        )
+                    finally:
+                        media_priority.reset(token)
+                identity = _block_identity(message, 0) if message is not None else None
+                if identity is None or identity[0][-2] != part["size"]:
+                    raise OSError("Stored Telegram media is missing or changed")
+                if "document_id" in part and identity[0][-3] != part["document_id"]:
+                    raise OSError("Stored Telegram media was replaced")
+                offset = (lo - part["offset"]) // BLOCK
+                final = (hi - part["offset"] + BLOCK - 1) // BLOCK
+                stream = stream_pooled_media(
+                    self.pool,
+                    client,
+                    message,
+                    channel=channel_id,
+                    offset=offset,
+                    limit=final - offset,
+                    background=True,
+                    authorize=authorize,
+                    retain_hot=row["mode"] == "manual" or row["target_bytes"] == size,
+                )
+                digest = (
+                    hashlib.sha256()
+                    if lo == part["offset"]
+                    and hi == part["offset"] + part["size"]
+                    and "sha256" in part
+                    else None
+                )
+                try:
+                    async for data in stream:
+                        now = self._clock()
+                        fill_bytes += len(data)
+                        if now - previous_fill >= 0.05:
+                            rate = fill_bytes / (now - previous_fill)
+                            observation = self._observed.get(row["file_id"])
+                            if observation is not None:
+                                previous_rate = observation["fill_rate"]
+                                observation["fill_rate"] = (
+                                    rate
+                                    if not previous_rate
+                                    else 0.75 * previous_rate + 0.25 * rate
+                                )
+                            previous_fill = now
+                            fill_bytes = 0
+                        if digest is not None:
+                            digest.update(data)
+                        row["bytes_done"] = min(
+                            row["target_bytes"], row["bytes_done"] + len(data)
+                        )
+                finally:
+                    await stream.aclose()
+                if digest is not None and digest.hexdigest() != part["sha256"]:
+                    await self.cache.clear(row["file_id"])
+                    raise OSError("Prepared Telegram part failed its checksum")
+            await self.cache.flush()
+            files = {
+                entry["id"]: entry for entry in (await self.cache.snapshot())["files"]
+            }
+            cached = files.get(row["file_id"], {})
+            if not any(
+                start <= row["start"] and end >= row["end"]
+                for start, end in cached.get("ready_ranges", [])
+            ):
+                raise PreloadCapacityError(
+                    "Cache capacity changed or blocks were evicted during preparation; "
+                    "free space or increase the budget"
+                )
+            row["state"] = "ready"
+        except asyncio.CancelledError:
+            row["state"] = "cancelled"
+            raise
+        except Exception as error:
+            row["state"] = "failed"
+            row["error"] = (
+                str(error)
+                if isinstance(error, (ValueError, OSError, PermissionError))
+                else "Telegram preparation failed; retry later"
+            )
+        finally:
+            row["finished_at"] = time.time()
+            if acquired:
+                async with self._condition:
+                    self._active -= 1
+                    self._condition.notify_all()
+
+    async def cancel(self, job_id):
+        row = self._jobs.get(job_id)
+        if row is None:
+            raise KeyError("Preparation job not found")
+        task = self._tasks.get(job_id)
+        if task is not None:
+            task.cancel()
+            await asyncio.gather(task, return_exceptions=True)
+            row["state"] = "cancelled"
+            row.setdefault("finished_at", time.time())
+        return dict(row)
+
+    async def clear(self, file_id=None):
+        for identity, viewer in list(self._viewer_timers):
+            if file_id is None or identity == file_id:
+                self._cancel_viewer_timer(identity, viewer)
+        if file_id is None:
+            self._observed.clear()
+        else:
+            self._observed.pop(file_id, None)
+        for identity, task in list(self._auto_tasks.items()):
+            if file_id is None or identity == file_id:
+                task.cancel()
+                await asyncio.gather(task, return_exceptions=True)
+        for row in list(self._jobs.values()):
+            if (file_id is None or row["file_id"] == file_id) and row[
+                "id"
+            ] in self._tasks:
+                await self.cancel(row["id"])
+        await self.cache.clear(file_id)
+
+    async def reconfigure(self, policy):
+        self.policy = policy
+        if not policy.auto_preload:
+            for identity, viewer in list(self._viewer_timers):
+                self._cancel_viewer_timer(identity, viewer)
+            self._observed.clear()
+            for task in list(self._auto_tasks.values()):
+                task.cancel()
+            await asyncio.gather(
+                *list(self._auto_tasks.values()), return_exceptions=True
+            )
+            for row in list(self._jobs.values()):
+                if row["mode"] == "auto" and row["id"] in self._tasks:
+                    await self.cancel(row["id"])
+        await self.cache.reconfigure(policy)
+        async with self._condition:
+            self._condition.notify_all()
+
+    async def snapshot(self):
+        cache = await self.cache.snapshot()
+        files = {row["id"]: row for row in cache["files"]}
+        jobs = []
+        for row in reversed(self._jobs.values()):
+            cached = files.get(row["file_id"], {})
+            jobs.append(
+                dict(row)
+                | {
+                    "ready_bytes": cached.get("ready_bytes", 0),
+                    "complete": cached.get("complete", False),
+                }
+            )
+        return {
+            "jobs": jobs,
+            "active_jobs": self._active,
+            "max_background_jobs": self.policy.max_background_jobs,
+            "cache": cache,
+        }
+
+    async def close(self):
+        self._closed = True
+        for identity, viewer in list(self._viewer_timers):
+            self._cancel_viewer_timer(identity, viewer)
+        tasks = list(self._auto_tasks.values()) + list(self._tasks.values())
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await self.cache.close()
diff --git a/tgdrive/media/previews.py b/tgdrive/media/previews.py
new file mode 100644
index 00000000..c1c1ebf0
--- /dev/null
+++ b/tgdrive/media/previews.py
@@ -0,0 +1,345 @@
+"""Bounded, owner/share-authorized preview helpers; never execute file content."""
+
+from __future__ import annotations
+
+import codecs
+import mimetypes
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import PurePath
+from typing import Any
+from urllib.parse import urlencode
+
+from telethon.errors import RPCError
+
+from tgdrive.media.logical_media import read_logical_prefix
+from tgdrive.media.media_metadata import get_message
+from tgdrive.media.media_reader import MediaReadCache, stream_pooled_media
+from tgdrive.media.media_scheduler import media_priority
+from tgdrive.media.streaming import (
+    PDF_PREVIEW_BYTES,
+    TelegramFileNotFound,
+    _media_from_message,
+)
+from tgdrive.storage.file_parts import validate_parts
+
+TEXT_PREVIEW_BYTES = 256 * 1024
+_TEXT_LANGUAGES = {
+    "txt": "text",
+    "md": "markdown",
+    "markdown": "markdown",
+    "rst": "text",
+    "log": "text",
+    "csv": "csv",
+    "tsv": "tsv",
+    "json": "json",
+    "jsonl": "json",
+    "ipynb": "json",
+    "yaml": "yaml",
+    "yml": "yaml",
+    "toml": "toml",
+    "ini": "ini",
+    "cfg": "ini",
+    "conf": "text",
+    "xml": "xml",
+    "svg": "xml",
+    "html": "html",
+    "htm": "html",
+    "css": "css",
+    "scss": "css",
+    "less": "css",
+    "js": "javascript",
+    "jsx": "javascript",
+    "mjs": "javascript",
+    "cjs": "javascript",
+    "ts": "typescript",
+    "mts": "typescript",
+    "cts": "typescript",
+    "tsx": "typescript",
+    "py": "python",
+    "pyi": "python",
+    "sh": "shell",
+    "bash": "shell",
+    "zsh": "shell",
+    "ps1": "powershell",
+    "bat": "text",
+    "sql": "sql",
+    "c": "c",
+    "h": "c",
+    "cpp": "cpp",
+    "hpp": "cpp",
+    "cc": "cpp",
+    "cs": "csharp",
+    "java": "java",
+    "kt": "kotlin",
+    "kts": "kotlin",
+    "rs": "rust",
+    "go": "go",
+    "rb": "ruby",
+    "php": "php",
+    "swift": "swift",
+    "dart": "dart",
+    "lua": "lua",
+    "r": "r",
+    "srt": "text",
+    "vtt": "text",
+    "tex": "latex",
+    "bib": "text",
+    "env": "text",
+    "gitignore": "text",
+    "dockerfile": "text",
+    "makefile": "text",
+    "license": "text",
+    "readme": "text",
+}
+
+
+_TS_PROBE_BYTES = 8192
+_TS_MIME_TYPES = {
+    "video/mp2t",
+    "video/mpegts",
+    "video/x-mpegts",
+    "application/mp2t",
+}
+
+
+def _decode_preview_text(data: bytes, *, truncated: bool) -> str | None:
+    """Do not turn binary/invalid encodings into plausible-looking source text."""
+    encoding = "utf-16" if data.startswith((b"\xff\xfe", b"\xfe\xff")) else "utf-8-sig"
+    try:
+        text = codecs.getincrementaldecoder(encoding)().decode(
+            data, final=not truncated
+        )
+    except UnicodeError:
+        return None
+    # Logs can contain backspace/ANSI escape; both stay inert in the text viewer.
+    if any(ord(char) < 32 and char not in "\t\n\r\f\b\x1b" for char in text):
+        return None
+    return text
+
+
+def _is_mpeg_transport_stream(data: bytes, mime_type: str | None) -> bool:
+    """Require repeated packet structure; neither a .ts suffix nor MIME is proof."""
+    sample = data[:_TS_PROBE_BYTES]
+    if _decode_preview_text(sample, truncated=True) is not None:
+        return False
+    normalized_mime = (
+        mime_type.partition(";")[0].strip().lower()
+        if isinstance(mime_type, str)
+        else ""
+    )
+    required = 3 if normalized_mime in _TS_MIME_TYPES else 5
+    # Account for ordinary TS, timestamp-prefixed M2TS, and FEC-appended packets.
+    for stride in (188, 192, 204):
+        last_start = min(1024, len(sample) - (required - 1) * stride - 188)
+        for start in range(last_start + 1):
+            for packet in range(required):
+                offset = start + packet * stride
+                if sample[offset] != 0x47:
+                    break
+                flags = sample[offset + 3]
+                adaptation = (flags >> 4) & 3
+                if not adaptation or (flags >> 6) == 1:
+                    break
+                if adaptation & 2 and sample[offset + 4] > (
+                    182 if adaptation == 3 else 183
+                ):
+                    break
+            else:
+                return True
+    return False
+
+
+@asynccontextmanager
+async def lease_media(
+    pool: Any, channel_id: int, message_id: int, *, background: bool = False
+) -> AsyncIterator[tuple[Any, Any, Any]]:
+    """Release even when metadata fetch fails before response construction."""
+
+    # Metadata must not hold the payload slot that its pooled reader needs.
+    priority = {"priority": "preload", "respect_cooldown": True} if background else {}
+    lease = pool.lease(prefer_premium=True, **priority)
+    client = await lease.__aenter__()
+
+    async def metadata():
+        token = media_priority.set("preload") if background else None
+        try:
+            return await get_message(client, channel_id, message_id)
+        finally:
+            if token is not None:
+                media_priority.reset(token)
+
+    try:
+        try:
+            message = await metadata()
+            media = _media_from_message(message)
+            if message is None or getattr(message, "empty", False) or media is None:
+                raise TelegramFileNotFound(
+                    "Stored Telegram message has no media"
+                ) from None
+        except OSError, RPCError, ValueError:
+            if pool.kind_of(client) != "user":
+                raise
+            await lease.__aexit__(None, None, None)
+            lease = None
+            replacement = pool.lease(**priority)
+            client = await replacement.__aenter__()
+            lease = replacement
+            message = await metadata()
+            media = _media_from_message(message)
+            if message is None or getattr(message, "empty", False) or media is None:
+                raise TelegramFileNotFound(
+                    "Stored Telegram message has no media"
+                ) from None
+        yield client, message, media
+    finally:
+        if lease is not None:
+            await lease.__aexit__(None, None, None)
+
+
+async def describe_preview(
+    *,
+    pool: Any,
+    channel_id: int,
+    message_id: int,
+    file_name: str,
+    size: int,
+    path: str,
+    auth: str | None,
+    parts: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    extension = PurePath(file_name).suffix.lower().lstrip(".")
+    language = _TEXT_LANGUAGES.get(extension or file_name.lower().lstrip("."))
+    base: dict[str, Any] = {"name": file_name, "size": size}
+    if extension in {"epub", "cbz", "cbr"}:
+        return base | {"kind": "book", "format": extension}
+    if extension == "pdf":
+        if size > PDF_PREVIEW_BYTES:
+            return base | {
+                "kind": "unsupported",
+                "reason": (
+                    "PDF previews support files up to 256 MiB "
+                    "to protect browser memory. "
+                    "Download the original to open this file."
+                ),
+            }
+        query = {"path": path, "preview": "1"}
+        if auth:
+            query["auth"] = auth
+        return base | {"kind": "pdf", "url": "/file?" + urlencode(query)}
+    if language is None:
+        return base | {
+            "kind": "unsupported",
+            "reason": (
+                "This format does not have a browser preview. "
+                "Download the original to open it."
+            ),
+        }
+    if parts is not None:
+        manifest = validate_parts(parts, size=size, message_id=message_id)
+        data = await read_logical_prefix(
+            pool=pool,
+            channel_id=channel_id,
+            parts=manifest,
+            size=size,
+            limit=TEXT_PREVIEW_BYTES,
+        )
+        mime_type = mimetypes.guess_type(file_name)[0]
+    else:
+        async with lease_media(pool, channel_id, message_id) as (
+            client,
+            message,
+            media,
+        ):
+            actual_size = getattr(media, "file_size", size)
+            if isinstance(actual_size, int):
+                base["size"] = actual_size
+            if callable(getattr(pool, "download_capacity", None)):
+                if pool._media_read_cache is None:
+                    pool._media_read_cache = MediaReadCache(pool.media_cache_dir)
+                pool._media_read_cache.register_file(
+                    channel_id=channel_id,
+                    message_id=message_id,
+                    size=base["size"],
+                    name=file_name,
+                )
+            # A preview shares the bounded prefix cache, without qualifying as
+            # playback or asking the preparation manager to fetch anything else.
+            iterator = stream_pooled_media(
+                pool, client, message, channel=channel_id, limit=1, offset=0
+            )
+            try:
+                data = await anext(iterator, b"")
+                mime_type = getattr(media, "mime_type", None)
+                if mime_type is None:
+                    native_document = getattr(
+                        getattr(message, "native", message), "document", None
+                    )
+                    mime_type = getattr(native_document, "mime_type", None)
+            finally:
+                await iterator.aclose()
+    if extension in {"ts", "mts"} and _is_mpeg_transport_stream(data, mime_type):
+        return base | {"kind": "video"}
+    clipped = data[:TEXT_PREVIEW_BYTES]
+    truncated = base["size"] > len(clipped)
+    text = _decode_preview_text(clipped, truncated=truncated)
+    if text is None:
+        return base | {
+            "kind": "unsupported",
+            "reason": (
+                "This file is not readable text in a supported encoding. "
+                "Download the original to open it."
+            ),
+        }
+    return base | {
+        "kind": "text",
+        "text": text,
+        "language": language,
+        "truncated": truncated,
+        "preview_bytes": len(clipped),
+    }
+
+
+async def describe_media(
+    *,
+    pool: Any,
+    channel_id: int,
+    message_id: int,
+    file_name: str,
+    size: int,
+    parts: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    if parts is not None:
+        validate_parts(parts, size=size, message_id=message_id)
+        return {
+            "original": {
+                "id": "original",
+                "label": "Original",
+                "is_original": True,
+                "size": size,
+                "mime_type": mimetypes.guess_type(file_name)[0]
+                or "application/octet-stream",
+                "width": None,
+                "height": None,
+                "duration": None,
+            },
+            "variants": [],
+        }
+    async with lease_media(pool, channel_id, message_id) as (client, message, media):
+        describe = getattr(client, "describe_media", None)
+        if callable(describe):
+            return describe(message)
+        return {
+            "original": {
+                "id": "original",
+                "label": "Original",
+                "is_original": True,
+                "size": getattr(media, "file_size", size),
+                "mime_type": mimetypes.guess_type(file_name)[0]
+                or "application/octet-stream",
+                "width": None,
+                "height": None,
+                "duration": None,
+            },
+            "variants": [],
+        }
diff --git a/tgdrive/media/ranges.py b/tgdrive/media/ranges.py
new file mode 100644
index 00000000..6262a75d
--- /dev/null
+++ b/tgdrive/media/ranges.py
@@ -0,0 +1,200 @@
+"""HTTP byte-range parsing and Telegram chunk planning.
+
+Only a single ``bytes`` range is accepted.  The parser deliberately rejects
+multi-range requests because the streamer does not produce multipart bodies.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+TELEGRAM_CHUNK_SIZE = 1024 * 1024
+_RANGE_RE = re.compile(r"^bytes=([0-9]*)-([0-9]*)$", re.IGNORECASE)
+
+
+class RangeError(ValueError):
+    """Base class for invalid or unsatisfiable HTTP ranges."""
+
+
+class MalformedRange(RangeError):
+    """The Range header is syntactically invalid or unsupported."""
+
+
+class RangeNotSatisfiable(RangeError):
+    """The Range header cannot select bytes from the current representation."""
+
+    def __init__(self, total: int, message: str = "range is not satisfiable") -> None:
+        self.total = total
+        super().__init__(message)
+
+    @property
+    def content_range(self) -> str:
+        """Value for a 416 response's ``Content-Range`` header."""
+
+        return f"bytes */{self.total}"
+
+
+@dataclass(frozen=True, slots=True)
+class ByteRange:
+    """A normalized inclusive byte interval."""
+
+    start: int
+    end: int
+    total: int
+    is_partial: bool
+
+    def __post_init__(self) -> None:
+        if self.total < 0:
+            raise ValueError("total size cannot be negative")
+        if self.total == 0:
+            if (self.start, self.end) != (0, -1):
+                raise ValueError("an empty representation must use range 0..-1")
+            if self.is_partial:
+                raise ValueError("an empty representation cannot be partial")
+            return
+        if not 0 <= self.start <= self.end < self.total:
+            raise ValueError("byte range lies outside the representation")
+
+    @property
+    def length(self) -> int:
+        return 0 if self.total == 0 else self.end - self.start + 1
+
+    @property
+    def content_range(self) -> str | None:
+        if not self.is_partial:
+            return None
+        return f"bytes {self.start}-{self.end}/{self.total}"
+
+
+@dataclass(frozen=True, slots=True)
+class TelegramChunk:
+    """One Telegram ``upload.GetFile`` read and the bytes retained from it."""
+
+    offset: int
+    limit: int
+    cut_start: int
+    cut_end: int
+
+    @property
+    def output_length(self) -> int:
+        return self.cut_end - self.cut_start
+
+
+@dataclass(frozen=True, slots=True)
+class TelegramChunkPlan:
+    """An exact aligned read plan for a normalized byte range."""
+
+    offset: int
+    chunk_size: int
+    part_count: int
+    first_part_cut: int
+    last_part_cut: int
+    requested_length: int
+
+    def iter_chunks(self) -> Iterator[TelegramChunk]:
+        """Yield every aligned Telegram read and its half-open slice."""
+
+        for index in range(self.part_count):
+            cut_start = self.first_part_cut if index == 0 else 0
+            cut_end = (
+                self.last_part_cut if index == self.part_count - 1 else self.chunk_size
+            )
+            yield TelegramChunk(
+                offset=self.offset + index * self.chunk_size,
+                limit=self.chunk_size,
+                cut_start=cut_start,
+                cut_end=cut_end,
+            )
+
+
+def _bounded_decimal(value: str, total: int) -> int:
+    # RFC ranges have no fixed digit limit. Saturating above the representation
+    # size preserves clamping/suffix semantics without Python's int digit limit.
+    significant = value.lstrip("0")
+    if len(significant) > len(str(total)):
+        return total + 1
+    return int(significant or "0")
+
+
+def parse_byte_range(value: str | None, total: int) -> ByteRange:
+    """Parse and normalize one HTTP ``Range`` header.
+
+    Supported forms are ``bytes=start-end``, ``bytes=start-``, and
+    ``bytes=-suffix_length``.  An absent header selects the full
+    representation.  Explicit ends beyond EOF are clamped as required by
+    RFC 9110.
+    """
+
+    if total < 0:
+        raise ValueError("total size cannot be negative")
+
+    if value is None:
+        return ByteRange(0, total - 1, total, is_partial=False)
+
+    raw = value.strip()
+    if "," in raw:
+        raise MalformedRange("multiple byte ranges are not supported")
+
+    match = _RANGE_RE.fullmatch(raw)
+    if match is None:
+        raise MalformedRange("expected a single 'bytes=start-end' range")
+
+    first, last = match.groups()
+    if not first and not last:
+        raise MalformedRange("a range start or suffix length is required")
+    if total == 0:
+        raise RangeNotSatisfiable(total)
+
+    if not first:
+        suffix_length = _bounded_decimal(last, total)
+        if suffix_length <= 0:
+            raise RangeNotSatisfiable(total, "suffix length must be positive")
+        length = min(suffix_length, total)
+        return ByteRange(total - length, total - 1, total, is_partial=True)
+
+    start = _bounded_decimal(first, total)
+    if start >= total:
+        raise RangeNotSatisfiable(total, "range starts beyond end of file")
+
+    if not last:
+        end = total - 1
+    else:
+        requested_end = _bounded_decimal(last, total)
+        if requested_end < start:
+            raise RangeNotSatisfiable(total, "range end precedes range start")
+        end = min(requested_end, total - 1)
+
+    return ByteRange(start, end, total, is_partial=True)
+
+
+def plan_telegram_chunks(
+    byte_range: ByteRange,
+    *,
+    chunk_size: int = TELEGRAM_CHUNK_SIZE,
+) -> TelegramChunkPlan:
+    """Build aligned 1 MiB Telegram reads for ``byte_range``.
+
+    ``first_part_cut`` and ``last_part_cut`` are slice indexes compatible
+    with ``chunk[first_part_cut:last_part_cut]`` when the plan has one part.
+    """
+
+    if chunk_size <= 0:
+        raise ValueError("chunk_size must be positive")
+    if byte_range.length == 0:
+        return TelegramChunkPlan(0, chunk_size, 0, 0, 0, 0)
+
+    first_part = byte_range.start // chunk_size
+    last_part = byte_range.end // chunk_size
+    part_count = last_part - first_part + 1
+    offset = first_part * chunk_size
+
+    return TelegramChunkPlan(
+        offset=offset,
+        chunk_size=chunk_size,
+        part_count=part_count,
+        first_part_cut=byte_range.start - offset,
+        last_part_cut=(byte_range.end % chunk_size) + 1,
+        requested_length=byte_range.length,
+    )
diff --git a/tgdrive/media/streaming.py b/tgdrive/media/streaming.py
new file mode 100644
index 00000000..bd34c6e2
--- /dev/null
+++ b/tgdrive/media/streaming.py
@@ -0,0 +1,697 @@
+"""Safe, range-aware streaming from Telegram's supported client API."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import math
+import mimetypes
+import re
+import secrets
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import AbstractAsyncContextManager
+from typing import Any
+from urllib.parse import quote
+
+from fastapi import Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+from starlette.types import Receive, Scope, Send
+from telethon.errors import FloodWaitError, RPCError
+
+from tgdrive.core.security import safe_name
+from tgdrive.media.media_metadata import get_message
+from tgdrive.media.ranges import (
+    MalformedRange,
+    RangeNotSatisfiable,
+    parse_byte_range,
+    plan_telegram_chunks,
+)
+from tgdrive.telegram.client_pool import ClientPool, MediaQueueFull
+
+logger = logging.getLogger(__name__)
+
+PDF_PREVIEW_BYTES = 256 * 1024**2
+
+_MEDIA_ATTRIBUTES = (
+    "audio",
+    "document",
+    "photo",
+    "sticker",
+    "animation",
+    "video",
+    "voice",
+    "video_note",
+)
+_SAFE_INLINE_IMAGE_TYPES = {
+    "image/avif",
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+}
+
+
+class TelegramVariantNotFound(ValueError):
+    """The requested rendition does not belong to this message."""
+
+
+class TelegramFileNotFound(FileNotFoundError):
+    public_detail = (
+        "The stored file is missing or changed in Telegram. Restore it from a "
+        "configured channel backup, or upload the original file again. "
+        "Do not edit or delete messages in TGDrive's storage channel."
+    )
+
+
+def _record_request_error(status, error):
+    if status is None:
+        return
+    status.update(phase="error", code=None, retry_at=None)
+    if isinstance(error, asyncio.CancelledError):
+        status["phase"] = None
+    elif isinstance(error, MediaQueueFull):
+        status.update(
+            phase="retry_wait",
+            code=error.code,
+            retry_at=time.monotonic() + error.retry_after,
+        )
+
+
+class _LeasedStreamingResponse(StreamingResponse):
+    def __init__(
+        self,
+        *args: Any,
+        release: Callable[[], Awaitable[None]],
+        authorize=None,
+        request_status=None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._release = release
+        self._authorize = authorize
+        self._request_status = request_status
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        try:
+            if self._authorize is not None:
+                await self._authorize()
+            await super().__call__(scope, receive, send)
+        except BaseException as error:
+            _record_request_error(self._request_status, error)
+            raise
+        finally:
+            # ASGI send can fail while the body is suspended at a yield.
+            # Explicitly close it so bounded prefetch work is not left to GC.
+            try:
+                close = getattr(self.body_iterator, "aclose", None)
+                if close is not None:
+                    await close()
+            finally:
+                try:
+                    await self._release()
+                finally:
+                    if (
+                        self._request_status is not None
+                        and self._request_status["phase"] == "receiving"
+                    ):
+                        self._request_status["phase"] = None
+
+
+class _PrimedBody:
+    """Own a started iterator even if ASGI fails before its first body send."""
+
+    def __init__(self, iterator, first, authorize=None):
+        self.iterator, self.first, self.authorize = iterator, first, authorize
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        try:
+            if self.authorize is not None:
+                await self.authorize()
+            if self.first is not None:
+                first, self.first = self.first, None
+                return first
+            return await anext(self.iterator)
+        except BaseException:
+            await self.aclose()
+            raise
+
+    async def aclose(self):
+        self.first = None
+        await self.iterator.aclose()
+
+
+class _ActivityBody:
+    """Track one HTTP consumer across a logical multipart response."""
+
+    def __init__(self, iterator, activity):
+        self.iterator, self.activity = iterator, activity
+        self.observation = None
+        self.started = self.closed = self.completed = False
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if not self.started:
+            self.started = True
+            if self.activity is not None:
+                manager, identity, viewer = self.activity
+                self.observation = manager.begin(identity, viewer)
+        try:
+            return await anext(self.iterator)
+        except StopAsyncIteration:
+            self.completed = True
+            await self.aclose()
+            raise
+        except BaseException:
+            await self.aclose()
+            raise
+
+    def delivered(self, **values):
+        if self.activity is not None and self.observation is not None:
+            manager, _identity, viewer = self.activity
+            manager.delivered(**values, request_id=viewer, observation=self.observation)
+
+    async def aclose(self):
+        try:
+            await self.iterator.aclose()
+        finally:
+            if self.started and not self.closed:
+                self.closed = True
+                if self.activity is not None and self.observation is not None:
+                    manager, identity, viewer = self.activity
+                    manager.finished(
+                        identity,
+                        viewer,
+                        completed=self.completed,
+                        observation=self.observation,
+                    )
+
+
+def _media_etag(identity):
+    return '"tg-' + hashlib.sha256(repr(identity).encode()).hexdigest() + '"'
+
+
+def media_etag(
+    channel_id, message_id, total, parts=None, quality=None, document_identity=None
+):
+    quality = quality if quality not in (None, "") else "original"
+    if parts is not None:
+        manifest = tuple(
+            (
+                p["index"],
+                p["offset"],
+                p["size"],
+                p["message_id"],
+                p["sha256"],
+                p.get("document_id"),
+            )
+            for p in parts
+        )
+        return _media_etag((channel_id, message_id, total, quality, manifest))
+    tag = _media_etag((channel_id, message_id, total, quality, document_identity))
+    # A catalog-only HEAD cannot prove the immutable Telegram document identity.
+    return tag if document_identity is not None else "W/" + tag
+
+
+def _request_range(request, etag):
+    value = request.headers.get("if-range")
+    # A weak tag or an unverifiable date cannot prove byte identity.
+    if value is not None and (value.strip().startswith("W/") or value.strip() != etag):
+        return None
+    return request.headers.get("range")
+
+
+def _not_modified(request, etag):
+    value = request.headers.get("if-none-match")
+    return value is not None and any(
+        tag.strip() == "*" or tag.strip().removeprefix("W/") == etag.removeprefix("W/")
+        for tag in value.split(",")
+    )
+
+
+def _is_playback_request(request, mime_type, *, download=False, preview=False):
+    """Only explicit player requests may warm beyond their HTTP byte range."""
+    return (
+        not download
+        and mime_type.startswith(("audio/", "video/"))
+        and (preview or request.headers.get("sec-fetch-dest") in {"audio", "video"})
+    )
+
+
+def _media_byte_rate(message, size):
+    """Use media duration for average bitrate instead of network burst speed."""
+    native = getattr(message, "native", message)
+    document = getattr(native, "document", None)
+    for attribute in getattr(document, "attributes", ()):
+        duration = getattr(attribute, "duration", None)
+        if type(duration) in (int, float) and math.isfinite(duration) and duration > 0:
+            rate = size / duration
+            return rate if math.isfinite(rate) and rate > 0 else None
+    return None
+
+
+def _observe_media_request(
+    pool,
+    *,
+    channel_id,
+    message_id,
+    size,
+    name,
+    request,
+    start,
+    end,
+    parts=None,
+    authorize=None,
+    request_id=None,
+    allow_preload=True,
+    media_rate=None,
+):
+    manager = getattr(pool, "_preload_manager", None)
+    if manager is not None:
+        if not allow_preload:
+            # Downloads and unclassified clients retain their requested blocks.
+            # Only identified playback may schedule work outside its HTTP range.
+            manager.register_file(
+                channel_id=channel_id,
+                message_id=message_id,
+                size=size,
+                name=name,
+                parts=parts,
+            )
+            return None
+        viewer = request_id or secrets.token_urlsafe(12)
+        identity = manager.observe(
+            channel_id=channel_id,
+            message_id=message_id,
+            size=size,
+            name=name,
+            parts=parts,
+            start=start,
+            end=end,
+            method=request.method,
+            authorize=authorize,
+            request_id=viewer,
+            media_rate=media_rate,
+            allow_full=request_id is not None,
+        )
+        return (manager, identity, viewer) if request.method == "GET" else None
+    elif callable(getattr(pool, "download_capacity", None)):
+        from tgdrive.media.media_reader import MediaReadCache
+
+        if pool._media_read_cache is None:
+            pool._media_read_cache = MediaReadCache(pool.media_cache_dir)
+        pool._media_read_cache.register_file(
+            channel_id=channel_id,
+            message_id=message_id,
+            size=size,
+            name=name,
+            parts=parts,
+        )
+
+
+async def _prime_response(
+    iterator,
+    *,
+    release,
+    status,
+    mime_type,
+    headers,
+    authorize=None,
+    request_status=None,
+):
+    try:
+        try:
+            first = await anext(iterator)
+        except StopAsyncIteration:
+            first = None
+    except BaseException as error:
+        _record_request_error(request_status, error)
+        try:
+            await iterator.aclose()
+        finally:
+            await release()
+        if isinstance(error, MediaQueueFull):
+            return JSONResponse(
+                {
+                    "detail": str(error),
+                    "code": error.code,
+                    "retry_after": error.retry_after,
+                },
+                status_code=503,
+                headers={
+                    "Retry-After": str(error.retry_after),
+                    "Cache-Control": "no-store",
+                },
+            )
+        raise
+    if request_status is not None:
+        request_status["phase"] = "receiving"
+    return _LeasedStreamingResponse(
+        _PrimedBody(iterator, first, authorize),
+        release=release,
+        authorize=authorize,
+        request_status=request_status,
+        status_code=status,
+        media_type=mime_type,
+        headers=headers,
+    )
+
+
+def _media_from_message(message: Any) -> Any | None:
+    for attribute in _MEDIA_ATTRIBUTES:
+        media = getattr(message, attribute, None)
+        if media is not None:
+            return media
+    return None
+
+
+def _content_disposition(
+    file_name: str, mime_type: str, *, download: bool = False, preview: bool = False
+) -> str:
+    normalized = safe_name(file_name)
+    disposition = (
+        "inline"
+        if not download
+        and (
+            mime_type.startswith(("audio/", "video/"))
+            or mime_type in _SAFE_INLINE_IMAGE_TYPES
+            or (preview and mime_type == "application/pdf")
+        )
+        else "attachment"
+    )
+    encoded = quote(normalized, safe="")
+    ascii_fallback = normalized.encode("ascii", "replace").decode().replace('"', "'")
+    return f"{disposition}; filename=\"{ascii_fallback}\"; filename*=UTF-8''{encoded}"
+
+
+async def stream_telegram_file(
+    *,
+    pool: ClientPool,
+    channel_id: int,
+    message_id: int,
+    file_name: str,
+    expected_size: int,
+    request: Request,
+    download: bool = False,
+    preview: bool = False,
+    quality: str | None = None,
+    parts: list[dict[str, Any]] | None = None,
+    authorize=None,
+    request_id: str | None = None,
+    request_status=None,
+) -> Response:
+    """Stream with an optional Premium user and a balanced client lease."""
+    if authorize is not None:
+        await authorize()
+    if parts is not None:
+        from tgdrive.media.multipart_streaming import stream_multipart_file
+
+        return await stream_multipart_file(
+            pool=pool,
+            channel_id=channel_id,
+            message_id=message_id,
+            file_name=file_name,
+            expected_size=expected_size,
+            parts=parts,
+            request=request,
+            download=download,
+            preview=preview,
+            quality=quality,
+            authorize=authorize,
+            request_id=request_id,
+            request_status=request_status,
+        )
+
+    lease: AbstractAsyncContextManager[Any] = pool.lease(
+        prefer_premium=True, respect_cooldown=True
+    )
+    client = await lease.__aenter__()
+    release_task: asyncio.Task[Any] | None = None
+
+    async def release() -> None:
+        nonlocal release_task
+        if release_task is None:
+            release_task = asyncio.create_task(lease.__aexit__(None, None, None))
+        interrupted = False
+        while not release_task.done():
+            try:
+                await asyncio.shield(release_task)
+            except asyncio.CancelledError:
+                # Keep lease cleanup owned until it drains, even if disconnect
+                # and shutdown cancel this response more than once.
+                interrupted = True
+        release_task.result()
+        if interrupted:
+            raise asyncio.CancelledError
+
+    try:
+
+        async def fetch_media() -> tuple[Any, Any]:
+            message = await get_message(client, channel_id, message_id)
+            media = _media_from_message(message)
+            if message is None or getattr(message, "empty", False) or media is None:
+                raise TelegramFileNotFound(
+                    f"Telegram message {message_id} has no media"
+                )
+            actual_size = getattr(media, "file_size", None)
+            if type(actual_size) is int and actual_size != expected_size:
+                raise TelegramFileNotFound(
+                    "Stored Telegram media size differs from the catalog"
+                )
+            return message, media
+
+        for attempt in range(3):
+            try:
+                message, media = await fetch_media()
+                break
+            except (OSError, RPCError, ValueError) as error:
+                problem = await pool.report_failure(client, error)
+                if isinstance(error, FloodWaitError):
+                    await pool.defer_client(
+                        client.name, time.time() + max(1, error.seconds)
+                    )
+                elif problem is None and pool.kind_of(client) != "user":
+                    raise
+                if attempt == 2:
+                    if problem is not None:
+                        raise problem from None
+                    raise
+                # Switch before headers, preserving optional-user fallback.
+                await release()
+                lease = pool.lease(respect_cooldown=True)
+                client = await lease.__aenter__()
+                release_task = None
+
+        if quality not in (None, "", "original") and not download:
+            select = getattr(client, "select_media_variant", None)
+            if not callable(select):
+                raise TelegramVariantNotFound("This media quality is unavailable")
+            try:
+                message = select(message, quality)
+            except (ValueError, KeyError) as exc:
+                raise TelegramVariantNotFound(
+                    "This media quality is unavailable"
+                ) from exc
+            media = _media_from_message(message)
+            if media is None:
+                raise TelegramVariantNotFound("This media quality is unavailable")
+        telegram_size = getattr(media, "file_size", None)
+        total = telegram_size if isinstance(telegram_size, int) else expected_size
+        if total < 0:
+            raise TelegramFileNotFound("Telegram media has an invalid size")
+
+        from tgdrive.telegram.clients import _block_identity
+
+        immutable = _block_identity(message, 0)
+        selected_quality = quality if not download else "original"
+        etag = media_etag(
+            channel_id,
+            message_id,
+            total,
+            quality=selected_quality,
+            document_identity=immutable[0][2:-1] if immutable else None,
+        )
+        if _not_modified(request, etag):
+            if authorize is not None:
+                await authorize()
+            await release()
+            return Response(
+                status_code=304,
+                headers={
+                    "ETag": etag,
+                    "Cache-Control": "private, no-store, no-transform",
+                },
+            )
+
+        try:
+            byte_range = parse_byte_range(_request_range(request, etag), total)
+        except MalformedRange as exc:
+            await release()
+            return Response(
+                status_code=400,
+                content=str(exc),
+                headers={"Accept-Ranges": "bytes"},
+            )
+        except RangeNotSatisfiable as exc:
+            await release()
+            return Response(
+                status_code=416,
+                headers={
+                    "Accept-Ranges": "bytes",
+                    "Content-Range": exc.content_range,
+                },
+            )
+
+        plan = plan_telegram_chunks(byte_range)
+        mime_type = mimetypes.guess_type(file_name)[0] or "application/octet-stream"
+        selected_mime = getattr(media, "mime_type", None)
+        if (
+            quality not in (None, "", "original")
+            and not download
+            and isinstance(selected_mime, str)
+            and re.fullmatch(r"(video|audio|image)/[a-zA-Z0-9.+-]+", selected_mime)
+        ):
+            mime_type = selected_mime
+        if (
+            preview
+            and not download
+            and mime_type == "application/pdf"
+            and total > PDF_PREVIEW_BYTES
+        ):
+            await release()
+            return Response(status_code=413, content="PDF preview limit is 256 MiB")
+
+        activity = _observe_media_request(
+            pool,
+            channel_id=channel_id,
+            message_id=message_id,
+            size=total,
+            name=file_name,
+            request=request,
+            start=byte_range.start,
+            end=byte_range.end + 1,
+            allow_preload=_is_playback_request(
+                request, mime_type, download=download, preview=preview
+            )
+            and quality in (None, "", "original"),
+            media_rate=_media_byte_rate(message, total),
+            authorize=authorize,
+            request_id=request_id,
+        )
+        # Pooled reads own their origin leases. A long warm response must not
+        # retain the account used for its short, fresh metadata validation.
+        if immutable is not None:
+            await release()
+
+        async def body() -> AsyncIterator[bytes]:
+            emitted = 0
+            from tgdrive.media.media_reader import stream_pooled_media
+
+            stream = stream_pooled_media(
+                pool,
+                client,
+                message,
+                channel=channel_id,
+                limit=plan.part_count,
+                offset=plan.offset // plan.chunk_size,
+                authorize=authorize,
+                request_id=request_id,
+            )
+            try:
+                chunk_index = 0
+                async for chunk in stream:
+                    if chunk_index >= plan.part_count:
+                        break
+                    cut_start = plan.first_part_cut if chunk_index == 0 else 0
+                    cut_end = (
+                        plan.last_part_cut
+                        if chunk_index == plan.part_count - 1
+                        else len(chunk)
+                    )
+                    selected = chunk[cut_start:cut_end]
+                    emitted += len(selected)
+                    chunk_index += 1
+                    if selected:
+                        yield selected
+                        if activity is not None:
+                            tracked_body.delivered(
+                                channel_id=channel_id,
+                                message_id=message_id,
+                                offset=byte_range.start + emitted - len(selected),
+                                length=len(selected),
+                            )
+                if emitted != plan.requested_length:
+                    raise OSError(
+                        "Telegram stream ended early "
+                        f"({emitted}/{plan.requested_length} bytes)"
+                    )
+            except Exception:
+                logger.exception("Telegram response stream failed")
+                raise
+            finally:
+                try:
+                    await stream.aclose()
+                finally:
+                    await release()
+
+        headers = {
+            "Accept-Ranges": "bytes",
+            "Content-Length": str(byte_range.length),
+            "Content-Encoding": "identity",
+            "Content-Disposition": _content_disposition(
+                file_name, mime_type, download=download, preview=preview
+            ),
+            "X-Content-Type-Options": "nosniff",
+            "Referrer-Policy": "no-referrer",
+            "Content-Security-Policy": "sandbox; default-src 'none'",
+            "Cache-Control": "private, no-store, no-transform",
+            "ETag": etag,
+        }
+        if (
+            mime_type.startswith(("audio/", "video/"))
+            or mime_type in _SAFE_INLINE_IMAGE_TYPES
+        ) and not download:
+            # Passive media may also be opened directly in the browser's native
+            # media document. A default-src none sandbox prevents that document
+            # from loading its own source in Chromium.
+            headers["Content-Security-Policy"] = (
+                "default-src 'none'; media-src 'self' blob:; img-src 'self' data:; "
+                "style-src 'unsafe-inline'; frame-ancestors 'self'"
+            )
+        elif preview and mime_type == "application/pdf" and not download:
+            headers["X-Frame-Options"] = "SAMEORIGIN"
+            headers["Content-Security-Policy"] = (
+                "sandbox; default-src 'none'; frame-ancestors 'self'"
+            )
+        if byte_range.content_range is not None:
+            headers["Content-Range"] = byte_range.content_range
+
+        if request.method == "HEAD":
+            if authorize is not None:
+                await authorize()
+            await release()
+            return Response(
+                status_code=206 if byte_range.is_partial else 200,
+                media_type=mime_type,
+                headers=headers,
+            )
+
+        tracked_body = _ActivityBody(body(), activity)
+        return await _prime_response(
+            tracked_body,
+            release=release,
+            status=206 if byte_range.is_partial else 200,
+            mime_type=mime_type,
+            headers=headers,
+            authorize=authorize,
+            request_status=request_status,
+        )
+    except BaseException:
+        await release()
+        raise
diff --git a/tgdrive/media/thumbnail_rebuild.py b/tgdrive/media/thumbnail_rebuild.py
new file mode 100644
index 00000000..df6938fd
--- /dev/null
+++ b/tgdrive/media/thumbnail_rebuild.py
@@ -0,0 +1,529 @@
+"""Owner-started, bounded thumbnail regeneration, separate from transfer admission."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import copy
+import json
+import os
+import re
+import secrets
+import tempfile
+import time
+from collections import OrderedDict
+from contextlib import suppress
+from pathlib import Path
+from typing import Literal
+
+from aiohttp import web
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel, ConfigDict
+
+from tgdrive.core.errors import (
+    NotDirectoryError,
+    NotFileError,
+    NotFoundError,
+    TrashedItemError,
+)
+from tgdrive.media import generated_thumbnails as covers
+from tgdrive.media.books import parse_book, read_range
+from tgdrive.media.media_scheduler import media_priority
+from tgdrive.media.thumbnail_worker import (
+    AUDIO_FORMATS,
+    IMAGE_CODECS,
+    OFFICE_FORMATS,
+    VIDEO_FORMATS,
+)
+
+BLOCK = 1024**2
+SOURCE_BUDGET = 64 * BLOCK
+PDF_BUDGET = 256 * BLOCK
+RATE = 2 * BLOCK
+SUPPORTED = covers.SUPPORTED | {".cbr"}
+
+
+def file_identity(data):
+    return data["message_id"], data["size"], data.get("parts")
+
+
+def write_state(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    descriptor, temporary = tempfile.mkstemp(dir=path.parent, prefix=".thumbnail-job-")
+    try:
+        with os.fdopen(descriptor, "w") as output:
+            json.dump(data, output, allow_nan=False)
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+class SourceLimit(Exception):
+    pass
+
+
+class RebuildSource:
+    """Four hot blocks and a cumulative per-file read limit, including repeat reads."""
+
+    def __init__(self, owner, data):
+        self.owner, self.data = owner, data
+        self.blocks = OrderedDict()
+        self.used = 0
+        self.budget = (
+            PDF_BUDGET if Path(data["name"]).suffix.lower() == ".pdf" else SOURCE_BUDGET
+        )
+        self.lock = asyncio.Lock()
+        self.token = secrets.token_urlsafe(32)
+        self.runner = None
+
+    async def authorize(self):
+        store = self.owner.runtime().store
+        current = store.get_file(store.resolve_id(self.data["id"]))
+        if store.drive_id != self.owner.drive_id or file_identity(
+            current
+        ) != file_identity(self.data):
+            raise SourceLimit("File removed or changed")
+
+    async def read(self, start, count):
+        if start < 0 or count < 1 or start + count > self.data["size"]:
+            raise SourceLimit("Invalid source range")
+        output = bytearray()
+        async with self.lock:
+            await self.authorize()
+            while len(output) < count:
+                offset = start + len(output)
+                index = offset // BLOCK
+                if index not in self.blocks:
+                    length = min(BLOCK, self.data["size"] - index * BLOCK)
+                    if self.used + length > self.budget:
+                        raise SourceLimit("Source read budget reached")
+                    await self.owner.wait_turn()
+                    began = time.monotonic()
+                    data = await read_range(
+                        self.owner.runtime().pool,
+                        self.owner.settings.storage_channel,
+                        self.data,
+                        index * BLOCK,
+                        length,
+                        self.authorize,
+                        background=True,
+                    )
+                    if len(data) != length:
+                        raise SourceLimit("Source ended early")
+                    self.used += len(data)
+                    self.owner.state["source_bytes"] += len(data)
+                    self.owner.state["current_bytes"] = self.used
+                    self.blocks[index] = data
+                    while len(self.blocks) > 4:
+                        self.blocks.popitem(last=False)
+                    await self.owner.persist_progress()
+                    await asyncio.sleep(
+                        max(0, length / RATE - (time.monotonic() - began))
+                    )
+                self.blocks.move_to_end(index)
+                block = self.blocks[index]
+                position = offset % BLOCK
+                output.extend(
+                    block[
+                        position : position
+                        + min(count - len(output), len(block) - position)
+                    ]
+                )
+        return bytes(output)
+
+    async def serve(self, request):
+        if request.path != "/" + self.token or request.method not in {"GET", "HEAD"}:
+            raise web.HTTPNotFound()
+        size = self.data["size"]
+        start, end, partial = 0, size - 1, False
+        if value := request.headers.get("Range"):
+            match = (
+                re.fullmatch(r"bytes=(\d+)-(\d*)", value) if len(value) < 128 else None
+            )
+            if not match:
+                raise web.HTTPRequestRangeNotSatisfiable()
+            start, raw_end = match.groups()
+            start, end = int(start), min(int(raw_end), end) if raw_end else end
+            partial = True
+        if not 0 <= start <= end < size:
+            raise web.HTTPRequestRangeNotSatisfiable()
+        await self.authorize()
+        headers = {
+            "Accept-Ranges": "bytes",
+            "Content-Length": str(end - start + 1),
+            "Content-Type": "application/octet-stream",
+        }
+        if partial:
+            headers["Content-Range"] = f"bytes {start}-{end}/{size}"
+        response = web.StreamResponse(status=206 if partial else 200, headers=headers)
+        await response.prepare(request)
+        if request.method == "HEAD":
+            return response
+        try:
+            while start <= end:
+                # Keep at most one chunk queued to the local decoder; its seeks
+                # close abandoned streams before another origin block is read.
+                data = await self.read(start, min(65536, end - start + 1))
+                await response.write(data)
+                start += len(data)
+                await asyncio.sleep(len(data) / RATE)
+            await response.write_eof()
+        except ConnectionError, SourceLimit, asyncio.CancelledError:
+            response.force_close()
+        return response
+
+    async def open(self):
+        app = web.Application(client_max_size=1024)
+        app.router.add_route("*", "/{tail:.*}", self.serve)
+        self.runner = web.AppRunner(
+            app, access_log=None, shutdown_timeout=0.1, handler_cancellation=True
+        )
+        await self.runner.setup()
+        site = web.TCPSite(self.runner, "127.0.0.1", 0)
+        await site.start()
+        port = site._server.sockets[0].getsockname()[1]
+        return f"http://127.0.0.1:{port}/{self.token}"
+
+    async def close(self):
+        if self.runner is not None:
+            await self.runner.cleanup()
+
+
+class ThumbnailRebuild:
+    def __init__(self, settings, runtime, thumbnails):
+        self.settings, self.runtime, self.thumbnails = settings, runtime, thumbnails
+        self.path = settings.resolved_data_dir / "thumbnail-rebuild.json"
+        self.directory = settings.resolved_cache_dir / "thumbnails"
+        self.staging = covers.CachedThumbnailRepair(self.directory)
+        self.state = {
+            "status": "idle",
+            "phase": "Ready",
+            "total": 0,
+            "processed": 0,
+            "generated": 0,
+            "skipped": 0,
+            "failed": 0,
+            "source_bytes": 0,
+        }
+        self.task = None
+        self.drive_id = None
+        self.last_saved = 0
+        self.stopping = False
+        self.start_lock = asyncio.Lock()
+
+    def snapshot(self):
+        return copy.deepcopy(self.state)
+
+    async def restore(self):
+        try:
+            if await asyncio.to_thread(lambda: self.path.stat().st_size) > 16384:
+                return
+            value = json.loads(await asyncio.to_thread(self.path.read_text))
+            if isinstance(value, dict) and value.get("status") in {
+                "running",
+                "completed",
+                "cancelled",
+                "interrupted",
+                "failed",
+            }:
+                self.state = value
+                if value["status"] == "running":
+                    self.state.update(
+                        status="interrupted",
+                        phase="Server restarted; start a new rebuild",
+                        finished_at=time.time(),
+                    )
+                    await self.persist()
+        except OSError, ValueError:
+            pass
+
+    async def persist(self):
+        try:
+            await covers._owned_disk_call(write_state, self.path, self.snapshot())
+            self.state.pop("persistence_warning", None)
+        except OSError:
+            self.state["persistence_warning"] = (
+                "Progress could not be saved to disk; keep this server running."
+            )
+        self.last_saved = time.monotonic()
+
+    async def persist_progress(self):
+        if time.monotonic() - self.last_saved >= 1:
+            await self.persist()
+
+    def busy(self):
+        runtime = self.runtime()
+        registry = getattr(runtime, "registry", None)
+        if registry is not None and any(
+            str(row.status) == "running" for row in registry.list()
+        ):
+            return True
+        pool = getattr(runtime, "pool", None)
+        if callable(getattr(pool, "performance_snapshot", None)):
+            return bool(pool.performance_snapshot().get("active", 0))
+        return False
+
+    async def wait_turn(self):
+        while self.busy():
+            self.state["phase"] = "Waiting for active transfers or playback"
+            await self.persist_progress()
+            await asyncio.sleep(0.5)
+        self.state["phase"] = "Regenerating thumbnail"
+
+    async def start(self):
+        async with self.start_lock:
+            return await self._start()
+
+    async def _start(self):
+        if self.task is not None and not self.task.done():
+            return self.snapshot()
+        if (
+            getattr(self.runtime(), "store", None) is None
+            or getattr(self.runtime(), "pool", None) is None
+        ):
+            raise HTTPException(503, "TGDrive is not ready")
+        self.state = {
+            "id": secrets.token_urlsafe(12),
+            "status": "running",
+            "phase": "Finding files",
+            "total": 0,
+            "processed": 0,
+            "generated": 0,
+            "skipped": 0,
+            "failed": 0,
+            "source_bytes": 0,
+            "current_bytes": 0,
+            "started_at": time.time(),
+            "recent_issues": [],
+        }
+        self.stopping = False
+        await self.persist()
+        self.task = asyncio.create_task(self.run(), name="tgdrive-thumbnail-rebuild")
+        return self.snapshot()
+
+    async def render_file(self, source):
+        data = source.data
+        suffix = Path(data["name"]).suffix.lower()
+        temporary = output = None
+        try:
+            if (
+                suffix in IMAGE_CODECS
+                or suffix in VIDEO_FORMATS
+                or suffix in AUDIO_FORMATS
+            ):
+                url = await source.open()
+                return await covers.generate(
+                    Path("remote"),
+                    data["name"],
+                    background=True,
+                    remote_url=url,
+                    source_size=data["size"],
+                )
+            if suffix in {".epub", ".cbz", ".cbr"} | OFFICE_FORMATS:
+                if suffix in {".epub", ".cbz"} | OFFICE_FORMATS:
+                    result = await parse_book(data, source.read, thumbnail=True)
+                else:
+                    index = await parse_book(data, source.read)
+                    entry = index["entries"][0]["name"]
+                    result = await parse_book(data, source.read, entry)
+                if result.get("kind") != "image":
+                    return None
+                content = base64.b64decode(result["data"], validate=True)
+                suffix = {
+                    "image/jpeg": ".jpg",
+                    "image/png": ".png",
+                    "image/webp": ".webp",
+                    "image/gif": ".gif",
+                    "image/avif": ".avif",
+                }.get(result["mime"])
+                if suffix is None:
+                    return None
+            elif suffix == ".pdf":
+                if data["size"] > PDF_BUDGET:
+                    raise SourceLimit("PDF exceeds 256 MiB rebuild limit")
+                content = None
+            else:
+                return None
+            required = len(content) if content is not None else data["size"]
+            opening = asyncio.create_task(
+                asyncio.to_thread(self.staging._open_source, required, 64 * BLOCK)
+            )
+            opened, interrupted = await covers._finish_owned(opening)
+            if opened is not None:
+                output, temporary = opened
+            if interrupted:
+                raise asyncio.CancelledError
+            if content is not None:
+                await covers._owned_disk_call(output.write, content)
+            else:
+                for start in range(0, data["size"], BLOCK):
+                    block = await source.read(start, min(BLOCK, data["size"] - start))
+                    await covers._owned_disk_call(output.write, block)
+            await covers._owned_disk_call(output.flush)
+            return await covers.generate(temporary, "cover" + suffix, background=True)
+        finally:
+            await source.close()
+            if output is not None:
+                await covers._owned_disk_call(
+                    self.staging._cleanup_source, output, temporary
+                )
+
+    async def run(self):
+        priority = media_priority.set("preload")
+        try:
+            self.drive_id = self.runtime().store.drive_id
+            pending, visited, files = ["/"], set(), set()
+            while pending:
+                path = pending.pop()
+                if path in visited:
+                    continue
+                visited.add(path)
+                try:
+                    rows = await asyncio.to_thread(
+                        self.runtime().store.list_directory, path
+                    )
+                except NotFoundError, NotDirectoryError, TrashedItemError:
+                    # A concurrent move/deletion can invalidate this directory.
+                    continue
+                for row in rows.values():
+                    if row["type"] == "file":
+                        files.add(row["id"])
+                    else:
+                        pending.append(path.rstrip("/") + "/" + row["id"])
+                self.state["total"] = len(files)
+                await self.persist_progress()
+                await asyncio.sleep(0)
+            await self.persist()
+            for item_id in sorted(files):
+                try:
+                    store = self.runtime().store
+                    data = store.get_file(store.resolve_id(item_id))
+                except NotFoundError, NotFileError, TrashedItemError:
+                    self.state["skipped"] += 1
+                    self.state["processed"] += 1
+                    await self.persist()
+                    continue
+                self.state.update(current_name=data["name"], current_bytes=0)
+                if Path(data["name"]).suffix.lower() not in SUPPORTED:
+                    self.state["skipped"] += 1
+                else:
+                    await self.wait_turn()
+                    source = RebuildSource(self, data)
+                    try:
+                        async with asyncio.timeout(240):
+                            cover = await self.render_file(source)
+                        await source.authorize()
+                        if cover:
+                            await asyncio.to_thread(
+                                covers.save,
+                                self.directory,
+                                self.settings.storage_channel,
+                                data["message_id"],
+                                cover,
+                            )
+                            stored = await asyncio.to_thread(
+                                covers.read,
+                                self.directory,
+                                self.settings.storage_channel,
+                                data["message_id"],
+                            )
+                            if stored != cover:
+                                raise SourceLimit(
+                                    "Thumbnail cache is full or unavailable"
+                                )
+                            await self.thumbnails.invalidate_file(
+                                self.settings.storage_channel, data["message_id"]
+                            )
+                            self.state["generated"] += 1
+                        else:
+                            self.state["skipped"] += 1
+                            self.issue(
+                                data["name"],
+                                "No cover within the rendering/read limits",
+                            )
+                    except SourceLimit as error:
+                        self.state["skipped"] += 1
+                        self.issue(data["name"], str(error))
+                    except Exception:
+                        self.state["failed"] += 1
+                        self.issue(
+                            data["name"],
+                            "File unavailable or thumbnail generation failed",
+                        )
+                self.state["processed"] += 1
+                await self.persist()
+                await asyncio.sleep(0.1)
+            self.state.update(
+                status="completed",
+                phase="Finished",
+                current_name="",
+                finished_at=time.time(),
+            )
+        except asyncio.CancelledError:
+            self.state.update(
+                status="interrupted" if self.stopping else "cancelled",
+                phase="Stopped",
+                finished_at=time.time(),
+            )
+        except Exception:
+            self.state.update(
+                status="failed",
+                phase="Could not continue; start a new rebuild",
+                finished_at=time.time(),
+            )
+        finally:
+            media_priority.reset(priority)
+            await self.persist()
+
+    def issue(self, name, reason):
+        self.state["recent_issues"] = [
+            *self.state["recent_issues"],
+            {"name": name, "reason": reason},
+        ][-5:]
+
+    async def cancel(self):
+        if self.task is not None and not self.task.done():
+            self.task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self.task
+            if self.state["status"] == "running":
+                self.state.update(
+                    status="interrupted" if self.stopping else "cancelled",
+                    phase="Stopped",
+                    finished_at=time.time(),
+                )
+                await self.persist()
+        return self.snapshot()
+
+    async def close(self):
+        self.stopping = True
+        await self.cancel()
+
+
+class RebuildRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    confirmed: Literal[True]
+
+
+def register_thumbnail_routes(app, settings, require_admin):
+    manager = ThumbnailRebuild(
+        settings, lambda: app.state.runtime, app.state.thumbnails
+    )
+    app.state.thumbnail_rebuild = manager
+    dependencies = [Depends(require_admin)]
+
+    @app.get("/api/v1/settings/thumbnails/rebuild", dependencies=dependencies)
+    async def status():
+        return manager.snapshot()
+
+    @app.post(
+        "/api/v1/settings/thumbnails/rebuild",
+        dependencies=dependencies,
+        status_code=202,
+    )
+    async def start(body: RebuildRequest):
+        return await manager.start()
+
+    @app.post("/api/v1/settings/thumbnails/rebuild/cancel", dependencies=dependencies)
+    async def cancel():
+        return await manager.cancel()
diff --git a/tgdrive/media/thumbnail_worker.py b/tgdrive/media/thumbnail_worker.py
new file mode 100644
index 00000000..d9f47f94
--- /dev/null
+++ b/tgdrive/media/thumbnail_worker.py
@@ -0,0 +1,378 @@
+"""Optional local thumbnail renderer. Original bytes are never rewritten."""
+
+from __future__ import annotations
+
+# Native tools run with fixed argument lists and no shell; see render().
+import math
+import os
+import secrets
+import subprocess  # nosec B404
+import sys
+from pathlib import Path
+
+IMAGE_CODECS = {
+    ".jpg": "mjpeg",
+    ".jpeg": "mjpeg",
+    ".png": "png",
+    ".webp": "webp",
+    ".gif": "gif",
+    ".bmp": "bmp",
+    ".tif": "tiff",
+    ".tiff": "tiff",
+}
+VIDEO_FORMATS = {
+    ".mp4": "mov",
+    ".m4v": "mov",
+    ".mov": "mov",
+    ".avif": "mov",
+    ".mkv": "matroska",
+    ".webm": "matroska",
+    ".avi": "avi",
+    ".wmv": "asf",
+    ".asf": "asf",
+    ".mpeg": "mpeg",
+    ".mpg": "mpeg",
+}
+AUDIO_FORMATS = {
+    ".mp3": "mp3",
+    ".flac": "flac",
+    ".m4a": "mov",
+    ".ogg": "ogg",
+    ".opus": "ogg",
+    ".wav": "wav",
+    ".aac": "aac",
+}
+OFFICE_FORMATS = {".docx", ".pptx", ".xlsx", ".odt", ".odp", ".ods"}
+MAX_BYTES = 64 * 1024
+# Shared libraries, HEVC reference frames and thread stacks all count toward
+# virtual address space. 512 MiB rejects ordinary UHD HEVC before scaling it.
+ADDRESS_SPACE_BYTES = 768 * 1024**2
+
+
+def archive_cover(path: Path, suffix: str) -> tuple[bytes, str] | None:
+    from tgdrive.media.book_worker import RemoteFile
+
+    with path.open("rb") as source:
+
+        def fetch(start, length):
+            source.seek(start)
+            return source.read(length)
+
+        return archive_cover_from_source(RemoteFile(path.stat().st_size, fetch), suffix)
+
+
+def archive_cover_from_source(source, suffix: str) -> tuple[bytes, str] | None:
+    from tgdrive.media.book_worker import (
+        IMAGES,
+        MAX_ENTRY,
+        image_type,
+        local_ref,
+        natural,
+        open_zip,
+        xml,
+        zip_bytes,
+    )
+
+    if suffix == ".cbr":
+        import base64
+
+        from tgdrive.media.book_worker import read_book
+
+        index = read_book(source, "cbr")
+        result = read_book(source, "cbr", index["entries"][0]["name"])
+        data = base64.b64decode(result["data"], validate=True)
+        kind = {
+            "image/jpeg": ".jpg",
+            "image/png": ".png",
+            "image/webp": ".webp",
+            "image/gif": ".gif",
+            "image/avif": ".avif",
+        }.get(result["mime"])
+        return (data, kind) if kind else None
+    with open_zip(source) as archive:
+        candidates = []
+        if suffix in OFFICE_FORMATS:
+            candidates = [
+                name
+                for name in (
+                    "docProps/thumbnail.jpeg",
+                    "docProps/thumbnail.jpg",
+                    "docProps/thumbnail.png",
+                    "Thumbnails/thumbnail.png",
+                )
+                if name in archive.namelist()
+            ]
+            if not candidates:
+                return None
+        elif suffix == ".epub":
+            if "META-INF/encryption.xml" in archive.namelist():
+                return None
+            container = xml(zip_bytes(archive, "META-INF/container.xml"))
+            package_name = next(
+                node.get("full-path")
+                for node in container.iter()
+                if node.tag.rsplit("}", 1)[-1] == "rootfile"
+            )
+            package = xml(zip_bytes(archive, package_name))
+            cover_ids = {
+                node.get("content")
+                for node in package.iter()
+                if node.tag.rsplit("}", 1)[-1] == "meta" and node.get("name") == "cover"
+            }
+            for node in package.iter():
+                if node.tag.rsplit("}", 1)[-1] != "item":
+                    continue
+                name = local_ref(package_name, node.get("href", ""))
+                if name and Path(name).suffix.lower() in IMAGES:
+                    if (
+                        "cover-image" in node.get("properties", "").split()
+                        or node.get("id") in cover_ids
+                    ):
+                        candidates.insert(0, name)
+                    else:
+                        candidates.append(name)
+        else:
+            candidates = sorted(
+                (
+                    name
+                    for name in archive.namelist()
+                    if Path(name).suffix.lower() in IMAGES
+                    and not name.startswith("__MACOSX/")
+                ),
+                key=natural,
+            )
+        if not candidates:
+            candidates = sorted(
+                (
+                    name
+                    for name in archive.namelist()
+                    if Path(name).suffix.lower() in IMAGES
+                    and not name.startswith("__MACOSX/")
+                ),
+                key=natural,
+            )
+        if not candidates:
+            return None
+        data = zip_bytes(archive, candidates[0], maximum=MAX_ENTRY)
+        mime = image_type(data)
+        kind = {
+            "image/jpeg": ".jpg",
+            "image/png": ".png",
+            "image/webp": ".webp",
+            "image/gif": ".gif",
+            "image/avif": ".avif",
+        }.get(mime)
+        return (data, kind) if kind is not None else None
+
+
+def video_seek_time(path: Path | str, suffix: str, *, remote=False) -> str:
+    """Pick between 40% and 60%; unavailable duration keeps a bounded fallback."""
+    command = [
+        "ffprobe",
+        "-v",
+        "error",
+        "-max_alloc",
+        "67108864",
+        "-protocol_whitelist",
+        "http,tcp" if remote else "file,pipe",
+        "-f",
+        VIDEO_FORMATS[suffix],
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "default=noprint_wrappers=1:nokey=1",
+        "-i",
+        str(path),
+    ]
+    try:
+        result = subprocess.run(  # noqa: S603  # nosec B603
+            command,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            timeout=10 if remote else 1.5,
+            check=False,
+        )
+        duration = float(result.stdout) if result.returncode == 0 else 0
+        if math.isfinite(duration) and duration > 0:
+            return f"{duration * (40 + secrets.randbelow(21)) / 100:.3f}"
+    except OSError, ValueError, subprocess.TimeoutExpired:
+        pass
+    return "10"
+
+
+def render(path: Path, suffix: str, *, remote_url=None, source_size=None) -> bytes:
+    source_name = remote_url or str(path)
+    cover_input = None
+    if suffix in {".epub", ".cbz", ".cbr"} | OFFICE_FORMATS:
+        try:
+            cover = archive_cover(path, suffix)
+        except Exception:
+            return b""
+        if cover is None:
+            return b""
+        cover_input, suffix = cover
+    # Force known demuxers/codecs. A disguised HLS/concat playlist must not turn
+    # an uploaded file into arbitrary file or network reads.
+    if suffix == ".pdf":
+        command = [
+            "pdftoppm",
+            "-f",
+            "1",
+            "-l",
+            "1",
+            "-singlefile",
+            "-scale-to",
+            "320",
+            "-jpeg",
+            "-jpegopt",
+            "quality=70",
+            "-hide-annotations",
+            str(path),
+        ]
+    elif suffix in IMAGE_CODECS or suffix in VIDEO_FORMATS or suffix in AUDIO_FORMATS:
+        command = [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-nostdin",
+            "-threads",
+            "1",
+            "-filter_threads",
+            "1",
+            "-max_alloc",
+            "67108864",
+            "-protocol_whitelist",
+            "http,tcp" if remote_url else "file,pipe",
+        ]
+        if suffix in IMAGE_CODECS:
+            command += ["-f", "image2pipe" if cover_input is not None else "image2"]
+            if cover_input is None:
+                command += ["-pattern_type", "none"]
+            command += ["-c:v", IMAGE_CODECS[suffix]]
+        else:
+            command += ["-f", (VIDEO_FORMATS | AUDIO_FORMATS)[suffix]]
+            if suffix in VIDEO_FORMATS and suffix != ".avif":
+                command += [
+                    "-ss",
+                    video_seek_time(
+                        source_name if remote_url else path,
+                        suffix,
+                        **({"remote": True} if remote_url else {}),
+                    ),
+                ]
+        if (
+            suffix in {".jpg", ".jpeg"}
+            and (
+                len(cover_input)
+                if cover_input is not None
+                else source_size
+                if remote_url
+                else path.stat().st_size
+            )
+            > 8 * 1024**2
+        ):
+            # Decode large JPEGs at one-eighth resolution before scaling; a
+            # full-resolution RGB allocation can exceed the worker's budget.
+            command += ["-lowres", "3"]
+        command += [
+            "-i",
+            "pipe:0" if cover_input is not None else source_name,
+            "-map",
+            "0:v:0",
+            "-frames:v",
+            "1",
+            "-an",
+            "-sn",
+            "-dn",
+            "-vf",
+            "scale=320:320:force_original_aspect_ratio=decrease",
+            "-threads",
+            "1",
+            "-q:v",
+            "6",
+            "-f",
+            "image2pipe",
+            "-c:v",
+            "mjpeg",
+            "pipe:1",
+        ]
+    else:
+        return b""
+    # A costly or damaged seek can time out or emit an incomplete frame even
+    # when decoding the first frame is cheap. Keep that fallback inside the
+    # parent's existing 12-second deadline instead of abandoning the cover.
+    timeouts = (70, 20) if remote_url else (6, 3)
+    for attempt, timeout in enumerate(
+        timeouts if "-ss" in command else ((90,) if remote_url else (8,))
+    ):
+        if attempt:
+            command[command.index("-ss") + 1] = "0"
+        try:
+            # Fixed tool/flags and a resolved staged path; no shell interprets input.
+            result = subprocess.run(  # noqa: S603  # nosec B603
+                command,
+                input=cover_input,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            continue
+        except OSError:
+            return b""
+        data = result.stdout
+        if (
+            result.returncode == 0
+            and 0 < len(data) <= MAX_BYTES
+            and data.startswith(b"\xff\xd8\xff")
+            and data.endswith(b"\xff\xd9")
+        ):
+            return data
+    return b""
+
+
+def main():
+    try:
+        import resource
+
+        resource.setrlimit(
+            resource.RLIMIT_AS, (ADDRESS_SPACE_BYTES, ADDRESS_SPACE_BYTES)
+        )
+        resource.setrlimit(resource.RLIMIT_CPU, (8, 8))
+        resource.setrlimit(resource.RLIMIT_FSIZE, (0, 0))
+    except ImportError:
+        pass
+    # Native tools inherit only a minimal environment, not Telegram credentials.
+    os.environ.clear()
+    os.environ.update(PATH=os.defpath, LANG="C.UTF-8")
+    mode = sys.argv[3] if len(sys.argv) > 3 else ""
+    if mode in {"remote", "background"} and hasattr(os, "nice"):
+        os.nice(10)
+    if mode == "remote":
+        from urllib.parse import urlsplit
+
+        url = urlsplit(sys.argv[1])
+        if (
+            url.scheme != "http"
+            or url.hostname != "127.0.0.1"
+            or not url.port
+            or url.username
+            or url.password
+        ):
+            return
+        sys.stdout.buffer.write(
+            render(
+                Path("remote"),
+                sys.argv[2],
+                remote_url=sys.argv[1],
+                source_size=int(sys.argv[4]),
+            )
+        )
+    else:
+        sys.stdout.buffer.write(render(Path(sys.argv[1]), sys.argv[2]))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tgdrive/media/thumbnails.py b/tgdrive/media/thumbnails.py
new file mode 100644
index 00000000..4bfa06d9
--- /dev/null
+++ b/tgdrive/media/thumbnails.py
@@ -0,0 +1,223 @@
+"""Small provider thumbnails with bounded work, never an original-file preview.
+
+Only payloads (including short-lived misses) are cached. Callers must authorize
+both before entering this cache and after awaiting it; shares/sessions never
+become part of a cache entry.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import time
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from telethon.errors import RPCError
+
+from tgdrive.media.media_metadata import get_message
+from tgdrive.media.media_scheduler import media_priority
+from tgdrive.telegram.client_pool import ClientPoolError
+
+THUMBNAIL_BYTES = 128 * 1024
+THUMBNAIL_DIMENSION = 640
+
+
+class ThumbnailBusy(Exception):
+    """Optional thumbnail work is temporarily unavailable."""
+
+
+@dataclass(frozen=True)
+class Thumbnail:
+    content: bytes
+    media_type: str
+
+    @property
+    def etag(self) -> str:
+        return '"' + hashlib.sha256(self.content).hexdigest() + '"'
+
+
+def image_type(content: bytes) -> str | None:
+    # Never serve an SVG/HTML/document body in an image-shaped endpoint.
+    if content.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if content.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if len(content) >= 12 and content[:4] == b"RIFF" and content[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+async def load_thumbnail(*, pool: Any, channel_id: int, message_id: int):
+    """Use an optional small-image transport; never fall back to stream_media."""
+    priority = media_priority.set("preload")
+    try:
+        async with pool.lease(
+            download=True,
+            allow_users=True,
+            respect_cooldown=True,
+            priority="preload",
+        ) as client:
+            download = getattr(client, "download_thumbnail", None)
+            if not callable(download):
+                return None
+            message = await get_message(client, channel_id, message_id)
+            if message is None or getattr(message, "empty", False):
+                return None
+            content = await download(
+                message,
+                max_bytes=THUMBNAIL_BYTES,
+                target_size=320,
+                max_dimension=THUMBNAIL_DIMENSION,
+            )
+            if (
+                not isinstance(content, bytes)
+                or not 0 < len(content) <= THUMBNAIL_BYTES
+            ):
+                return None
+            media_type = image_type(content)
+            return Thumbnail(content, media_type) if media_type else None
+    except (OSError, RPCError, ClientPoolError, ValueError) as exc:
+        raise ThumbnailBusy from exc
+    finally:
+        media_priority.reset(priority)
+
+
+@dataclass
+class _Flight:
+    task: asyncio.Task[Thumbnail | None]
+    waiters: int = 0
+    abandoned: bool = False
+
+
+class ThumbnailCache:
+    """Per-app LRU, two fills, bounded pending work, and concurrent coalescing."""
+
+    def __init__(
+        self,
+        *,
+        max_bytes: int = 16 * 1024**2,
+        max_entries: int = 256,
+        max_pending: int = 16,
+        timeout: float = 10,
+        ttl: float = 3600,
+        missing_ttl: float = 300,
+    ) -> None:
+        self.max_bytes = max_bytes
+        self.max_entries = max_entries
+        self.max_pending = max_pending
+        self.timeout = timeout
+        self.ttl = ttl
+        self.missing_ttl = missing_ttl
+        self.bytes = 0
+        self._entries: OrderedDict[
+            tuple[Any, ...], tuple[float, Thumbnail | None, Any]
+        ] = OrderedDict()
+        self._flights: dict[tuple[Any, ...], _Flight] = {}
+        self._slots = asyncio.Semaphore(2)
+        self._closed = False
+
+    async def get(
+        self,
+        key: tuple[Any, ...],
+        load: Callable[[], Awaitable[Thumbnail | None]],
+        *,
+        missing_revision: Any = None,
+    ) -> Thumbnail | None:
+        if self._closed:
+            raise ThumbnailBusy
+        self._expire()
+        cached = self._entries.get(key)
+        if cached is not None:
+            if cached[1] is not None or cached[2] == missing_revision:
+                self._entries.move_to_end(key)
+                return cached[1]
+            self._entries.pop(key)
+        flight = self._flights.get(key)
+        while flight is not None and flight.abandoned:
+            await asyncio.gather(flight.task, return_exceptions=True)
+            if self._flights.get(key) is flight:
+                self._flights.pop(key, None)
+            flight = self._flights.get(key)
+        if self._closed:
+            raise ThumbnailBusy
+        if flight is None:
+            if len(self._flights) >= self.max_pending:
+                raise ThumbnailBusy
+            flight = _Flight(
+                asyncio.create_task(self._fill(key, load, missing_revision))
+            )
+            self._flights[key] = flight
+        flight.waiters += 1
+        try:
+            return await asyncio.shield(flight.task)
+        finally:
+            flight.waiters -= 1
+            if not flight.waiters and not flight.task.done():
+                flight.abandoned = True
+                flight.task.cancel()
+                await asyncio.gather(flight.task, return_exceptions=True)
+            if flight.task.done() and self._flights.get(key) is flight:
+                self._flights.pop(key, None)
+
+    async def _fill(self, key, load, missing_revision):
+        try:
+            async with asyncio.timeout(self.timeout):
+                async with self._slots:
+                    result = await load()
+        except TimeoutError as exc:
+            raise ThumbnailBusy from exc
+        # The transport and test/custom adapters both stay under the same cap.
+        if result is not None and len(result.content) > THUMBNAIL_BYTES:
+            result = None
+        if result is not None and len(result.content) > self.max_bytes:
+            return result
+        self._expire()
+        self._entries[key] = (
+            time.monotonic() + (self.ttl if result is not None else self.missing_ttl),
+            result,
+            missing_revision,
+        )
+        self.bytes += len(result.content) if result is not None else 0
+        while self.bytes > self.max_bytes or len(self._entries) > self.max_entries:
+            _key, (_deadline, value, _revision) = self._entries.popitem(last=False)
+            self.bytes -= len(value.content) if value is not None else 0
+        return result
+
+    def _expire(self):
+        now = time.monotonic()
+        for key, (deadline, value, _revision) in list(self._entries.items()):
+            if deadline <= now:
+                del self._entries[key]
+                self.bytes -= len(value.content) if value is not None else 0
+
+    async def invalidate_file(self, channel: int, message: int):
+        keys = {
+            key
+            for key in (*self._entries, *self._flights)
+            if key[:2] == (channel, message)
+        }
+        tasks = []
+        for key in keys:
+            flight = self._flights.get(key)
+            if flight is not None:
+                flight.task.cancel()
+                tasks.append(flight.task)
+            cached = self._entries.pop(key, None)
+            if cached is not None and cached[1] is not None:
+                self.bytes -= len(cached[1].content)
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    async def close(self):
+        self._closed = True
+        tasks = [flight.task for flight in self._flights.values()]
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        self._flights.clear()
+        self._entries.clear()
+        self.bytes = 0
diff --git a/tgdrive/observability/__init__.py b/tgdrive/observability/__init__.py
new file mode 100644
index 00000000..49fc7f61
--- /dev/null
+++ b/tgdrive/observability/__init__.py
@@ -0,0 +1 @@
+"""Traffic accounting, resource metrics, and performance history."""
diff --git a/tgdrive/observability/performance_api.py b/tgdrive/observability/performance_api.py
new file mode 100644
index 00000000..53c1e0cc
--- /dev/null
+++ b/tgdrive/observability/performance_api.py
@@ -0,0 +1,235 @@
+"""Authenticated controls for disposable media storage and origin capacity."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import resource
+import shutil
+import time
+from pathlib import Path
+from typing import Any
+
+from fastapi import Depends, HTTPException, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from tgdrive.settings.performance_preferences import get_performance_settings
+
+
+class PrepareFile(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    path: str = Field(min_length=1, max_length=4096)
+
+
+class ClearCache(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    file_id: str | None = Field(default=None, min_length=1, max_length=128)
+
+
+def system_snapshot(settings):
+    try:
+        usage = shutil.disk_usage(settings.resolved_data_dir)
+        disk = {
+            "available": True,
+            "total_bytes": usage.total,
+            "free_bytes": usage.free,
+            "used_bytes": usage.used,
+        }
+    except OSError:
+        disk = {"available": False, "total_bytes": 0, "free_bytes": 0, "used_bytes": 0}
+    memory = {}
+    try:
+        for line in Path("/proc/meminfo").read_text().splitlines():
+            name, value = line.split(":", 1)
+            if name in {"MemTotal", "MemAvailable"}:
+                memory[name] = int(value.strip().split()[0]) * 1024
+    except OSError, ValueError:
+        pass
+    # Container limits matter more than host-wide free memory.
+    for name, filename in (
+        ("cgroup_limit", "memory.max"),
+        ("cgroup_current", "memory.current"),
+    ):
+        try:
+            raw = (Path("/sys/fs/cgroup") / filename).read_text().strip()
+            memory[name] = int(raw) if raw != "max" else None
+        except OSError, ValueError:
+            pass
+    try:
+        load = list(os.getloadavg())
+    except OSError, AttributeError:
+        load = []
+    current_rss = None
+    try:
+        for line in Path("/proc/self/status").read_text().splitlines():
+            if line.startswith("VmRSS:"):
+                current_rss = int(line.split()[1]) * 1024
+                break
+    except OSError, ValueError, IndexError:
+        pass
+    return {
+        "at": time.time(),
+        "memory": memory,
+        "process_rss_bytes": current_rss,
+        "cpu_count": os.cpu_count(),
+        "process_peak_rss_bytes": resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        * 1024,
+        "load_average": load,
+        "disk": disk,
+        "staging_budget_bytes": settings.staging_budget_bytes,
+    }
+
+
+def register_performance_routes(
+    app, settings, *, require_admin, get_runtime, get_store
+):
+    admin = [Depends(require_admin)]
+
+    async def service(request):
+        value = get_performance_settings(settings, get_runtime(request))
+        await value.initialize()
+        return value
+
+    def response(value, **headers):
+        return JSONResponse(value, headers={"Cache-Control": "no-store", **headers})
+
+    def media_manager(request):
+        manager = getattr(get_runtime(request), "preloads", None)
+        if manager is None:
+            raise HTTPException(503, "Media storage is not available yet")
+        return manager
+
+    @app.get("/api/v1/settings/performance", dependencies=admin)
+    async def preferences(request: Request):
+        value = await service(request)
+        return response(await value.snapshot(), ETag=value.etag())
+
+    @app.patch("/api/v1/settings/performance", dependencies=admin)
+    async def update_preferences(request: Request, changes: dict[str, Any]):
+        value = await service(request)
+        try:
+            result = await value.save(changes, expected=request.headers.get("if-match"))
+        except ValidationError:
+            raise HTTPException(
+                422, "Invalid performance settings. Check values and supported limits."
+            ) from None
+        return response(result, ETag=value.etag())
+
+    @app.get("/api/v1/preloads", dependencies=admin)
+    async def preloads(request: Request):
+        await service(request)
+        return response(await media_manager(request).snapshot())
+
+    @app.post("/api/v1/preloads", dependencies=admin, status_code=202)
+    async def prepare(payload: PrepareFile, request: Request):
+        await service(request)
+        store, runtime = get_store(request), get_runtime(request)
+        manager = media_manager(request)
+        path = store.resolve_id(payload.path.rstrip("/").rsplit("/", 1)[-1])
+        data = store.get_file(path)
+
+        async def authorize():
+            # Deletion, trash and recovery must stop background work too.
+            if getattr(getattr(runtime, "backup", None), "recovery_required", False):
+                raise HTTPException(409, "Drive recovery is required")
+            current = await asyncio.to_thread(
+                store.get_file, store.resolve_id(data["id"]) if "id" in data else path
+            )
+            if any(
+                current.get(key) != data.get(key)
+                for key in ("message_id", "size", "parts")
+            ):
+                raise HTTPException(
+                    409, "The file changed during preparation; request the new version"
+                )
+
+        try:
+            job = await manager.prepare(
+                channel_id=settings.storage_channel,
+                message_id=data["message_id"],
+                size=data["size"],
+                name=data["name"],
+                parts=data.get("parts"),
+                authorize=authorize,
+            )
+        except ValueError as exc:
+            raise HTTPException(409, str(exc)) from None
+        return JSONResponse(job, status_code=202, headers={"Cache-Control": "no-store"})
+
+    @app.post("/api/v1/preloads/clear", dependencies=admin)
+    async def clear(payload: ClearCache, request: Request):
+        await service(request)
+        await media_manager(request).clear(payload.file_id)
+        return response({"status": "ok"})
+
+    @app.post("/api/v1/preloads/{job_id}/cancel", dependencies=admin)
+    async def cancel(job_id: str, request: Request):
+        await service(request)
+        try:
+            await media_manager(request).cancel(job_id)
+        except KeyError:
+            raise HTTPException(404, "Preload job not found") from None
+        return response({"status": "ok"})
+
+    @app.get("/api/v1/performance", dependencies=admin)
+    async def performance(request: Request):
+        value = await service(request)
+        runtime, store = get_runtime(request), get_store(request)
+        pool = getattr(runtime, "pool", None)
+        snapshot = getattr(pool, "performance_snapshot", None)
+        cache = getattr(pool, "_media_read_cache", None)
+        statistics = getattr(store, "statistics", None)
+        drive = await asyncio.to_thread(statistics) if callable(statistics) else {}
+        return response(
+            {
+                "telegram": snapshot() if callable(snapshot) else {},
+                "cache": await cache.snapshot()
+                if cache is not None
+                else {
+                    "policy": value.value.cache_policy().as_dict(),
+                    "memory": {
+                        "bytes": 0,
+                        "max_bytes": value.value.cache_memory_bytes,
+                        "effective_max_bytes": 0,
+                        "entries": 0,
+                        "hits": 0,
+                        "misses": 0,
+                    },
+                    "disk": {
+                        "available": False,
+                        "bytes": 0,
+                        "max_bytes": value.value.cache_disk_bytes,
+                    },
+                    "files": [],
+                    "pending_writes": 0,
+                },
+                "server": (await asyncio.to_thread(system_snapshot, settings))
+                | request.app.state.traffic.resources.value,
+                "drive": drive,
+                "traffic": request.app.state.traffic.snapshot(),
+                "history_scope": (
+                    "Last 5 minutes; sampled every 3 seconds; resets on restart."
+                ),
+            }
+        )
+
+    @app.get("/api/v1/performance/history", dependencies=admin)
+    async def performance_history(request: Request, start: float, end: float):
+        from tgdrive.observability.telemetry_history import validate_range
+
+        try:
+            validate_range(start, end)
+        except ValueError as exc:
+            raise HTTPException(422, str(exc)) from None
+        try:
+            result = await asyncio.to_thread(
+                request.app.state.telemetry_history.query, start, end
+            )
+        except ValueError as exc:
+            raise HTTPException(422, str(exc)) from None
+        except Exception:
+            raise HTTPException(
+                503, "Performance history is temporarily unavailable. Try again."
+            ) from None
+        return response(result)
diff --git a/tgdrive/observability/resource_metrics.py b/tgdrive/observability/resource_metrics.py
new file mode 100644
index 00000000..0916f2fc
--- /dev/null
+++ b/tgdrive/observability/resource_metrics.py
@@ -0,0 +1,177 @@
+"""Sample Linux CPU and interface counters without optional monitoring services."""
+
+from __future__ import annotations
+
+import os
+import time
+from collections import deque
+from pathlib import Path
+
+from tgdrive.observability.traffic import HISTORY_SECONDS, MAX_SAMPLE_GAP_SECONDS
+
+
+class ResourceMetrics:
+    def __init__(self, *, proc=Path("/proc"), cgroup=Path("/sys/fs/cgroup")):
+        self.proc, self.cgroup = proc, cgroup
+        self.started_at = time.time()
+        self._cpu_previous = None
+        self._network_previous = None
+        self._received = self._sent = 0
+        self.history = deque(maxlen=120)
+        self.value = {"cpu": {"percent": None}, "network": {"available": False}}
+
+    def _cpu_counter(self):
+        try:
+            capacity = float(os.cpu_count() or 1)
+            if hasattr(os, "sched_getaffinity"):
+                capacity = min(capacity, len(os.sched_getaffinity(0)))
+            quota, period = (self.cgroup / "cpu.max").read_text().split()
+            if quota != "max":
+                capacity = min(capacity, int(quota) / int(period))
+            stats = dict(
+                line.split()
+                for line in (self.cgroup / "cpu.stat").read_text().splitlines()
+            )
+            return "cgroup", int(stats["usage_usec"]) / 1_000_000, capacity
+        except OSError, ValueError, KeyError, ZeroDivisionError:
+            pass
+        try:
+            counters = [
+                int(value)
+                for value in (self.proc / "stat")
+                .read_text()
+                .splitlines()[0]
+                .split()[1:9]
+            ]
+            if len(counters) < 4:
+                return None
+            idle = counters[3] + (counters[4] if len(counters) > 4 else 0)
+            return "host", sum(counters) - idle, sum(counters)
+        except OSError, ValueError, IndexError:
+            return None
+
+    def _network_counter(self):
+        try:
+            interfaces = {}
+            for line in (self.proc / "net/dev").read_text().splitlines():
+                if ":" not in line:
+                    continue
+                name, values = line.split(":", 1)
+                fields = values.split()
+                if name.strip() != "lo" and len(fields) >= 9:
+                    interfaces[name.strip()] = (int(fields[0]), int(fields[8]))
+            routes = []
+            try:
+                for line in (self.proc / "net/route").read_text().splitlines()[1:]:
+                    fields = line.split()
+                    if (
+                        len(fields) >= 8
+                        and fields[1] == "00000000"
+                        and int(fields[3], 16) & 1
+                    ):
+                        routes.append((int(fields[6]), fields[0]))
+            except OSError:
+                pass
+            try:
+                for line in (self.proc / "net/ipv6_route").read_text().splitlines():
+                    fields = line.split()
+                    if (
+                        len(fields) >= 10
+                        and fields[0] == "0" * 32
+                        and fields[1] == "00"
+                    ):
+                        routes.append((int(fields[5], 16), fields[-1]))
+            except OSError:
+                pass
+            eligible = sorted(route for route in routes if route[1] in interfaces)
+            interface = (
+                eligible[0][1]
+                if eligible
+                else next(iter(interfaces))
+                if len(interfaces) == 1
+                else None
+            )
+            return (interface, *interfaces[interface]) if interface else None
+        except OSError, ValueError, IndexError:
+            return None
+
+    def sample(self):
+        now = time.monotonic()
+        cpu = self._cpu_counter()
+        percent = None
+        if cpu is not None and self._cpu_previous is not None:
+            previous_at, previous = self._cpu_previous
+            elapsed = now - previous_at
+            if cpu[0] == previous[0] and 0 < elapsed <= MAX_SAMPLE_GAP_SECONDS:
+                denominator = (
+                    elapsed * cpu[2] if cpu[0] == "cgroup" else cpu[2] - previous[2]
+                )
+                delta = cpu[1] - previous[1]
+                if denominator > 0 and delta >= 0:
+                    percent = min(100.0, 100 * delta / denominator)
+        self._cpu_previous = (now, cpu) if cpu is not None else None
+        cpu_value = {"percent": percent, "scope": cpu[0] if cpu else None}
+        if cpu is not None and cpu[0] == "cgroup":
+            cpu_value["capacity_cores"] = cpu[2]
+        network = self._network_counter()
+        incoming = outgoing = None
+        if network is not None and self._network_previous is not None:
+            previous_at, previous = self._network_previous
+            elapsed = now - previous_at
+            if network[0] == previous[0]:
+                received, sent = network[1] - previous[1], network[2] - previous[2]
+                if received >= 0 and sent >= 0:
+                    self._received += received
+                    self._sent += sent
+                    if 0 < elapsed <= MAX_SAMPLE_GAP_SECONDS:
+                        incoming, outgoing = received / elapsed, sent / elapsed
+        self._network_previous = (now, network) if network is not None else None
+        self.value = {
+            "cpu": cpu_value,
+            "network": {
+                "available": network is not None,
+                "interface": network[0] if network else None,
+                "started_at": self.started_at,
+                "received_bytes": self._received,
+                "sent_bytes": self._sent,
+                "received_bytes_per_second": incoming,
+                "sent_bytes_per_second": outgoing,
+                "scope": (
+                    "Default network interface; includes URL imports, "
+                    "Telegram and HTTP traffic."
+                ),
+            },
+        }
+        # Keep measured history even when nobody has the dashboard open. Reading
+        # the cgroup files here avoids polling the whole system/disk each tick.
+        memory = {}
+        for key, filename in (
+            ("memory_bytes", "memory.current"),
+            ("memory_limit_bytes", "memory.max"),
+        ):
+            try:
+                raw = (self.cgroup / filename).read_text().strip()
+                memory[key] = int(raw) if raw != "max" else None
+            except OSError, ValueError:
+                memory[key] = None
+        at = time.time()
+        if (
+            self.history
+            and not 0 <= at - self.history[-1]["at"] <= MAX_SAMPLE_GAP_SECONDS
+        ):
+            self.history.clear()
+        while self.history and self.history[0]["at"] < at - HISTORY_SECONDS:
+            self.history.popleft()
+        self.history.append(
+            {
+                "at": at,
+                "cpu_percent": percent,
+                "cpu_scope": cpu_value["scope"],
+                **memory,
+                "received_bytes_per_second": incoming,
+                "sent_bytes_per_second": outgoing,
+                "network_interface": network[0] if network else None,
+            }
+        )
+        self.value = self.value | {"history": list(self.history)}
+        return self.value
diff --git a/tgdrive/observability/telemetry_history.py b/tgdrive/observability/telemetry_history.py
new file mode 100644
index 00000000..ac8f9164
--- /dev/null
+++ b/tgdrive/observability/telemetry_history.py
@@ -0,0 +1,352 @@
+"""Disposable, bounded telemetry history; never a source of drive metadata.
+
+Three-second observations are reduced to time-weighted minute aggregates. The
+configured MongoDB stores history.
+No credentials, filenames, account names or request identifiers are persisted.
+"""
+
+from __future__ import annotations
+
+import math
+import threading
+import time
+from pathlib import Path
+
+RETENTION_SECONDS = 31 * 86400
+MAX_POINTS = 360
+METRICS = (
+    "cpu_percent",
+    "memory_bytes",
+    "received_bytes_per_second",
+    "sent_bytes_per_second",
+)
+TOTALS = (
+    "network_received_bytes",
+    "network_sent_bytes",
+    "http_upload_bytes",
+    "http_download_bytes",
+    "http_requests",
+    "http_errors",
+    "telegram_upload_bytes",
+    "telegram_download_bytes",
+)
+
+
+def number(value):
+    return (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+        and value >= 0
+    )
+
+
+def validate_range(start, end, *, now=None):
+    now = time.time() if now is None else now
+    if (
+        not number(start)
+        or not number(end)
+        or start >= end
+        or start >= now
+        or end > now + 60
+        or end - start > RETENTION_SECONDS
+        or start < now - RETENTION_SECONDS - 60
+    ):
+        raise ValueError("Choose a past interval within the last 31 days.")
+    return float(start), min(float(end), now)
+
+
+class HistoryStorage:
+    """All methods run off the event loop, serialized by TelemetryHistory."""
+
+    def __init__(self, directory: Path):
+        self.directory = directory
+        self.mongo = None
+        self.ready = False
+
+    def initialize(self):
+        if self.ready:
+            return
+        from tgdrive.storage.mongo import DatabaseUnavailable, for_directory
+
+        self.mongo = for_directory(self.directory)
+        if self.mongo is None:
+            raise DatabaseUnavailable("MongoDB is required for telemetry history.")
+        self.mongo.db.telemetry_minutes.create_index("at")
+        self.ready = True
+
+    def load(self, minute):
+        self.initialize()
+        state = self.mongo.db.telemetry_state.find_one({"_id": "lifetime"})
+        current = self.mongo.db.telemetry_minutes.find_one({"_id": minute})
+        return state, current
+
+    def write(self, rows, state, cutoff):
+        self.initialize()
+        # Absolute replacements make a retry idempotent, including an unknown
+        # write outcome. The lifetime checkpoint is never incremented twice.
+        from pymongo import ReplaceOne
+
+        if rows:
+            self.mongo.db.telemetry_minutes.bulk_write(
+                [ReplaceOne({"_id": r["at"]}, r, upsert=True) for r in rows],
+                ordered=False,
+            )
+        self.mongo.db.telemetry_state.replace_one(
+            {"_id": "lifetime"}, state, upsert=True
+        )
+        self.mongo.db.telemetry_minutes.delete_many({"at": {"$lt": cutoff}})
+
+    def read(self, start, end):
+        self.initialize()
+        return list(
+            self.mongo.db.telemetry_minutes.find(
+                {"at": {"$gte": math.floor(start / 60) * 60, "$lt": end}}
+            )
+            .sort("at", 1)
+            .limit(31 * 1440 + 2)
+        )
+
+    def earliest(self):
+        self.initialize()
+        row = self.mongo.db.telemetry_minutes.find_one({}, sort=[("at", 1)])
+        return row["first"] if row else None
+
+
+class TelemetryHistory:
+    def __init__(self, directory: Path, *, storage=None):
+        self.storage = storage or HistoryStorage(directory)
+        self._lock = threading.RLock()
+        self._ready = False
+        self._minutes = {}
+        self._previous = None
+        self._baselines = {}
+        self._totals = dict.fromkeys(TOTALS, None)
+        self._tracked_since = None
+        self._updated_at = None
+        self._last_flush = 0.0
+        self._highest_at = 0
+
+    @property
+    def initialized(self):
+        return self._ready
+
+    def _initialize(self, now):
+        if self._ready:
+            return
+        state, minute = self.storage.load(math.floor(now / 60) * 60)
+        if state:
+            self._tracked_since = state.get("tracked_since")
+            self._updated_at = state.get("last_updated")
+            self._totals.update(
+                {k: v for k, v in state.get("totals", {}).items() if k in TOTALS}
+            )
+        if minute:
+            self._minutes[minute["at"]] = minute
+            self._highest_at = minute["last"]
+        self._ready = True
+
+    def _count(self, key, source, current):
+        if not number(current):
+            return
+        identity = (key, source)
+        # Refresh insertion order so replacing many connections cannot evict a
+        # still-active account and count its cumulative bytes a second time.
+        previous = self._baselines.pop(identity, 0)
+        self._baselines[identity] = current
+        delta = current - previous if current >= previous else current
+        self._totals[key] = (self._totals[key] or 0) + delta
+        # Replacement connections do not grow monitoring memory indefinitely.
+        if len(self._baselines) > 512:
+            self._baselines.pop(next(iter(self._baselines)))
+
+    def observe(self, sample, traffic, telegram=None, *, sources=None, now=None):
+        """Consume one actual sample, including counters once, on a worker thread."""
+        now = sample["at"] if now is None else now
+        if not number(now):
+            return
+        with self._lock:
+            self._initialize(now)
+            self._tracked_since = self._tracked_since or now
+            self._updated_at = now
+            network = traffic.get("network", {})
+            for key, source in (
+                (
+                    "network_received_bytes",
+                    network.get("received_bytes")
+                    if network.get("available", True)
+                    else None,
+                ),
+                (
+                    "network_sent_bytes",
+                    network.get("sent_bytes")
+                    if network.get("available", True)
+                    else None,
+                ),
+                ("http_upload_bytes", traffic.get("upload_bytes")),
+                ("http_download_bytes", traffic.get("download_bytes")),
+                ("http_requests", traffic.get("requests")),
+                ("http_errors", traffic.get("errors")),
+            ):
+                self._count(key, "process", source)
+            for account in (telegram or {}).get("accounts", []):
+                account_requests = account.get("requests") or {}
+                identity = (sources or {}).get(account["name"], account["name"])
+                for direction in ("upload", "download"):
+                    self._count(
+                        f"telegram_{direction}_bytes",
+                        identity,
+                        account_requests.get(direction + "_bytes"),
+                    )
+            previous = self._previous
+            if (
+                previous
+                and previous["at"] >= self._highest_at
+                and 0 < now - previous["at"] <= 30
+            ):
+                self._accumulate(previous, sample)
+            # A suspension, restart or clock reversal starts a fresh interval.
+            self._previous = dict(sample)
+            self._highest_at = max(self._highest_at, now)
+            # Bound RAM when the metrics database is unavailable for hours.
+            while len(self._minutes) > 120:
+                del self._minutes[min(self._minutes)]
+
+    def _accumulate(self, previous, sample):
+        start, end = previous["at"], sample["at"]
+        while start < end:
+            minute = math.floor(start / 60) * 60
+            stop = min(end, minute + 60)
+            seconds = stop - start
+            row = self._minutes.setdefault(
+                minute,
+                {
+                    "at": minute,
+                    "values": {},
+                    "sources": {},
+                    "first": start,
+                    "last": stop,
+                },
+            )
+            row["first"], row["last"] = min(row["first"], start), max(row["last"], stop)
+            for key in METRICS:
+                value = sample.get(key)
+                source_key = (
+                    "cpu_scope"
+                    if key == "cpu_percent"
+                    else "network_interface"
+                    if key.endswith("per_second")
+                    else "memory_limit_bytes"
+                )
+                source = sample.get(source_key)
+                if key != "memory_bytes" and source != previous.get(source_key):
+                    continue
+                if not number(value):
+                    continue
+                weighted = row["values"].setdefault(key, [0.0, 0.0])
+                weighted[0] += value * seconds
+                weighted[1] += seconds
+                if source_key not in row["sources"]:
+                    row["sources"][source_key] = source
+                elif row["sources"][source_key] != source:
+                    row["sources"][source_key] = "mixed"
+            start = stop
+
+    def flush(self, *, force=False, now=None):
+        now = time.time() if now is None else now
+        with self._lock:
+            self._initialize(now)
+            monotonic = time.monotonic()
+            if not force and monotonic - self._last_flush < 60:
+                return
+            # Back off even on failure; file service does not wait on diagnostics.
+            self._last_flush = monotonic
+            state = {
+                "tracked_since": self._tracked_since,
+                "last_updated": self._updated_at,
+                "totals": self._totals,
+            }
+            self.storage.write(
+                list(self._minutes.values()),
+                state,
+                math.floor((now - RETENTION_SECONDS) / 60) * 60,
+            )
+            current = math.floor(now / 60) * 60
+            self._minutes = {k: v for k, v in self._minutes.items() if k >= current}
+
+    def query(self, start, end, *, now=None):
+        now = time.time() if now is None else now
+        start, end = validate_range(start, end, now=now)
+        with self._lock:
+            self._initialize(now)
+            # Historical data is deliberately minute-granular. Return the actual
+            # boundary minutes rather than pretending to resolve individual seconds.
+            start = math.floor(start / 60) * 60
+            end = min(math.ceil(end / 60) * 60, now)
+            rows = {row["at"]: row for row in self.storage.read(start, end)}
+            rows.update(
+                {k: v for k, v in self._minutes.items() if k < end and k + 60 > start}
+            )
+            bucket = max(60, math.ceil((end - start) / MAX_POINTS / 60) * 60)
+            accumulators = [({}, {}) for _ in range(math.ceil((end - start) / bucket))]
+            for row in rows.values():
+                index = int((row["at"] - start) // bucket)
+                if not 0 <= index < len(accumulators):
+                    continue
+                values, source_sets = accumulators[index]
+                for key, (total, seconds) in row["values"].items():
+                    pair = values.setdefault(key, [0.0, 0.0])
+                    pair[0] += total
+                    pair[1] += seconds
+                for key, source in row["sources"].items():
+                    source_sets.setdefault(key, set()).add(source)
+            points = []
+            # Anchor to the requested interval so the result never exceeds 360.
+            for index in range(math.ceil((end - start) / bucket)):
+                at, stop = (
+                    start + index * bucket,
+                    min(end, start + (index + 1) * bucket),
+                )
+                values, source_sets = accumulators[index]
+                point = {"at": at, "end_at": stop, "coverage_seconds": {}}
+                for key in ("cpu_scope", "network_interface", "memory_limit_bytes"):
+                    sources = source_sets.get(key, set())
+                    point[key] = (
+                        next(iter(sources))
+                        if len(sources) == 1 and "mixed" not in sources
+                        else None
+                    )
+                for key in METRICS:
+                    total, seconds = values.get(key, (0, 0))
+                    valid = seconds > 0 and (
+                        key == "memory_bytes"
+                        or point[
+                            "cpu_scope" if key == "cpu_percent" else "network_interface"
+                        ]
+                        is not None
+                    )
+                    point[key] = total / seconds if valid else None
+                    point["coverage_seconds"][key] = seconds if valid else 0
+                points.append(point)
+            return {
+                "available": True,
+                "start": start,
+                "end": end,
+                "bucket_seconds": bucket,
+                "retention_seconds": RETENTION_SECONDS,
+                "earliest_at": min(
+                    (
+                        value
+                        for value in [
+                            self.storage.earliest(),
+                            *(r["first"] for r in self._minutes.values()),
+                        ]
+                        if value is not None
+                    ),
+                    default=None,
+                ),
+                "tracked_since": self._tracked_since,
+                "last_updated": self._updated_at,
+                "totals": dict(self._totals),
+                "samples": points,
+            }
diff --git a/tgdrive/observability/traffic.py b/tgdrive/observability/traffic.py
new file mode 100644
index 00000000..b3152bc2
--- /dev/null
+++ b/tgdrive/observability/traffic.py
@@ -0,0 +1,162 @@
+"""Bounded process counters for delivered HTTP bytes, separate from origin traffic."""
+
+import asyncio
+import logging
+import time
+from collections import deque
+
+logger = logging.getLogger(__name__)
+HISTORY_SECONDS = 300
+MAX_SAMPLE_GAP_SECONDS = 30
+
+
+class TrafficCounters:
+    def __init__(self):
+        from tgdrive.observability.resource_metrics import ResourceMetrics
+
+        self.resources = ResourceMetrics()
+        self.started_at = time.time()
+        self.requests = 0
+        self.active = 0
+        self.download_bytes = 0
+        self.upload_bytes = 0
+        self.errors = 0
+        self.history = deque(maxlen=120)
+        self._last_sample = 0
+
+    def snapshot(self):
+        now = time.time()
+        current = {
+            "at": now,
+            "requests": self.requests,
+            "active": self.active,
+            "download_bytes": self.download_bytes,
+            "upload_bytes": self.upload_bytes,
+            "errors": self.errors,
+        }
+        # Never draw a continuous rate across a suspended process or wall-clock jump.
+        if (
+            self.history
+            and not 0 <= now - self.history[-1]["at"] <= MAX_SAMPLE_GAP_SECONDS
+        ):
+            self.history.clear()
+            self._last_sample = 0
+        while self.history and self.history[0]["at"] < now - HISTORY_SECONDS:
+            self.history.popleft()
+        previous = self.history[-1] if self.history else None
+        if previous is not None and now - previous["at"] < 1:
+            previous = self.history[-2] if len(self.history) > 1 else None
+        seconds = now - previous["at"] if previous else 0
+        rates = {
+            name + "_per_second": (
+                max(0, current[name] - previous[name]) / seconds
+                if previous is not None and seconds > 0
+                else None
+            )
+            for name in ("download_bytes", "upload_bytes")
+        }
+        if now - self._last_sample >= 1:
+            self._last_sample = now
+            self.history.append(current)
+        return (
+            current
+            | rates
+            | {
+                "started_at": self.started_at,
+                "history": list(self.history),
+                "history_window_seconds": HISTORY_SECONDS,
+            }
+        )
+
+
+async def sample_performance(counters, pool, *, interval=3, history=None):
+    """Keep recent history without a dashboard; local resource reads use a thread."""
+    retry_history_at = 0
+    while True:
+        try:
+            await asyncio.to_thread(counters.resources.sample)
+        except Exception:
+            logger.exception("Could not sample server resources")
+        counters.snapshot()
+        snapshot = getattr(pool, "performance_snapshot", None)
+        telegram = None
+        if callable(snapshot):
+            try:
+                telegram = snapshot()
+            except Exception:
+                # Diagnostics must not interrupt file service or terminate sampling.
+                logger.exception("Could not sample Telegram activity")
+        if history is not None and (
+            history.initialized or time.monotonic() >= retry_history_at
+        ):
+            try:
+                await checkpoint_history(counters, pool, history, telegram=telegram)
+            except Exception:
+                retry_history_at = time.monotonic() + 60
+                logger.exception("Could not checkpoint performance history")
+        await asyncio.sleep(interval)
+
+
+async def checkpoint_history(counters, pool, history, *, telegram=None, force=False):
+    samples = counters.resources.value.get("history", [])
+    if samples:
+        # Counter identities stay process-local, never names in persisted metrics.
+        sources = {
+            slot.name: id(getattr(slot.client, "_media_scheduler", slot.client))
+            for slot in getattr(pool, "_slots", [])
+        }
+        snapshot = getattr(pool, "performance_snapshot", None)
+        if telegram is None and callable(snapshot):
+            try:
+                telegram = snapshot()
+            except Exception:
+                # Broken origin diagnostics must not discard HTTP/server history.
+                logger.exception("Could not checkpoint Telegram counters")
+        await asyncio.to_thread(
+            history.observe,
+            samples[-1],
+            counters.snapshot()
+            | {"network": counters.resources.value.get("network", {})},
+            telegram,
+            sources=sources,
+        )
+    await asyncio.to_thread(history.flush, force=force)
+
+
+class TrafficMiddleware:
+    def __init__(self, app, counters):
+        self.app, self.counters = app, counters
+
+    async def __call__(self, scope, receive, send):
+        path = scope.get("path", "")
+        tracked = scope["type"] == "http" and (
+            path == "/file" or path.startswith("/api/v1/uploads")
+        )
+        if not tracked:
+            return await self.app(scope, receive, send)
+        self.counters.active += 1
+        self.counters.requests += 1
+        failed = False
+
+        async def read():
+            message = await receive()
+            if message["type"] == "http.request":
+                self.counters.upload_bytes += len(message.get("body", b""))
+            return message
+
+        async def write(message):
+            nonlocal failed
+            if message["type"] == "http.response.start" and message["status"] >= 400:
+                failed = True
+            await send(message)
+            if message["type"] == "http.response.body":
+                self.counters.download_bytes += len(message.get("body", b""))
+
+        try:
+            await self.app(scope, read, write)
+        except BaseException:
+            failed = True
+            raise
+        finally:
+            self.counters.active -= 1
+            self.counters.errors += int(failed)
diff --git a/tgdrive/recovery/__init__.py b/tgdrive/recovery/__init__.py
new file mode 100644
index 00000000..a5dbde0b
--- /dev/null
+++ b/tgdrive/recovery/__init__.py
@@ -0,0 +1 @@
+"""Database protection, recovery checkpoints, and restore operations."""
diff --git a/tgdrive/recovery/backup.py b/tgdrive/recovery/backup.py
new file mode 100644
index 00000000..a999cb53
--- /dev/null
+++ b/tgdrive/recovery/backup.py
@@ -0,0 +1,40 @@
+"""Shared backup errors and bounded portable recovery JSON decoding."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from tgdrive.storage.store import MAX_STORE_BYTES
+
+
+class BackupError(RuntimeError):
+    """A checkpoint or explicit restore failed; retry timing contains no credentials."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class RecoveryConflict(BackupError):
+    """Local metadata cannot safely mutate the configured remote drive."""
+
+    code = "RECOVERY_REQUIRED"
+
+
+def decode_catalog_snapshot(content: bytes) -> object:
+    if len(content) > MAX_STORE_BYTES:
+        raise BackupError("metadata backup exceeds the safe size limit")
+
+    def unique_pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise BackupError("metadata backup contains duplicate JSON keys")
+            result[key] = value
+        return result
+
+    try:
+        return json.loads(content.decode("utf-8"), object_pairs_hook=unique_pairs)
+    except (UnicodeDecodeError, ValueError, RecursionError) as exc:
+        raise BackupError("metadata backup is not valid bounded UTF-8 JSON") from exc
diff --git a/tgdrive/recovery/mongo_backup.py b/tgdrive/recovery/mongo_backup.py
new file mode 100644
index 00000000..3bc8bd3a
--- /dev/null
+++ b/tgdrive/recovery/mongo_backup.py
@@ -0,0 +1,530 @@
+"""Encrypted full MongoDB snapshots, independent of normal transfer completion."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import secrets
+import time
+import zlib
+from datetime import UTC, datetime
+from pathlib import Path
+
+from bson import json_util
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+from tgdrive.recovery.backup import BackupError, RecoveryConflict
+from tgdrive.storage.mongo_store import MongoStore
+from tgdrive.storage.store import ROOT_ID, SCHEMA_VERSION
+
+MAGIC = b"TGDRIVE-MONGO-1\n"
+COLLECTIONS = (
+    "catalog",
+    "nodes",
+    "shares",
+    "operations",
+    "deletions",
+    "preparations",
+    "settings",
+    "identities",
+    "sessions",
+    "jobs",
+    "receipts",
+    "bot_folders",
+    "backups",
+)
+MAX_EXPANDED = 1024**3
+
+
+def backup_key(settings):
+    value = settings.mongodb_backup_key
+    if value is None:
+        raise BackupError(
+            "Configure MONGODB_BACKUP_KEY before enabling encrypted backups"
+        )
+    try:
+        key = bytes.fromhex(value.get_secret_value())
+    except ValueError:
+        raise BackupError(
+            "MONGODB_BACKUP_KEY must contain 64 hexadecimal characters"
+        ) from None
+    if len(key) != 32:
+        raise BackupError("MONGODB_BACKUP_KEY must contain 64 hexadecimal characters")
+    return key
+
+
+def file_checksum(path):
+    with Path(path).open("rb") as source:
+        return hashlib.file_digest(source, "sha256").hexdigest()
+
+
+def write_snapshot(backend, path: Path, key: bytes):
+    """Return the encrypted snapshot's revision, record counts and checksum."""
+    nonce = os.urandom(12)
+    encryptor = Cipher(algorithms.AES(key), modes.GCM(nonce)).encryptor()
+    encryptor.authenticate_additional_data(MAGIC)
+    compressor = zlib.compressobj(level=6)
+    total = 0
+    counts = {}
+    revision = None
+    target = path.open("xb")
+    try:
+        with target:
+            path.chmod(0o600)
+            target.write(MAGIC + nonce)
+
+            def write(value):
+                nonlocal total
+                data = (json_util.dumps(value, separators=(",", ":")) + "\n").encode()
+                total += len(data)
+                if total > MAX_EXPANDED:
+                    raise BackupError("MongoDB backup exceeds the 1 GiB expanded limit")
+                target.write(encryptor.update(compressor.compress(data)))
+
+            with backend.client.start_session(snapshot=True) as session:
+                write(
+                    {
+                        "format": "tgdrive-mongodb",
+                        "version": 1,
+                        "created_at": datetime.now(UTC),
+                    }
+                )
+                for name in COLLECTIONS:
+                    count = 0
+                    for document in backend.db[name].find({}, session=session):
+                        write({"collection": name, "document": document})
+                        if name == "catalog" and document["_id"] == "catalog":
+                            revision = document["revision"]
+                        count += 1
+                    counts[name] = count
+            if counts["catalog"] != 1 or type(revision) is not int or revision < 1:
+                raise BackupError("MongoDB backup catalog revision is invalid")
+            write({"complete": True, "counts": counts})
+            target.write(encryptor.update(compressor.flush()))
+            target.write(encryptor.finalize())
+            target.write(encryptor.tag)
+            target.flush()
+            os.fsync(target.fileno())
+        return revision, counts, file_checksum(path)
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+
+
+def decode_snapshot(path: Path, key: bytes):
+    """Validate authentication, framing, bounds and completeness before restoring."""
+    if path.stat().st_size > MAX_EXPANDED:
+        raise BackupError("Encrypted backup is too large")
+    data = path.read_bytes()
+    if not data.startswith(MAGIC) or len(data) < len(MAGIC) + 12 + 16:
+        raise BackupError("This is not a TGDrive MongoDB backup")
+    nonce = data[len(MAGIC) : len(MAGIC) + 12]
+    decryptor = Cipher(algorithms.AES(key), modes.GCM(nonce, data[-16:])).decryptor()
+    decryptor.authenticate_additional_data(MAGIC)
+    try:
+        compressed = (
+            decryptor.update(data[len(MAGIC) + 12 : -16]) + decryptor.finalize()
+        )
+        decoder = zlib.decompressobj()
+        content = decoder.decompress(compressed, MAX_EXPANDED + 1)
+        if (
+            len(content) > MAX_EXPANDED
+            or not decoder.eof
+            or decoder.unconsumed_tail
+            or decoder.unused_data
+        ):
+            raise ValueError
+        records = [json_util.loads(line) for line in content.splitlines()]
+        if not records or records[0].get("format") != "tgdrive-mongodb":
+            raise ValueError
+        if records[0].get("version") != 1 or not records[-1].get("complete"):
+            raise ValueError
+        result = {name: [] for name in COLLECTIONS}
+        seen = {name: set() for name in COLLECTIONS}
+        for record in records[1:-1]:
+            name = record["collection"]
+            document = record["document"]
+            if (
+                name not in result
+                or not isinstance(document, dict)
+                or "_id" not in document
+            ):
+                raise ValueError
+            if document["_id"] in seen[name]:
+                raise ValueError
+            seen[name].add(document["_id"])
+            result[name].append(document)
+        if records[-1]["counts"] != {
+            name: len(values) for name, values in result.items()
+        }:
+            raise ValueError
+        if len(result["catalog"]) != 1 or not result["nodes"]:
+            raise ValueError
+        MongoStore.validate_snapshot_records(result)
+        return result
+    except Exception:
+        raise BackupError(
+            "Backup authentication or validation failed; nothing restored"
+        ) from None
+
+
+def check_restore_destination(backend, *, allow_pristine=False, session=None):
+    """Accept an empty database or an unused automatically initialized drive."""
+    catalogs = list(backend.db.catalog.find({}, session=session))
+    if not allow_pristine:
+        if any(backend.db[name].find_one({}, session=session) for name in COLLECTIONS):
+            raise FileExistsError("Restore requires an empty MongoDB database")
+        return
+    if not catalogs:
+        # Signing into a recovery-only shell creates sessions and may refresh
+        # account names; neither is an existing drive to overwrite.
+        if any(
+            backend.db[name].find_one({}, session=session)
+            for name in COLLECTIONS
+            if name not in {"sessions", "identities"}
+        ):
+            raise FileExistsError(
+                "This database contains drive records. Restore into an empty database."
+            )
+        return
+    if len(catalogs) != 1:
+        raise FileExistsError("The destination is not a new, unused drive")
+    catalog = catalogs[0]
+    # create() starts at revision 1; initial channel binding is the sole commit.
+    if (
+        catalog.get("_id") != "catalog"
+        or catalog.get("schema_version") != SCHEMA_VERSION
+        or catalog.get("revision") != 2
+        or catalog.get("generation") != 1
+    ):
+        raise FileExistsError("Restore requires a new, unused drive")
+    nodes = list(backend.db.nodes.find({}, session=session))
+    if (
+        len(nodes) != 1
+        or nodes[0].get("_id") != ROOT_ID
+        or nodes[0].get("parent_id") is not None
+        or nodes[0].get("kind") != "folder"
+        or nodes[0].get("name") != "/"
+        or nodes[0].get("trashed") is not False
+    ):
+        raise FileExistsError("The destination already contains files or folders")
+    for name in COLLECTIONS:
+        if name in {
+            "catalog",
+            "nodes",
+            "settings",
+            "sessions",
+            "identities",
+            "backups",
+        }:
+            continue
+        if backend.db[name].find_one({}, session=session):
+            raise FileExistsError("The destination contains drive work or shared links")
+    for row in backend.db.settings.find({}, session=session):
+        if row.get("_id") == "bootstrap":
+            continue
+        if row.get("_id") == "telegram" and row.get("revision") == 1:
+            continue
+        raise FileExistsError("The destination contains saved settings changes")
+
+
+def restore_decoded_snapshot(backend, data, *, allow_pristine=False):
+    """Recheck destination and atomically import a previously authenticated archive."""
+    MongoStore.validate_snapshot_records(data)
+    backend.ping()
+    # Revocation is explicit: restored browser cookies must never reactivate.
+    data = {**data, "sessions": []}
+
+    def restore(session):
+        backend.fence(session)
+        check_restore_destination(
+            backend, allow_pristine=allow_pristine, session=session
+        )
+        if allow_pristine:
+            for name in COLLECTIONS:
+                backend.db[name].delete_many({}, session=session)
+        for name, values in data.items():
+            if values:
+                backend.db[name].insert_many(values, session=session)
+
+    backend.transaction(restore, allow_paused=True)
+    with backend._settings_lock:
+        backend._settings_cached = False
+        backend._settings_document = None
+    MongoStore._indexes(backend)
+
+
+def restore_snapshot(backend, path: Path, key: bytes):
+    restore_decoded_snapshot(backend, decode_snapshot(path, key))
+
+
+class MongoProtection:
+    """Cloud commits protect normal work; Telegram copies run independently."""
+
+    def __init__(self, settings, pool, backend):
+        self.settings, self.pool, self.backend = settings, pool, backend
+        self._stop = asyncio.Event()
+        self._task = None
+        self._lock = asyncio.Lock()
+        self._last_error = None
+        self._last_success_at = None
+        self.recovery_required = False
+        self.recovery_error = None
+
+    async def restore(self):
+        return await asyncio.to_thread(MongoStore, self.backend)
+
+    def check_local_binding(self, store):
+        if store.storage_channel_id not in (None, self.settings.storage_channel):
+            raise RecoveryConflict(
+                "This MongoDB drive belongs to a different Telegram channel"
+            )
+
+    def check_upload_allowed(self, store):
+        self.backend.check_owner()
+        self.check_local_binding(store)
+
+    async def verify_lineage(self, store):
+        self.check_upload_allowed(store)
+
+    async def restore_publication_cooldown(self):
+        return
+
+    async def ensure_revision(self, store, required_revision):
+        self.check_upload_allowed(store)
+        if required_revision > store.revision:
+            raise BackupError("The catalog revision is not committed")
+        return store.revision
+
+    def protection_status(self, store):
+        try:
+            self.check_upload_allowed(store)
+            state, error = "protected", None
+        except Exception:
+            state, error = "error", "MongoDB connection or ownership needs attention"
+        result = {
+            "state": state,
+            "backend": "mongodb",
+            "metadata_revision": store.revision,
+            "protected_revision": store.revision if state == "protected" else 0,
+            "backup_error": self._last_error,
+            "backup_key_configured": bool(self.settings.mongodb_backup_key),
+            "last_success_at": self._last_success_at,
+        }
+        if error:
+            result["error"] = error
+        return result
+
+    def history(self, *, limit=None):
+        rows = self.backend.db.backups.find({}, {"_id": 0, "local_path": 0}).sort(
+            "created_at", -1
+        )
+        result = list(rows.limit(limit or 100))
+        if result and result[0].get("status") == "confirmed":
+            self._last_success_at = result[0].get("confirmed_at")
+        return result
+
+    async def backup(self, store, *, force=False):
+        self.check_upload_allowed(store)
+        if store.storage_channel_id is None:
+            await asyncio.to_thread(
+                store.bind_storage_channel, self.settings.storage_channel
+            )
+        if force:
+            return await self.snapshot_now(store)
+        return False
+
+    async def snapshot_now(self, store):
+        async with self._lock:
+            await self.verify_lineage(store)
+            backend = self.backend
+            key = backup_key(self.settings)
+            pending = await asyncio.to_thread(
+                backend.db.backups.find_one,
+                {"status": "pending"},
+                sort=[("created_at", 1)],
+            )
+            if pending is None:
+                identity = secrets.token_urlsafe(16)
+                directory = self.settings.resolved_cache_dir / "mongo-backups"
+                directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+                path = directory / (identity + ".tgdb")
+                export = asyncio.create_task(
+                    asyncio.to_thread(write_snapshot, backend, path, key)
+                )
+                try:
+                    revision, counts, digest = await asyncio.shield(export)
+                except asyncio.CancelledError:
+                    # The unadmitted file still belongs to its worker until it drains.
+                    while not export.done():
+                        try:
+                            await asyncio.shield(export)
+                        except asyncio.CancelledError:
+                            continue
+                        except Exception:
+                            break
+                    if not export.cancelled() and export.exception() is None:
+                        path.unlink(missing_ok=True)
+                    raise
+                row = {
+                    "_id": identity,
+                    "id": identity,
+                    "status": "pending",
+                    "created_at": datetime.now(UTC).isoformat(),
+                    "revision": revision,
+                    "local_path": str(path),
+                    "sha256": digest,
+                    "random_id": secrets.randbits(63),
+                    "sender": None,
+                    "message_id": None,
+                    "channel_id": self.settings.storage_channel,
+                    "retry_at": 0,
+                    "counts": counts,
+                    "format": "mongodb-encrypted-v1",
+                }
+                await asyncio.to_thread(backend.db.backups.insert_one, row)
+                pending = row
+            if pending["channel_id"] != self.settings.storage_channel:
+                raise BackupError("Pending backup belongs to another channel")
+            remaining = pending.get("retry_at", 0) - time.time()
+            if remaining > 0:
+                raise BackupError(
+                    "Telegram backup is waiting before retry", retry_after=remaining
+                )
+            path = Path(pending["local_path"])
+            # A fresh host may have the database but not its previous temporary file.
+            # Do not resend changed bytes under an existing random_id.
+            if not path.is_file():
+                await asyncio.to_thread(
+                    backend.db.backups.update_one,
+                    {"_id": pending["_id"]},
+                    {"$set": {"status": "interrupted"}},
+                )
+                raise BackupError(
+                    "The previous backup file is unavailable; "
+                    "a new snapshot will be scheduled"
+                )
+            digest = await asyncio.to_thread(file_checksum, path)
+            if digest != pending["sha256"]:
+                raise BackupError("The staged backup checksum failed")
+            try:
+                async with self.pool.lease(client_name=pending["sender"]) as client:
+                    if pending["sender"] is None:
+                        pending["sender"] = client.name
+                        await asyncio.to_thread(
+                            backend.db.backups.update_one,
+                            {"_id": pending["_id"]},
+                            {"$set": {"sender": client.name}},
+                        )
+                    message = await client.send_document(
+                        self.settings.storage_channel,
+                        str(path),
+                        file_name="tgdrive-" + pending["id"] + ".tgdb",
+                        random_id=pending["random_id"],
+                        caption="TGDrive encrypted MongoDB backup · "
+                        + pending["created_at"],
+                    )
+                    identity = getattr(message, "id", None)
+                    if type(identity) is not int or identity <= 0:
+                        raise BackupError("Telegram did not confirm the backup")
+                    # Verify the exact remote encrypted bytes before recording success.
+                    fetched = await client.get_messages(
+                        self.settings.storage_channel, message_ids=identity
+                    )
+                    remote_size = getattr(
+                        getattr(fetched, "document", None), "file_size", None
+                    )
+                    if remote_size != path.stat().st_size:
+                        raise BackupError("Telegram backup size verification failed")
+                    remote_hash = hashlib.sha256()
+                    iterator = client.stream_media(
+                        fetched, limit=(remote_size + 1024**2 - 1) // 1024**2, offset=0
+                    )
+                    try:
+                        async for block in iterator:
+                            remote_hash.update(block)
+                    finally:
+                        await iterator.aclose()
+                    if remote_hash.hexdigest() != digest:
+                        raise BackupError("Telegram backup verification failed")
+                await asyncio.to_thread(
+                    backend.db.backups.update_one,
+                    {"_id": pending["_id"]},
+                    {
+                        "$set": {
+                            "status": "confirmed",
+                            "message_id": identity,
+                            "confirmed_at": datetime.now(UTC).isoformat(),
+                        }
+                    },
+                )
+                path.unlink(missing_ok=True)
+                self._last_error = None
+                self._last_success_at = datetime.now(UTC).isoformat()
+                return True
+            except Exception as exc:
+                seconds = getattr(exc, "seconds", None)
+                if isinstance(seconds, (int, float)) and seconds > 0:
+                    deadline = time.time() + seconds + 0.25
+                    await asyncio.to_thread(
+                        backend.db.backups.update_one,
+                        {"_id": pending["_id"]},
+                        {"$set": {"retry_at": deadline}},
+                    )
+                    await self.pool.defer_channel(deadline)
+                self._last_error = (
+                    "The encrypted Telegram backup will retry automatically."
+                )
+                raise
+
+    def start(self, store):
+        if self._task is None:
+            self._task = asyncio.create_task(self._loop(store), name="mongodb-backup")
+        return self._task
+
+    async def _loop(self, store):
+        delay = 30
+        try:
+            pending = await asyncio.to_thread(
+                self.backend.db.backups.find_one, {"status": "pending"}
+            )
+            latest = await asyncio.to_thread(
+                self.backend.db.backups.find_one,
+                {"status": "confirmed"},
+                sort=[("created_at", -1)],
+            )
+            if pending:
+                delay = max(1, pending.get("retry_at", 0) - time.time())
+            elif latest and latest.get("confirmed_at"):
+                confirmed = datetime.fromisoformat(latest["confirmed_at"]).timestamp()
+                delay = max(
+                    1,
+                    self.settings.mongodb_backup_seconds
+                    - max(0, time.time() - confirmed),
+                )
+        except Exception:
+            delay = 60
+        while not self._stop.is_set():
+            try:
+                await asyncio.wait_for(self._stop.wait(), timeout=delay)
+                return
+            except TimeoutError:
+                pass
+            try:
+                await self.snapshot_now(store)
+                delay = self.settings.mongodb_backup_seconds
+            except asyncio.CancelledError:
+                raise
+            except Exception:
+                self._last_error = (
+                    "The encrypted Telegram backup will retry automatically."
+                )
+                delay = 60
+
+    async def stop(self, store):
+        self._stop.set()
+        if self._task:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+            self._task = None
diff --git a/tgdrive/recovery/restore_api.py b/tgdrive/recovery/restore_api.py
new file mode 100644
index 00000000..c4a3abc9
--- /dev/null
+++ b/tgdrive/recovery/restore_api.py
@@ -0,0 +1,291 @@
+"""Owner-only upload and restore of authenticated full MongoDB archives."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import secrets
+
+from fastapi import Depends, HTTPException, Request
+from fastapi.responses import JSONResponse
+from pymongo.errors import PyMongoError
+
+from tgdrive.core.security import SESSION_COOKIE
+from tgdrive.recovery.backup import BackupError
+from tgdrive.recovery.mongo_backup import (
+    MAX_EXPANDED,
+    check_restore_destination,
+    decode_snapshot,
+    restore_decoded_snapshot,
+)
+from tgdrive.storage.mongo import DatabaseUnavailable
+
+logger = logging.getLogger(__name__)
+RESTORE_PATH = "/api/v1/backup/restore"
+
+
+class RestoreError(HTTPException):
+    def __init__(self, status_code, detail, code):
+        super().__init__(status_code=status_code, detail=detail)
+        self.code = code
+
+
+async def _drain(task):
+    """Repeated disconnect cancellation cannot release resources before work ends."""
+    interrupted = False
+    while True:
+        try:
+            result = await asyncio.shield(task)
+            break
+        except asyncio.CancelledError:
+            if task.cancelled():
+                raise
+            interrupted = True
+    if interrupted:
+        raise asyncio.CancelledError
+    return result
+
+
+async def _finish(operation, *args, **kwargs):
+    task = asyncio.create_task(asyncio.to_thread(operation, *args, **kwargs))
+    return await _drain(task)
+
+
+def register_restore_routes(app, settings, *, require_admin, get_runtime):
+    lock = asyncio.Lock()
+
+    @app.exception_handler(RestoreError)
+    async def restore_error(_request, error):
+        return JSONResponse(
+            {
+                "detail": error.detail,
+                "code": error.code,
+                "restart_required": error.code == "DATABASE_RESTORE_UNCONFIRMED",
+            },
+            status_code=error.status_code,
+            headers={"Cache-Control": "no-store"},
+        )
+
+    @app.post(RESTORE_PATH, dependencies=[Depends(require_admin)])
+    async def restore_archive(request: Request):
+        if settings.demo_mode:
+            raise HTTPException(403, "Database restore is disabled in demo mode")
+        content_type = request.headers.get("content-type", "").split(";", 1)[0]
+        if content_type != "application/octet-stream":
+            logger.warning(
+                "Database archive restore rejected: invalid upload content type"
+            )
+            raise HTTPException(415, "Upload the archive as application/octet-stream")
+        key_values = request.headers.getlist("x-tgdrive-recovery-key")
+        if len(key_values) != 1 or not re.fullmatch(r"[a-fA-F0-9]{64}", key_values[0]):
+            logger.warning(
+                "Database archive restore rejected: recovery key format is invalid"
+            )
+            raise HTTPException(
+                422, "Enter the original 64-character MongoDB recovery key"
+            )
+        if request.headers.getlist("x-tgdrive-confirm") != ["RESTORE"]:
+            logger.warning(
+                "Database archive restore rejected: owner confirmation is missing"
+            )
+            raise HTTPException(422, "Confirm the database restore by entering RESTORE")
+        if lock.locked():
+            raise HTTPException(409, "A database restore is already running")
+        async with lock:
+            await require_admin(request)
+            runtime = get_runtime(request)
+            if getattr(runtime, "archive_restore_restart_required", False):
+                raise HTTPException(409, "Restart TGDrive before another restore")
+            backend = runtime.mongo
+            replica = getattr(runtime, "replica", None)
+            if replica is not None and (
+                replica.blocked or replica.status().get("configured")
+            ):
+                logger.warning(
+                    "Database archive restore rejected: finish channel recovery "
+                    "or disable its backup first"
+                )
+                raise HTTPException(
+                    409,
+                    "Finish channel recovery or disable the independent backup "
+                    "before restoring",
+                )
+            if (settings.resolved_data_dir / "channel-activation.json").exists():
+                logger.warning(
+                    "Database archive restore rejected: pending channel activation "
+                    "requires review"
+                )
+                raise HTTPException(
+                    409, "Finish the pending channel activation before restoring"
+                )
+            try:
+                await _finish(check_restore_destination, backend, allow_pristine=True)
+            except FileExistsError:
+                logger.warning(
+                    "Database archive restore rejected: "
+                    "destination has existing drive work"
+                )
+                raise RestoreError(
+                    409,
+                    "Restore requires an empty MongoDB database or a new, unused "
+                    "drive. Existing data was preserved.",
+                    "RESTORE_DESTINATION_NOT_EMPTY",
+                ) from None
+            except DatabaseUnavailable, PyMongoError:
+                logger.warning(
+                    "Database archive restore rejected: MongoDB is unavailable; "
+                    "restore database access"
+                )
+                raise RestoreError(
+                    503,
+                    "MongoDB is unavailable; restore was not started",
+                    "DATABASE_RESTORE_UNAVAILABLE",
+                ) from None
+            directory = settings.resolved_cache_dir / "mongo-restore"
+            path = directory / (secrets.token_hex(16) + ".tgdb")
+            try:
+                directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+                with path.open("xb") as target:
+                    path.chmod(0o600)
+                    total = 0
+                    async for part in request.stream():
+                        total += len(part)
+                        if total > MAX_EXPANDED:
+                            logger.warning(
+                                "Database archive restore rejected: archive "
+                                "exceeds the 1 GiB limit"
+                            )
+                            raise HTTPException(
+                                413, "MongoDB archive exceeds the 1 GiB limit"
+                            )
+                        await _finish(target.write, part)
+                data = await _finish(
+                    decode_snapshot, path, bytes.fromhex(key_values[0])
+                )
+                await require_admin(request)
+                try:
+                    await _finish(
+                        check_restore_destination, backend, allow_pristine=True
+                    )
+                except FileExistsError:
+                    logger.warning(
+                        "Database archive restore rejected: "
+                        "destination changed during upload"
+                    )
+                    raise RestoreError(
+                        409,
+                        "The destination changed while the archive was uploaded. "
+                        "Existing data was preserved.",
+                        "RESTORE_DESTINATION_NOT_EMPTY",
+                    ) from None
+                if replica is not None and (
+                    replica.blocked or replica.status().get("configured")
+                ):
+                    raise HTTPException(
+                        409, "Channel recovery changed; inspect it before restoring"
+                    )
+
+                async def commit():
+                    # Stop request admissions before draining all background writers.
+                    runtime.archive_restore_restart_required = True
+                    runtime.recovery_only = True
+                    try:
+                        await _finish(backend.pause_writes)
+                        for name in (
+                            "premium_login_service",
+                            "thumbnail_rebuild",
+                            "thumbnails",
+                        ):
+                            resource = getattr(request.app.state, name, None)
+                            if resource is not None:
+                                await resource.close()
+                        connections = getattr(runtime, "connection_manager", None)
+                        if connections is not None:
+                            await connections.close()
+                        failures = await runtime.stop()
+                        runtime.store = None
+                        if failures:
+                            raise RuntimeError("The drive did not stop cleanly")
+                        await _finish(backend.acquire)
+                        try:
+                            await _finish(
+                                restore_decoded_snapshot,
+                                backend,
+                                data,
+                                allow_pristine=True,
+                            )
+                        finally:
+                            await _finish(backend.release)
+                    except Exception:
+                        logger.warning(
+                            "MongoDB archive restore could not be confirmed; "
+                            "restart required"
+                        )
+                        raise RestoreError(
+                            503,
+                            "Restore could not be confirmed. Restart TGDrive and "
+                            "review Storage & Backups before retrying.",
+                            "DATABASE_RESTORE_UNCONFIRMED",
+                        ) from None
+                    # SessionManager caches persisted tokens for range requests;
+                    # imported sessions are also discarded by the restore engine.
+                    request.app.state.sessions._mongo_sessions.clear()
+                    logger.info(
+                        "Full MongoDB archive restored; service restart required"
+                    )
+
+                task = asyncio.create_task(commit())
+                await _drain(task)
+            except BackupError:
+                logger.warning(
+                    "Database archive restore rejected: archive authentication or "
+                    "validation failed; check file and key"
+                )
+                raise RestoreError(
+                    422,
+                    "Archive authentication or validation failed. Check the backup "
+                    "file and its original recovery key; nothing was restored.",
+                    "ARCHIVE_INVALID",
+                ) from None
+            except DatabaseUnavailable, PyMongoError:
+                logger.warning(
+                    "Database archive restore was not started: MongoDB access failed"
+                )
+                raise RestoreError(
+                    503,
+                    "MongoDB is unavailable; restore was not started",
+                    "DATABASE_RESTORE_UNAVAILABLE",
+                ) from None
+            except OSError:
+                logger.warning(
+                    "Database archive restore staging failed; check cache storage "
+                    "and permissions"
+                )
+                raise RestoreError(
+                    507,
+                    "The archive could not be staged. Check temporary storage and "
+                    "permissions, then retry.",
+                    "ARCHIVE_STAGING_FAILED",
+                ) from None
+            finally:
+                try:
+                    path.unlink(missing_ok=True)
+                except OSError:
+                    logger.warning(
+                        "Could not remove staged encrypted restore archive; "
+                        "check cache permissions"
+                    )
+            response = JSONResponse(
+                {
+                    "restart_required": True,
+                    "detail": (
+                        "Database restored. Restart TGDrive through Docker or "
+                        "Coolify, then sign in using the restored credentials. "
+                        "Explicit environment settings still take precedence."
+                    ),
+                },
+                headers={"Cache-Control": "no-store"},
+            )
+            response.delete_cookie(SESSION_COOKIE, path="/")
+            return response
diff --git a/tgdrive/replication/__init__.py b/tgdrive/replication/__init__.py
new file mode 100644
index 00000000..5bcd0e61
--- /dev/null
+++ b/tgdrive/replication/__init__.py
@@ -0,0 +1 @@
+"""Channel replica transport, state, bootstrap, and activation."""
diff --git a/tgdrive/replication/replica.py b/tgdrive/replication/replica.py
new file mode 100644
index 00000000..e2e8cf72
--- /dev/null
+++ b/tgdrive/replication/replica.py
@@ -0,0 +1,1158 @@
+"""Optional independent channel copies with crash-resumable, explicit recovery."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import math
+import secrets
+import shutil
+import time
+from contextlib import suppress
+from datetime import UTC, datetime
+from functools import partial
+
+from pydantic import SecretStr
+
+from tgdrive.replication.replica_state import (
+    ReplicaJournal,
+    atomic_private,
+    decode_bundle,
+    encode_bundle,
+    files_in,
+    parts_in,
+    read_private,
+    remap_catalog,
+    validate_catalog,
+)
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.storage.store import DriveStore
+
+HEALTH_CHECK_INTERVAL_SECONDS = 60 * 60
+
+
+def now():
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+class ChannelReplica:
+    def __init__(self, settings, runtime, *, transport_factory=None):
+        from tgdrive.replication.replica_transport import (
+            ReplicaRequestPacer,
+            ReplicaTransport,
+        )
+
+        self.settings, self.runtime = settings, runtime
+        self._request_pacer = ReplicaRequestPacer()
+        self.factory = transport_factory or partial(
+            ReplicaTransport, pacer=self._request_pacer
+        )
+        self.directory = settings.resolved_data_dir
+        self.journal = ReplicaJournal(self.directory)
+        saved_mongo_key = self.journal.get("mongodb_key")
+        if settings.mongodb_backup_key is None and saved_mongo_key:
+            settings.mongodb_backup_key = SecretStr(saved_mongo_key)
+            protection = getattr(runtime, "backup", None)
+            if protection is not None and hasattr(protection, "settings"):
+                protection.settings.mongodb_backup_key = settings.mongodb_backup_key
+        self._task = None
+        self._wake = asyncio.Event()
+        self._operation = asyncio.Lock()
+        self.control = asyncio.Lock()
+        self._closed = False
+
+    @property
+    def blocked(self):
+        return bool(self.journal.get("recovery") or self.journal.get("activation"))
+
+    def status(self):
+        config = self.journal.get("config", {})
+        state = self.journal.get("status", {})
+        store = getattr(self.runtime, "store", None)
+        revision = store.revision if store else 0
+        result = {
+            "enabled": bool(config.get("enabled")),
+            "configured": bool(config),
+            "recovery_only": bool(getattr(self.runtime, "recovery_only", False)),
+            "phase": "idle" if config else "disabled",
+            "source_channel": self.settings.storage_channel,
+            "backup_channel": config.get("channel"),
+            "revision": revision,
+            "protected_revision": 0,
+            "last_success_at": None,
+            "current_file": "",
+            "total_files": 0,
+            "done_files": 0,
+            "total_parts": 0,
+            "done_parts": 0,
+            "total_bytes": 0,
+            "done_bytes": 0,
+            "error": None,
+            **state,
+            "report": self.journal.get("report", []),
+            "restore_point": self.journal.get("restore_point"),
+        }
+        result["pending_revision"] = max(0, revision - result["protected_revision"])
+        candidate = self.journal.get("candidate")
+        if candidate:
+            catalog = candidate["catalog"]
+            files = list(files_in(catalog))
+            result["recovery_candidate"] = {
+                "revision": catalog["revision"],
+                "channel": catalog["storage_channel_id"],
+                "files": len(files),
+                "bytes": sum(f["size"] for f in files),
+                "complete": bool(candidate.get("complete")),
+            }
+        return result
+
+    def update(self, **values):
+        self.journal.set("status", self.journal.get("status", {}) | values)
+
+    def report(self, level, message):
+        rows = self.journal.get("report", [])
+        self.journal.set(
+            "report",
+            [*rows, {"at": now(), "level": level, "message": message}][-100:],
+        )
+
+    def key(self):
+        value = self.journal.get("key")
+        if value is None:
+            value = secrets.token_hex(32)
+            self.journal.set("key", value)
+        return value
+
+    async def configure(self, channel, token, independent):
+        if not independent or channel == self.settings.storage_channel or channel >= 0:
+            raise SettingsProblem(
+                "Use two different private channels and confirm independent "
+                "owner accounts."
+            )
+        if self.blocked:
+            raise SettingsProblem(
+                "Pause the current operation before changing backup settings.",
+                status=409,
+            )
+        transport = self.factory(self.settings, token)
+        try:
+            await transport.start()
+            await transport.inspect(self.settings.storage_channel)
+            target = await transport.inspect(channel)
+            pinned = await transport.pinned_message(channel)
+            point = self.journal.get("restore_point", {})
+            if pinned is not None and not (
+                point.get("backup_channel") == channel
+                and point.get("backup_message_id") == pinned
+            ):
+                raise SettingsProblem(
+                    "The destination already has a pinned message. Use a new dedicated "
+                    "private channel, or inspect its existing recovery point instead "
+                    "of overwriting it.",
+                    status=409,
+                )
+            config = {
+                "channel": channel,
+                "token": token,
+                "enabled": True,
+                "title": target["title"],
+            }
+            self.journal.set("config", config)
+            from tgdrive.replication.replica_bootstrap import save_bootstrap
+
+            await asyncio.to_thread(save_bootstrap, self.settings)
+            if (
+                getattr(self.runtime, "mongo", None) is not None
+                and self.settings.mongodb_backup_key is None
+            ):
+                mongo_key = secrets.token_hex(32)
+                self.journal.set("mongodb_key", mongo_key)
+                self.settings.mongodb_backup_key = SecretStr(mongo_key)
+                self.runtime.backup.settings.mongodb_backup_key = SecretStr(mongo_key)
+            self.journal.set("job", None)
+            self.key()
+            self.update(
+                phase="idle", error=None, protected_revision=0, last_success_at=None
+            )
+            self.report(
+                "info",
+                "Private channels and backup bot verified. "
+                "Initial synchronization scheduled.",
+            )
+            self.start()
+            self._wake.set()
+        finally:
+            await transport.close()
+        return self.status()
+
+    def start(self):
+        if self._task is None or self._task.done():
+            self._task = asyncio.create_task(
+                self._loop(), name="independent-channel-backup"
+            )
+
+    async def close(self):
+        self._closed = True
+        if self._task:
+            self._task.cancel()
+            await asyncio.gather(self._task, return_exceptions=True)
+        self.journal.close()
+
+    async def action(self, action):
+        config = self.journal.get("config", {})
+        if action in {"pause", "disable"}:
+            if self.journal.get("activation"):
+                raise SettingsProblem(
+                    "Restart to apply the confirmed recovery first.", status=409
+                )
+            self.update(phase="paused" if action == "pause" else "disabled")
+            if action == "disable":
+                config["enabled"] = False
+                self.journal.set("config", config)
+                self.journal.set("recovery", None)
+                self.journal.set("candidate", None)
+            self.report(
+                "info",
+                "Operation paused. Confirmed source and backup messages are retained.",
+            )
+        elif action in {"resume", "retry", "sync"}:
+            error = self.journal.get("status", {}).get("error")
+            if error and error.get("retry_at", 0) > time.time():
+                self.update(phase="waiting")
+            else:
+                self.update(phase="idle", error=None)
+                if action == "sync" or error:
+                    self.update(checked_at=0)
+            if config:
+                config["enabled"] = True
+                self.journal.set("config", config)
+            self.start()
+            self._wake.set()
+        else:
+            raise SettingsProblem("Unknown backup action")
+        return self.status()
+
+    async def _loop(self):
+        while not self._closed:
+            state = self.journal.get("status", {})
+            config = self.journal.get("config", {})
+            retry_at = (state.get("error") or {}).get("retry_at", 0)
+            recovery = self.journal.get("recovery")
+            runnable = state.get("phase") not in {
+                "paused",
+                "disabled",
+                "error",
+                "ready_to_activate",
+                "restart_required",
+            }
+            if (
+                runnable
+                and retry_at <= time.time()
+                and (recovery or config.get("enabled"))
+            ):
+                async with self._operation:
+                    # A control request may arrive while another operation owns
+                    # the lock. Do not execute the earlier eligibility snapshot.
+                    state = self.journal.get("status", {})
+                    config = self.journal.get("config", {})
+                    recovery = self.journal.get("recovery")
+                    if (
+                        state.get("phase")
+                        in {
+                            "paused",
+                            "disabled",
+                            "error",
+                            "ready_to_activate",
+                            "restart_required",
+                        }
+                        or (state.get("error") or {}).get("retry_at", 0) > time.time()
+                        or not (recovery or config.get("enabled"))
+                    ):
+                        continue
+                    try:
+                        if recovery:
+                            await self._recover_copy(recovery)
+                        elif getattr(self.runtime, "store", None) is not None:
+                            await self._sync(config)
+                    except asyncio.CancelledError:
+                        raise
+                    except Exception as error:
+                        retryable = bool(getattr(error, "retryable", False))
+                        delay = max(5, float(getattr(error, "retry_after", None) or 30))
+                        detail = (
+                            str(error)
+                            if isinstance(error, (SettingsProblem, ValueError))
+                            or hasattr(error, "code")
+                            else "Telegram backup operation could not be confirmed."
+                        )
+                        if (
+                            getattr(error, "code", None) == "REPLICA_FLOOD_WAIT"
+                            and not recovery
+                            and self.journal.get("job") is None
+                            and self.journal.get("restore_point")
+                        ):
+                            detail = "Routine backup health check delayed. " + detail
+                        operation = getattr(error, "operation", None)
+                        if operation:
+                            detail += f" Operation: {operation}."
+                        if retryable:
+                            detail += f" Retry in {math.ceil(delay)} seconds."
+                        # Never echo arbitrary credential-bearing provider exceptions.
+                        detail = detail[:400]
+                        phase = self.journal.get("status", {}).get("phase")
+                        self.update(
+                            phase=(
+                                phase
+                                if phase in {"paused", "disabled"}
+                                else "waiting"
+                                if retryable
+                                else "error"
+                            ),
+                            error={
+                                "code": getattr(error, "code", "REPLICA_FAILED"),
+                                "detail": detail,
+                                "action": (
+                                    "Leave TGDrive running. Backup will retry after "
+                                    "the displayed deadline; channel permissions "
+                                    "do not need changing for this cooldown."
+                                    if getattr(error, "code", None)
+                                    == "REPLICA_FLOOD_WAIT"
+                                    else "Check channel access, bot permissions and "
+                                    "the source file. Retry after correcting "
+                                    "the problem. "
+                                    "The last confirmed restore point is retained."
+                                ),
+                                "retry_at": time.time() + delay if retryable else 0,
+                            },
+                        )
+                        self.report("error", detail)
+            self._wake.clear()
+            with suppress(TimeoutError):
+                await asyncio.wait_for(self._wake.wait(), timeout=10)
+
+    def _credentials(self):
+        from tgdrive.replication.replica_settings import collect_credentials
+
+        return collect_credentials(self.settings, self.runtime)
+
+    async def _copy_catalog(self, transport, catalog, destination):
+        from tgdrive.replication.replica_transport import MAX_VERIFY_BATCH
+
+        source = catalog["storage_channel_id"]
+        files = list(files_in(catalog))
+        total_parts = sum(len(parts_in(f)) for f in files)
+        self.update(
+            total_files=len(files),
+            total_parts=total_parts,
+            total_bytes=sum(f["size"] for f in files),
+            done_files=0,
+            done_parts=0,
+            done_bytes=0,
+        )
+        mapping = {}
+        done_parts = done_bytes = 0
+        # A resumed job must still recheck every journaled document. Batch those
+        # reads so each cooldown does not trigger two requests per old part.
+        verified = {}
+        verify_many = getattr(transport, "verify_many", None)
+        if callable(verify_many):
+            batch = []
+
+            async def check_batch():
+                if not batch:
+                    return
+                self.update(current_file="Checking previously copied parts")
+                await verify_many(
+                    destination, [(message, size) for _identity, message, size in batch]
+                )
+                verified.update(
+                    (identity, message) for identity, message, _size in batch
+                )
+                batch.clear()
+
+            for node in files:
+                for part in parts_in(node):
+                    if self.journal.get("status", {}).get("phase") in {
+                        "paused",
+                        "disabled",
+                    }:
+                        return None
+                    identity = (
+                        f"{catalog['drive_id']}:{source}:{destination}:"
+                        f"{part['message_id']}:{part['size']}"
+                    )
+                    _random_id, message = self.journal.intent(identity, part["size"])
+                    if message is not None:
+                        batch.append((identity, message, part["size"]))
+                        if len(batch) == MAX_VERIFY_BATCH:
+                            await check_batch()
+            await check_batch()
+        for count, node in enumerate(files):
+            for part in parts_in(node):
+                if self.journal.get("status", {}).get("phase") in {
+                    "paused",
+                    "disabled",
+                }:
+                    return None
+                self.update(current_file=node["name"])
+                identity = (
+                    f"{catalog['drive_id']}:{source}:{destination}:"
+                    f"{part['message_id']}:{part['size']}"
+                )
+                random_id, message = self.journal.intent(identity, part["size"])
+                if message is None:
+                    message = await transport.copy(
+                        source,
+                        part["message_id"],
+                        destination,
+                        random_id=random_id,
+                        expected_size=part["size"],
+                    )
+                    self.journal.confirm(identity, message)
+                elif verified.get(identity) != message:
+                    await transport.verify(destination, message, part["size"])
+                mapping[str(part["message_id"])] = message
+                done_parts += 1
+                done_bytes += part["size"]
+                self.update(done_parts=done_parts, done_bytes=done_bytes)
+                await asyncio.sleep(0)
+            self.update(done_files=count + 1)
+        return remap_catalog(catalog, destination, mapping)
+
+    async def _publish(
+        self,
+        transport,
+        source,
+        target,
+        catalog,
+        replica,
+        credentials,
+        key,
+        *,
+        pin_source=False,
+    ):
+        digest = hashlib.sha256(
+            json.dumps(
+                [
+                    catalog,
+                    replica,
+                    credentials,
+                    hashlib.sha256(key.encode()).hexdigest(),
+                ],
+                sort_keys=True,
+            ).encode()
+        ).hexdigest()
+        path = self.directory / "replica-bundles" / (digest + ".tgdb")
+        if not path.exists():
+            content = encode_bundle(
+                {
+                    "format": "tgdrive-replica",
+                    "version": 1,
+                    "complete": True,
+                    "created_at": now(),
+                    "catalog": catalog,
+                    "replica_catalog": replica,
+                    "credentials": credentials,
+                },
+                key,
+            )
+            if (
+                shutil.disk_usage(self.directory).free
+                < len(content) + self.settings.min_free_bytes
+            ):
+                raise SettingsProblem(
+                    "Not enough local disk space to stage a recovery bundle. "
+                    "Free space and retry.",
+                    status=507,
+                )
+            atomic_private(path, content)
+        staged = decode_bundle(read_private(path), key)
+        if (
+            staged["catalog"] != catalog
+            or staged["replica_catalog"] != replica
+            or staged["credentials"] != credentials
+        ):
+            raise ValueError(
+                "The staged recovery bundle does not match this restore point"
+            )
+        with path.open("rb") as content:
+            ciphertext_digest = hashlib.file_digest(content, "sha256").hexdigest()
+        ids = []
+        for channel, pin in [(target, True), (source, pin_source)]:
+            identity = f"bundle:{channel}:{ciphertext_digest}"
+            random_id, message = self.journal.intent(identity, path.stat().st_size)
+            if message is None:
+                message = await transport.publish(
+                    channel,
+                    path,
+                    random_id=random_id,
+                    caption="TGDrive independent recovery bundle v1",
+                    pin=pin,
+                )
+                self.journal.confirm(identity, message)
+            else:
+                await transport.verify(channel, message, path.stat().st_size)
+            ids.append(message)
+        self.journal.set_many(
+            {
+                "restore_point": {
+                    "source_channel": source,
+                    "source_message_id": ids[1],
+                    "backup_channel": target,
+                    "backup_message_id": ids[0],
+                    "revision": catalog["revision"],
+                    "created_at": now(),
+                    "bundle_size": path.stat().st_size,
+                },
+                "credentials_digest": hashlib.sha256(
+                    json.dumps(credentials, sort_keys=True).encode()
+                ).hexdigest(),
+                "restore_point_key": key,
+                "restore_point_mongodb_key": credentials.get("mongodb_backup_key"),
+            }
+        )
+        return ids
+
+    async def _sync(self, config, *, force_check=False):
+        store = self.runtime.store
+        state = self.journal.get("status", {})
+        error = state.get("error") or {}
+        if error.get("retry_at", 0) > time.time():
+            from tgdrive.recovery.backup import BackupError
+
+            raise BackupError(
+                "Telegram requested a wait before backup resumes.",
+                retry_after=error["retry_at"] - time.time(),
+            )
+        current_credentials = await asyncio.to_thread(self._credentials)
+        if self.journal.get("status", {}).get("phase") in {"paused", "disabled"}:
+            return
+        credentials_digest = hashlib.sha256(
+            json.dumps(current_credentials, sort_keys=True).encode()
+        ).hexdigest()
+        same_credentials = self.journal.get("credentials_digest") == credentials_digest
+        point = self.journal.get("restore_point", {})
+        check_only = (
+            same_credentials
+            and state.get("protected_revision") == store.revision
+            and bool(point.get("backup_message_id"))
+        )
+        if (
+            check_only
+            and not error
+            and not force_check
+            and state.get("checked_at", 0) > time.time() - HEALTH_CHECK_INTERVAL_SECONDS
+        ):
+            if state.get("phase") in {"idle", "waiting", "syncing"}:
+                self.update(phase="protected", current_file="", error=None)
+            return
+        job = self.journal.get("job")
+        if (
+            job is not None
+            and getattr(self.runtime, "mongo", None) is not None
+            and job["credentials"].get("mongodb_backup_key")
+            != current_credentials.get("mongodb_backup_key")
+        ):
+            raise SettingsProblem(
+                "The pending backup captured a different MongoDB recovery key. "
+                "Restore that key to resume, or verify Backup settings again "
+                "to start a new snapshot with the current key. Existing restore "
+                "points and confirmed file copies are retained.",
+                code="REPLICA_MONGODB_KEY_CHANGED",
+                status=409,
+            )
+        if job is None and not check_only:
+            catalog = await asyncio.to_thread(store.export)
+            if self.journal.get("status", {}).get("phase") in {"paused", "disabled"}:
+                return
+            if catalog.get("storage_channel_id") not in {
+                None,
+                self.settings.storage_channel,
+            }:
+                raise ValueError("Catalog and source channel do not match")
+            catalog["storage_channel_id"] = self.settings.storage_channel
+            validate_catalog(catalog)
+            job = {"catalog": catalog, "credentials": current_credentials}
+            self.journal.set("job", job)
+        if check_only:
+            # The recorded checkpoint is still confirmed while its health is
+            # checked; do not present an unchanged drive as copying files again.
+            self.journal.set("job", None)
+            self.update(phase="protected", current_file="", error=None)
+        else:
+            self.update(phase="syncing", error=None)
+        transport = self.factory(self.settings, config["token"])
+        try:
+            await transport.start()
+            await transport.inspect(self.settings.storage_channel)
+            await transport.inspect(config["channel"])
+            if check_only:
+                await transport.verify(
+                    config["channel"], point["backup_message_id"], point["bundle_size"]
+                )
+                current_pin = await transport.pinned_message(config["channel"])
+                if current_pin != point["backup_message_id"]:
+                    raise SettingsProblem(
+                        "The latest recovery checkpoint is no longer pinned. The "
+                        "confirmed restore point remains available by its recorded "
+                        "message ID. Inspect the backup channel before resuming.",
+                        code="REPLICA_PIN_CHANGED",
+                        status=409,
+                    )
+                phase = self.journal.get("status", {}).get("phase")
+                self.update(
+                    phase=phase if phase in {"paused", "disabled"} else "protected",
+                    error=None,
+                    checked_at=time.time(),
+                )
+                self._request_pacer.reset()
+                self.journal.set("job", None)
+                return
+            catalog = job["catalog"]
+            replica = await self._copy_catalog(transport, catalog, config["channel"])
+            if replica is None:
+                return
+            if self.journal.get("status", {}).get("phase") in {"paused", "disabled"}:
+                return
+            from tgdrive.replication.replica_mongo import mirror_mongodb
+
+            self.update(current_file="Preparing the database safety copy")
+            archive = await mirror_mongodb(
+                self,
+                transport,
+                source_channel=self.settings.storage_channel,
+                destination_channel=config["channel"],
+                revision=catalog["revision"],
+                settings_fingerprint=hashlib.sha256(
+                    json.dumps(job["credentials"], sort_keys=True).encode()
+                ).hexdigest(),
+            )
+            if self.journal.get("status", {}).get("phase") in {"paused", "disabled"}:
+                return
+            credentials = dict(job["credentials"])
+            if archive is not None:
+                credentials["mongodb_archive"] = archive
+                self.update(database_archive=archive)
+            await self._publish(
+                transport,
+                self.settings.storage_channel,
+                config["channel"],
+                catalog,
+                replica,
+                credentials,
+                self.key(),
+            )
+            self.journal.set(
+                "credentials_digest",
+                hashlib.sha256(
+                    json.dumps(job["credentials"], sort_keys=True).encode()
+                ).hexdigest(),
+            )
+            phase = self.journal.get("status", {}).get("phase")
+            self.update(
+                phase=phase if phase in {"paused", "disabled"} else "protected",
+                protected_revision=catalog["revision"],
+                last_success_at=now(),
+                current_file="",
+                error=None,
+                checked_at=time.time(),
+            )
+            self.report(
+                "info",
+                "Restore point confirmed in both channels "
+                f"at catalog revision {catalog['revision']}.",
+            )
+            self._request_pacer.reset()
+            self.journal.set("job", None)
+        finally:
+            await transport.close()
+
+    async def inspect_recovery(self, source, token, key, message_id=None):
+        transport = self.factory(self.settings, token)
+        path = self.directory / (".replica-inspect-" + secrets.token_hex(12))
+        try:
+            await transport.start()
+            await transport.inspect(source)
+            try:
+                inspected_id = await transport.download(source, message_id, path)
+            except Exception as error:
+                if getattr(error, "code", None) != "REPLICA_DOCUMENT_TYPE":
+                    raise
+                path.unlink(missing_ok=True)
+                inspected_id = await transport.download_catalog(
+                    source, path, message_id
+                )
+                from tgdrive.recovery.backup import decode_catalog_snapshot
+
+                catalog = decode_catalog_snapshot(read_private(path))
+                validate_catalog(catalog)
+                if catalog.get("storage_channel_id") != source:
+                    raise ValueError(
+                        "Catalog checkpoint belongs to another channel"
+                    ) from None
+                key = key or self.key()
+                if len(bytes.fromhex(key.strip())) != 32:
+                    raise ValueError(
+                        "Supply a 64-character hexadecimal recovery key"
+                    ) from None
+                bundle = {"credentials": await asyncio.to_thread(self._credentials)}
+                self.report(
+                    "warning",
+                    "A catalog-only checkpoint was selected. Keep the original "
+                    "SESSION_SECRET to preserve public share links. Application "
+                    "preferences and unfinished transfers are not included "
+                    "in this catalog.",
+                )
+            else:
+                if not key:
+                    raise ValueError(
+                        "Supply the offline key for this encrypted recovery bundle"
+                    )
+                bundle = decode_bundle(read_private(path), key)
+                catalog = next(
+                    (
+                        bundle[name]
+                        for name in ("replica_catalog", "catalog")
+                        if bundle[name].get("storage_channel_id") == source
+                    ),
+                    None,
+                )
+            if catalog is None:
+                raise ValueError(
+                    "This restore point does not belong to the selected channel"
+                )
+            current_store = getattr(self.runtime, "store", None)
+            if (
+                current_store is not None
+                and current_store.drive_id != catalog["drive_id"]
+            ):
+                raise ValueError(
+                    "The recovery point belongs to another drive. Preserve this "
+                    "installation and recover that drive separately."
+                )
+            self.journal.set(
+                "candidate",
+                {
+                    "catalog": catalog,
+                    "credentials": bundle["credentials"],
+                    "token": token,
+                    "key": key.strip(),
+                    "complete": False,
+                    "inspection": {
+                        "source_channel": source,
+                        "source_message_id": inspected_id,
+                        "revision": catalog["revision"],
+                        "created_at": now(),
+                    },
+                },
+            )
+            self.update(phase="paused", error=None)
+            self.report(
+                "info",
+                "Authenticated restore point inspected. "
+                "No live files or configuration changed.",
+            )
+        finally:
+            path.unlink(missing_ok=True)
+            await transport.close()
+        return self.status()
+
+    async def recover_to(
+        self, target, target_token, confirmation, *, catalog_only=False
+    ):
+        candidate = self.journal.get("candidate")
+        if not candidate or confirmation != str(target) or target >= 0:
+            raise SettingsProblem(
+                "Inspect a restore point, then type the new destination "
+                "channel ID exactly."
+            )
+        source = candidate["catalog"]["storage_channel_id"]
+        if source == target and not catalog_only:
+            raise SettingsProblem("Recovery requires a different destination channel.")
+        if catalog_only and target != source:
+            raise SettingsProblem(
+                "Database-only recovery must use the inspected surviving channel."
+            )
+        if (
+            not target_token
+            or target_token.split(":")[0] == candidate["token"].split(":")[0]
+        ):
+            raise SettingsProblem("Supply a new main bot distinct from the backup bot.")
+        registry = getattr(self.runtime, "registry", None)
+        if registry and any(
+            r.committed.status in {"queued", "running"} for r in registry.list()
+        ):
+            raise SettingsProblem(
+                "Cancel or finish all transfers before recovery. Their existing "
+                "channel references must not replay after recovery.",
+                status=409,
+            )
+        self.journal.set(
+            "recovery",
+            {
+                "target": target,
+                "target_token": target_token,
+                "catalog_only": catalog_only,
+            },
+        )
+        self.update(phase="recovering", error=None)
+        self.start()
+        self._wake.set()
+        return self.status()
+
+    async def _recover_copy(self, recovery):
+        if (
+            self.journal.get("status", {}).get("phase") in {"paused", "disabled"}
+            or self.journal.get("recovery") is None
+        ):
+            return
+        candidate = self.journal.get("candidate")
+        source = candidate["catalog"]["storage_channel_id"]
+        transport = self.factory(self.settings, candidate["token"])
+        try:
+            await transport.start()
+            await transport.inspect(source)
+            await transport.inspect(recovery["target"])
+            target_pin = await transport.pinned_message(recovery["target"])
+            if (
+                self.journal.get("status", {}).get("phase") in {"paused", "disabled"}
+                or self.journal.get("recovery") is None
+            ):
+                return
+            reservation = {
+                "drive_id": candidate["catalog"]["drive_id"],
+                "source": source,
+                "target": recovery["target"],
+            }
+            if (
+                not recovery.get("catalog_only")
+                and self.journal.get("recovery_destination") != reservation
+            ):
+                if target_pin is not None:
+                    raise SettingsProblem(
+                        "The replacement channel already has a pinned message. "
+                        "Use a new dedicated private channel.",
+                        status=409,
+                    )
+                self.journal.set("recovery_destination", reservation)
+            # Separately authenticate the replacement main bot before copying.
+            probe_settings = self.settings.model_copy(
+                update={"bot_tokens_csv": SecretStr("")}
+            )
+            probe = self.factory(probe_settings, recovery["target_token"])
+            try:
+                await probe.start()
+                await probe.inspect(recovery["target"])
+            finally:
+                await probe.close()
+            if (
+                self.journal.get("status", {}).get("phase") in {"paused", "disabled"}
+                or self.journal.get("recovery") is None
+            ):
+                return
+            self.update(phase="recovering", error=None)
+            if recovery.get("catalog_only"):
+                for node in files_in(candidate["catalog"]):
+                    for part in parts_in(node):
+                        if (
+                            self.journal.get("status", {}).get("phase")
+                            in {"paused", "disabled"}
+                            or self.journal.get("recovery") is None
+                        ):
+                            return
+                        await transport.verify(source, part["message_id"], part["size"])
+                restored = remap_catalog(
+                    candidate["catalog"],
+                    source,
+                    {
+                        str(p["message_id"]): p["message_id"]
+                        for n in files_in(candidate["catalog"])
+                        for p in parts_in(n)
+                    },
+                )
+            else:
+                restored = await self._copy_catalog(
+                    transport, candidate["catalog"], recovery["target"]
+                )
+            if restored is None:
+                return
+            if (
+                self.journal.get("status", {}).get("phase") in {"paused", "disabled"}
+                or self.journal.get("recovery") is None
+            ):
+                return
+            if (
+                target_pin is not None
+                and not recovery.get("catalog_only")
+                and not self.journal.owns_publication(recovery["target"], target_pin)
+            ):
+                await self._verify_recovery_pin(
+                    transport, recovery["target"], target_pin, candidate, restored
+                )
+            credentials = dict(
+                candidate["credentials"], bot_tokens=[recovery["target_token"]]
+            )
+            archive = credentials.get("mongodb_archive")
+            if archive and not recovery.get("catalog_only"):
+                source_id = (
+                    archive["replica_message_id"]
+                    if archive["replica_channel"] == source
+                    else archive["source_message_id"]
+                )
+                if source not in {
+                    archive["replica_channel"],
+                    archive["source_channel"],
+                }:
+                    raise ValueError(
+                        "The database archive is not bound to the surviving channel"
+                    )
+                identity = (
+                    f"recover-mongo:{source}:{source_id}:{recovery['target']}:"
+                    f"{archive['sha256']}"
+                )
+                random_id, receipt = self.journal.intent(identity, archive["size"])
+                if receipt is None:
+                    receipt = await transport.copy(
+                        source,
+                        source_id,
+                        recovery["target"],
+                        random_id=random_id,
+                        expected_size=archive["size"],
+                    )
+                    self.journal.confirm(identity, receipt)
+                else:
+                    await transport.verify(recovery["target"], receipt, archive["size"])
+                credentials["mongodb_archive"] = dict(
+                    archive,
+                    source_channel=source,
+                    source_message_id=source_id,
+                    replica_channel=recovery["target"],
+                    replica_message_id=receipt,
+                )
+            if (
+                self.journal.get("status", {}).get("phase") in {"paused", "disabled"}
+                or self.journal.get("recovery") is None
+            ):
+                return
+            if not recovery.get("catalog_only"):
+                await self._publish(
+                    transport,
+                    source,
+                    recovery["target"],
+                    candidate["catalog"],
+                    restored,
+                    credentials,
+                    candidate["key"],
+                )
+            if (
+                self.journal.get("status", {}).get("phase") in {"paused", "disabled"}
+                or self.journal.get("recovery") is None
+            ):
+                return
+            await self._publish_primary_catalog(transport, restored)
+            if (
+                self.journal.get("status", {}).get("phase") in {"paused", "disabled"}
+                or self.journal.get("recovery") is None
+            ):
+                return
+            if recovery.get("catalog_only"):
+                self.journal.set_many(
+                    {
+                        "restore_point": candidate["inspection"],
+                        "restore_point_key": candidate["key"],
+                        "restore_point_mongodb_key": credentials.get(
+                            "mongodb_backup_key"
+                        ),
+                        "credentials_digest": hashlib.sha256(
+                            json.dumps(credentials, sort_keys=True).encode()
+                        ).hexdigest(),
+                    }
+                )
+            candidate.update(catalog=restored, credentials=credentials, complete=True)
+            self.journal.set("candidate", candidate)
+            self.update(phase="ready_to_activate", current_file="", error=None)
+            self.report(
+                "info",
+                "All destination files and recovery metadata confirmed. "
+                "Review and activate to switch TGDrive.",
+            )
+        finally:
+            await transport.close()
+
+    def activate(self):
+        candidate = self.journal.get("candidate")
+        if not candidate or not candidate.get("complete"):
+            raise SettingsProblem(
+                "Complete and verify recovery before activation.", status=409
+            )
+        from tgdrive.replication.replica_activation import prepare_activation
+
+        prepare_activation(self.settings, candidate)
+        self.journal.set("activation", True)
+        self.update(phase="restart_required")
+        self.report(
+            "info",
+            "Recovery activation saved. Restart TGDrive; "
+            "the former catalog is preserved.",
+        )
+        return self.status()
+
+    def recovery_kit(self):
+        candidate = self.journal.get("candidate")
+        if candidate and not candidate.get("complete"):
+            key, point = candidate["key"], candidate.get("inspection")
+            mongodb_key = candidate["credentials"].get("mongodb_backup_key")
+        else:
+            key = self.journal.get("restore_point_key") or self.key()
+            point = self.journal.get("restore_point")
+            mongodb_key = self.journal.get("restore_point_mongodb_key")
+        return {
+            "format": "tgdrive-replica-key-v1",
+            "key": key,
+            "restore_point": point,
+            "next_backup_key": self.key(),
+            "mongodb_backup_key": mongodb_key,
+            "next_mongodb_backup_key": (
+                self.settings.mongodb_backup_key.get_secret_value()
+                if self.settings.mongodb_backup_key
+                else None
+            ),
+            "instructions": (
+                "Keep this file outside Telegram and the TGDrive server. "
+                "Paste key into "
+                "web recovery for the recorded restore point. Save an updated file "
+                "after a new confirmed backup. Never share it."
+            ),
+        }
+
+    async def _verify_recovery_pin(
+        self, transport, channel, message_id, candidate, restored
+    ):
+        path = self.directory / (".replica-pin-" + secrets.token_hex(12))
+        try:
+            try:
+                await transport.download(channel, message_id, path)
+            except Exception as error:
+                if getattr(error, "code", None) != "REPLICA_DOCUMENT_TYPE":
+                    raise
+                path.unlink(missing_ok=True)
+                await transport.download_catalog(channel, path, message_id)
+                from tgdrive.recovery.backup import decode_catalog_snapshot
+
+                matched = decode_catalog_snapshot(read_private(path)) == restored
+            else:
+                bundle = decode_bundle(read_private(path), candidate["key"])
+                matched = (
+                    bundle["catalog"] == candidate["catalog"]
+                    and bundle["replica_catalog"] == restored
+                )
+            if not matched:
+                raise ValueError(
+                    "The replacement channel pin changed outside this recovery. "
+                    "Nothing was activated."
+                )
+        finally:
+            path.unlink(missing_ok=True)
+
+    async def _publish_primary_catalog(self, transport, catalog):
+        raw = DriveStore._json_bytes(catalog)
+        digest = hashlib.sha256(raw).hexdigest()
+        path = self.directory / "replica-bundles" / (digest + ".json")
+        if not path.exists():
+            atomic_private(path, raw)
+        identity = f"primary-catalog:{catalog['storage_channel_id']}:{digest}"
+        random_id, message = self.journal.intent(identity, len(raw))
+        if message is None:
+            caption = (
+                f"TGDrive checkpoint v1\nDrive: {catalog['drive_id']}"
+                f"\nChannel: {catalog['storage_channel_id']}"
+                f"\nRevision: {catalog['revision']}\nSHA256: {digest}"
+            )
+            message = await transport.publish_catalog(
+                catalog["storage_channel_id"],
+                path,
+                random_id=random_id,
+                caption=caption,
+                pin=True,
+            )
+            self.journal.confirm(identity, message)
+        else:
+            await transport.verify(catalog["storage_channel_id"], message, len(raw))
+
+    def _mutation_config(self):
+        if self.blocked:
+            raise SettingsProblem(
+                "Channel recovery is in progress. Resume it or disable the "
+                "unfinished recovery before changing files.",
+                status=409,
+            )
+        config = self.journal.get("config", {})
+        if not config.get("enabled"):
+            return None
+        if self.journal.get("status", {}).get("phase") in {"paused", "disabled"}:
+            raise SettingsProblem(
+                "Resume independent backup before Telegram mutations, "
+                "or explicitly disable backup protection.",
+                status=409,
+            )
+        return config
+
+    async def before_mutation(self):
+        if self._mutation_config() is None:
+            return
+        async with self._operation:
+            config = self._mutation_config()
+            if config is None:
+                return
+            required = self.runtime.store.revision
+            for _ in range(2):
+                saved_retry_at = (
+                    self.journal.get("status", {}).get("error") or {}
+                ).get("retry_at", 0)
+                remaining_wait = saved_retry_at - time.time()
+                if remaining_wait > 0:
+                    from tgdrive.recovery.backup import BackupError
+
+                    # Reject outside the provider-error handler: a later check
+                    # must not turn the saved cooldown into a new deadline.
+                    raise BackupError(
+                        "Telegram requested a wait before backup resumes.",
+                        retry_after=remaining_wait,
+                    )
+                try:
+                    await self._sync(config, force_check=True)
+                except Exception as error:
+                    delay = getattr(error, "retry_after", None)
+                    if delay or getattr(error, "retryable", False):
+                        delay = max(5, float(delay or 30))
+                        phase = self.journal.get("status", {}).get("phase")
+                        self.update(
+                            phase=(
+                                phase if phase in {"paused", "disabled"} else "waiting"
+                            ),
+                            error={
+                                "code": getattr(error, "code", "REPLICA_WAIT"),
+                                "detail": (
+                                    "Telegram requested a wait before backup resumes."
+                                ),
+                                "action": (
+                                    "Leave TGDrive running or retry after the "
+                                    "displayed deadline."
+                                ),
+                                "retry_at": time.time() + delay,
+                            },
+                        )
+                    raise
+                if self._mutation_config() is None:
+                    return
+                if (
+                    self.journal.get("status", {}).get("protected_revision", 0)
+                    >= required
+                ):
+                    return
+        raise SettingsProblem(
+            "The required backup restore point is not confirmed. "
+            "Check backup status and retry.",
+            status=503,
+        )
diff --git a/tgdrive/replication/replica_activation.py b/tgdrive/replication/replica_activation.py
new file mode 100644
index 00000000..b7a6cc7a
--- /dev/null
+++ b/tgdrive/replication/replica_activation.py
@@ -0,0 +1,759 @@
+"""Explicit, replayable channel recovery activation at an owned startup boundary.
+
+Preparation never replaces a running catalog. Apply must run after the data-dir
+and Mongo owner locks, before opening catalog/jobs/upload handles. The existing
+MongoDB sessions and the replica journal are retained; sessions are never imported.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import os
+import re
+import secrets
+import stat
+
+from pydantic import SecretStr
+
+from tgdrive.core.config import Settings
+from tgdrive.recovery.backup import decode_catalog_snapshot
+from tgdrive.replication.replica_state import MAX_BUNDLE, atomic_private, read_private
+from tgdrive.settings.managed_settings import (
+    MAX_CLIENTS,
+    ManagedClient,
+    ManagedDocument,
+    SettingsProblem,
+    credential_id,
+    read_document,
+)
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.store import ROOT_ID, SCHEMA_VERSION, DriveStore
+
+MANIFEST = "channel-activation.json"
+_PHASES = {"prepared", "preserved", "installing", "catalog", "configured", "applied"}
+_MONGO_DOMAIN = ("nodes", "shares", "operations", "deletions", "preparations")
+_MONGO_ARCHIVE = (
+    *_MONGO_DOMAIN,
+    "catalog",
+    "settings",
+    "jobs",
+    "receipts",
+    "bot_folders",
+    "backups",
+)
+
+
+class ActivationError(SettingsProblem):
+    def __init__(self, detail):
+        super().__init__(detail, code="RECOVERY_ACTIVATION_FAILED", status=409)
+
+
+def _raw(value):
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    ).encode()
+
+
+def _digest(value):
+    return hashlib.sha256(_raw(value)).hexdigest()
+
+
+def _sync(directory):
+    fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def _document(credentials, revision):
+    clients = [
+        ManagedClient(
+            id=credential_id("bot", token),
+            label=f"Storage bot {index}",
+            kind="bot",
+            credential=SecretStr(token),
+        )
+        for index, token in enumerate(credentials["bot_tokens"], 1)
+    ]
+    # A restored channel has different access requirements. Old credentials are
+    # retained for owner review, but no old bot/Premium session is auto-enabled.
+    original = ManagedDocument.model_validate(credentials["managed_document"])
+    identifiers = {row.id for row in clients}
+    active = {row.credential.get_secret_value() for row in clients}
+    for row in original.clients:
+        if row.kind == "bot" and row.credential.get_secret_value() in active:
+            continue
+        if len(clients) >= MAX_CLIENTS:
+            # The full original remains in the private manifest/capsule.
+            break
+        identity = row.id
+        if identity in identifiers:
+            identity = (
+                "recovered-"
+                + hashlib.sha256(
+                    (row.kind + row.credential.get_secret_value()).encode()
+                ).hexdigest()[:24]
+            )
+        identifiers.add(identity)
+        clients.append(
+            row.model_copy(
+                update={
+                    "id": identity,
+                    "enabled": False,
+                    "runtime_name": None,
+                }
+            )
+        )
+    return ManagedDocument(
+        revision=revision,
+        api_id=credentials["api_id"],
+        api_hash=SecretStr(credentials["api_hash"]),
+        clients=clients,
+    )
+
+
+def _checked_settings(
+    settings, catalog, credentials, document=None, *, restore_mongodb_key=True
+):
+    restoring = document is None
+    if document is None:
+        document = _document(credentials, 1)
+    rows = [
+        row
+        for kind in ("bot", "user")
+        for row in document.clients
+        if row.kind == kind and row.enabled
+    ]
+    value = settings.model_dump(by_alias=True)
+    value.update(
+        {
+            "STORAGE_CHANNEL": catalog["storage_channel_id"],
+            "API_ID": document.api_id,
+            "API_HASH": document.api_hash,
+            "BOT_TOKENS": ",".join(
+                row.credential.get_secret_value() for row in rows if row.kind == "bot"
+            ),
+            "STRING_SESSIONS": ",".join(
+                row.credential.get_secret_value() for row in rows if row.kind == "user"
+            ),
+            "SESSION_SECRET": credentials["session_secret"],
+            "MAIN_BOT_TOKEN": None,  # nosec B105 # None clears the credential.
+            "managed_revision": document.revision if document is not None else 0,
+            "managed_client_ids": tuple(row.id for row in rows),
+            "managed_client_labels": tuple(row.label for row in rows),
+        }
+    )
+    if restore_mongodb_key and "mongodb_backup_key" in credentials:
+        value["MONGODB_BACKUP_KEY"] = credentials["mongodb_backup_key"]
+    if restoring:
+        for filename, policy in credentials["preferences"].items():
+            if filename == "transfer-preferences.json":
+                value["TELEGRAM_UPLOADS_PER_BOT"] = policy["uploads_per_bot"]
+            elif filename == "performance-preferences.json":
+                value.update({name.upper(): item for name, item in policy.items()})
+    # Init values outrank managed/environment sources. This applies every Settings
+    # validator and prevents model_copy from smuggling unvalidated credentials.
+    return Settings(_env_file=None, **value)
+
+
+def _candidate(settings, candidate):
+    try:
+        if not isinstance(candidate, dict) or candidate.get("complete") is not True:
+            raise ValueError
+        catalog = candidate["catalog"]
+        if (
+            not isinstance(catalog, dict)
+            or catalog.get("schema_version") != SCHEMA_VERSION
+        ):
+            raise ValueError
+        if (
+            type(catalog.get("storage_channel_id")) is not int
+            or catalog["storage_channel_id"] >= 0
+        ):
+            raise ValueError
+        validated = DriveStore._from_payload(catalog)
+        try:
+            catalog = validated.export()
+        finally:
+            validated.close()
+        # Never restore source-channel mutation receipts, including preparation
+        # request IDs which could accidentally replay from an old browser tab.
+        catalog["operations"] = []
+        catalog["deletions"] = []
+        catalog.pop("folder_preparations", None)
+        credentials = candidate["credentials"]
+        required = {
+            "api_id",
+            "api_hash",
+            "session_secret",
+            "bot_tokens",
+            "managed_document",
+            "preferences",
+        }
+        optional = {
+            "mongodb_backup_key",
+            "mongodb_archive",
+        }
+        if (
+            not isinstance(credentials, dict)
+            or not required <= set(credentials)
+            or set(credentials) - required - optional
+        ):
+            raise ValueError
+        from tgdrive.replication.replica_settings import (
+            POLICIES,
+            validate_recovery_settings,
+        )
+
+        validate_recovery_settings(credentials)
+        extras = {
+            name: copy.deepcopy(credentials[name])
+            for name in ("managed_document", "preferences", *optional)
+            if name in credentials
+        }
+        extras["preferences"] = {
+            name: POLICIES[name].model_validate(policy).model_dump()
+            for name, policy in extras["preferences"].items()
+        }
+        if "mongodb_backup_key" in extras:
+            extras["mongodb_backup_key"] = extras["mongodb_backup_key"].lower()
+        if type(credentials["api_id"]) is not int:
+            raise ValueError
+        if not isinstance(credentials["bot_tokens"], list) or not all(
+            isinstance(token, str) for token in credentials["bot_tokens"]
+        ):
+            raise ValueError
+        checked = _checked_settings(settings, catalog, credentials)
+        credentials = {
+            "api_id": checked.api_id,
+            "api_hash": checked.api_hash.get_secret_value(),
+            "session_secret": checked.session_secret.get_secret_value(),
+            "bot_tokens": list(checked.bot_tokens),
+            **extras,
+        }
+        token, key = candidate["token"], candidate["key"]
+        _document(dict(credentials, bot_tokens=[token]), 1)
+        if not isinstance(key, str) or not re.fullmatch(r"[0-9a-fA-F]{64}", key):
+            raise ValueError
+        return {
+            "catalog": catalog,
+            "credentials": credentials,
+            "complete": True,
+            "token": token,
+            "key": key.lower(),
+        }
+    except Exception:
+        raise ActivationError(
+            "Recovery activation data is invalid; nothing changed."
+        ) from None
+
+
+def _mongo_empty(backend, session):
+    root = backend.db.nodes.find_one({"_id": ROOT_ID}, session=session)
+    return (
+        bool(root and root.get("kind") == "folder" and root.get("parent_id") is None)
+        and backend.db.nodes.count_documents({}, session=session) == 1
+        and not any(
+            backend.db[name].find_one({}, session=session)
+            for name in _MONGO_DOMAIN
+            if name != "nodes"
+        )
+    )
+
+
+def _mongo_state(backend):
+    def read(session):
+        metadata = backend.db.catalog.find_one({"_id": "catalog"}, session=session)
+        if metadata is None:
+            if any(
+                backend.db[name].find_one({}, session=session) for name in _MONGO_DOMAIN
+            ):
+                raise ActivationError(
+                    "MongoDB contains orphaned catalog state; preserve and repair "
+                    "it first."
+                )
+            return {"kind": "missing"}
+        return {
+            "kind": "mongodb",
+            "drive_id": metadata.get("drive_id"),
+            "revision": metadata.get("revision"),
+            "channel": metadata.get("storage_channel_id"),
+            "digest": _digest(metadata),
+            "empty": _mongo_empty(backend, session),
+        }
+
+    return backend.transaction(read)
+
+
+def _source(settings, backend=None):
+    if backend is None:
+        from tgdrive.storage.mongo import for_settings
+
+        backend = for_settings(settings)
+    return _mongo_state(backend)
+
+
+def _compatible(expected, catalog):
+    if (
+        expected["kind"] == "mongodb"
+        and not expected["empty"]
+        and expected["drive_id"] != catalog["drive_id"]
+    ):
+        raise ActivationError(
+            "This installation contains a different drive. "
+            "Use a separate data directory."
+        )
+
+
+def _manifest_path(settings):
+    return settings.resolved_data_dir / MANIFEST
+
+
+def _mongodb_key_fingerprint(settings):
+    key = settings.mongodb_backup_key
+    return (
+        hashlib.sha256(bytes.fromhex(key.get_secret_value())).hexdigest()
+        if key is not None
+        else None
+    )
+
+
+def _activation_identity(value):
+    fields = (
+        "candidate",
+        "expected",
+        "settings_revision",
+        "settings_sha256",
+        "backend",
+        "mongodb_key_before_sha256",
+    )
+    return _digest({name: value[name] for name in fields})
+
+
+def _load(settings):
+    path = _manifest_path(settings)
+    if not path.exists() and not path.is_symlink():
+        return None
+    try:
+        value = decode_catalog_snapshot(read_private(path))
+        if (
+            not isinstance(value, dict)
+            or set(value)
+            != {
+                "version",
+                "id",
+                "candidate",
+                "expected",
+                "phase",
+                "settings_revision",
+                "settings_sha256",
+                "backend",
+                "mongodb_key_before_sha256",
+            }
+            or value["version"] != 1
+            or value["phase"] not in _PHASES
+        ):
+            raise ValueError
+        checked = _candidate(settings, value["candidate"])
+        if checked != value["candidate"] or value["backend"] != "mongodb":
+            raise ValueError
+        fingerprint = value["mongodb_key_before_sha256"]
+        if fingerprint is not None and (
+            not isinstance(fingerprint, str)
+            or re.fullmatch(r"[0-9a-f]{64}", fingerprint) is None
+        ):
+            raise ValueError
+        identity = _activation_identity(value)
+        if value["id"] != identity or not isinstance(value["expected"], dict):
+            raise ValueError
+        if (
+            type(value["settings_revision"]) is not int
+            or value["settings_revision"] < 0
+        ):
+            raise ValueError
+        return value
+    except Exception:
+        raise ActivationError(
+            "The private activation record is invalid. Preserve it and repeat "
+            "recovery inspection."
+        ) from None
+
+
+def _write(settings, value):
+    content = _raw(value)
+    if len(content) > MAX_BUNDLE:
+        raise ActivationError("Recovery activation exceeds the 64 MiB limit.")
+    atomic_private(_manifest_path(settings), content)
+
+
+def prepare_activation(settings, candidate):
+    """Persist intent only; current catalog/configuration remain untouched."""
+    checked = _candidate(settings, candidate)
+    existing = _load(settings)
+    if existing and existing["phase"] != "applied":
+        if existing["candidate"] == checked:
+            return existing["id"]
+        raise ActivationError(
+            "Another activation is pending. Restart and finish it before preparing "
+            "another."
+        )
+    expected = _source(settings)
+    _compatible(expected, checked["catalog"])
+    document = read_document(settings.resolved_data_dir)
+    value = {
+        "version": 1,
+        "candidate": checked,
+        "expected": expected,
+        "settings_revision": document.revision if document else 0,
+        "settings_sha256": hashlib.sha256(document.private_bytes()).hexdigest()
+        if document
+        else None,
+        "backend": "mongodb",
+        "mongodb_key_before_sha256": _mongodb_key_fingerprint(settings),
+        "phase": "prepared",
+    }
+    value["id"] = _activation_identity(value)
+    if existing:
+        atomic_private(
+            settings.resolved_data_dir / "recovery-archive" / existing["id"] / MANIFEST,
+            _raw(existing),
+        )
+    _write(settings, value)
+    return value["id"]
+
+
+def effective_settings(settings):
+    """Use recovery credentials before constructing pools and session managers."""
+    value = _load(settings)
+    if value is None:
+        return settings
+    candidate = value["candidate"]
+    try:
+        document = None
+        applied = value["phase"] == "applied"
+        if applied:
+            document = read_document(settings.resolved_data_dir)
+        fingerprint = _mongodb_key_fingerprint(settings)
+        rotated = (
+            applied
+            and fingerprint is not None
+            and fingerprint != value["mongodb_key_before_sha256"]
+        )
+        return _checked_settings(
+            settings,
+            candidate["catalog"],
+            candidate["credentials"],
+            document,
+            # Before activation, the capsule key always wins. Afterwards, a
+            # changed deployment key is an intentional rotation; an unchanged
+            # old key or missing key must not undo recovery.
+            restore_mongodb_key=not rotated,
+        )
+    except DatabaseUnavailable:
+        raise
+    except Exception:
+        raise ActivationError(
+            "The activated connection settings are invalid. Preserve local state "
+            "and repair the connection."
+        ) from None
+
+
+def _copy_file(source, destination):
+    if source.is_symlink() or destination.is_symlink():
+        raise ActivationError("Recovery preservation encountered an unsafe file path.")
+    if destination.exists():
+        return
+    source_fd = os.open(source, os.O_RDONLY | os.O_NOFOLLOW)
+    temporary = destination.with_name(
+        "." + destination.name + "-" + secrets.token_hex(12)
+    )
+    destination.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    try:
+        if not stat.S_ISREG(os.fstat(source_fd).st_mode):
+            raise ActivationError("Recovery preservation requires regular files.")
+        with (
+            os.fdopen(source_fd, "rb", closefd=False) as original,
+            os.fdopen(fd, "wb") as target,
+        ):
+            while chunk := original.read(1024**2):
+                target.write(chunk)
+            target.flush()
+            os.fsync(target.fileno())
+        os.replace(temporary, destination)
+        _sync(destination.parent)
+    finally:
+        os.close(source_fd)
+        temporary.unlink(missing_ok=True)
+
+
+def _archive_dir(directory, identity):
+    archive = directory
+    for name in ("recovery-archive", identity):
+        archive = archive / name
+        if archive.is_symlink():
+            raise ActivationError(
+                "The recovery archive path is unsafe; nothing changed."
+            )
+    return archive
+
+
+def _preserve_mongo(backend, archive):
+    from bson import json_util
+
+    destination = archive / "mongodb-before.json"
+    if destination.exists() or destination.is_symlink():
+        read_private(destination)
+        return
+    temporary = archive / (".mongodb-preserve-" + secrets.token_hex(12))
+
+    def snapshot(session):
+        backend.fence(session)
+        temporary.unlink(missing_ok=True)
+        fd = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        total = 0
+        with os.fdopen(fd, "wb") as target:
+
+            def write(content):
+                nonlocal total
+                total += len(content)
+                if total > MAX_BUNDLE:
+                    raise ActivationError(
+                        "MongoDB preservation exceeds the 64 MiB recovery limit."
+                    )
+                target.write(content)
+
+            write(b"{")
+            for index, name in enumerate(_MONGO_ARCHIVE):
+                if index:
+                    write(b",")
+                write(json.dumps(name).encode() + b":[")
+                for row_index, row in enumerate(
+                    backend.db[name].find({}, session=session)
+                ):
+                    if row_index:
+                        write(b",")
+                    write(json_util.dumps(row, separators=(",", ":")).encode())
+                write(b"]")
+            write(b"}")
+            target.flush()
+            os.fsync(target.fileno())
+
+    try:
+        backend.transaction(snapshot)
+        os.replace(temporary, destination)
+        _sync(archive)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _preserve(settings, value, backend):
+    directory = settings.resolved_data_dir
+    archive = _archive_dir(directory, value["id"])
+    archive.mkdir(parents=True, exist_ok=True, mode=0o700)
+    atomic_private(archive / MANIFEST, _raw(value))
+    bootstrap = directory / "replica-bootstrap.json"
+    if bootstrap.exists() or bootstrap.is_symlink():
+        _copy_file(bootstrap, archive / bootstrap.name)
+    _preserve_mongo(backend, archive)
+    return archive
+
+
+def _mongo_nodes(catalog):
+    from tgdrive.storage.mongo_store import MongoStore
+
+    stack = [(catalog["root"], None)]
+    rows = []
+    while stack:
+        node, parent = stack.pop()
+        values = {
+            key: copy.deepcopy(node[key])
+            for key in (
+                "upload_date",
+                "trashed",
+                "starred",
+                "message_id",
+                "size",
+                "parts",
+                "sha256",
+            )
+            if key in node
+        }
+        values["part_count"] = len(node.get("parts") or [None])
+        rows.append(
+            MongoStore._node(node["id"], parent, node["name"], node["type"], **values)
+        )
+        if node["type"] == "folder":
+            stack.extend((child, node["id"]) for child in node["children"].values())
+    return rows
+
+
+def _apply_mongo(settings, value, backend):
+    candidate = value["candidate"]
+    desired = _document(candidate["credentials"], value["settings_revision"] + 1)
+    connection_document = json.loads(desired.private_bytes())
+
+    def replace(session):
+        backend.fence(session)
+        before = backend.db.catalog.find_one({"_id": "catalog"}, session=session)
+        if before and before.get("replica_activation_id") == value["id"]:
+            return
+        # Read and compare inside the same fenced transaction as every replace.
+        if before is None:
+            current = {"kind": "missing"}
+        else:
+            current = {
+                "kind": "mongodb",
+                "drive_id": before.get("drive_id"),
+                "revision": before.get("revision"),
+                "channel": before.get("storage_channel_id"),
+                "digest": _digest(before),
+                "empty": _mongo_empty(backend, session),
+            }
+        if current != value["expected"]:
+            raise ActivationError(
+                "MongoDB metadata changed after recovery was prepared; nothing was "
+                "replaced."
+            )
+        current_settings = backend.db.settings.find_one(
+            {"_id": "telegram"}, session=session
+        )
+        if (current_settings["revision"] if current_settings else 0) != value[
+            "settings_revision"
+        ]:
+            raise ActivationError(
+                "Connection settings changed after recovery was prepared; nothing "
+                "was replaced."
+            )
+        settings_digest = (
+            hashlib.sha256(
+                ManagedDocument.model_validate(
+                    current_settings["document"]
+                ).private_bytes()
+            ).hexdigest()
+            if current_settings
+            else None
+        )
+        if settings_digest != value["settings_sha256"]:
+            raise ActivationError("Connection settings changed; nothing was replaced.")
+        for name in (*_MONGO_DOMAIN, "jobs", "receipts", "bot_folders", "backups"):
+            backend.db[name].delete_many({}, session=session)
+        nodes = _mongo_nodes(candidate["catalog"])
+        backend.db.nodes.insert_many(nodes, session=session)
+        shares = [
+            dict(row, _id=row["id"]) for row in candidate["catalog"].get("shares", [])
+        ]
+        if shares:
+            backend.db.shares.insert_many(shares, session=session)
+        metadata = {
+            "_id": "catalog",
+            "schema_version": SCHEMA_VERSION,
+            "drive_id": candidate["catalog"]["drive_id"],
+            "revision": candidate["catalog"]["revision"],
+            "backed_up_revision": candidate["catalog"]["revision"],
+            "storage_channel_id": candidate["catalog"]["storage_channel_id"],
+            "generation": (before or {}).get("generation", 0) + 1,
+            "replica_activation_id": value["id"],
+        }
+        backend.db.catalog.replace_one(
+            {"_id": "catalog"}, metadata, upsert=True, session=session
+        )
+        backend.db.settings.replace_one(
+            {"_id": "telegram"},
+            {
+                "_id": "telegram",
+                "revision": desired.revision,
+                "document": connection_document,
+            },
+            upsert=True,
+            session=session,
+        )
+        for filename, policy in candidate["credentials"]["preferences"].items():
+            identity = filename.removesuffix(".json")
+            backend.db.settings.replace_one(
+                {"_id": identity},
+                {"_id": identity, "document": policy},
+                upsert=True,
+                session=session,
+            )
+        bootstrap = backend.db.settings.find_one({"_id": "bootstrap"}, session=session)
+        if bootstrap:
+            bootstrap["document"].update(
+                {
+                    "STORAGE_CHANNEL": metadata["storage_channel_id"],
+                    "SESSION_SECRET": candidate["credentials"]["session_secret"],
+                }
+            )
+            if "mongodb_backup_key" in candidate["credentials"]:
+                bootstrap["document"]["MONGODB_BACKUP_KEY"] = candidate["credentials"][
+                    "mongodb_backup_key"
+                ]
+            backend.db.settings.replace_one(
+                {"_id": "bootstrap"}, bootstrap, session=session
+            )
+
+    backend.transaction(replace)
+    with backend._settings_lock:
+        backend._settings_cached = False
+        backend._settings_document = None
+
+
+def _check_connections(settings, value):
+    current = read_document(settings.resolved_data_dir)
+    revision = current.revision if current else 0
+    digest = hashlib.sha256(current.private_bytes()).hexdigest() if current else None
+    if revision != value["settings_revision"] or digest != value["settings_sha256"]:
+        raise ActivationError(
+            "Connection settings changed after recovery was prepared; "
+            "nothing was replaced. Inspect recovery again."
+        )
+
+
+def apply_activation(settings, mongo_backend=None):
+    """Apply once under startup ownership; any interrupted step is safe to replay."""
+    value = _load(settings)
+    if value is None or value["phase"] == "applied":
+        return False
+    if mongo_backend is None:
+        raise ActivationError(
+            "The configured recovery database is unavailable; no fallback was "
+            "attempted."
+        )
+    if value["phase"] == "prepared":
+        _check_connections(settings, value)
+        if _source(settings, mongo_backend) != value["expected"]:
+            raise ActivationError(
+                "Local metadata changed after recovery was prepared; nothing was "
+                "replaced."
+            )
+        _preserve(settings, value, mongo_backend)
+        value["phase"] = "preserved"
+        _write(settings, value)
+    if value["phase"] == "preserved":
+        _check_connections(settings, value)
+        if _source(settings, mongo_backend) != value["expected"]:
+            raise ActivationError(
+                "Local metadata changed during recovery preparation; nothing was "
+                "replaced."
+            )
+        # This durable boundary authorizes replay after an interrupted MongoDB
+        # transaction, with the previous state preserved above.
+        value["phase"] = "installing"
+        _write(settings, value)
+    if value["phase"] == "installing":
+        _apply_mongo(settings, value, mongo_backend)
+        value["phase"] = "catalog"
+        _write(settings, value)
+    if value["phase"] == "catalog":
+        value["phase"] = "configured"
+        _write(settings, value)
+    value["phase"] = "applied"
+    _write(settings, value)
+    return True
diff --git a/tgdrive/replication/replica_api.py b/tgdrive/replication/replica_api.py
new file mode 100644
index 00000000..d5ceda83
--- /dev/null
+++ b/tgdrive/replication/replica_api.py
@@ -0,0 +1,178 @@
+"""Owner-only optional replica controls, including recovery-only startup."""
+
+from __future__ import annotations
+
+import json
+
+from fastapi import Depends, HTTPException, Request, Response
+from pydantic import Field, SecretStr, StrictBool
+
+from tgdrive.settings.managed_settings import PrivateModel, SettingsProblem
+
+
+class ConfigureReplica(PrivateModel):
+    channel_id: int = Field(lt=0)
+    bot_token: SecretStr = Field(min_length=20, max_length=256)
+    independent_accounts: StrictBool
+
+
+class ReplicaAction(PrivateModel):
+    action: str = Field(max_length=32)
+
+
+class RecoverReplica(PrivateModel):
+    source_channel: int | None = Field(default=None, lt=0)
+    bot_token: SecretStr | None = Field(default=None, min_length=20, max_length=256)
+    key: SecretStr | None = Field(default=None, min_length=64, max_length=64)
+    message_id: int | None = Field(default=None, gt=0)
+    target_channel: int | None = Field(default=None, lt=0)
+    target_bot_token: SecretStr | None = Field(
+        default=None, min_length=20, max_length=256
+    )
+    confirm_channel: str = Field(default="", max_length=32)
+    activate: StrictBool = False
+    catalog_only: StrictBool = False
+
+
+def register_replica_routes(app, settings, require_admin, get_runtime):
+    def service(request):
+        runtime = get_runtime(request)
+        if getattr(runtime, "replica", None) is None:
+            from tgdrive.replication.replica import ChannelReplica
+
+            runtime.replica = ChannelReplica(settings, runtime)
+        return runtime.replica
+
+    async def invoke(operation):
+        try:
+            return await operation
+        except SettingsProblem:
+            raise
+        except Exception as error:
+            from tgdrive.replication.replica_transport import ReplicaTransportError
+
+            detail = (
+                str(error)
+                if isinstance(error, (ReplicaTransportError, ValueError))
+                else "Backup operation could not be verified. "
+                "Review channel access and try again."
+            )
+            raise HTTPException(422, detail) from None
+
+    admin = [Depends(require_admin)]
+
+    @app.get("/api/v1/replica", dependencies=admin)
+    async def status(request: Request, response: Response):
+        response.headers["Cache-Control"] = "no-store"
+        return service(request).status()
+
+    @app.post("/api/v1/replica/configure", dependencies=admin)
+    async def configure(payload: ConfigureReplica, request: Request):
+        current = service(request)
+        if getattr(get_runtime(request), "store", None) is None:
+            raise HTTPException(
+                409, "Restore the existing catalog before configuring a new backup."
+            )
+        async with current.control:
+            if current._operation.locked():
+                raise HTTPException(
+                    409, "Pause and wait for the current part to finish first."
+                )
+            async with current._operation:
+                return await invoke(
+                    current.configure(
+                        payload.channel_id,
+                        payload.bot_token.get_secret_value(),
+                        payload.independent_accounts,
+                    )
+                )
+
+    @app.post("/api/v1/replica/action", dependencies=admin)
+    async def action(payload: ReplicaAction, request: Request):
+        current = service(request)
+        async with current.control:
+            return await invoke(current.action(payload.action))
+
+    @app.get("/api/v1/replica/key", dependencies=admin)
+    async def key(request: Request):
+        current = service(request)
+        return Response(
+            json.dumps(current.recovery_kit()),
+            media_type="application/json",
+            headers={
+                "Cache-Control": "no-store",
+                "Content-Disposition": (
+                    'attachment; filename="tgdrive-channel-recovery-key.json"'
+                ),
+            },
+        )
+
+    @app.get("/api/v1/replica/report", dependencies=admin)
+    async def report(request: Request):
+        return Response(
+            json.dumps(service(request).status(), ensure_ascii=False),
+            media_type="application/json",
+            headers={
+                "Cache-Control": "no-store",
+                "Content-Disposition": (
+                    'attachment; filename="tgdrive-channel-backup-report.json"'
+                ),
+            },
+        )
+
+    @app.post("/api/v1/replica/recover", dependencies=admin)
+    async def recover(payload: RecoverReplica, request: Request):
+        current = service(request)
+        async with current.control:
+            if current._operation.locked():
+                raise HTTPException(
+                    409, "Pause and wait for the current part to finish first."
+                )
+            async with current._operation:
+                if payload.activate:
+                    candidate = current.journal.get("candidate")
+                    if candidate and candidate.get("complete"):
+                        catalog = candidate.get("catalog")
+                        destination = (
+                            catalog.get("storage_channel_id")
+                            if isinstance(catalog, dict)
+                            else None
+                        )
+                        if type(destination) is not int or destination >= 0:
+                            raise SettingsProblem(
+                                "The recovery destination is invalid. "
+                                "Inspect recovery again.",
+                                status=409,
+                            )
+                        if payload.confirm_channel != str(destination):
+                            raise SettingsProblem(
+                                "Type the recovered destination channel ID "
+                                "to confirm activation.",
+                                status=422,
+                            )
+                    return current.activate()
+                if payload.target_channel is not None:
+                    return await invoke(
+                        current.recover_to(
+                            payload.target_channel,
+                            payload.target_bot_token.get_secret_value()
+                            if payload.target_bot_token
+                            else "",
+                            payload.confirm_channel,
+                            catalog_only=payload.catalog_only,
+                        )
+                    )
+                if payload.source_channel is None or payload.bot_token is None:
+                    raise HTTPException(
+                        422,
+                        "Supply the surviving channel, its backup bot "
+                        "and the offline recovery key.",
+                    )
+                return await invoke(
+                    current.inspect_recovery(
+                        payload.source_channel,
+                        payload.bot_token.get_secret_value(),
+                        payload.key.get_secret_value() if payload.key else None,
+                        payload.message_id,
+                    )
+                )
diff --git a/tgdrive/replication/replica_bootstrap.py b/tgdrive/replication/replica_bootstrap.py
new file mode 100644
index 00000000..f18bdb7a
--- /dev/null
+++ b/tgdrive/replication/replica_bootstrap.py
@@ -0,0 +1,66 @@
+"""Portable recovery credentials validated against the configured MongoDB backend."""
+
+from __future__ import annotations
+
+import json
+
+from argon2 import PasswordHasher
+
+from tgdrive.replication.replica_state import atomic_private, read_private
+
+FIELDS = {
+    "API_ID",
+    "API_HASH",
+    "BOT_TOKENS",
+    "STORAGE_CHANNEL",
+    "SESSION_SECRET",
+    "ADMIN_PASSWORD_HASH",
+}
+
+
+def save_bootstrap(settings):
+    password = settings.admin_password_hash
+    password_hash = (
+        password.get_secret_value()
+        if password
+        else PasswordHasher().hash(settings.admin_password.get_secret_value())
+    )
+    values = {
+        "API_ID": settings.api_id,
+        "API_HASH": settings.api_hash.get_secret_value(),
+        "BOT_TOKENS": settings.bot_tokens_csv.get_secret_value(),
+        "STORAGE_CHANNEL": settings.storage_channel,
+        "SESSION_SECRET": settings.session_secret.get_secret_value(),
+        "ADMIN_PASSWORD_HASH": password_hash,
+    }
+    atomic_private(
+        settings.resolved_data_dir / "replica-bootstrap.json",
+        json.dumps({"version": 1, "settings": values}).encode(),
+    )
+
+
+def load_bootstrap(directory, *, mongodb_uri, mongodb_database="tgdrive"):
+    path = directory / "replica-bootstrap.json"
+    if not path.exists():
+        return None
+    payload = json.loads(read_private(path, maximum=64 * 1024))
+    if not isinstance(payload, dict) or set(payload) != {"version", "settings"}:
+        raise ValueError("Invalid private recovery bootstrap")
+    values = payload["settings"]
+    if payload["version"] != 1 or not isinstance(values, dict) or set(values) != FIELDS:
+        raise ValueError("Invalid private recovery bootstrap")
+    if type(values["API_ID"]) is not int or type(values["STORAGE_CHANNEL"]) is not int:
+        raise ValueError("Invalid private recovery bootstrap")
+    from tgdrive.core.config import Settings
+
+    # Explicit injected API credentials bypass managed-source lookup; validation
+    # never connects to MongoDB or Telegram, and never echoes rejected secrets.
+    Settings(
+        _env_file=None,
+        **values,
+        MONGODB_URI=mongodb_uri,
+        MONGODB_DATABASE=mongodb_database,
+        DATA_DIR=directory,
+        CACHE_DIR=directory.parent / "recovery-validation-cache",
+    )
+    return values
diff --git a/tgdrive/replication/replica_mongo.py b/tgdrive/replication/replica_mongo.py
new file mode 100644
index 00000000..8b3ad92f
--- /dev/null
+++ b/tgdrive/replication/replica_mongo.py
@@ -0,0 +1,263 @@
+"""Mirror confirmed encrypted MongoDB archives without downloading originals.
+
+The portable channel catalog remains the automatic recovery point. This extra
+archive retains the independently consistent full MongoDB snapshot for advanced
+recovery, including app settings and records not replayed during channel failover.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import math
+import os
+import re
+import stat
+from pathlib import Path
+
+from tgdrive.recovery.mongo_backup import MAGIC, MAX_EXPANDED
+from tgdrive.settings.managed_settings import SettingsProblem
+
+
+def _check_pending_key(service, configured, key):
+    """A resumed immutable ciphertext must match the key placed in the capsule.
+
+    Pending snapshots have no key fingerprint. Authenticate their staged
+    ciphertext in bounded blocks before allowing a resumed publication;
+    do not expand, rewrite or discard the pending database archive.
+    """
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+    backend = getattr(service, "backend", None)
+    if backend is None:
+        return
+    pending = backend.db.backups.find_one(
+        {"status": "pending"}, sort=[("created_at", 1)]
+    )
+    if pending is None:
+        return
+    path = Path(pending["local_path"])
+    if not path.exists():
+        return  # Existing MongoProtection will mark this interrupted safely.
+    root = configured.resolved_cache_dir / "mongo-backups"
+    if path.is_symlink() or not path.resolve().is_relative_to(root.resolve()):
+        raise SettingsProblem("The staged MongoDB safety copy path is invalid.")
+    descriptor = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+    try:
+        info = os.fstat(descriptor)
+        if (
+            not stat.S_ISREG(info.st_mode)
+            or not len(MAGIC) + 28 <= info.st_size <= MAX_EXPANDED
+        ):
+            raise ValueError
+        with os.fdopen(descriptor, "rb", closefd=False) as source:
+            if source.read(len(MAGIC)) != MAGIC:
+                raise ValueError
+            nonce = source.read(12)
+            source.seek(-16, os.SEEK_END)
+            tag = source.read(16)
+            decoder = Cipher(
+                algorithms.AES(bytes.fromhex(key)), modes.GCM(nonce, tag)
+            ).decryptor()
+            decoder.authenticate_additional_data(MAGIC)
+            source.seek(len(MAGIC) + 12)
+            remaining = info.st_size - len(MAGIC) - 28
+            while remaining:
+                block = source.read(min(1024**2, remaining))
+                if not block:
+                    raise ValueError
+                decoder.update(block)
+                remaining -= len(block)
+            decoder.finalize()
+    except Exception:
+        raise SettingsProblem(
+            "The pending MongoDB archive does not authenticate with the current "
+            "recovery key. Preserve it and restore its original key before "
+            "retrying; no existing archive was changed.",
+            code="REPLICA_MONGODB_KEY_MISMATCH",
+            status=409,
+        ) from None
+    finally:
+        os.close(descriptor)
+
+
+async def mirror_mongodb(
+    replica,
+    transport,
+    *,
+    source_channel: int,
+    destination_channel: int,
+    revision: int | None = None,
+    settings_fingerprint: str | None = None,
+):
+    if replica.journal.get("status", {}).get("phase") in {"paused", "disabled"}:
+        return None
+    backend = getattr(replica.runtime, "mongo", None)
+    if backend is None:
+        return None
+    configured = replica.settings
+    secret = getattr(configured, "mongodb_backup_key", None)
+    if secret is None:
+        raise SettingsProblem(
+            "Full MongoDB safety copies require MONGODB_BACKUP_KEY. Preserve the "
+            "existing database, configure its recovery key, save an independent "
+            "copy and restart before retrying channel backup.",
+            code="REPLICA_MONGODB_KEY_REQUIRED",
+            status=409,
+        )
+    key = secret.get_secret_value()
+    if re.fullmatch(r"[0-9a-fA-F]{64}", key) is None:
+        raise SettingsProblem("The MongoDB recovery key is invalid.")
+    if (
+        source_channel != configured.storage_channel
+        or source_channel == destination_channel
+        or type(destination_channel) is not int
+        or not -(1 << 63) <= destination_channel < 0
+    ):
+        raise SettingsProblem("MongoDB safety copy channels do not match this drive.")
+    store = replica.runtime.store
+    required = store.revision if revision is None else revision
+    if type(required) is not int or not 0 < required <= store.revision:
+        raise SettingsProblem("The requested MongoDB backup revision is invalid.")
+    if settings_fingerprint is not None and (
+        not isinstance(settings_fingerprint, str)
+        or re.fullmatch(r"[0-9a-fA-F]{64}", settings_fingerprint) is None
+    ):
+        raise SettingsProblem("The saved settings fingerprint is invalid.")
+    fingerprint = hashlib.sha256(bytes.fromhex(key)).hexdigest()
+    cache_key = (
+        f"mongo-snapshot:{store.drive_id}:{source_channel}:{destination_channel}:"
+        f"{required}:{fingerprint}"
+    )
+    if settings_fingerprint is not None:
+        # Policy/connection edits do not necessarily advance catalog revision.
+        # Retain their captured identity through retries, but require a fresh
+        # full database snapshot for the next changed settings generation.
+        cache_key += ":settings:" + settings_fingerprint.lower()
+    archive = replica.journal.get(cache_key)
+    if archive is None:
+        service = replica.runtime.backup
+        # Use the existing service and its publication lock. Never introduce a
+        # second snapshot writer or temporarily replace its configured key.
+        for _ in range(2):
+            await asyncio.to_thread(_check_pending_key, service, configured, key)
+            try:
+                await service.snapshot_now(store)
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:
+                from tgdrive.replication.replica_transport import ReplicaTransportError
+
+                delay = getattr(error, "retry_after", None) or getattr(
+                    error, "seconds", None
+                )
+                if type(delay) in (int, float) and math.isfinite(delay) and delay > 0:
+                    raise ReplicaTransportError(
+                        "Telegram requested a wait before the full database "
+                        "backup resumes.",
+                        "REPLICA_FLOOD_WAIT",
+                        retry_after=max(1, delay),
+                        retryable=True,
+                    ) from None
+                if (
+                    isinstance(error, (TimeoutError, OSError))
+                    or getattr(error, "timeout", False) is True
+                ):
+                    raise ReplicaTransportError(
+                        "The full database safety copy could not be confirmed. "
+                        "It will retry when connectivity returns.",
+                        "REPLICA_MONGODB_UNAVAILABLE",
+                        retryable=True,
+                    ) from None
+                raise SettingsProblem(
+                    "The full MongoDB safety copy failed. Check database access, "
+                    "the recovery key, temporary storage and Telegram permissions, "
+                    "then retry. Existing confirmed backups are retained.",
+                    code="REPLICA_MONGODB_SNAPSHOT_FAILED",
+                    status=503,
+                ) from None
+            rows = await asyncio.to_thread(service.history, limit=100)
+            latest = next(
+                (
+                    row
+                    for row in rows
+                    if row.get("status") == "confirmed"
+                    and row.get("channel_id") == source_channel
+                    and row.get("format") == "mongodb-encrypted-v1"
+                    and type(row.get("revision")) is int
+                    and row["revision"] >= required
+                ),
+                None,
+            )
+            if latest is not None:
+                break
+        else:
+            raise SettingsProblem(
+                "A current full MongoDB safety copy has not been confirmed. "
+                "Retry after the database snapshot finishes.",
+                code="REPLICA_MONGODB_SNAPSHOT_PENDING",
+                status=503,
+            )
+        identity = latest.get("id")
+        message_id = latest.get("message_id")
+        digest = latest.get("sha256")
+        if (
+            not isinstance(identity, str)
+            or re.fullmatch(r"[A-Za-z0-9_-]{1,128}", identity) is None
+            or type(message_id) is not int
+            or not 0 < message_id < 2**31
+            or not isinstance(digest, str)
+            or re.fullmatch(r"[0-9a-f]{64}", digest) is None
+        ):
+            raise SettingsProblem("The confirmed MongoDB snapshot record is invalid.")
+        async with replica.runtime.pool.lease() as client:
+            message = await client.get_messages(source_channel, message_ids=message_id)
+        document = getattr(message, "document", None)
+        size = getattr(document, "file_size", None)
+        if (
+            type(size) is not int
+            or not 0 < size <= MAX_EXPANDED
+            or getattr(document, "file_name", None) != "tgdrive-" + identity + ".tgdb"
+        ):
+            raise SettingsProblem(
+                "The full MongoDB archive is missing or differs from its "
+                "confirmed record. Preserve existing backups and retry.",
+                code="REPLICA_MONGODB_ARCHIVE_MISSING",
+                status=409,
+            )
+        archive = {
+            "format": "mongodb-encrypted-v1",
+            "id": identity,
+            "revision": latest["revision"],
+            "source_channel": source_channel,
+            "source_message_id": message_id,
+            "replica_channel": destination_channel,
+            "size": size,
+            "sha256": digest,
+            "created_at": latest.get("created_at"),
+        }
+        # Persist exactly which confirmed source ciphertext will be copied.
+        replica.journal.set(cache_key, archive)
+    if replica.journal.get("status", {}).get("phase") in {"paused", "disabled"}:
+        return None
+    copy_key = (
+        f"mongo-copy:{store.drive_id}:{source_channel}:{destination_channel}:"
+        f"{archive['source_message_id']}:{archive['size']}:{archive['sha256']}"
+    )
+    operation_id, receipt = replica.journal.intent(copy_key, archive["size"])
+    if receipt is None:
+        receipt = await transport.copy(
+            source_channel,
+            archive["source_message_id"],
+            destination_channel,
+            random_id=operation_id,
+            expected_size=archive["size"],
+        )
+        replica.journal.confirm(copy_key, receipt)
+    else:
+        await transport.verify(destination_channel, receipt, archive["size"])
+    result = archive | {"replica_message_id": receipt}
+    from tgdrive.replication.replica_settings import validate_recovery_settings
+
+    validate_recovery_settings({"mongodb_archive": result, "mongodb_backup_key": key})
+    return result
diff --git a/tgdrive/replication/replica_settings.py b/tgdrive/replication/replica_settings.py
new file mode 100644
index 00000000..2ce6d092
--- /dev/null
+++ b/tgdrive/replication/replica_settings.py
@@ -0,0 +1,157 @@
+"""Bounded saved-domain settings carried inside encrypted recovery capsules."""
+
+from __future__ import annotations
+
+import json
+
+from tgdrive.settings.bot_settings import BotUploadPreferences
+from tgdrive.settings.managed_settings import (
+    MAX_SETTINGS_BYTES,
+    ManagedDocument,
+    initial_clients,
+    read_document,
+)
+from tgdrive.settings.performance_preferences import (
+    PerformancePreferences,
+    PerformanceSettings,
+)
+from tgdrive.settings.transfer_preferences import TransferPreferences, UploadPreferences
+
+POLICIES = {
+    "performance-preferences.json": PerformancePreferences,
+    "transfer-preferences.json": UploadPreferences,
+    "bot-preferences.json": BotUploadPreferences,
+}
+MAX_SETTINGS_TOTAL = 256 * 1024
+
+
+def collect_credentials(settings, runtime):
+    """Capture saved application policies, never deployment paths or DB URI.
+
+    This synchronous snapshot should run in a worker thread. Schema validation
+    and byte bounds apply to saved records; a malformed saved policy cannot
+    silently be omitted from a claimed complete recovery capsule.
+    """
+    credentials = {
+        "api_id": settings.api_id,
+        "api_hash": settings.api_hash.get_secret_value(),
+        "session_secret": settings.session_secret.get_secret_value(),
+        "bot_tokens": list(settings.bot_tokens),
+    }
+    document = read_document(settings.resolved_data_dir)
+    if document is None:
+        document = ManagedDocument(
+            revision=max(1, settings.managed_revision),
+            api_id=settings.api_id,
+            api_hash=settings.api_hash,
+            clients=initial_clients(settings),
+        )
+    credentials["managed_document"] = json.loads(document.private_bytes())
+    backend = runtime.mongo
+    preferences = {}
+    for filename, model in POLICIES.items():
+        row = backend.db.settings.find_one({"_id": filename.removesuffix(".json")})
+        raw = row["document"] if row else None
+        if raw is None:
+            if model is PerformancePreferences:
+                raw = PerformanceSettings(settings, runtime).value.model_dump()
+            elif model is BotUploadPreferences:
+                raw = BotUploadPreferences().model_dump()
+            else:
+                raw = {"uploads_per_bot": TransferPreferences(settings, runtime)._value}
+        if len(json.dumps(raw, allow_nan=False).encode()) > MAX_SETTINGS_BYTES:
+            raise ValueError("Saved application policy exceeds the recovery size limit")
+        if model is PerformancePreferences:
+            raw = PerformanceSettings(settings, runtime).value.model_dump() | raw
+        preferences[filename] = model.model_validate(raw).model_dump()
+    credentials["preferences"] = preferences
+    key = getattr(settings, "mongodb_backup_key", None)
+    if key is not None:
+        credentials["mongodb_backup_key"] = key.get_secret_value()
+    if len(json.dumps(credentials, allow_nan=False).encode()) > MAX_SETTINGS_TOTAL:
+        raise ValueError("Saved recovery settings exceed the bounded size limit")
+    return credentials
+
+
+def validate_recovery_settings(credentials):
+    """Validate bounded application settings and optional database archive details."""
+    if "managed_document" in credentials:
+        raw = credentials["managed_document"]
+        if len(json.dumps(raw, allow_nan=False).encode()) > MAX_SETTINGS_BYTES:
+            raise ValueError
+        # PrivateModel normally allows coercion. Serialized capsules must carry
+        # actual scalar types so booleans cannot impersonate API/revision IDs.
+        if (
+            not isinstance(raw, dict)
+            or type(raw.get("api_id")) is not int
+            or type(raw.get("revision")) is not int
+            or type(raw.get("schema_version")) is not int
+            or not isinstance(raw.get("clients"), list)
+            or any(
+                not isinstance(row, dict) or type(row.get("enabled", True)) is not bool
+                for row in raw["clients"]
+            )
+        ):
+            raise ValueError
+        document = ManagedDocument.model_validate(raw)
+        if json.loads(document.private_bytes()) != raw:
+            raise ValueError
+    if "preferences" in credentials:
+        raw = credentials["preferences"]
+        if not isinstance(raw, dict) or set(raw) != set(POLICIES):
+            raise ValueError
+        for filename, value in raw.items():
+            if len(json.dumps(value, allow_nan=False).encode()) > MAX_SETTINGS_BYTES:
+                raise ValueError
+            POLICIES[filename].model_validate(value)
+    if "mongodb_archive" in credentials:
+        import re
+
+        from tgdrive.storage.store import _validate_timestamp
+
+        archive = credentials["mongodb_archive"]
+        if not isinstance(archive, dict) or set(archive) != {
+            "format",
+            "id",
+            "revision",
+            "source_channel",
+            "source_message_id",
+            "replica_channel",
+            "replica_message_id",
+            "size",
+            "sha256",
+            "created_at",
+        }:
+            raise ValueError
+        if archive["format"] != "mongodb-encrypted-v1":
+            raise ValueError
+        if (
+            not isinstance(archive["id"], str)
+            or re.fullmatch(r"[A-Za-z0-9_-]{1,128}", archive["id"]) is None
+            or type(archive["revision"]) is not int
+            or not 0 < archive["revision"] < 2**63
+            or type(archive["size"]) is not int
+            or not 0 < archive["size"] <= 1024**3
+            or not isinstance(archive["sha256"], str)
+            or re.fullmatch(r"[0-9a-f]{64}", archive["sha256"]) is None
+        ):
+            raise ValueError
+        for name in ("source_channel", "replica_channel"):
+            if type(archive[name]) is not int or not -(1 << 63) <= archive[name] < 0:
+                raise ValueError
+        for name in ("source_message_id", "replica_message_id"):
+            if type(archive[name]) is not int or not 0 < archive[name] < 2**31:
+                raise ValueError
+        if archive["source_channel"] == archive["replica_channel"]:
+            raise ValueError
+        _validate_timestamp(archive["created_at"])
+        if "mongodb_backup_key" not in credentials:
+            raise ValueError
+    if "mongodb_backup_key" in credentials:
+        import re
+
+        key = credentials["mongodb_backup_key"]
+        if not isinstance(key, str) or re.fullmatch(r"[0-9a-fA-F]{64}", key) is None:
+            raise ValueError
+    if len(json.dumps(credentials, allow_nan=False).encode()) > MAX_SETTINGS_TOTAL:
+        raise ValueError
diff --git a/tgdrive/replication/replica_state.py b/tgdrive/replication/replica_state.py
new file mode 100644
index 00000000..484132d3
--- /dev/null
+++ b/tgdrive/replication/replica_state.py
@@ -0,0 +1,317 @@
+"""Private durable replica journal and bounded, authenticated recovery bundles."""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import secrets
+import sqlite3
+import threading
+from pathlib import Path
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from tgdrive.recovery.backup import decode_catalog_snapshot
+from tgdrive.storage.store import DriveStore
+
+MAGIC = b"TGDRIVE-REPLICA-1\n"
+MAX_BUNDLE = 64 * 1024**2
+
+
+def atomic_private(path: Path, content: bytes):
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    temporary = path.with_name("." + path.name + "-" + secrets.token_hex(12))
+    fd = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    try:
+        with os.fdopen(fd, "wb") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temporary, path)
+        directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def read_private(path: Path, *, maximum=MAX_BUNDLE):
+    fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW)
+    try:
+        info = os.fstat(fd)
+        import stat
+
+        if not stat.S_ISREG(info.st_mode) or info.st_size > maximum:
+            raise ValueError("Invalid private recovery file")
+        if info.st_mode & 0o077:
+            raise ValueError("Recovery files must have mode 0600")
+        with os.fdopen(fd, "rb", closefd=False) as source:
+            return source.read(maximum + 1)
+    finally:
+        os.close(fd)
+
+
+class ReplicaJournal:
+    def __init__(self, directory: Path):
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        path = directory / "channel-backup.sqlite3"
+        if path.is_symlink():
+            raise ValueError("Unsafe backup journal path")
+        self.db = sqlite3.connect(path, check_same_thread=False)
+        path.chmod(0o600)
+        self.lock = threading.RLock()
+        self.db.execute("PRAGMA journal_mode=WAL")
+        self.db.execute("PRAGMA synchronous=FULL")
+        self.db.executescript("""
+            CREATE TABLE IF NOT EXISTS state(key TEXT PRIMARY KEY, value TEXT NOT NULL);
+            CREATE TABLE IF NOT EXISTS copies(
+                key TEXT PRIMARY KEY, random_id INTEGER NOT NULL,
+                message_id INTEGER, size INTEGER NOT NULL
+            );
+        """)
+        self.db.commit()
+
+    def get(self, key, default=None):
+        with self.lock:
+            row = self.db.execute(
+                "SELECT value FROM state WHERE key=?", (key,)
+            ).fetchone()
+            return json.loads(row[0]) if row else copy.deepcopy(default)
+
+    def set(self, key, value):
+        self.set_many({key: value})
+
+    def set_many(self, values):
+        """Commit related state together, including explicit null values."""
+        rows = [
+            (key, json.dumps(value, allow_nan=False, ensure_ascii=False))
+            for key, value in values.items()
+        ]
+        with self.lock, self.db:
+            self.db.executemany(
+                "INSERT INTO state VALUES(?,?) ON CONFLICT(key) "
+                "DO UPDATE SET value=excluded.value",
+                rows,
+            )
+
+    def intent(self, key, size):
+        with self.lock, self.db:
+            self.db.execute(
+                "INSERT OR IGNORE INTO copies VALUES(?,?,NULL,?)",
+                (key, secrets.randbelow(2**63 - 1) + 1, size),
+            )
+            row = self.db.execute(
+                "SELECT random_id,message_id,size FROM copies WHERE key=?", (key,)
+            ).fetchone()
+            if row[2] != size:
+                raise ValueError("Replica intent size changed")
+            return row[0], row[1]
+
+    def confirm(self, key, message_id):
+        if type(message_id) is not int or message_id <= 0:
+            raise ValueError("Invalid replica confirmation")
+        with self.lock, self.db:
+            self.db.execute(
+                "UPDATE copies SET message_id=? WHERE key=?", (message_id, key)
+            )
+
+    def owns_publication(self, channel, message_id):
+        with self.lock:
+            return (
+                self.db.execute(
+                    "SELECT 1 FROM copies WHERE message_id=? "
+                    "AND (key LIKE ? OR key LIKE ?) LIMIT 1",
+                    (message_id, f"bundle:{channel}:%", f"primary-catalog:{channel}:%"),
+                ).fetchone()
+                is not None
+            )
+
+    def close(self):
+        with self.lock:
+            self.db.close()
+
+
+def files_in(catalog):
+    stack = [catalog["root"]]
+    while stack:
+        node = stack.pop()
+        if node["type"] == "folder":
+            stack.extend(reversed(list(node["children"].values())))
+        else:
+            yield node
+
+
+def parts_in(node):
+    return node.get("parts") or [
+        {"message_id": node["message_id"], "size": node["size"]}
+    ]
+
+
+def validate_catalog(catalog):
+    store = DriveStore._from_payload(catalog)
+    store.close()
+
+
+def remap_catalog(catalog, channel, mapping):
+    result = copy.deepcopy(catalog)
+    for node in files_in(result):
+        old_anchor = node["message_id"]
+        node["message_id"] = mapping[str(old_anchor)]
+        for part in node.get("parts", []):
+            part["message_id"] = mapping[str(part["message_id"])]
+    # Old jobs/deletion receipts are tied to their old channel. They must never
+    # replay into a recovered channel with coincidentally matching message IDs.
+    result["operations"] = []
+    result["deletions"] = []
+    result["storage_channel_id"] = channel
+    result["backed_up_revision"] = result["revision"]
+    validate_catalog(result)
+    return result
+
+
+def encode_bundle(payload, key):
+    raw = json.dumps(payload, allow_nan=False, ensure_ascii=False).encode()
+    if len(raw) > MAX_BUNDLE - 1024:
+        raise ValueError("The recovery bundle exceeds the 64 MiB limit")
+    nonce = secrets.token_bytes(12)
+    return MAGIC + nonce + AESGCM(bytes.fromhex(key)).encrypt(nonce, raw, MAGIC)
+
+
+def decode_bundle(content, key):
+    """Authenticate and validate a complete, internally equivalent channel pair."""
+    import re
+
+    from tgdrive.storage.store import _validate_timestamp
+
+    try:
+        if (
+            not isinstance(content, bytes)
+            or len(content) > MAX_BUNDLE
+            or not content.startswith(MAGIC)
+            or not isinstance(key, str)
+            or re.fullmatch(r"[0-9a-fA-F]{64}", key.strip()) is None
+        ):
+            raise ValueError
+        offset = len(MAGIC)
+        raw = AESGCM(bytes.fromhex(key.strip())).decrypt(
+            content[offset : offset + 12], content[offset + 12 :], MAGIC
+        )
+        result = decode_catalog_snapshot(raw)
+        required = {
+            "format",
+            "version",
+            "complete",
+            "created_at",
+            "catalog",
+            "replica_catalog",
+            "credentials",
+        }
+        if not isinstance(result, dict) or set(result) != required:
+            raise ValueError
+        if (
+            result["format"] != "tgdrive-replica"
+            or type(result["version"]) is not int
+            or result["version"] != 1
+            or result["complete"] is not True
+        ):
+            raise ValueError
+        _validate_timestamp(result["created_at"])
+        credentials = result["credentials"]
+        base_fields = {
+            "api_id",
+            "api_hash",
+            "session_secret",
+            "bot_tokens",
+            "managed_document",
+            "preferences",
+        }
+        optional_fields = {
+            "mongodb_backup_key",
+            "mongodb_archive",
+        }
+        if (
+            not isinstance(credentials, dict)
+            or not base_fields <= set(credentials)
+            or set(credentials) - base_fields - optional_fields
+        ):
+            raise ValueError
+        from tgdrive.replication.replica_settings import validate_recovery_settings
+
+        validate_recovery_settings(credentials)
+        if (
+            type(credentials["api_id"]) is not int
+            or not 0 < credentials["api_id"] <= 2147483647
+            or not isinstance(credentials["api_hash"], str)
+            or re.fullmatch(r"[0-9a-fA-F]{32}", credentials["api_hash"]) is None
+        ):
+            raise ValueError
+        secret = credentials["session_secret"]
+        if (
+            not isinstance(secret, str)
+            or not 32 <= len(secret) <= 4096
+            or secret != secret.strip()
+            or secret.startswith("<")
+            or any(ord(char) < 32 or ord(char) == 127 for char in secret)
+        ):
+            raise ValueError
+        tokens = credentials["bot_tokens"]
+        if (
+            not isinstance(tokens, list)
+            or not 1 <= len(tokens) <= 256
+            or any(
+                not isinstance(token, str)
+                or len(token) > 512
+                or re.fullmatch(r"[1-9][0-9]{4,14}:[A-Za-z0-9_-]{20,}", token) is None
+                for token in tokens
+            )
+            or len({token.split(":", 1)[0] for token in tokens}) != len(tokens)
+        ):
+            raise ValueError
+        original, replica = result["catalog"], result["replica_catalog"]
+        for catalog in (original, replica):
+            validate_catalog(catalog)
+            channel = catalog.get("storage_channel_id")
+            if type(channel) is not int or not -(1 << 63) <= channel < 0:
+                raise ValueError
+        if original["storage_channel_id"] == replica["storage_channel_id"]:
+            raise ValueError
+        archive = credentials.get("mongodb_archive")
+        if archive is not None and (
+            archive["source_channel"] != original["storage_channel_id"]
+            or archive["replica_channel"] != replica["storage_channel_id"]
+            or archive["revision"] < original["revision"]
+        ):
+            raise ValueError
+        old_files = {node["id"]: node for node in files_in(original)}
+        new_files = {node["id"]: node for node in files_in(replica)}
+        if set(old_files) != set(new_files):
+            raise ValueError
+        mapping = {}
+        destinations = {}
+        for node_id, old in old_files.items():
+            before, after = parts_in(old), parts_in(new_files[node_id])
+            if len(before) != len(after):
+                raise ValueError
+            for old_part, new_part in zip(before, after, strict=True):
+                source, target = old_part["message_id"], new_part["message_id"]
+                if source in mapping and mapping[source] != target:
+                    raise ValueError
+                if target in destinations and destinations[target] != source:
+                    raise ValueError
+                mapping[source] = target
+                destinations[target] = source
+        expected = remap_catalog(
+            original,
+            replica["storage_channel_id"],
+            {str(source): target for source, target in mapping.items()},
+        )
+        if expected != replica:
+            raise ValueError
+        return result
+    except Exception:
+        raise ValueError(
+            "Recovery key or bundle validation failed; nothing changed"
+        ) from None
diff --git a/tgdrive/replication/replica_transport.py b/tgdrive/replication/replica_transport.py
new file mode 100644
index 00000000..f81cace0
--- /dev/null
+++ b/tgdrive/replication/replica_transport.py
@@ -0,0 +1,925 @@
+"""Bounded Telegram transport for independent, journaled channel replicas.
+
+Existing documents are sent with messages.sendMedia/InputMediaDocument rather
+than forwarded or downloaded/re-uploaded. The caller persists random IDs before
+calling this layer, and must retain them after any ambiguous provider response.
+https://core.telegram.org/method/messages.sendMedia
+Account-wide deduplication and temporary in-flight duplicates:
+https://core.telegram.org/api/updates#updatemessageid-updates
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import math
+import os
+import re
+import secrets
+import stat
+import time
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path
+from typing import Any
+
+from telethon import TelegramClient, functions, types, utils
+from telethon.errors import NetworkMigrateError, PhoneMigrateError, UserMigrateError
+
+CAPSULE_NAME = "tgdrive-replica.tgdb"
+MAX_CAPSULE_BYTES = 64 * 1024 * 1024
+MAX_VERIFY_BATCH = 32
+_BLOCK = 512 * 1024
+_BOT = re.compile(r"[1-9][0-9]{4,14}:[A-Za-z0-9_-]{20,}")
+
+
+class ReplicaRequestPacer:
+    """Serialize replica calls and retain conservative pacing across retries."""
+
+    def __init__(self, *, interval=1.0, maximum_interval=4.0, clock=None, sleep=None):
+        self.interval = self.minimum_interval = interval
+        self.maximum_interval = maximum_interval
+        self._clock = clock or time.monotonic
+        self._sleep = sleep or asyncio.sleep
+        self._next_at = 0.0
+        self._lock = asyncio.Lock()
+
+    @asynccontextmanager
+    async def slot(self):
+        async with self._lock:
+            delay = self._next_at - self._clock()
+            if delay > 0:
+                await self._sleep(delay)
+            try:
+                yield
+            finally:
+                self._next_at = self._clock() + self.interval
+
+    def slow_down(self):
+        self.interval = min(self.maximum_interval, self.interval * 2)
+
+    def reset(self):
+        # Retain the next slot: confirming a checkpoint must not create a burst.
+        self.interval = self.minimum_interval
+
+
+class ReplicaTransportError(RuntimeError):
+    """A credential-free error suitable for the owner-facing replica report."""
+
+    def __init__(
+        self,
+        detail: str,
+        code: str = "REPLICA_TRANSPORT",
+        *,
+        retry_after: float | None = None,
+        retryable: bool = False,
+    ) -> None:
+        super().__init__(detail)
+        self.detail = detail
+        self.code = code
+        self.retry_after = retry_after
+        self.retryable = retryable
+        self.operation: str | None = None
+
+
+def _provider_error(error: Exception) -> ReplicaTransportError:
+    name = type(error).__name__
+    if name in {"PhoneMigrateError", "NetworkMigrateError", "UserMigrateError"}:
+        return ReplicaTransportError(
+            "Telegram could not finish connecting the backup bot to its data "
+            "center. Retry the backup operation.",
+            "REPLICA_DC_MIGRATION",
+            retryable=True,
+        )
+    if name == "RandomIdDuplicateError":
+        return ReplicaTransportError(
+            "Telegram is still completing this message. Backup will retry the "
+            "same saved operation after a short wait.",
+            "REPLICA_IN_FLIGHT",
+            retry_after=5,
+            retryable=True,
+        )
+    seconds = getattr(error, "seconds", None)
+    if (
+        type(seconds) in (int, float)
+        and math.isfinite(seconds)
+        and (seconds > 0 or name in {"FloodWaitError", "SlowModeWaitError"})
+    ):
+        return ReplicaTransportError(
+            "Telegram requested a pause. Backup will resume after the wait.",
+            "REPLICA_FLOOD_WAIT",
+            retry_after=max(1, seconds),
+            retryable=True,
+        )
+    if name in {
+        "AccessTokenExpiredError",
+        "AccessTokenInvalidError",
+        "AuthKeyUnregisteredError",
+        "AuthKeyInvalidError",
+        "AuthKeyDuplicatedError",
+        "SessionRevokedError",
+        "UserDeactivatedError",
+        "UserDeactivatedBanError",
+        "TokenInvalidError",
+        "UnauthorizedError",
+    }:
+        return ReplicaTransportError(
+            "The backup bot cannot sign in. Check its token or replace the bot.",
+            "REPLICA_CREDENTIALS",
+        )
+    if name in {
+        "ChannelPrivateError",
+        "ChannelInvalidError",
+        "ChatAdminRequiredError",
+        "UserNotParticipantError",
+        "ChatWriteForbiddenError",
+        "PeerIdInvalidError",
+        "ChatForbiddenError",
+        "UserBannedInChannelError",
+    }:
+        return ReplicaTransportError(
+            "The backup bot needs administrator access to both private channels. "
+            "Check channel IDs and its post, edit and delete permissions.",
+            "REPLICA_ACCESS",
+        )
+    if name in {"ChatForwardsRestrictedError", "MediaTtlInvalidError"}:
+        return ReplicaTransportError(
+            "Telegram content protection prevents copying. Disable Restrict Saving "
+            "Content on the dedicated TGDrive channels, then retry.",
+            "REPLICA_PROTECTED",
+        )
+    if name in {
+        "FileReferenceExpiredError",
+        "FileReferenceInvalidError",
+        "FilerefUpgradeNeededError",
+    }:
+        return ReplicaTransportError(
+            "Telegram's file reference expired. Backup will fetch it again and retry.",
+            "REPLICA_FILE_REFERENCE",
+            retryable=True,
+        )
+    if isinstance(error, (TimeoutError, OSError)) or name in {
+        "ServerError",
+        "RpcCallFailError",
+        "TimedOutError",
+        "FloodError",
+    }:
+        return ReplicaTransportError(
+            "Telegram could not confirm the operation. It is safe to resume the "
+            "same backup operation after connectivity returns.",
+            "REPLICA_UNAVAILABLE",
+            retryable=True,
+        )
+    return ReplicaTransportError(
+        "Telegram rejected the backup operation. Check channel access and retry; "
+        "the existing confirmed backup has been preserved.",
+        "REPLICA_PROVIDER_ERROR",
+    )
+
+
+def _integer(value: Any, name: str, *, minimum: int, maximum: int) -> int:
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise ReplicaTransportError(f"Invalid {name}.", "REPLICA_INPUT")
+    return value
+
+
+def _channel(value: Any) -> int:
+    return _integer(value, "channel ID", minimum=-(1 << 63), maximum=-1)
+
+
+def _message(value: Any) -> int:
+    return _integer(value, "message ID", minimum=1, maximum=(1 << 31) - 1)
+
+
+def _random(value: Any) -> int:
+    value = _integer(
+        value, "operation identity", minimum=-(1 << 63), maximum=(1 << 63) - 1
+    )
+    if value == 0:
+        raise ReplicaTransportError("Invalid operation identity.", "REPLICA_INPUT")
+    return value
+
+
+class ReplicaTransport:
+    """One independent backup bot, with no unbounded history/search operations.
+
+    The backup bot must be an administrator in source and destination channels:
+    a fresh source message supplies its current file reference, while an actual
+    destination message is independently confirmed before a replica is counted.
+    A native client may be injected for offline transport-contract tests.
+    """
+
+    def __init__(self, settings, bot_token: str, *, client=None, pacer=None) -> None:
+        self._settings = settings
+        self._token = bot_token.strip() if isinstance(bot_token, str) else ""
+        self._client = client
+        self._started = False
+        self._lock = asyncio.Lock()
+        self._pacer = pacer or ReplicaRequestPacer()
+        self._peers = {}
+        self._session_file: Path | None = None
+
+    def _persistent_session(self, identity: int) -> Path:
+        """Keep backup authorization separate from primary bots and rotated tokens."""
+        fingerprint = hashlib.sha256(
+            (
+                f"{self._settings.api_id}\0"
+                f"{self._settings.api_hash.get_secret_value()}\0{self._token}"
+            ).encode()
+        ).hexdigest()[:24]
+        directory = self._settings.resolved_data_dir / "sessions"
+        path = directory / f"backup-bot-{identity}-{fingerprint}.session"
+        try:
+            if directory.is_symlink():
+                raise ValueError("Unsafe session directory")
+            directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+            directory.chmod(0o700)
+            # Precreate privately before SQLite opens it. Reject existing links,
+            # special files and sidecar links rather than following them.
+            for candidate in (
+                path,
+                path.with_name(path.name + "-journal"),
+                path.with_name(path.name + "-wal"),
+                path.with_name(path.name + "-shm"),
+            ):
+                try:
+                    info = candidate.lstat()
+                except FileNotFoundError:
+                    continue
+                if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+                    raise ValueError("Unsafe session file")
+                candidate.chmod(0o600)
+            descriptor = os.open(path, os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
+            try:
+                info = os.fstat(descriptor)
+                if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1:
+                    raise ValueError("Unsafe session file")
+                os.fchmod(descriptor, 0o600)
+            finally:
+                os.close(descriptor)
+        except OSError, ValueError:
+            raise ReplicaTransportError(
+                "The saved backup bot session cannot be opened safely. "
+                "Check DATA_DIR session storage and permissions before retrying.",
+                "REPLICA_SESSION",
+            ) from None
+        return path
+
+    async def _request(self, operation, call, *args, **kwargs):
+        async with self._pacer.slot():
+            try:
+                return await call(*args, **kwargs)
+            except (
+                PhoneMigrateError,
+                NetworkMigrateError,
+                UserMigrateError,
+                ValueError,
+            ):
+                # Login owns the bounded DC handoff; inspect owns unresolved peers.
+                raise
+            except ReplicaTransportError:
+                raise
+            except Exception as error:
+                mapped = _provider_error(error)
+                mapped.operation = operation
+                if mapped.code == "REPLICA_FLOOD_WAIT":
+                    self._pacer.slow_down()
+                raise mapped from None
+
+    async def _peer(self, channel):
+        # Cache only the input peer, never channel privacy, permissions or TTL.
+        if channel not in self._peers:
+            self._peers[channel] = await self._request(
+                "resolve_peer", self._client.get_input_entity, channel
+            )
+        return self._peers[channel]
+
+    @asynccontextmanager
+    async def _guard(self, seconds: int = 90):
+        try:
+            async with asyncio.timeout(seconds):
+                yield
+        except ReplicaTransportError:
+            raise
+        except Exception as error:
+            raise _provider_error(error) from None
+
+    async def start(self) -> None:
+        if self._started:
+            return
+        if not _BOT.fullmatch(self._token):
+            raise ReplicaTransportError(
+                "Enter a valid backup bot token.", "REPLICA_CREDENTIALS"
+            )
+        identity = int(self._token.split(":", 1)[0])
+        primary = getattr(self._settings, "bot_tokens", ())
+        if any(int(token.split(":", 1)[0]) == identity for token in primary):
+            raise ReplicaTransportError(
+                "Use a separate backup bot; this bot is already a primary storage bot.",
+                "REPLICA_SAME_BOT",
+            )
+        if self._client is None:
+            self._session_file = self._persistent_session(identity)
+            try:
+                self._client = TelegramClient(
+                    str(self._session_file),
+                    self._settings.api_id,
+                    self._settings.api_hash.get_secret_value(),
+                    receive_updates=False,
+                    flood_sleep_threshold=0,
+                    request_retries=0,
+                    raise_last_call_error=True,
+                    connection_retries=0,
+                    timeout=15,
+                    auto_reconnect=True,
+                )
+            except Exception:
+                raise ReplicaTransportError(
+                    "The saved backup bot session could not be read. Preserve "
+                    "the session file and check its storage before retrying.",
+                    "REPLICA_SESSION",
+                ) from None
+            self._client.parse_mode = None
+        try:
+            async with self._guard(30):
+                if self._session_file is not None:
+                    self._persistent_session(identity)
+                await self._client.connect()
+                for attempt in range(2):
+                    try:
+                        # Telethon's is_user_authorized() catches every RPCError,
+                        # including FloodWait, and treats it as a signed-out
+                        # session. get_me() only treats Unauthorized as signed
+                        # out, so provider waits reach the durable coordinator.
+                        account = await self._request("get_me", self._client.get_me)
+                        if account is None:
+                            account = await self._request(
+                                "sign_in", self._client.sign_in, bot_token=self._token
+                            )
+                        break
+                    except PhoneMigrateError, NetworkMigrateError, UserMigrateError:
+                        # With request_retries=0, Telethon switches DC but raises
+                        # before retrying authorization. Retry only sign-in;
+                        # durable message retries remain owned by the journal.
+                        if attempt:
+                            raise
+                if (
+                    account is None
+                    or not getattr(account, "bot", False)
+                    or getattr(account, "id", None) != identity
+                ):
+                    raise ReplicaTransportError(
+                        "The backup bot identity did not match its token.",
+                        "REPLICA_CREDENTIALS",
+                    )
+                if self._session_file is not None:
+                    self._persistent_session(identity)
+            self._started = True
+        except BaseException:
+            await self.close()
+            raise
+
+    async def close(self) -> None:
+        self._started = False
+        self._peers.clear()
+        if self._client is not None:
+            with suppress(Exception):
+                async with asyncio.timeout(10):
+                    await self._client.disconnect()
+
+    def _ready(self) -> None:
+        if not self._started:
+            raise ReplicaTransportError(
+                "Connect the backup bot before continuing.", "REPLICA_NOT_CONNECTED"
+            )
+
+    async def inspect(self, channel: int, *, writable: bool = True) -> dict:
+        self._ready()
+        channel = _channel(channel)
+        async with self._guard(25):
+            try:
+                peer = await self._peer(channel)
+            except ValueError:
+                raise ReplicaTransportError(
+                    f"The backup bot cannot access channel {channel}. Check the "
+                    "channel ID and add the bot as an administrator in both "
+                    "private channels, then retry.",
+                    "REPLICA_ACCESS",
+                ) from None
+            result = await self._request(
+                "channels.getFullChannel",
+                self._client,
+                functions.channels.GetFullChannelRequest(utils.get_input_channel(peer)),
+            )
+            chat = next(
+                (row for row in result.chats if utils.get_peer_id(row) == channel), None
+            )
+            if chat is None or not getattr(chat, "broadcast", False):
+                raise ReplicaTransportError(
+                    "Use a dedicated private broadcast channel, not a group.",
+                    "REPLICA_CHANNEL_TYPE",
+                )
+            if getattr(chat, "username", None) or any(
+                getattr(row, "active", False)
+                for row in (getattr(chat, "usernames", None) or ())
+            ):
+                raise ReplicaTransportError(
+                    "Both TGDrive channels must be private. Remove the public "
+                    "channel username in Telegram, then retry.",
+                    "REPLICA_PUBLIC_CHANNEL",
+                )
+            if getattr(result.full_chat, "ttl_period", None):
+                raise ReplicaTransportError(
+                    "Turn off Telegram auto-delete in both TGDrive channels "
+                    "before continuing. Auto-delete would remove stored files "
+                    "and their backups.",
+                    "REPLICA_AUTO_DELETE",
+                )
+            if (
+                getattr(chat, "restricted", False)
+                or getattr(chat, "noforwards", False)
+                or getattr(result.full_chat, "noforwards", False)
+            ):
+                raise ReplicaTransportError(
+                    "This channel restricts saving or copying content. Remove the "
+                    "restriction in Telegram before using channel backups.",
+                    "REPLICA_PROTECTED",
+                )
+            if getattr(chat, "left", False):
+                raise ReplicaTransportError(
+                    "The backup bot no longer belongs to this channel. Add it "
+                    "again as an administrator before resuming.",
+                    "REPLICA_ACCESS",
+                )
+            rights = getattr(chat, "admin_rights", None)
+            creator = getattr(chat, "creator", False)
+            required = ("post_messages", "edit_messages", "delete_messages")
+            if not creator and (
+                rights is None
+                or (
+                    writable
+                    and not all(getattr(rights, key, False) for key in required)
+                )
+            ):
+                raise ReplicaTransportError(
+                    "Add the backup bot as an administrator in both private "
+                    "channels with post, edit and delete permissions.",
+                    "REPLICA_PERMISSIONS",
+                )
+            return {"id": channel, "title": str(chat.title)[:256], "private": True}
+
+    async def pinned_message(self, channel: int) -> int | None:
+        """Read only the current channel pin, never history or a search result."""
+        self._ready()
+        channel = _channel(channel)
+        async with self._lock, self._guard(25):
+            await self.inspect(channel, writable=False)
+            peer = await self._peer(channel)
+            result = await self._request(
+                "channels.getFullChannel",
+                self._client,
+                functions.channels.GetFullChannelRequest(utils.get_input_channel(peer)),
+            )
+            identity = getattr(result.full_chat, "pinned_msg_id", None)
+            return None if identity is None else _message(identity)
+
+    @staticmethod
+    def _document(channel: int, message_id: int, message):
+        if message is None or getattr(message, "id", None) != message_id:
+            raise ReplicaTransportError(
+                "A required channel message is missing. Restore channel access or "
+                "choose another confirmed recovery point.",
+                "REPLICA_MESSAGE_MISSING",
+            )
+        peer = getattr(message, "peer_id", None)
+        if peer is not None and utils.get_peer_id(peer) != channel:
+            raise ReplicaTransportError(
+                "Telegram returned a message from an unexpected channel.",
+                "REPLICA_VERIFY_FAILED",
+            )
+        document = getattr(message, "document", None)
+        if document is None:
+            raise ReplicaTransportError(
+                "The required message no longer contains a document.",
+                "REPLICA_DOCUMENT_MISSING",
+            )
+        if getattr(message, "noforwards", False) or getattr(
+            getattr(message, "media", None), "ttl_seconds", None
+        ):
+            raise ReplicaTransportError(
+                "The required document is protected or expires automatically.",
+                "REPLICA_PROTECTED",
+            )
+        return message, document
+
+    async def _get(self, channel: int, message_id: int):
+        message = await self._request(
+            "channels.getMessages", self._client.get_messages, channel, ids=message_id
+        )
+        return self._document(channel, message_id, message)
+
+    async def _sent(self, channel: int, result: Any, random_id: int) -> int:
+        if isinstance(result, types.UpdateShortSentMessage):
+            return _message(result.id)
+        updates = (
+            [result.update]
+            if isinstance(result, types.UpdateShort)
+            else getattr(result, "updates", ())
+        )
+        if any(isinstance(row, types.UpdateNewScheduledMessage) for row in updates):
+            raise ReplicaTransportError(
+                "Telegram scheduled the backup instead of confirming delivery.",
+                "REPLICA_NOT_CONFIRMED",
+                retryable=True,
+            )
+        identity = next(
+            (
+                row.id
+                for row in updates
+                if isinstance(row, types.UpdateMessageID) and row.random_id == random_id
+            ),
+            None,
+        )
+        if identity is None:
+            identity = next(
+                (
+                    row.message.id
+                    for row in updates
+                    if isinstance(
+                        row, (types.UpdateNewMessage, types.UpdateNewChannelMessage)
+                    )
+                    and getattr(row.message, "peer_id", None) is not None
+                    and utils.get_peer_id(row.message.peer_id) == channel
+                ),
+                None,
+            )
+        if identity is None:
+            raise ReplicaTransportError(
+                "Telegram did not confirm a destination message. Resume the same "
+                "operation; do not start a second copy.",
+                "REPLICA_NOT_CONFIRMED",
+                retryable=True,
+            )
+        return _message(identity)
+
+    async def copy(
+        self,
+        source_channel: int,
+        source_message: int,
+        destination_channel: int,
+        *,
+        random_id: int,
+        expected_size: int,
+    ) -> int:
+        self._ready()
+        source_channel, destination_channel = (
+            _channel(source_channel),
+            _channel(destination_channel),
+        )
+        source_message, random_id = _message(source_message), _random(random_id)
+        _integer(expected_size, "document size", minimum=0, maximum=(1 << 63) - 1)
+        if source_channel == destination_channel:
+            raise ReplicaTransportError(
+                "Choose a backup channel different from the source channel.",
+                "REPLICA_SAME_CHANNEL",
+            )
+        async with self._lock, self._guard():
+            await self.inspect(source_channel, writable=False)
+            await self.inspect(destination_channel)
+            _, document = await self._get(source_channel, source_message)
+            if getattr(document, "size", None) != expected_size:
+                raise ReplicaTransportError(
+                    "A source document size differs from the catalog. Preserve "
+                    "the current backup and review this file.",
+                    "REPLICA_SIZE_MISMATCH",
+                )
+            peer = await self._peer(destination_channel)
+            result = await self._request(
+                "messages.sendMedia",
+                self._client,
+                functions.messages.SendMediaRequest(
+                    peer=peer,
+                    media=types.InputMediaDocument(
+                        id=utils.get_input_document(document)
+                    ),
+                    message="",
+                    random_id=random_id,
+                    silent=True,
+                ),
+            )
+            identity = await self._sent(destination_channel, result, random_id)
+            sent, copied = await self._get(destination_channel, identity)
+            if (
+                copied.size != expected_size
+                or copied.id != document.id
+                or copied.access_hash != document.access_hash
+                or getattr(sent, "fwd_from", None) is not None
+            ):
+                raise ReplicaTransportError(
+                    "Telegram's copied document did not match the source. The "
+                    "replica has not been marked protected.",
+                    "REPLICA_VERIFY_FAILED",
+                )
+            return identity
+
+    async def verify(self, channel: int, message_id: int, expected_size: int) -> None:
+        """Verify an existing committed document without reading original bytes."""
+        self._ready()
+        channel, message_id = _channel(channel), _message(message_id)
+        _integer(expected_size, "document size", minimum=0, maximum=(1 << 63) - 1)
+        async with self._lock, self._guard():
+            await self.inspect(channel, writable=False)
+            _, document = await self._get(channel, message_id)
+            if getattr(document, "size", None) != expected_size:
+                raise ReplicaTransportError(
+                    "The channel document does not match its catalog size. "
+                    "Preserve the current catalog and choose another recovery point.",
+                    "REPLICA_SIZE_MISMATCH",
+                )
+
+    async def verify_many(self, channel: int, documents: list[tuple[int, int]]) -> None:
+        """Check a bounded group of journaled parts with one fresh channel read."""
+        self._ready()
+        channel = _channel(channel)
+        if not 1 <= len(documents) <= MAX_VERIFY_BATCH:
+            raise ReplicaTransportError("Invalid verification batch.", "REPLICA_INPUT")
+        expected = {}
+        for message_id, size in documents:
+            message_id = _message(message_id)
+            _integer(size, "document size", minimum=0, maximum=(1 << 63) - 1)
+            if message_id in expected and expected[message_id] != size:
+                raise ReplicaTransportError(
+                    "Conflicting sizes for a backup document.", "REPLICA_SIZE_MISMATCH"
+                )
+            expected[message_id] = size
+        async with self._lock, self._guard():
+            await self.inspect(channel, writable=False)
+            messages = await self._request(
+                "channels.getMessages",
+                self._client.get_messages,
+                channel,
+                ids=list(expected),
+            )
+            found = {}
+            for message in messages:
+                identity = getattr(message, "id", None)
+                if message is None:
+                    continue
+                if identity not in expected or identity in found:
+                    raise ReplicaTransportError(
+                        "Telegram returned an unexpected backup document.",
+                        "REPLICA_VERIFY_FAILED",
+                    )
+                found[identity] = message
+            for message_id, size in expected.items():
+                _, document = self._document(channel, message_id, found.get(message_id))
+                if document.size != size:
+                    raise ReplicaTransportError(
+                        "The channel document does not match its catalog size. "
+                        "Preserve the current catalog and choose another "
+                        "recovery point.",
+                        "REPLICA_SIZE_MISMATCH",
+                    )
+
+    @staticmethod
+    def _capsule(document, filename: str = CAPSULE_NAME) -> int:
+        size = getattr(document, "size", None)
+        names = [
+            row.file_name
+            for row in getattr(document, "attributes", ())
+            if isinstance(row, types.DocumentAttributeFilename)
+        ]
+        if names != [filename]:
+            raise ReplicaTransportError(
+                "The selected message has a different document type. Choose a "
+                "confirmed TGDrive recovery checkpoint.",
+                "REPLICA_DOCUMENT_TYPE",
+            )
+        if type(size) is not int or not 0 < size <= MAX_CAPSULE_BYTES:
+            raise ReplicaTransportError(
+                "The selected recovery archive exceeds the bounded transport "
+                "size. Choose a supported confirmed checkpoint.",
+                "REPLICA_ARCHIVE_INVALID",
+            )
+        return size
+
+    async def _read_to(self, document, target, size: int) -> str:
+        digest = hashlib.sha256()
+        count = 0
+        iterator = self._client.iter_download(
+            document, request_size=_BLOCK, chunk_size=_BLOCK, file_size=size
+        )
+        try:
+            async for block in iterator:
+                if not isinstance(block, (bytes, bytearray, memoryview)):
+                    raise ReplicaTransportError(
+                        "Telegram returned an invalid recovery archive block.",
+                        "REPLICA_VERIFY_FAILED",
+                    )
+                count += len(block)
+                if count > size or count > MAX_CAPSULE_BYTES:
+                    raise ReplicaTransportError(
+                        "The recovery archive exceeded its declared size.",
+                        "REPLICA_VERIFY_FAILED",
+                    )
+                digest.update(block)
+                if target is not None:
+                    target.write(block)
+        finally:
+            if callable(getattr(iterator, "aclose", None)):
+                await iterator.aclose()
+        if count != size:
+            raise ReplicaTransportError(
+                "Telegram returned an incomplete recovery archive. Retry the "
+                "same operation.",
+                "REPLICA_VERIFY_FAILED",
+                retryable=True,
+            )
+        return digest.hexdigest()
+
+    async def _publish(
+        self,
+        channel: int,
+        path: Path,
+        *,
+        random_id: int,
+        caption: str,
+        pin: bool,
+        filename: str,
+    ) -> int:
+        self._ready()
+        channel, random_id, path = _channel(channel), _random(random_id), Path(path)
+        if not isinstance(caption, str) or len(caption) > 1024:
+            raise ReplicaTransportError("Invalid checkpoint caption.", "REPLICA_INPUT")
+        async with self._lock, self._guard(180):
+            await self.inspect(channel)
+            size = path.stat().st_size
+            if not 0 < size <= MAX_CAPSULE_BYTES:
+                raise ReplicaTransportError(
+                    "The recovery archive exceeds the 64 MiB transport limit.",
+                    "REPLICA_ARCHIVE_TOO_LARGE",
+                )
+            with await asyncio.to_thread(path.open, "rb") as source:
+                digest = await asyncio.to_thread(
+                    lambda: hashlib.file_digest(source, "sha256").hexdigest()
+                )
+                source.seek(0)
+                uploaded = await self._request(
+                    "upload_recovery_bundle",
+                    self._client.upload_file,
+                    source,
+                    file_name=filename,
+                    file_size=size,
+                    part_size_kb=512,
+                )
+            peer = await self._peer(channel)
+            result = await self._request(
+                "messages.sendMedia",
+                self._client,
+                functions.messages.SendMediaRequest(
+                    peer=peer,
+                    media=types.InputMediaUploadedDocument(
+                        file=uploaded,
+                        mime_type="application/octet-stream",
+                        attributes=[types.DocumentAttributeFilename(filename)],
+                        force_file=True,
+                    ),
+                    message=caption,
+                    random_id=random_id,
+                    silent=True,
+                ),
+            )
+            identity = await self._sent(channel, result, random_id)
+            _, document = await self._get(channel, identity)
+            if (
+                self._capsule(document, filename) != size
+                or await self._read_to(document, None, size) != digest
+            ):
+                raise ReplicaTransportError(
+                    "The remote recovery archive checksum did not match. "
+                    "The previous confirmed recovery point has been preserved.",
+                    "REPLICA_VERIFY_FAILED",
+                )
+            if pin:
+                await self._request(
+                    "messages.updatePinnedMessage",
+                    self._client,
+                    functions.messages.UpdatePinnedMessageRequest(
+                        peer=peer,
+                        id=identity,
+                        silent=True,
+                    ),
+                )
+            return identity
+
+    async def _download(
+        self,
+        channel: int,
+        message_id: int | None,
+        destination: Path,
+        *,
+        filename: str,
+    ) -> int:
+        self._ready()
+        channel, destination = _channel(channel), Path(destination)
+        if message_id is not None:
+            message_id = _message(message_id)
+        async with self._lock, self._guard(180):
+            await self.inspect(channel, writable=False)
+            if message_id is None:
+                peer = await self._peer(channel)
+                full = await self._request(
+                    "channels.getFullChannel",
+                    self._client,
+                    functions.channels.GetFullChannelRequest(
+                        utils.get_input_channel(peer)
+                    ),
+                )
+                message_id = getattr(full.full_chat, "pinned_msg_id", None)
+                if message_id is None:
+                    raise ReplicaTransportError(
+                        "No recovery checkpoint is pinned. Enter a confirmed "
+                        "TGDrive replica checkpoint message ID.",
+                        "REPLICA_CHECKPOINT_MISSING",
+                    )
+                message_id = _message(message_id)
+            _, document = await self._get(channel, message_id)
+            size = self._capsule(document, filename)
+            if destination.exists():
+                raise ReplicaTransportError(
+                    "The recovery destination file already exists. Preserve it "
+                    "and choose a new temporary destination.",
+                    "REPLICA_LOCAL_EXISTS",
+                )
+            destination.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+            temporary = destination.with_name(
+                destination.name + "." + secrets.token_hex(8)
+            )
+            try:
+                with temporary.open("xb") as target:
+                    temporary.chmod(0o600)
+                    await self._read_to(document, target, size)
+                    target.flush()
+                    os.fsync(target.fileno())
+                # Link creates the final name exclusively; a concurrent file is
+                # preserved instead of overwritten by a recovery download.
+                os.link(temporary, destination)
+            finally:
+                temporary.unlink(missing_ok=True)
+            return message_id
+
+    async def download(
+        self, channel: int, message_id: int | None, destination: Path
+    ) -> int:
+        """Download a confirmed replica capsule by ID or latest pinned message."""
+        return await self._download(
+            channel, message_id, destination, filename=CAPSULE_NAME
+        )
+
+    async def download_catalog(
+        self, channel: int, destination: Path, message_id: int | None = None
+    ) -> int:
+        """Read a current-format drive.json checkpoint by pin or explicit ID.
+
+        Recovery publishes this catalog after confirming its encrypted capsule.
+        The caller must validate format, drive identity, and channel binding.
+        Capsule fallback is only safe on DOCUMENT_TYPE, never after failed
+        decryption, authorization, or malformed archive errors.
+        """
+        return await self._download(
+            channel, message_id, destination, filename="drive.json"
+        )
+
+    async def publish(
+        self, channel: int, path: Path, *, random_id: int, caption: str, pin: bool
+    ) -> int:
+        return await self._publish(
+            channel,
+            path,
+            random_id=random_id,
+            caption=caption,
+            pin=pin,
+            filename=CAPSULE_NAME,
+        )
+
+    async def publish_catalog(
+        self,
+        channel: int,
+        path: Path,
+        *,
+        random_id: int,
+        caption: str,
+        pin: bool = True,
+    ) -> int:
+        """Confirm and pin a normal SQLite drive.json checkpoint after recovery.
+
+        The caller owns the validated portable catalog and its normal checkpoint
+        marker. This does not replace the encrypted capsule retained elsewhere.
+        """
+        return await self._publish(
+            channel,
+            path,
+            random_id=random_id,
+            caption=caption,
+            pin=pin,
+            filename="drive.json",
+        )
diff --git a/tgdrive/server.py b/tgdrive/server.py
new file mode 100644
index 00000000..e055b7ee
--- /dev/null
+++ b/tgdrive/server.py
@@ -0,0 +1,57 @@
+"""Single-worker container launcher with narrowly scoped proxy discovery."""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+import os
+import socket
+
+import uvicorn
+
+logger = logging.getLogger(__name__)
+# The listener is reachable within the container network; Compose controls ingress.
+_CONTAINER_BIND = "0.0.0.0"  # noqa: S104  # nosec B104
+
+
+def trusted_proxy_ips() -> str:
+    explicit = os.environ.get("FORWARDED_ALLOW_IPS", "").strip()
+    if explicit and explicit != "auto":
+        return explicit
+    trusted = {"127.0.0.1", "::1"}
+    for host in os.environ.get("TGDRIVE_PROXY_HOSTS", "").split(","):
+        host = host.strip()
+        if not host:
+            continue
+        try:
+            addresses = socket.getaddrinfo(host, None, type=socket.SOCK_STREAM)
+        except socket.gaierror:
+            logger.warning(
+                "Configured proxy hostname could not be resolved; only loopback "
+                "and other resolved proxies are trusted. Restart after the proxy "
+                "joins the application network."
+            )
+            continue
+        for address in addresses:
+            ip = ipaddress.ip_address(address[4][0])
+            if ip.is_private and not ip.is_unspecified and not ip.is_multicast:
+                trusted.add(str(ip))
+    return ",".join(sorted(trusted))
+
+
+def main() -> None:
+    uvicorn.run(
+        "tgdrive.web.app:create_app",
+        factory=True,
+        host=_CONTAINER_BIND,
+        port=8000,
+        workers=1,
+        proxy_headers=True,
+        forwarded_allow_ips=trusted_proxy_ips(),
+        timeout_graceful_shutdown=45,
+        access_log=False,
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tgdrive/settings/__init__.py b/tgdrive/settings/__init__.py
new file mode 100644
index 00000000..73284ca2
--- /dev/null
+++ b/tgdrive/settings/__init__.py
@@ -0,0 +1 @@
+"""Managed preferences, connection management, and account login."""
diff --git a/tgdrive/settings/bot_settings.py b/tgdrive/settings/bot_settings.py
new file mode 100644
index 00000000..da3dc724
--- /dev/null
+++ b/tgdrive/settings/bot_settings.py
@@ -0,0 +1,201 @@
+"""Owner-managed bot upload destination, applied to the next import."""
+
+from __future__ import annotations
+
+import asyncio
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from tgdrive.core.errors import (
+    DuplicateNameError,
+    NotDirectoryError,
+    NotFoundError,
+    TrashedItemError,
+)
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.storage.store import _normalize_path
+
+DEFAULT_FOLDER_NAME = "TGDriveBotModeFiles"
+SETTINGS_LOCATION = "/?view=settings&section=transfers#bot-mode"
+_MISSING = (NotDirectoryError, NotFoundError, TrashedItemError)
+
+
+class BotUploadPreferences(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    folder_path: str | None = Field(default=None, max_length=17000)
+    site_url: str | None = Field(default=None, max_length=2048)
+
+    @field_validator("folder_path")
+    @classmethod
+    def valid_folder(cls, value):
+        return _normalize_path(value)[1] if value is not None else None
+
+    @field_validator("site_url")
+    @classmethod
+    def valid_site(cls, value):
+        if value is None:
+            return None
+        parsed = urlsplit(value)
+        if (
+            parsed.scheme not in {"http", "https"}
+            or not parsed.hostname
+            or parsed.username is not None
+            or parsed.password is not None
+            or parsed.path not in {"", "/"}
+            or parsed.query
+            or parsed.fragment
+            or any(ord(char) < 33 for char in value)
+        ):
+            raise ValueError("Use the HTTP or HTTPS address of your TGDrive website")
+        return value.rstrip("/")
+
+
+def folder_label(store, path):
+    store.get_directory(path)
+    names = ["My Files"]
+    parts = path.strip("/").split("/") if path != "/" else []
+    for index in range(len(parts)):
+        names.append(store.get_directory("/" + "/".join(parts[: index + 1]))["name"])
+    label = " / ".join(names)
+    return label if len(label) <= 600 else "…" + label[-599:]
+
+
+class BotSettings:
+    def __init__(self, settings, runtime):
+        self.settings = settings
+        self.runtime = runtime
+        self.value = BotUploadPreferences()
+        self._loaded = False
+        self._lock = asyncio.Lock()
+
+    def _read(self):
+        backend = self.runtime.mongo
+        row = backend.db.settings.find_one({"_id": "bot-preferences"})
+        raw = row["document"] if row else {}
+        return BotUploadPreferences.model_validate(raw)
+
+    def _write(self, value):
+        document = value.model_dump()
+        backend = self.runtime.mongo
+        backend.write(
+            backend.db.settings,
+            "replace_one",
+            {"_id": "bot-preferences"},
+            {"_id": "bot-preferences", "document": document},
+            upsert=True,
+        )
+
+    async def _load(self):
+        if not self._loaded:
+            try:
+                self.value = await asyncio.to_thread(self._read)
+            except Exception:
+                raise SettingsProblem(
+                    "Could not read bot upload settings.", status=503
+                ) from None
+            self._loaded = True
+
+    def _destination(self):
+        store = self.runtime.store
+        path = self.value.folder_path
+        if path is None:
+            for item in store.list_directory("/").values():
+                if item["name"].casefold() == DEFAULT_FOLDER_NAME.casefold():
+                    if item["type"] != "folder":
+                        raise SettingsProblem(
+                            f"A file named {DEFAULT_FOLDER_NAME} already exists. "
+                            "Choose a bot upload folder on the website."
+                        )
+                    path = f"/{item['id']}"
+                    break
+        if path is None:
+            return None, f"My Files / {DEFAULT_FOLDER_NAME}"
+        return path, folder_label(store, path)
+
+    async def snapshot(self):
+        async with self._lock:
+            await self._load()
+            try:
+                path, label = await asyncio.to_thread(self._destination)
+                available = True
+            except (*_MISSING, SettingsProblem):
+                path, label, available = (
+                    self.value.folder_path,
+                    "Folder unavailable",
+                    False,
+                )
+            site_url = getattr(self.settings, "public_url", None) or self.value.site_url
+            return {
+                "folder_path": self.value.folder_path,
+                "resolved_path": path,
+                "folder_label": label,
+                "available": available,
+                "enabled": bool(self.settings.main_bot_token_value),
+                "settings_url": site_url + SETTINGS_LOCATION if site_url else None,
+            }
+
+    async def save(self, value: BotUploadPreferences):
+        async with self._lock:
+            await self._load()
+            if "site_url" not in value.model_fields_set:
+                value = value.model_copy(update={"site_url": self.value.site_url})
+            if value.folder_path is not None:
+                try:
+                    await asyncio.to_thread(
+                        self.runtime.store.get_directory, value.folder_path
+                    )
+                except _MISSING:
+                    raise SettingsProblem(
+                        "Choose an existing folder outside Trash.", status=409
+                    ) from None
+            try:
+                await asyncio.to_thread(self._write, value)
+            except Exception:
+                raise SettingsProblem(
+                    "Could not save the bot upload folder. Try again.", status=503
+                ) from None
+            self.value = value
+        return await self.snapshot()
+
+    async def destination(self):
+        """Create the dedicated default lazily, then pin its stable folder ID."""
+        async with self._lock:
+            await self._load()
+            try:
+                path, label = await asyncio.to_thread(self._destination)
+            except _MISSING:
+                raise SettingsProblem(
+                    "The bot upload folder was moved or deleted. "
+                    "Use /set_folder to choose another on the website.",
+                    status=409,
+                ) from None
+            if path is None:
+                replica = getattr(self.runtime, "replica", None)
+                if replica is not None:
+                    await replica.before_mutation()
+                try:
+                    folder = await asyncio.to_thread(
+                        self.runtime.store.create_folder, "/", DEFAULT_FOLDER_NAME
+                    )
+                    path = f"/{folder['id']}"
+                except DuplicateNameError:
+                    path, label = await asyncio.to_thread(self._destination)
+            if self.value.folder_path is None:
+                value = self.value.model_copy(update={"folder_path": path})
+                try:
+                    await asyncio.to_thread(self._write, value)
+                except Exception:
+                    raise SettingsProblem(
+                        "Could not save the bot upload folder.", status=503
+                    ) from None
+                self.value = value
+            return path, label
+
+
+def get_bot_settings(settings, runtime):
+    service = getattr(runtime, "bot_settings", None)
+    if service is None:
+        service = BotSettings(settings, runtime)
+        runtime.bot_settings = service
+    return service
diff --git a/tgdrive/settings/managed_settings.py b/tgdrive/settings/managed_settings.py
new file mode 100644
index 00000000..9ce68b6a
--- /dev/null
+++ b/tgdrive/settings/managed_settings.py
@@ -0,0 +1,203 @@
+"""Private, atomic Telegram connection overrides; never drive metadata."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+MAX_CLIENTS = 50
+MAX_SETTINGS_BYTES = 64 * 1024
+_BOT = re.compile(r"[1-9][0-9]{4,14}:[A-Za-z0-9_-]{20,}")
+_ID = re.compile(r"[a-z0-9-]{1,80}")
+
+
+class SettingsProblem(RuntimeError):
+    def __init__(self, detail: str, *, code="SETTINGS_INVALID", status=422):
+        super().__init__(detail)
+        self.code = code
+        self.status = status
+
+
+class PrivateModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+
+
+class ManagedClient(PrivateModel):
+    id: str = Field(min_length=1, max_length=80)
+    label: str = Field(min_length=1, max_length=80)
+    kind: Literal["bot", "user"]
+    enabled: bool = True
+    credential: SecretStr
+    runtime_name: str | None = None
+
+    @field_validator("id")
+    @classmethod
+    def valid_id(cls, value: str) -> str:
+        if not _ID.fullmatch(value):
+            raise ValueError("Invalid connection identifier")
+        return value
+
+    @field_validator("label")
+    @classmethod
+    def valid_label(cls, value: str) -> str:
+        value = value.strip()
+        if not value or any(
+            ord(character) < 32 or ord(character) == 127 for character in value
+        ):
+            raise ValueError("Connection labels must contain visible text")
+        return value
+
+    @field_validator("credential")
+    @classmethod
+    def valid_credential(cls, value: SecretStr) -> SecretStr:
+        raw = value.get_secret_value().strip()
+        if not 1 <= len(raw) <= 8192 or any(character.isspace() for character in raw):
+            raise ValueError("Connection credential is invalid")
+        return SecretStr(raw)
+
+
+class ManagedDocument(PrivateModel):
+    schema_version: Literal[1] = 1
+    revision: int = Field(ge=1)
+    api_id: int = Field(gt=0, le=2147483647)
+    api_hash: SecretStr
+    clients: list[ManagedClient] = Field(min_length=1, max_length=MAX_CLIENTS)
+
+    @field_validator("api_hash")
+    @classmethod
+    def valid_hash(cls, value: SecretStr) -> SecretStr:
+        raw = value.get_secret_value().strip()
+        if not re.fullmatch(r"[a-fA-F0-9]{32}", raw):
+            raise ValueError("API hash must contain exactly 32 hexadecimal characters")
+        return SecretStr(raw)
+
+    @field_validator("clients")
+    @classmethod
+    def valid_clients(cls, values: list[ManagedClient]) -> list[ManagedClient]:
+        if len({row.id for row in values}) != len(values):
+            raise ValueError("Connection identifiers must be unique")
+        if not any(row.kind == "bot" and row.enabled for row in values):
+            raise ValueError("Keep at least one enabled storage bot")
+        for row in values:
+            if row.kind == "bot" and not _BOT.fullmatch(
+                row.credential.get_secret_value()
+            ):
+                raise ValueError("A storage bot token is invalid")
+        return values
+
+    def private_bytes(self) -> bytes:
+        result = self.model_dump(exclude={"api_hash", "clients"})
+        result["api_hash"] = self.api_hash.get_secret_value()
+        result["clients"] = [
+            row.model_dump(exclude={"credential"})
+            | {"credential": row.credential.get_secret_value()}
+            for row in self.clients
+        ]
+        raw = json.dumps(result, ensure_ascii=False, allow_nan=False).encode()
+        if len(raw) > MAX_SETTINGS_BYTES:
+            raise SettingsProblem("Connection settings exceed the 64 KiB limit")
+        return raw
+
+
+def read_document(data_dir: Path) -> ManagedDocument | None:
+    from pymongo.errors import PyMongoError
+
+    from tgdrive.storage.mongo import DatabaseUnavailable, for_directory
+
+    backend = for_directory(data_dir)
+    if backend is None:
+        raise SettingsProblem(
+            "Connection settings require a configured MongoDB database.", status=503
+        )
+    try:
+        with backend._settings_lock:
+            if not backend._settings_cached:
+                row = backend.db.settings.find_one({"_id": "telegram"})
+                backend._settings_document = (
+                    ManagedDocument.model_validate(row["document"]) if row else None
+                )
+                backend._settings_cached = True
+            document = backend._settings_document
+            return document.model_copy(deep=True) if document is not None else None
+    except PyMongoError, DatabaseUnavailable:
+        raise DatabaseUnavailable(
+            "MongoDB is unavailable. Restore database access before starting TGDrive."
+        ) from None
+    except Exception:
+        raise SettingsProblem(
+            "Could not read MongoDB connection settings.", status=503
+        ) from None
+
+
+def save_document(
+    data_dir: Path, document: ManagedDocument, expected_revision: int
+) -> None:
+    from tgdrive.storage.mongo import for_directory
+
+    backend = for_directory(data_dir)
+    raw = document.private_bytes()
+    if backend is None:
+        raise SettingsProblem(
+            "Connection settings require a configured MongoDB database.", status=503
+        )
+    from pymongo.errors import DuplicateKeyError
+
+    value = json.loads(raw)
+    try:
+        result = backend.write(
+            backend.db.settings,
+            "replace_one",
+            {"_id": "telegram", "revision": expected_revision},
+            {"_id": "telegram", "revision": document.revision, "document": value},
+            upsert=expected_revision == 0,
+        )
+        if expected_revision and result.matched_count != 1:
+            raise SettingsProblem(
+                "Connection settings changed. Refresh and retry.",
+                code="SETTINGS_CONFLICT",
+                status=409,
+            )
+    except DuplicateKeyError:
+        raise SettingsProblem(
+            "Connection settings changed. Refresh and retry.",
+            code="SETTINGS_CONFLICT",
+            status=409,
+        ) from None
+    with backend._settings_lock:
+        backend._settings_document = document.model_copy(deep=True)
+        backend._settings_cached = True
+
+
+def credential_id(kind: str, credential: str) -> str:
+    # Opaque source identity; raw credentials never appear in response IDs.
+    return kind + "-" + hashlib.sha256(credential.encode()).hexdigest()[:24]
+
+
+def initial_clients(settings) -> list[ManagedClient]:
+    rows = []
+    identities = iter(settings.managed_client_ids)
+    labels = iter(settings.managed_client_labels)
+    for kind, values in (
+        ("bot", settings.bot_tokens),
+        ("user", settings.string_sessions),
+    ):
+        for index, value in enumerate(values, 1):
+            rows.append(
+                ManagedClient(
+                    id=next(identities, credential_id(kind, value)),
+                    label=next(
+                        labels,
+                        f"Storage bot {index}"
+                        if kind == "bot"
+                        else f"Premium account {index}",
+                    ),
+                    kind=kind,
+                    credential=SecretStr(value),
+                )
+            )
+    return rows
diff --git a/tgdrive/settings/management.py b/tgdrive/settings/management.py
new file mode 100644
index 00000000..ae8aeb65
--- /dev/null
+++ b/tgdrive/settings/management.py
@@ -0,0 +1,845 @@
+"""Owner-only connection management with isolated verification and restart apply."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import secrets
+import shutil
+import time
+from collections import Counter
+from contextlib import suppress
+from typing import Any, Literal
+
+from pydantic import Field, SecretStr, ValidationError
+from telethon import TelegramClient, functions, utils
+from telethon.sessions import StringSession
+
+from tgdrive.core.config import Settings
+from tgdrive.settings.managed_settings import (
+    MAX_CLIENTS,
+    ManagedClient,
+    ManagedDocument,
+    PrivateModel,
+    SettingsProblem,
+    initial_clients,
+    read_document,
+    save_document,
+)
+from tgdrive.telegram.channel_state import storage_channel_problem
+from tgdrive.telegram.client_identity import IdentityCache, account_identity
+from tgdrive.telegram.connection_errors import connection_problem
+
+_PREFLIGHT_LOG = logging.getLogger("tgdrive.private_telegram_preflight")
+_PREFLIGHT_LOG.addHandler(logging.NullHandler())
+_PREFLIGHT_LOG.propagate = False
+_PREFLIGHT_LOG.setLevel(logging.CRITICAL + 1)
+
+
+class ClientChange(PrivateModel):
+    id: str | None = Field(default=None, max_length=80)
+    label: str = Field(min_length=1, max_length=80)
+    kind: Literal["bot", "user"]
+    enabled: bool = True
+    credential: SecretStr | None = None
+
+
+class SettingsChange(PrivateModel):
+    expected_revision: int = Field(ge=0)
+    api_id: int | None = Field(default=None, gt=0, le=2147483647)
+    api_hash: SecretStr | None = None
+    clients: list[ClientChange] | None = Field(
+        default=None, min_length=1, max_length=MAX_CLIENTS
+    )
+
+
+async def verify_connection(
+    api_id: int,
+    api_hash: str,
+    row: ManagedClient,
+    channel: int,
+    *,
+    identity_cache: IdentityCache | None = None,
+    require_pin: bool = True,
+) -> str:
+    """No messages are sent: use a separate in-memory session for every probe."""
+    client = None
+    try:
+        session = (
+            StringSession(row.credential.get_secret_value())
+            if row.kind == "user"
+            else StringSession()
+        )
+        client = TelegramClient(
+            session,
+            api_id,
+            api_hash,
+            receive_updates=False,
+            flood_sleep_threshold=0,
+            request_retries=2,
+            connection_retries=0,
+            timeout=10,
+            auto_reconnect=False,
+            base_logger=_PREFLIGHT_LOG,
+        )
+        client.parse_mode = None
+        async with asyncio.timeout(25):
+            await client.connect()
+            if row.kind == "bot":
+                await client.sign_in(bot_token=row.credential.get_secret_value())
+            elif not await client.is_user_authorized():
+                raise SettingsProblem(
+                    "Premium session has expired or is not authorized"
+                )
+            account = await client.get_me()
+            if account is None or bool(account.bot) != (row.kind == "bot"):
+                raise SettingsProblem(
+                    "Telegram account does not match the connection type"
+                )
+            if row.kind == "bot" and account.id != int(
+                row.credential.get_secret_value().split(":", 1)[0]
+            ):
+                raise SettingsProblem("Telegram bot identity did not match its token")
+            if row.kind == "user" and not getattr(account, "premium", False):
+                raise SettingsProblem(
+                    "This account does not have an active Telegram Premium subscription"
+                )
+            peer = await client.get_input_entity(channel)
+            result = await client(
+                functions.channels.GetFullChannelRequest(utils.get_input_channel(peer))
+            )
+            chat = next(
+                (item for item in result.chats if utils.get_peer_id(item) == channel),
+                None,
+            )
+            if chat is None or not getattr(chat, "broadcast", False):
+                raise SettingsProblem(
+                    "The account cannot access the configured storage channel"
+                )
+            problem = storage_channel_problem(chat, getattr(result, "full_chat", None))
+            if problem is not None:
+                raise SettingsProblem(problem[1], code=problem[0])
+            rights = getattr(chat, "admin_rights", None)
+            required = (
+                (
+                    ("post_messages", "edit_messages", "delete_messages")
+                    if require_pin
+                    else ("post_messages", "delete_messages")
+                )
+                if row.kind == "bot"
+                else ("post_messages",)
+            )
+            if not getattr(chat, "creator", False) and (
+                rights is None
+                or not all(getattr(rights, key, False) for key in required)
+            ):
+                raise SettingsProblem(
+                    "Storage bots need the required channel administrator permissions; "
+                    "Premium accounts need permission to post."
+                )
+            runtime_name = (
+                f"storage-bot-{account.id}"
+                if row.kind == "bot"
+                else f"premium-user-{account.id}"
+            )
+            if identity_cache is not None:
+                with suppress(Exception):
+                    identity = account_identity(account)
+                    if any(identity.values()):
+                        await asyncio.to_thread(
+                            identity_cache.write, runtime_name, identity
+                        )
+            return runtime_name
+    except SettingsProblem:
+        raise
+    except Exception as error:
+        access_problem = connection_problem(error, row.kind)
+        delay = getattr(error, "seconds", None)
+        if access_problem is not None:
+            detail = str(access_problem)
+        elif isinstance(delay, int) and delay > 0:
+            detail = (
+                "Telegram temporarily limited verification. Wait before trying again."
+            )
+        else:
+            detail = (
+                "Telegram could not verify this connection. Check credentials, "
+                "account access, and network connectivity."
+            )
+        problem = SettingsProblem(detail, code="SETTINGS_PREFLIGHT_FAILED", status=503)
+        problem.retry_after = delay if isinstance(delay, int) and delay > 0 else None
+        problem.retryable = isinstance(
+            error, (TimeoutError, ConnectionError, OSError)
+        ) or type(error).__name__ in {
+            "ServerError",
+            "RpcCallFailError",
+            "TimedOutError",
+        }
+        raise problem from None
+    finally:
+        if client is not None:
+            with suppress(Exception):
+                await client.disconnect()
+
+
+class ConnectionManager:
+    def __init__(self, settings: Any, runtime: Any, *, verifier=verify_connection):
+        self.settings = settings
+        self.runtime = runtime
+        self.verifier = verifier
+        self.lock = asyncio.Lock()
+        self.active = initial_clients(settings)
+        self.identity_cache = IdentityCache(settings.resolved_data_dir)
+        self._cached_names: dict[str, dict[str, str | None]] = {}
+        self._checks: dict[str, dict[str, Any]] = {}
+        self._checks_revision: int | None = None
+        self._check_tasks: set[asyncio.Task] = set()
+        self._refresh_not_before = 0.0
+
+    @property
+    def restart_required(self) -> bool:
+        revision, _, _, _ = self._desired()
+        return revision != self.settings.managed_revision
+
+    def login_api(self) -> tuple[int, SecretStr, int]:
+        """Private handoff for bounded login challenges; never an HTTP response."""
+        self._ensure_idle()
+        revision, api_id, api_hash, _ = self._desired()
+        return api_id, api_hash, revision
+
+    def session_is_saved(self, session_string: str) -> bool | None:
+        """Resolve ambiguous save outcomes without exposing the private session."""
+        try:
+            document = read_document(self.settings.resolved_data_dir)
+            if document is None:
+                return False
+            return any(
+                row.kind == "user"
+                and secrets.compare_digest(
+                    row.credential.get_secret_value().encode(), session_string.encode()
+                )
+                for row in document.clients
+            )
+        except Exception:
+            # Never revoke an authorization that may already be persisted.
+            return None
+
+    def check_upload_allowed(self) -> None:
+        if self.restart_required:
+            raise SettingsProblem(
+                "Connection changes are saved. Restart TGDrive before uploading.",
+                code="SETTINGS_RESTART_REQUIRED",
+                status=409,
+            )
+
+    def _ensure_idle(self) -> None:
+        runtime = self.runtime
+        if getattr(getattr(runtime, "bot_mode", None), "active_imports", 0):
+            raise SettingsProblem(
+                "Wait for the bot import to finish before changing connections.",
+                code="SETTINGS_BUSY",
+                status=409,
+            )
+        registry = getattr(runtime, "registry", None) or getattr(
+            getattr(runtime, "transfers", None), "registry", None
+        )
+        if registry is not None and any(
+            str(record.committed.status) not in {"completed", "cancelled"}
+            for record in registry.list()
+        ):
+            raise SettingsProblem(
+                "Finish or cancel pending transfers before changing connections.",
+                code="SETTINGS_BUSY",
+                status=409,
+            )
+        if self._stats()["staging_reserved_bytes"]:
+            raise SettingsProblem(
+                "Finish or cancel browser uploads before changing connections.",
+                code="SETTINGS_BUSY",
+                status=409,
+            )
+        backup = getattr(runtime, "backup", None)
+        store = getattr(runtime, "store", None)
+        if store is not None and callable(getattr(backup, "protection_status", None)):
+            status = backup.protection_status(store)
+            clean_watermark = (
+                status.get("protected_revision") == store.revision
+                and status.get("metadata_revision") == store.revision
+            )
+            if status.get("recovery_required") or (
+                status.get("state") != "protected" and not clean_watermark
+            ):
+                raise SettingsProblem(
+                    "Wait for the current drive backup to be confirmed before "
+                    "changing connections.",
+                    code="SETTINGS_BUSY",
+                    status=409,
+                )
+
+    def _desired(self) -> tuple[int, int, SecretStr, list[ManagedClient]]:
+        document = read_document(self.settings.resolved_data_dir)
+        if document is not None:
+            return (
+                document.revision,
+                document.api_id,
+                document.api_hash,
+                document.clients,
+            )
+        return 0, self.settings.api_id, self.settings.api_hash, self.active
+
+    async def _active_snapshot(
+        self,
+        desired: list[ManagedClient] | None = None,
+    ) -> list[dict[str, Any]]:
+        pool = getattr(self.runtime, "pool", None)
+        statuses = (
+            await pool.status() if callable(getattr(pool, "status", None)) else ()
+        )
+        names = [getattr(status, "name", "") for status in statuses] + [
+            row.runtime_name
+            or (
+                "storage-bot-" + row.credential.get_secret_value().split(":", 1)[0]
+                if row.kind == "bot"
+                else ""
+            )
+            for row in desired or []
+        ]
+        try:
+            self._cached_names = await asyncio.to_thread(
+                self.identity_cache.read_many, names
+            )
+        except Exception:
+            self._cached_names = {}  # Optional display data never blocks settings.
+        result = []
+        for index, row in enumerate(self.active):
+            # Pool preserves bot-first and user-second source order, including failures.
+            status = statuses[index] if index < len(statuses) else None
+            result.append(
+                {
+                    "id": row.id,
+                    "label": row.label,
+                    "display_name": getattr(status, "display_name", None),
+                    "username": getattr(status, "username", None),
+                    "identity_refreshing": bool(
+                        getattr(status, "identity_refreshing", False)
+                    ),
+                    "kind": row.kind,
+                    "identity_retry_at": getattr(status, "identity_retry_at", None),
+                    "runtime_name": getattr(status, "name", None),
+                    "connected": getattr(status, "connected", None),
+                    "healthy": bool(getattr(status, "healthy", False)),
+                    "premium": bool(
+                        row.kind == "user" and getattr(status, "started", False)
+                    ),
+                    "active_leases": getattr(status, "active_leases", 0),
+                    "error": getattr(status, "error", None)
+                    or (
+                        "Connection unavailable. Refresh to check credentials and "
+                        "storage-channel access; repair the connection and restart "
+                        "TGDrive if needed."
+                        if getattr(status, "last_error_type", None)
+                        else None
+                    ),
+                    "error_code": getattr(status, "error_code", None),
+                }
+            )
+        return result
+
+    async def refresh_connections(self) -> dict[str, Any]:
+        """Check saved credentials in isolated sessions; never block startup."""
+        async with self.lock:
+            if not self._check_tasks and time.monotonic() >= self._refresh_not_before:
+                revision, api_id, api_hash, rows = await asyncio.to_thread(
+                    self._desired
+                )
+                self._checks_revision = revision
+                self._checks = {
+                    row.id: {"connection_check": "queued"}
+                    for row in rows
+                    if row.enabled
+                }
+                self._refresh_not_before = time.monotonic() + 30
+                gate = asyncio.Semaphore(2)
+                for row in rows:
+                    if not row.enabled:
+                        continue
+                    task = asyncio.create_task(
+                        self._check_connection(revision, api_id, api_hash, row, gate)
+                    )
+                    self._check_tasks.add(task)
+                    task.add_done_callback(self._check_tasks.discard)
+        return await self.snapshot()
+
+    async def _check_connection(self, revision, api_id, api_hash, row, gate):
+        state = self._checks[row.id]
+        name = row.runtime_name
+        if name is None and row.kind == "bot":
+            name = "storage-bot-" + row.credential.get_secret_value().split(":", 1)[0]
+        try:
+            deadline = 0.0
+            for attempt in range(3):
+                while True:
+                    if name:
+                        with suppress(Exception):
+                            deadline = max(
+                                deadline,
+                                await asyncio.to_thread(
+                                    self.identity_cache.retry_at, name
+                                ),
+                            )
+                        retry_at = getattr(
+                            getattr(self.runtime, "pool", None),
+                            "account_retry_at",
+                            None,
+                        )
+                        if callable(retry_at):
+                            deadline = max(deadline, await retry_at(name))
+                    if deadline <= time.time():
+                        break
+                    state.update(
+                        connection_check="waiting", connection_retry_at=deadline
+                    )
+                    await asyncio.sleep(max(0, deadline - time.time()))
+                async with gate:
+                    current_revision, _, _, _ = await asyncio.to_thread(self._desired)
+                    if current_revision != revision:
+                        return
+                    state.update(connection_check="checking", connection_retry_at=None)
+                    try:
+                        async with asyncio.timeout(30):
+                            if self.verifier is verify_connection:
+                                verified_name = await self.verifier(
+                                    api_id,
+                                    api_hash.get_secret_value(),
+                                    row,
+                                    self.settings.storage_channel,
+                                    identity_cache=self.identity_cache,
+                                    require_pin=False,
+                                )
+                            else:
+                                verified_name = await self.verifier(
+                                    api_id,
+                                    api_hash.get_secret_value(),
+                                    row,
+                                    self.settings.storage_channel,
+                                )
+                        pool = getattr(self.runtime, "pool", None)
+                        restore = getattr(pool, "restore_channel_access", None)
+                        if (
+                            callable(restore)
+                            and revision == self.settings.managed_revision
+                        ):
+                            await restore(verified_name)
+                        state.update(
+                            connection_check="passed",
+                            connection_check_error=None,
+                            connection_checked_at=time.time(),
+                        )
+                        return
+                    except Exception as error:
+                        # Only our sanitized verifier messages may reach the browser.
+                        detail = (
+                            str(error)
+                            if isinstance(error, SettingsProblem)
+                            else ("Could not check this connection. Try again.")
+                        )
+                        delay = getattr(error, "retry_after", None)
+                        limited = isinstance(delay, int) and delay > 0
+                        deadline = time.time() + (
+                            delay + 0.25 if limited else (5 if attempt == 0 else 15)
+                        )
+                        if limited and name:
+                            with suppress(Exception):
+                                await asyncio.to_thread(
+                                    self.identity_cache.defer, name, deadline
+                                )
+                            defer = getattr(
+                                getattr(self.runtime, "pool", None),
+                                "defer_client",
+                                None,
+                            )
+                            if callable(defer):
+                                await defer(name, deadline)
+                        if attempt == 2 or not (
+                            limited
+                            or getattr(error, "retryable", False)
+                            or isinstance(
+                                error, (TimeoutError, ConnectionError, OSError)
+                            )
+                        ):
+                            state.update(
+                                connection_check="failed",
+                                connection_check_error=detail,
+                                connection_checked_at=time.time(),
+                                connection_retry_at=deadline if limited else None,
+                            )
+                            return
+                        state.update(
+                            connection_check="waiting",
+                            connection_retry_at=deadline,
+                            connection_check_error=None,
+                        )
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            state.update(
+                connection_check="failed",
+                connection_check_error="Could not check this connection. Try again.",
+                connection_checked_at=time.time(),
+                connection_retry_at=None,
+            )
+
+    async def close(self) -> None:
+        tasks = list(self._check_tasks)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        self._check_tasks.clear()
+
+    async def snapshot(self) -> dict[str, Any]:
+        revision, api_id, _, rows = await asyncio.to_thread(self._desired)
+        active = await self._active_snapshot(rows)
+        return await asyncio.to_thread(self._snapshot, revision, api_id, rows, active)
+
+    def _snapshot(
+        self,
+        revision: int,
+        api_id: int,
+        rows: list[ManagedClient],
+        active: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        active_by_id = {row["id"]: row for row in active}
+        clients = []
+        for row in rows:
+            live = active_by_id.get(row.id, {})
+            if row.runtime_name and live.get("runtime_name") != row.runtime_name:
+                live = {}  # A replacement account has not started yet.
+            identity = {
+                "display_name": live.get("display_name"),
+                "username": live.get("username"),
+            }
+            identity = self._cached_names.get(
+                row.runtime_name
+                or live.get("runtime_name")
+                or (
+                    "storage-bot-" + row.credential.get_secret_value().split(":", 1)[0]
+                    if row.kind == "bot"
+                    else None
+                ),
+                identity,
+            )
+            clients.append(
+                {
+                    "id": row.id,
+                    "label": row.label,
+                    "kind": row.kind,
+                    "enabled": row.enabled,
+                    "configured": True,
+                    "display_name": identity.get("display_name"),
+                    "username": identity.get("username"),
+                    "identity_refreshing": live.get("identity_refreshing", False),
+                    "identity_retry_at": live.get("identity_retry_at"),
+                    "connected": live.get("connected"),
+                    "healthy": live.get("healthy", False),
+                    "premium": live.get("premium", False),
+                    "active_leases": live.get("active_leases", 0),
+                    "error": live.get("error"),
+                    "error_code": live.get("error_code"),
+                    **(
+                        self._checks.get(row.id, {})
+                        if row.enabled and revision == self._checks_revision
+                        else {}
+                    ),
+                }
+            )
+        backup = getattr(self.runtime, "backup", None)
+        store = getattr(self.runtime, "store", None)
+        return {
+            "revision": revision,
+            "applied_revision": self.settings.managed_revision,
+            "restart_required": revision != self.settings.managed_revision,
+            "admission_paused": revision != self.settings.managed_revision,
+            "application_mode": "restart",
+            "api_id": api_id,
+            "api_hash_configured": True,
+            "storage_channel": self.settings.storage_channel,
+            "clients": clients,
+            "active_clients": active,
+            "storage_channel_error": getattr(
+                self.runtime, "storage_channel_error", None
+            ),
+            "stats": self._stats(),
+            "recovery": backup.protection_status(store)
+            if store is not None
+            and callable(getattr(backup, "protection_status", None))
+            else None,
+        }
+
+    def _stats(self) -> dict[str, Any]:
+        store = getattr(self.runtime, "store", None)
+        result = {
+            "files": 0,
+            "folders": 0,
+            "total_bytes": 0,
+            "trashed_files": 0,
+            "trashed_bytes": 0,
+        }
+        if callable(getattr(store, "statistics", None)):
+            result.update(store.statistics())
+        registry = getattr(self.runtime, "registry", None) or getattr(
+            getattr(self.runtime, "transfers", None), "registry", None
+        )
+        records = (
+            [record.committed for record in registry.list()]
+            if registry is not None
+            else ()
+        )
+        counts = Counter(str(item.status) for item in records)
+        result.update(
+            active_jobs=counts["running"] + counts["cancelling"],
+            queued_jobs=counts["queued"],
+            failed_jobs=counts["error"],
+            staging_budget_bytes=self.settings.staging_budget_bytes,
+            staging_reserved_bytes=0,
+            free_disk_bytes=None,
+        )
+        mongo = self.runtime.mongo
+        finished = {
+            row.id for row in records if str(row.status) in {"completed", "cancelled"}
+        }
+        result["staging_reserved_bytes"] = sum(
+            row["data"]["total_size"]
+            for row in mongo.db.receipts.find(
+                {"data.state": {"$in": ["receiving", "queued", "cancelling"]}}
+            )
+            if row["_id"] not in finished
+        )
+        with suppress(OSError):
+            result["free_disk_bytes"] = shutil.disk_usage(
+                self.settings.resolved_cache_dir
+            ).free
+        return result
+
+    async def _credential_repair(
+        self, document: ManagedDocument, existing: list[ManagedClient], api_id, api_hash
+    ) -> dict[str, str] | None:
+        """Allow credential-only repairs without discarding pending sender journals."""
+        if (
+            document.api_id != api_id
+            or document.api_hash != api_hash
+            or [row.id for row in document.clients] != [row.id for row in existing]
+        ):
+            return None
+        statuses = ()
+        pool = getattr(self.runtime, "pool", None)
+        if callable(getattr(pool, "status", None)):
+            statuses = await pool.status()
+        live_names = {
+            row.id: status.name
+            for row, status in zip(self.active, statuses, strict=False)
+        }
+        changed = {}
+        for row, prior in zip(document.clients, existing, strict=True):
+            if row.kind != prior.kind or row.enabled != prior.enabled:
+                return None
+            if row.credential == prior.credential:
+                continue
+            name = (
+                "storage-bot-" + prior.credential.get_secret_value().split(":", 1)[0]
+                if prior.kind == "bot"
+                else prior.runtime_name or live_names.get(prior.id)
+            )
+            if not name or not name.startswith(("storage-bot-", "premium-user-")):
+                return None
+            changed[row.id] = name
+        return changed or None
+
+    async def save(self, change: SettingsChange) -> dict[str, Any]:
+        async with self.lock:
+            await self.close()
+            self._checks.clear()
+            self._refresh_not_before = 0
+            revision, api_id, api_hash, existing = self._desired()
+            if change.expected_revision != revision:
+                raise SettingsProblem(
+                    "Connection settings changed. Refresh before saving.",
+                    code="SETTINGS_CONFLICT",
+                    status=409,
+                )
+            known = {row.id: row for row in existing}
+            rows = existing
+            if change.clients is not None:
+                rows = []
+                for requested in change.clients:
+                    prior = known.get(requested.id) if requested.id else None
+                    if requested.id is not None and prior is None:
+                        raise SettingsProblem("Unknown connection identifier")
+                    if prior is not None and prior.kind != requested.kind:
+                        raise SettingsProblem("A connection type cannot be changed")
+                    credential = requested.credential or (
+                        prior.credential if prior else None
+                    )
+                    if credential is None:
+                        raise SettingsProblem("New connections require a credential")
+                    rows.append(
+                        ManagedClient(
+                            id=prior.id if prior else secrets.token_hex(16),
+                            label=requested.label,
+                            kind=requested.kind,
+                            enabled=requested.enabled,
+                            credential=credential,
+                            runtime_name=prior.runtime_name
+                            if prior and requested.credential is None
+                            else None,
+                        )
+                    )
+            try:
+                document = ManagedDocument(
+                    revision=revision + 1,
+                    api_id=change.api_id if change.api_id is not None else api_id,
+                    api_hash=change.api_hash
+                    if change.api_hash is not None
+                    else api_hash,
+                    clients=rows,
+                )
+            except ValidationError:
+                raise SettingsProblem(
+                    "Invalid connection settings. Check API credentials and keep "
+                    "at least one enabled storage bot."
+                ) from None
+            document.private_bytes()  # Bound the file before any network work.
+            # Validate the effective startup configuration before saving.
+            effective = self.settings.model_dump(by_alias=True)
+            effective.update(
+                API_ID=document.api_id,
+                API_HASH=document.api_hash,
+                BOT_TOKENS=",".join(
+                    row.credential.get_secret_value()
+                    for row in rows
+                    if row.kind == "bot" and row.enabled
+                ),
+                STRING_SESSIONS=",".join(
+                    row.credential.get_secret_value()
+                    for row in rows
+                    if row.kind == "user" and row.enabled
+                ),
+            )
+            try:
+                Settings(_env_file=None, **effective)
+            except ValidationError:
+                raise SettingsProblem(
+                    "These connections cannot satisfy the current configuration. "
+                    "Check the configured storage credentials."
+                ) from None
+            repair = None
+            try:
+                self._ensure_idle()
+            except SettingsProblem:
+                repair = await self._credential_repair(
+                    document, existing, api_id, api_hash
+                )
+                if repair is None:
+                    raise
+            # Verify replacements before saving; retain unchanged connections
+            # during a same-account repair. Running clients are not replaced here.
+            gate = asyncio.Semaphore(2)
+
+            async def verify(row):
+                if not row.enabled:
+                    return row.runtime_name
+                if repair is not None and row.id not in repair:
+                    return row.runtime_name
+                async with gate:
+                    if self.verifier is verify_connection:
+                        return await verify_connection(
+                            document.api_id,
+                            document.api_hash.get_secret_value(),
+                            row,
+                            self.settings.storage_channel,
+                            identity_cache=self.identity_cache,
+                            require_pin=False,
+                        )
+                    return await self.verifier(
+                        document.api_id,
+                        document.api_hash.get_secret_value(),
+                        row,
+                        self.settings.storage_channel,
+                    )
+
+            try:
+                async with asyncio.timeout(90):
+                    names = await asyncio.gather(
+                        *(verify(row) for row in rows), return_exceptions=True
+                    )
+                    for result in names:
+                        if isinstance(result, SettingsProblem):
+                            raise result
+                        if isinstance(result, BaseException):
+                            raise SettingsProblem(
+                                "Telegram verification failed. No changes were saved.",
+                                code="SETTINGS_PREFLIGHT_FAILED",
+                                status=503,
+                            )
+            except TimeoutError:
+                raise SettingsProblem(
+                    "Telegram verification timed out. No changes were saved.",
+                    code="SETTINGS_PREFLIGHT_FAILED",
+                    status=503,
+                ) from None
+            active_names = [
+                name
+                for row, name in zip(rows, names, strict=True)
+                if row.enabled and name is not None
+            ]
+            if len(set(active_names)) != len(active_names):
+                raise SettingsProblem("The same Telegram account cannot be added twice")
+            for row, name in zip(rows, names, strict=True):
+                if repair is not None and row.id in repair and name != repair[row.id]:
+                    raise SettingsProblem(
+                        "Pending transfers require the same Telegram account. "
+                        "Replace the token or session for that account; changing "
+                        "its identity requires finishing pending transfers first.",
+                        code="SETTINGS_BUSY",
+                        status=409,
+                    )
+                row.runtime_name = name
+            # Build every fallible response field before the commit. In
+            # particular, cancellation while collecting pool health must not
+            # make an authenticated login revoke an already persisted session.
+            active = await self._active_snapshot(rows)
+            response = self._snapshot(document.revision, document.api_id, rows, active)
+            if repair is None:
+                self._ensure_idle()
+            await asyncio.to_thread(
+                save_document, self.settings.resolved_data_dir, document, revision
+            )
+            return response
+
+    async def add_authenticated_session(
+        self, expected_revision: int, label: str, session_string: str
+    ) -> dict[str, Any]:
+        revision, _, _, existing = self._desired()
+        if revision != expected_revision:
+            raise SettingsProblem(
+                "Connection settings changed. Refresh before saving.",
+                code="SETTINGS_CONFLICT",
+                status=409,
+            )
+        clients = [
+            ClientChange(id=row.id, label=row.label, kind=row.kind, enabled=row.enabled)
+            for row in existing
+        ]
+        clients.append(
+            ClientChange(label=label, kind="user", credential=SecretStr(session_string))
+        )
+        return await self.save(
+            SettingsChange(expected_revision=revision, clients=clients)
+        )
+
+
+def get_connection_manager(settings, runtime) -> ConnectionManager:
+    manager = getattr(runtime, "connection_manager", None)
+    if manager is None:
+        manager = ConnectionManager(settings, runtime)
+        runtime.connection_manager = manager
+    return manager
diff --git a/tgdrive/settings/management_api.py b/tgdrive/settings/management_api.py
new file mode 100644
index 00000000..cca46ec0
--- /dev/null
+++ b/tgdrive/settings/management_api.py
@@ -0,0 +1,80 @@
+"""Narrow owner routes; credentials are write-only and never serialized."""
+
+from fastapi import Depends, Request, Response
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError
+
+from tgdrive.settings.bot_settings import BotUploadPreferences, get_bot_settings
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.settings.management import SettingsChange, get_connection_manager
+from tgdrive.settings.premium_login_api import register_premium_routes
+from tgdrive.settings.transfer_preferences import (
+    UploadPreferences,
+    get_transfer_preferences,
+)
+
+
+def register_management_routes(app, settings, *, require_admin, get_runtime):
+    register_premium_routes(
+        app,
+        require_admin=require_admin,
+        get_service=lambda request: get_connection_manager(
+            settings, get_runtime(request)
+        ),
+    )
+    admin = [Depends(require_admin)]
+
+    @app.get("/api/v1/settings/bot-mode", dependencies=admin)
+    async def bot_preferences(request: Request, response: Response):
+        response.headers["Cache-Control"] = "no-store"
+        return await get_bot_settings(settings, get_runtime(request)).snapshot()
+
+    @app.patch("/api/v1/settings/bot-mode", dependencies=admin)
+    async def save_bot_preferences(
+        change: BotUploadPreferences, request: Request, response: Response
+    ):
+        response.headers["Cache-Control"] = "no-store"
+        return await get_bot_settings(settings, get_runtime(request)).save(change)
+
+    @app.exception_handler(SettingsProblem)
+    async def settings_problem(_request: Request, error: SettingsProblem):
+        return JSONResponse(
+            {"detail": str(error), "code": error.code}, status_code=error.status
+        )
+
+    @app.get("/api/v1/settings", dependencies=admin)
+    async def connection_settings(request: Request, response: Response):
+        response.headers["Cache-Control"] = "no-store"
+        manager = get_connection_manager(settings, get_runtime(request))
+        return await manager.snapshot()
+
+    @app.patch("/api/v1/settings", dependencies=admin)
+    async def update_connection_settings(
+        change: SettingsChange, request: Request, response: Response
+    ):
+        response.headers["Cache-Control"] = "no-store"
+        manager = get_connection_manager(settings, get_runtime(request))
+        try:
+            return await manager.save(change)
+        except ValidationError:
+            raise SettingsProblem("Invalid connection settings") from None
+
+    @app.post("/api/v1/settings/refresh", dependencies=admin, status_code=202)
+    async def refresh_connections(request: Request, response: Response):
+        response.headers["Cache-Control"] = "no-store"
+        manager = get_connection_manager(settings, get_runtime(request))
+        return await manager.refresh_connections()
+
+    @app.get("/api/v1/settings/uploads", dependencies=admin)
+    async def upload_preferences(request: Request, response: Response):
+        response.headers["Cache-Control"] = "no-store"
+        return await get_transfer_preferences(settings, get_runtime(request)).snapshot()
+
+    @app.patch("/api/v1/settings/uploads", dependencies=admin)
+    async def save_upload_preferences(
+        change: UploadPreferences, request: Request, response: Response
+    ):
+        response.headers["Cache-Control"] = "no-store"
+        return await get_transfer_preferences(settings, get_runtime(request)).save(
+            change
+        )
diff --git a/tgdrive/settings/performance_preferences.py b/tgdrive/settings/performance_preferences.py
new file mode 100644
index 00000000..21cf3283
--- /dev/null
+++ b/tgdrive/settings/performance_preferences.py
@@ -0,0 +1,260 @@
+"""Durable operator-owned resource policies, applied without a restart."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from tgdrive.settings.managed_settings import SettingsProblem
+
+
+class PerformancePreferences(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    timezone: str = "Asia/Kolkata"
+    cache_memory_bytes: int = Field(default=256 * 1024**2, ge=0, le=8 * 1024**3)
+    cache_disk_bytes: int = Field(default=10 * 1024**3, ge=0, le=2 * 1024**4)
+    cache_min_free_bytes: int = Field(default=1024**3, ge=0, le=2 * 1024**4)
+    cache_ttl_seconds: int = Field(default=86400, ge=60, le=2678400)
+    auto_preload: bool = True
+    preload_max_jobs: int = Field(default=2, ge=1, le=8)
+    remote_download_concurrency: int = Field(default=2, ge=1, le=8)
+    telegram_upload_pipeline: int = Field(default=4, ge=1, le=16)
+    telegram_request_limit: int = Field(default=8, ge=1, le=32)
+    telegram_parts_per_second: int = Field(default=48, ge=1, le=128)
+    telegram_media_per_bot: int = Field(default=3, ge=1, le=16)
+    telegram_max_queue: int = Field(default=256, ge=1, le=4096)
+    upload_split_mib: int = Field(default=2000, ge=0, le=2000)
+    max_file_size: int = Field(default=16 * 1024**3, ge=1, le=2 * 1024**4)
+    staging_budget_bytes: int = Field(default=16 * 1024**3, ge=1, le=2 * 1024**4)
+    min_free_bytes: int = Field(default=1024**3, ge=0, le=2 * 1024**4)
+
+    @field_validator("timezone")
+    @classmethod
+    def timezone_exists(cls, value):
+        try:
+            ZoneInfo(value)
+        except (ValueError, ZoneInfoNotFoundError) as error:
+            raise ValueError(
+                "Choose a valid IANA timezone, such as Asia/Kolkata"
+            ) from error
+        return value
+
+    def cache_policy(self):
+        from tgdrive.media.media_policy import MediaCachePolicy
+
+        return MediaCachePolicy(
+            disk_max_bytes=self.cache_disk_bytes,
+            memory_max_bytes=self.cache_memory_bytes,
+            min_free_bytes=self.cache_min_free_bytes,
+            ttl_seconds=self.cache_ttl_seconds,
+            max_background_jobs=self.preload_max_jobs,
+            auto_preload=self.auto_preload,
+        )
+
+
+class PerformanceSettings:
+    def __init__(self, settings, runtime):
+        self.settings, self.runtime = settings, runtime
+        initial = PerformancePreferences().model_dump()
+        initial.update(
+            {key: getattr(settings, key) for key in initial if hasattr(settings, key)}
+        )
+        initial["max_file_size"] = (
+            settings.max_file_size or settings.staging_budget_bytes
+        )
+        self.value = PerformancePreferences.model_validate(initial)
+        self._lock = asyncio.Lock()
+        self._loaded = False
+
+    def _read(self):
+        backend = self.runtime.mongo
+        row = backend.db.settings.find_one({"_id": "performance-preferences"})
+        raw = row["document"] if row else None
+        return (
+            PerformancePreferences.model_validate(self.value.model_dump() | raw)
+            if raw is not None
+            else self.value
+        )
+
+    def _write(self, value):
+        document = value.model_dump()
+        backend = self.runtime.mongo
+        backend.write(
+            backend.db.settings,
+            "replace_one",
+            {"_id": "performance-preferences"},
+            {"_id": "performance-preferences", "document": document},
+            upsert=True,
+        )
+
+    async def _apply(self, value):
+        for key, item in value.model_dump().items():
+            setattr(self.settings, key, item)
+        manager = getattr(self.runtime, "transfers", None)
+        remote = getattr(manager, "remote", None) or getattr(
+            self.runtime, "remote", None
+        )
+        if remote is not None:
+            remote.max_bytes = self.settings.upload_limit
+            remote.min_free_bytes = value.min_free_bytes
+            scheduler = getattr(remote, "scheduler", None)
+            if scheduler is not None:
+                await scheduler.configure(value.remote_download_concurrency)
+        pool = getattr(self.runtime, "pool", None)
+        if pool is None or not hasattr(pool, "__dict__"):
+            return
+        for method, argument in (
+            ("set_media_per_bot", value.telegram_media_per_bot),
+            ("set_media_queue_limit", value.telegram_max_queue),
+        ):
+            setter = getattr(pool, method, None)
+            if callable(setter):
+                await setter(argument)
+        for slot in getattr(pool, "_slots", ()):
+            client = getattr(slot, "client", None)
+            configure = getattr(client, "configure_transport", None)
+            if callable(configure):
+                configure(
+                    upload_pipeline=value.telegram_upload_pipeline,
+                    request_limit=value.telegram_request_limit,
+                    parts_per_second=value.telegram_parts_per_second,
+                )
+        from tgdrive.media.media_reader import MediaReadCache
+        from tgdrive.media.preloading import PreloadManager
+
+        policy = value.cache_policy()
+        cache = getattr(pool, "_media_read_cache", None)
+        manager = getattr(self.runtime, "preloads", None)
+        if manager is None:
+            if cache is None:
+                directory = getattr(pool, "media_cache_dir", None)
+                if directory is None:
+                    directory = self.settings.resolved_data_dir / "media-cache"
+                    pool.media_cache_dir = directory
+                pool._media_read_cache = MediaReadCache(directory, policy)
+            else:
+                await cache.reconfigure(policy)
+            pool._media_read_cache.deferred_writes = True
+            self.runtime.preloads = PreloadManager(pool, policy=policy)
+        else:
+            await manager.reconfigure(policy)
+
+    async def initialize(self):
+        async with self._lock:
+            if not self._loaded:
+                try:
+                    value = await asyncio.to_thread(self._read)
+                    await self._apply(value)
+                except Exception:
+                    raise SettingsProblem(
+                        "Could not load performance settings; "
+                        "check MongoDB access and saved settings, then retry.",
+                        status=503,
+                    ) from None
+                self.value, self._loaded = value, True
+
+    def etag(self):
+        raw = json.dumps(self.value.model_dump(), sort_keys=True).encode()
+        return '"' + hashlib.sha256(raw).hexdigest() + '"'
+
+    async def snapshot(self):
+        await self.initialize()
+        return self.value.model_dump() | {
+            "revision": self.etag(),
+            "defaults": PerformancePreferences().model_dump(),
+            "documentation_url": "https://github.com/TechShreyash/TGDrive/blob/main/docs/configuration.md",
+        }
+
+    async def save(self, changes, *, expected=None):
+        await self.initialize()
+        async with self._lock:
+            if expected is not None and expected != self.etag():
+                raise SettingsProblem(
+                    "Settings changed in another tab. Reload before saving.", status=409
+                )
+            try:
+                value = PerformancePreferences.model_validate(
+                    self.value.model_dump() | changes
+                )
+                if (
+                    {"cache_disk_bytes", "cache_min_free_bytes"}.intersection(changes)
+                    and value.cache_disk_bytes > 0
+                    and value.cache_min_free_bytes < 64 * 1024**2
+                ):
+                    raise SettingsProblem(
+                        "Keep at least 64 MiB (0.0625 GiB) free "
+                        "while disk caching is enabled. "
+                        "Use the 1 GiB default for normal operation.",
+                        status=422,
+                    )
+                upload_keys = {
+                    "max_file_size",
+                    "staging_budget_bytes",
+                    "min_free_bytes",
+                }
+                if upload_keys.intersection(changes):
+                    if value.max_file_size > value.staging_budget_bytes:
+                        raise SettingsProblem(
+                            "Maximum file size cannot exceed "
+                            "the temporary upload budget. "
+                            "Increase the budget or lower the file limit.",
+                            status=422,
+                        )
+                    if value.min_free_bytes < 64 * 1024**2:
+                        raise SettingsProblem(
+                            "Keep at least 64 MiB free for upload storage. "
+                            "The recommended default is 1 GiB.",
+                            status=422,
+                        )
+                    from tgdrive.transfers.staging import staging_usage
+
+                    manager = getattr(self.runtime, "transfers", None)
+                    reserved, _ = staging_usage(manager)
+                    if value.staging_budget_bytes < reserved:
+                        raise SettingsProblem(
+                            "The temporary budget is below space "
+                            "already reserved by uploads. "
+                            "Finish or cancel transfers first.",
+                            status=409,
+                        )
+                await asyncio.to_thread(self._write, value)
+            except SettingsProblem:
+                raise
+            except ValueError:
+                raise
+            except Exception:
+                raise SettingsProblem(
+                    "Could not save performance settings. No changes were applied.",
+                    status=503,
+                ) from None
+            try:
+                await self._apply(value)
+            except Exception:
+                restored = True
+                try:
+                    await asyncio.to_thread(self._write, self.value)
+                    await self._apply(self.value)
+                except Exception:
+                    restored = False
+                detail = (
+                    "Could not apply performance settings. "
+                    "The previous policy was restored."
+                    if restored
+                    else "Could not apply performance settings. "
+                    "Restart the service to reconcile the saved policy."
+                )
+                raise SettingsProblem(detail, status=503) from None
+            self.value = value
+        return await self.snapshot()
+
+
+def get_performance_settings(settings, runtime):
+    service = getattr(runtime, "performance_settings", None)
+    if service is None:
+        service = PerformanceSettings(settings, runtime)
+        runtime.performance_settings = service
+    return service
diff --git a/tgdrive/settings/premium_login.py b/tgdrive/settings/premium_login.py
new file mode 100644
index 00000000..8548d415
--- /dev/null
+++ b/tgdrive/settings/premium_login.py
@@ -0,0 +1,463 @@
+"""Short-lived owner-bound Telegram login without browser session exports."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import re
+import secrets
+import time
+from collections import deque
+from collections.abc import Awaitable, Callable
+from contextlib import asynccontextmanager, suppress
+from dataclasses import dataclass, field
+from typing import Any
+
+from telethon import TelegramClient
+from telethon.errors import (
+    FloodWaitError,
+    PasswordHashInvalidError,
+    PhoneCodeExpiredError,
+    PhoneCodeInvalidError,
+    PhoneNumberInvalidError,
+    SessionPasswordNeededError,
+)
+from telethon.sessions import StringSession
+
+LOGIN_TTL = 300
+MAX_CHALLENGES = 2
+MAX_ATTEMPTS = 5
+# Telegram RPC diagnostics can contain authentication input. This dedicated
+# transport logger intentionally has no output even when application DEBUG is on.
+_AUTH_LOG = logging.getLogger("tgdrive.private_telegram_login")
+_AUTH_LOG.addHandler(logging.NullHandler())
+_AUTH_LOG.propagate = False
+_AUTH_LOG.setLevel(logging.CRITICAL + 1)
+
+
+class PremiumLoginProblem(RuntimeError):
+    def __init__(
+        self,
+        detail: str,
+        *,
+        code: str = "TELEGRAM_LOGIN_FAILED",
+        status: int = 422,
+        retry_after: int | None = None,
+    ):
+        super().__init__(detail)
+        self.code, self.status, self.retry_after = code, status, retry_after
+
+
+@dataclass(repr=False)
+class _Challenge:
+    owner: str
+    client: Any
+    phone: str
+    label: str
+    revision: int
+    expires: float
+    phone_code_hash: str = ""
+    stage: str = "code"
+    attempts: int = 0
+    authorized: bool = False
+    saved: bool = False
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    cleanup: asyncio.Task | None = None
+
+
+def _new_client(api_id: int, api_hash: str) -> TelegramClient:
+    return TelegramClient(
+        StringSession(),
+        api_id,
+        api_hash,
+        receive_updates=False,
+        request_retries=1,
+        connection_retries=1,
+        flood_sleep_threshold=0,
+        auto_reconnect=False,
+        base_logger=_AUTH_LOG,
+        device_model="TGDrive web connection",
+    )
+
+
+class PremiumLoginService:
+    def __init__(
+        self,
+        api_credentials: Callable[[], tuple[int, Any, int]],
+        save_session: Callable[[int, str, str], Awaitable[dict[str, Any]]],
+        *,
+        client_factory: Callable[[int, str], Any] = _new_client,
+        clock: Callable[[], float] = time.monotonic,
+        is_session_saved: Callable[[str], bool | None] | None = None,
+    ):
+        self.api_credentials = api_credentials
+        self.save_session = save_session
+        self.client_factory, self.clock = client_factory, clock
+        self.is_session_saved = is_session_saved
+        self.challenges: dict[str, _Challenge] = {}
+        self._starts: deque[float] = deque(maxlen=6)
+        self._phones: deque[tuple[str, float]] = deque(maxlen=32)
+        self._cooldown = 0.0
+        self._guard = asyncio.Lock()
+        self._reaper: asyncio.Task | None = None
+        self._closed = False
+        self._operations: set[asyncio.Task] = set()
+        self._cleanups: set[asyncio.Task] = set()
+
+    @asynccontextmanager
+    async def _operation(self):
+        if self._closed:
+            raise PremiumLoginProblem(
+                "Login is unavailable while TGDrive stops.", status=503
+            )
+        task = asyncio.current_task()
+        self._operations.add(task)
+        try:
+            yield
+        finally:
+            self._operations.discard(task)
+
+    async def _dispose(self, challenge: _Challenge) -> None:
+        # Cleanup owns its own bounded task: a disconnected HTTP request or
+        # cancelled reaper must not abandon an authorization after map removal.
+        task = challenge.cleanup
+        if task is None:
+            task = asyncio.create_task(
+                self._cleanup(challenge), name="telegram-login-cleanup"
+            )
+            challenge.cleanup = task
+            self._cleanups.add(task)
+            task.add_done_callback(self._cleanups.discard)
+        cancelled = False
+        while not task.done():
+            try:
+                await asyncio.shield(task)
+            except asyncio.CancelledError:
+                cancelled = True
+        if cancelled:
+            raise asyncio.CancelledError
+        task.result()
+
+    async def _cleanup(self, challenge: _Challenge) -> None:
+        # All challenges own a fresh session. Even a lost sign-in reply may
+        # have authorized it remotely, so try logout for every unsaved session.
+        # Never revoke a session whose settings save committed or is ambiguous.
+        try:
+            if not challenge.saved:
+                with suppress(Exception):
+                    async with asyncio.timeout(5):
+                        await challenge.client.log_out()
+        finally:
+            with suppress(Exception):
+                async with asyncio.timeout(5):
+                    await challenge.client.disconnect()
+
+    async def _expire(self) -> None:
+        for identity, challenge in list(self.challenges.items()):
+            if challenge.expires <= self.clock() and not challenge.lock.locked():
+                self.challenges.pop(identity, None)
+                await self._dispose(challenge)
+
+    async def _reap(self) -> None:
+        try:
+            while not self._closed:
+                await asyncio.sleep(15)
+                await self._expire()
+        except asyncio.CancelledError:
+            return
+
+    def _check_rate(self) -> None:
+        now = self.clock()
+        if self._cooldown > now:
+            raise PremiumLoginProblem(
+                "Telegram asks you to wait before trying again.",
+                code="TELEGRAM_LOGIN_WAIT",
+                status=429,
+                retry_after=max(1, int(self._cooldown - now + 1)),
+            )
+
+    def _flood(self, error: FloodWaitError) -> PremiumLoginProblem:
+        seconds = max(1, min(86400, int(error.seconds)))
+        self._cooldown = max(self._cooldown, self.clock() + seconds)
+        return PremiumLoginProblem(
+            "Telegram asks you to wait before trying again.",
+            code="TELEGRAM_LOGIN_WAIT",
+            status=429,
+            retry_after=seconds,
+        )
+
+    def _result(self, identity: str, challenge: _Challenge) -> dict[str, Any]:
+        return {
+            "challenge_id": identity,
+            "stage": challenge.stage,
+            "expires_in_seconds": max(0, int(challenge.expires - self.clock())),
+        }
+
+    async def begin(
+        self,
+        owner: str,
+        expected_revision: int,
+        phone: str,
+        label: str,
+    ) -> dict[str, Any]:
+        async with self._operation():
+            return await self._begin(owner, expected_revision, phone, label)
+
+    async def _begin(
+        self,
+        owner: str,
+        expected_revision: int,
+        phone: str,
+        label: str,
+    ) -> dict[str, Any]:
+        phone = re.sub(r"[ ()-]", "", phone)
+        if not re.fullmatch(r"\+[1-9][0-9]{6,14}", phone):
+            raise PremiumLoginProblem("Enter your phone number with its country code.")
+        label = label.strip()
+        if not 1 <= len(label) <= 80 or any(
+            ord(char) < 32 or ord(char) == 127 for char in label
+        ):
+            raise PremiumLoginProblem(
+                "Choose a connection name of 1-80 visible characters."
+            )
+        await self._expire()
+        async with self._guard:
+            if self._closed:
+                raise PremiumLoginProblem(
+                    "Login is unavailable while TGDrive stops.", status=503
+                )
+            self._check_rate()
+            now = self.clock()
+            while self._starts and self._starts[0] <= now - 900:
+                self._starts.popleft()
+            if len(self._starts) >= 6 or len(self.challenges) >= MAX_CHALLENGES:
+                raise PremiumLoginProblem(
+                    "Finish or cancel the current login "
+                    "before requesting another code.",
+                    status=429,
+                    retry_after=60,
+                )
+            digest = hashlib.sha256(phone.encode()).hexdigest()
+            if any(key == digest and stamp > now - 60 for key, stamp in self._phones):
+                raise PremiumLoginProblem(
+                    "Wait a minute before requesting another code.",
+                    status=429,
+                    retry_after=60,
+                )
+            api_id, api_hash, revision = self.api_credentials()
+            if expected_revision != revision:
+                raise PremiumLoginProblem(
+                    "Settings changed. Reload settings before connecting this account.",
+                    code="SETTINGS_CONFLICT",
+                    status=409,
+                )
+            raw_hash = (
+                api_hash.get_secret_value()
+                if hasattr(api_hash, "get_secret_value")
+                else api_hash
+            )
+            client = self.client_factory(api_id, raw_hash)
+            challenge = _Challenge(
+                owner, client, phone, label, revision, now + LOGIN_TTL
+            )
+            identity = secrets.token_urlsafe(32)
+            self.challenges[identity] = challenge
+            self._starts.append(now)
+            self._phones.append((digest, now))
+            if self._reaper is None:
+                self._reaper = asyncio.create_task(self._reap())
+        try:
+            async with challenge.lock, asyncio.timeout(30):
+                await client.connect()
+                sent = await client.send_code_request(phone)
+                code_hash = getattr(sent, "phone_code_hash", None)
+                if not isinstance(code_hash, str) or not code_hash:
+                    raise PremiumLoginProblem(
+                        "Telegram could not send a login code. Try again later."
+                    )
+                challenge.phone_code_hash = code_hash
+                return self._result(identity, challenge)
+        except BaseException as error:
+            self.challenges.pop(identity, None)
+            await self._dispose(challenge)
+            if isinstance(error, asyncio.CancelledError):
+                raise
+            if isinstance(error, FloodWaitError):
+                raise self._flood(error) from None
+            if isinstance(error, PhoneNumberInvalidError):
+                raise PremiumLoginProblem(
+                    "Telegram did not recognize this phone number."
+                ) from None
+            if isinstance(error, PremiumLoginProblem):
+                raise
+            raise PremiumLoginProblem(
+                "Telegram could not send a login code. "
+                "Check your API settings and try again.",
+                status=502,
+            ) from None
+
+    def _owned(self, identity: str, owner: str) -> _Challenge:
+        challenge = self.challenges.get(identity)
+        if challenge is None or challenge.owner != owner:
+            raise PremiumLoginProblem(
+                "This login expired. Start again.",
+                code="TELEGRAM_LOGIN_EXPIRED",
+                status=410,
+            )
+        return challenge
+
+    async def verify(
+        self,
+        owner: str,
+        identity: str,
+        *,
+        code: str | None = None,
+        password: str | None = None,
+    ) -> dict[str, Any]:
+        async with self._operation():
+            return await self._verify(owner, identity, code=code, password=password)
+
+    async def _verify(
+        self,
+        owner: str,
+        identity: str,
+        *,
+        code: str | None = None,
+        password: str | None = None,
+    ) -> dict[str, Any]:
+        await self._expire()
+        challenge = self._owned(identity, owner)
+        async with challenge.lock:
+            self._owned(identity, owner)
+            self._check_rate()
+            if challenge.expires <= self.clock():
+                self.challenges.pop(identity, None)
+                await self._dispose(challenge)
+                raise PremiumLoginProblem(
+                    "This login expired. Start again.",
+                    code="TELEGRAM_LOGIN_EXPIRED",
+                    status=410,
+                )
+            if challenge.stage == "code" and (
+                code is None
+                or not re.fullmatch(r"[0-9]{3,10}", code)
+                or password is not None
+            ):
+                raise PremiumLoginProblem("Enter the code from Telegram.")
+            if challenge.stage == "password" and (
+                password is None or not 1 <= len(password) <= 512 or code is not None
+            ):
+                raise PremiumLoginProblem(
+                    "Enter your Telegram two-step verification password."
+                )
+            challenge.attempts += 1
+            try:
+                async with asyncio.timeout(90):
+                    if challenge.stage == "code":
+                        await challenge.client.sign_in(
+                            phone=challenge.phone,
+                            code=code,
+                            phone_code_hash=challenge.phone_code_hash,
+                        )
+                    else:
+                        await challenge.client.sign_in(password=password)
+                    challenge.authorized = True
+                    account = await challenge.client.get_me()
+                    if (
+                        not account
+                        or getattr(account, "bot", False)
+                        or not getattr(account, "premium", False)
+                    ):
+                        raise PremiumLoginProblem(
+                            "This account does not have Telegram Premium. "
+                            "Your storage bots are still available.",
+                            code="TELEGRAM_PREMIUM_REQUIRED",
+                        )
+                    session = challenge.client.session.save()
+                    try:
+                        result = await self.save_session(
+                            challenge.revision, challenge.label, session
+                        )
+                    except BaseException:
+                        if self.is_session_saved is not None:
+                            try:
+                                committed = self.is_session_saved(session)
+                            except Exception:
+                                committed = None
+                            # An unreadable post-commit file cannot prove that
+                            # nothing was saved. Preserve the authorization.
+                            challenge.saved = committed is not False
+                        raise
+                    challenge.saved = True
+                self.challenges.pop(identity, None)
+                await self._dispose(challenge)
+                return {"stage": "complete", "settings": result}
+            except SessionPasswordNeededError:
+                challenge.stage = "password"
+                return self._result(identity, challenge)
+            except PhoneCodeInvalidError, PasswordHashInvalidError:
+                if challenge.attempts < MAX_ATTEMPTS:
+                    raise PremiumLoginProblem(
+                        "That code is incorrect. Try again."
+                        if challenge.stage == "code"
+                        else "That password is incorrect. Try again.",
+                        code="TELEGRAM_LOGIN_INVALID",
+                    ) from None
+                self.challenges.pop(identity, None)
+                await self._dispose(challenge)
+                raise PremiumLoginProblem(
+                    "Too many attempts. Start a new login.", status=429, retry_after=60
+                ) from None
+            except FloodWaitError as error:
+                raise self._flood(error) from None
+            except BaseException as error:
+                self.challenges.pop(identity, None)
+                await self._dispose(challenge)
+                if isinstance(error, asyncio.CancelledError):
+                    raise
+                if isinstance(error, PhoneCodeExpiredError):
+                    raise PremiumLoginProblem(
+                        "This login code expired. Start again.",
+                        code="TELEGRAM_LOGIN_EXPIRED",
+                        status=410,
+                    ) from None
+                if isinstance(error, PremiumLoginProblem) or (
+                    hasattr(error, "code") and str(error.code).startswith("SETTINGS_")
+                ):
+                    raise
+                raise PremiumLoginProblem(
+                    "This account could not be connected. "
+                    "Check its storage channel access and try again.",
+                    status=502,
+                ) from None
+
+    async def cancel(self, owner: str, identity: str) -> None:
+        challenge = self.challenges.get(identity)
+        if challenge is None or challenge.owner != owner:
+            return
+        async with challenge.lock:
+            if self.challenges.pop(identity, None) is not None:
+                await self._dispose(challenge)
+
+    async def close(self) -> None:
+        self._closed = True
+        current = asyncio.current_task()
+        pending = {task for task in self._operations if task is not current}
+        if self._reaper is not None and self._reaper is not current:
+            pending.add(self._reaper)
+        for task in pending:
+            task.cancel()
+        # Provider waits are interrupted before waiting for challenge locks.
+        # Each owned cleanup remains bounded by its two five-second deadlines.
+        if pending:
+            await asyncio.gather(*pending, return_exceptions=True)
+        remaining = list(self.challenges.values())
+        self.challenges.clear()
+        if remaining:
+            await asyncio.gather(
+                *(self._dispose(challenge) for challenge in remaining),
+                return_exceptions=True,
+            )
+        if self._cleanups:
+            await asyncio.gather(*self._cleanups, return_exceptions=True)
diff --git a/tgdrive/settings/premium_login_api.py b/tgdrive/settings/premium_login_api.py
new file mode 100644
index 00000000..b4e374f8
--- /dev/null
+++ b/tgdrive/settings/premium_login_api.py
@@ -0,0 +1,85 @@
+"""Owner-only endpoints for a bounded Telegram Premium connection flow."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from fastapi import Depends, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, ConfigDict, Field, SecretStr
+
+from tgdrive.core.security import SESSION_COOKIE
+from tgdrive.settings.premium_login import PremiumLoginProblem, PremiumLoginService
+
+
+class LoginStart(BaseModel):
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+    expected_revision: int = Field(ge=0)
+    phone: SecretStr = Field(min_length=1, max_length=32)
+    label: str = Field(min_length=1, max_length=80)
+
+
+class LoginVerify(BaseModel):
+    model_config = ConfigDict(extra="forbid", hide_input_in_errors=True)
+    challenge_id: str = Field(
+        min_length=32, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+    )
+    code: SecretStr | None = Field(default=None, max_length=16)
+    password: SecretStr | None = Field(default=None, max_length=512)
+
+
+def register_premium_routes(app: Any, *, require_admin: Any, get_service: Any) -> None:
+    def service(request: Request) -> PremiumLoginService:
+        current = getattr(app.state, "premium_login_service", None)
+        if current is None:
+            manager = get_service(request)
+            current = PremiumLoginService(
+                manager.login_api,
+                manager.add_authenticated_session,
+                is_session_saved=manager.session_is_saved,
+            )
+            app.state.premium_login_service = current
+        return current
+
+    def owner(request: Request) -> str:
+        return hashlib.sha256(
+            request.cookies.get(SESSION_COOKIE, "").encode()
+        ).hexdigest()
+
+    @app.exception_handler(PremiumLoginProblem)
+    async def login_error(
+        _request: Request, error: PremiumLoginProblem
+    ) -> JSONResponse:
+        return JSONResponse(
+            {"detail": str(error), "code": error.code},
+            status_code=error.status,
+            headers={"Retry-After": str(error.retry_after)}
+            if error.retry_after
+            else None,
+        )
+
+    admin = [Depends(require_admin)]
+
+    @app.post("/api/v1/settings/premium-login/start", dependencies=admin)
+    async def begin(payload: LoginStart, request: Request) -> dict[str, Any]:
+        return await service(request).begin(
+            owner(request),
+            payload.expected_revision,
+            payload.phone.get_secret_value(),
+            payload.label,
+        )
+
+    @app.post("/api/v1/settings/premium-login/verify", dependencies=admin)
+    async def verify(payload: LoginVerify, request: Request) -> dict[str, Any]:
+        return await service(request).verify(
+            owner(request),
+            payload.challenge_id,
+            code=payload.code.get_secret_value() if payload.code else None,
+            password=payload.password.get_secret_value() if payload.password else None,
+        )
+
+    @app.delete("/api/v1/settings/premium-login/{challenge_id}", dependencies=admin)
+    async def cancel(challenge_id: str, request: Request) -> dict[str, str]:
+        await service(request).cancel(owner(request), challenge_id)
+        return {"status": "cancelled"}
diff --git a/tgdrive/settings/transfer_preferences.py b/tgdrive/settings/transfer_preferences.py
new file mode 100644
index 00000000..e1f15fb0
--- /dev/null
+++ b/tgdrive/settings/transfer_preferences.py
@@ -0,0 +1,91 @@
+"""Durable owner upload scheduling preferences, applied without a restart."""
+
+from __future__ import annotations
+
+import asyncio
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from tgdrive.settings.managed_settings import SettingsProblem
+
+
+class UploadPreferences(BaseModel):
+    model_config = ConfigDict(extra="forbid", strict=True)
+    uploads_per_bot: int = Field(ge=1, le=4)
+
+
+class TransferPreferences:
+    def __init__(self, settings, runtime):
+        self.settings = settings
+        self.runtime = runtime
+        self._lock = asyncio.Lock()
+        self._loaded = False
+        self._value = getattr(settings, "telegram_uploads_per_bot", 1)
+
+    def _read(self) -> int:
+        backend = self.runtime.mongo
+        row = backend.db.settings.find_one({"_id": "transfer-preferences"})
+        raw = row["document"] if row else None
+        return (
+            UploadPreferences.model_validate(raw).uploads_per_bot
+            if raw is not None
+            else self._value
+        )
+
+    def _write(self, value: int) -> None:
+        document = {"uploads_per_bot": value}
+        backend = self.runtime.mongo
+        backend.write(
+            backend.db.settings,
+            "replace_one",
+            {"_id": "transfer-preferences"},
+            {"_id": "transfer-preferences", "document": document},
+            upsert=True,
+        )
+
+    async def initialize(self) -> None:
+        async with self._lock:
+            if not self._loaded:
+                try:
+                    value = await asyncio.to_thread(self._read)
+                except Exception:
+                    raise SettingsProblem(
+                        "Could not read upload settings.", status=503
+                    ) from None
+                await self.runtime.pool.set_uploads_per_bot(value)
+                self._value = value
+                self._loaded = True
+
+    async def snapshot(self) -> dict:
+        await self.initialize()
+        clients = await self.runtime.pool.status()
+        bots = sum(
+            client.kind == "bot" and client.started and client.healthy
+            for client in clients
+        )
+        return {
+            "uploads_per_bot": self._value,
+            "connected_bots": bots,
+            "bot_upload_slots": bots * self._value,
+        }
+
+    async def save(self, change: UploadPreferences) -> dict:
+        await self.initialize()
+        async with self._lock:
+            try:
+                await asyncio.to_thread(self._write, change.uploads_per_bot)
+            except Exception:
+                raise SettingsProblem(
+                    "Could not save upload settings. Try again.", status=503
+                ) from None
+            await self.runtime.pool.set_uploads_per_bot(change.uploads_per_bot)
+            self._value = change.uploads_per_bot
+        return await self.snapshot()
+
+
+def get_transfer_preferences(settings, runtime) -> TransferPreferences:
+    service = getattr(runtime, "transfer_preferences", None)
+    if service is None:
+        service = TransferPreferences(settings, runtime)
+        runtime.transfer_preferences = service
+    return service
diff --git a/tgdrive/storage/__init__.py b/tgdrive/storage/__init__.py
new file mode 100644
index 00000000..de8f7a02
--- /dev/null
+++ b/tgdrive/storage/__init__.py
@@ -0,0 +1 @@
+"""Drive catalog, database persistence, and stored file metadata."""
diff --git a/tgdrive/storage/demo_files.py b/tgdrive/storage/demo_files.py
new file mode 100644
index 00000000..09361d4f
--- /dev/null
+++ b/tgdrive/storage/demo_files.py
@@ -0,0 +1,105 @@
+"""Stable demo content identity and request/job-scoped catalog write policy."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from tgdrive.core.errors import NotFoundError
+from tgdrive.settings.managed_settings import SettingsProblem
+
+DEMO_FILES_ID = "tgdrive-demo-files"
+DEMO_FILES_NAME = "Demo Files"
+restricted_writes: ContextVar[bool] = ContextVar(
+    "demo_restricted_writes", default=False
+)
+
+
+class DemoFilesReadOnly(SettingsProblem):
+    def __init__(self):
+        super().__init__(
+            "Demo Files is read-only. Use My Files outside this folder to upload "
+            "or change files, or sign in with the full-access demo password.",
+            code="DEMO_FILES_READ_ONLY",
+            status=403,
+        )
+
+
+@contextmanager
+def write_policy(restricted: bool):
+    token = restricted_writes.set(restricted)
+    try:
+        yield
+    finally:
+        restricted_writes.reset(token)
+
+
+def request_policy(request):
+    from tgdrive.web.demo_access import is_demo_restricted
+
+    restricted_writes.set(is_demo_restricted(request))
+
+
+def check_ids(identities):
+    """Called under the catalog transaction, including background file commits."""
+    if restricted_writes.get() and DEMO_FILES_ID in identities:
+        raise DemoFilesReadOnly()
+
+
+def check_path(store, path, *, descendants=False, identity=None):
+    """Preflight current identity before staging, network work, or job changes."""
+    if not restricted_writes.get():
+        return
+    node_id = identity or (
+        path.rstrip("/").rsplit("/", 1)[-1] if path != "/" else "root"
+    )
+    current = store.resolve_id(node_id)
+    check_ids(current.strip("/").split("/"))
+    if descendants:
+        try:
+            demo = store.resolve_id(DEMO_FILES_ID)
+        except NotFoundError:
+            return
+        if current == "/" or demo.startswith(current.rstrip("/") + "/"):
+            raise DemoFilesReadOnly()
+
+
+def check_receipt(store, item):
+    check_path(store, item["parent_id"], identity=item.get("parent_node_id"))
+
+
+def check_transfer(store, record):
+    context = record.context
+    if context.get("kind") == "delete":
+        for intent in store.pending_deletions():
+            if intent["id"] == context.get("deletion_id"):
+                check_path(
+                    store, intent["path"], descendants=True, identity=intent["root_id"]
+                )
+                return
+    if context.get("destination") or context.get("destination_id"):
+        check_path(
+            store,
+            context.get("destination", "/"),
+            identity=context.get("destination_id"),
+        )
+
+
+def annotate(record):
+    """Annotate independent HTTP records; never add presentation fields to storage."""
+    if isinstance(record, list):
+        for item in record:
+            annotate(item)
+    elif isinstance(record, dict):
+        identity = record.get("id")
+        path = record.get("path", "")
+        if identity == DEMO_FILES_ID:
+            record["demo_files"] = True
+        if restricted_writes.get() and (
+            identity == DEMO_FILES_ID or DEMO_FILES_ID in path.strip("/").split("/")
+        ):
+            record["read_only"] = True
+        for value in tuple(record.values()):
+            if isinstance(value, (dict, list)):
+                annotate(value)
+    return record
diff --git a/tgdrive/storage/file_parts.py b/tgdrive/storage/file_parts.py
new file mode 100644
index 00000000..d108b86a
--- /dev/null
+++ b/tgdrive/storage/file_parts.py
@@ -0,0 +1,80 @@
+"""Pure validation for ordered Telegram parts of one logical file."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from tgdrive.core.errors import ValidationError
+
+MAX_FILE_PARTS = 4096
+MAX_FILE_SIZE = (1 << 63) - 1
+_PART_KEYS = {"index", "offset", "size", "message_id", "sha256"}
+_OPTIONAL_KEYS = {"document_id"}
+_SHA256 = re.compile(r"[0-9a-fA-F]{64}")
+
+
+def validate_sha256(value: Any, *, optional: bool = True) -> str | None:
+    if value is None and optional:
+        return None
+    if not isinstance(value, str) or not _SHA256.fullmatch(value):
+        raise ValidationError("sha256 must contain exactly 64 hexadecimal characters")
+    return value.lower()
+
+
+def validate_parts(parts: Any, *, size: int, message_id: int) -> list[dict[str, Any]]:
+    """Return independent canonical records; reject gaps, overlaps and aliases."""
+    if type(size) is not int or not 0 < size <= MAX_FILE_SIZE:
+        raise ValidationError("multipart file size must be a positive 64-bit integer")
+    if type(message_id) is not int or not 0 < message_id <= MAX_FILE_SIZE:
+        raise ValidationError("multipart anchor must be a positive message id")
+    if not isinstance(parts, list) or not 1 <= len(parts) <= MAX_FILE_PARTS:
+        raise ValidationError(f"file parts must contain 1-{MAX_FILE_PARTS} records")
+    result = []
+    offset = 0
+    identities = set()
+    for index, part in enumerate(parts):
+        if (
+            not isinstance(part, dict)
+            or not set(part) >= _PART_KEYS
+            or set(part) - _PART_KEYS - _OPTIONAL_KEYS
+        ):
+            raise ValidationError("file part has missing or unknown fields")
+        if any(
+            type(part[key]) is not int
+            for key in ("index", "offset", "size", "message_id")
+        ):
+            raise ValidationError("file part offsets, sizes and ids must be integers")
+        if part["index"] != index or part["offset"] != offset:
+            raise ValidationError(
+                "file parts must be contiguous and start at index/offset zero"
+            )
+        if (
+            not 0 < part["size"] <= MAX_FILE_SIZE
+            or not 0 < part["message_id"] <= MAX_FILE_SIZE
+        ):
+            raise ValidationError(
+                "file part size and message id must be positive 64-bit integers"
+            )
+        if "document_id" in part and (
+            type(part["document_id"]) is not int
+            or part["document_id"] == 0
+            or not -(1 << 63) <= part["document_id"] < (1 << 63)
+        ):
+            raise ValidationError(
+                "document_id must be a non-zero signed 64-bit integer"
+            )
+        if part["message_id"] in identities:
+            raise ValidationError("file parts cannot repeat a Telegram message")
+        identities.add(part["message_id"])
+        offset += part["size"]
+        if offset > size:
+            raise ValidationError("file parts exceed the logical file size")
+        result.append(
+            {**part, "sha256": validate_sha256(part["sha256"], optional=False)}
+        )
+    if offset != size or result[0]["message_id"] != message_id:
+        raise ValidationError(
+            "file parts must match the logical size and first message id"
+        )
+    return result
diff --git a/tgdrive/storage/mongo.py b/tgdrive/storage/mongo.py
new file mode 100644
index 00000000..82772e81
--- /dev/null
+++ b/tgdrive/storage/mongo.py
@@ -0,0 +1,408 @@
+"""MongoDB connection ownership, bounded requests and installation fencing.
+
+MongoDB is required. No connection string is included in exceptions or
+application status.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import uuid
+from contextlib import suppress
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from bson.codec_options import CodecOptions, TypeDecoder, TypeRegistry
+from bson.int64 import Int64
+from pymongo import MongoClient, ReturnDocument
+from pymongo.errors import DuplicateKeyError, PyMongoError
+from pymongo.read_concern import ReadConcern
+from pymongo.write_concern import WriteConcern
+
+
+class _IntegerDecoder(TypeDecoder):
+    bson_type = Int64
+
+    def transform_bson(self, value):
+        return int(value)
+
+
+class DatabaseUnavailable(RuntimeError):
+    pass
+
+
+_backends: dict[tuple[str, str], MongoBackend] = {}
+_directories: dict[Path, MongoBackend] = {}
+_guard = threading.RLock()
+
+
+def configure(data_dir: Path, uri: str, database: str = "tgdrive") -> MongoBackend:
+    with _guard:
+        key = (uri, database)
+        if key not in _backends:
+            _backends[key] = MongoBackend(uri, database)
+        backend = _backends[key]
+        _directories[data_dir.resolve()] = backend
+        return backend
+
+
+def for_directory(data_dir: Path) -> MongoBackend | None:
+    return _directories.get(data_dir.resolve())
+
+
+def for_settings(settings: Any) -> MongoBackend:
+    uri = getattr(settings, "mongodb_uri", None)
+    if not uri:
+        raise DatabaseUnavailable("MONGODB_URI is required; TGDrive requires MongoDB.")
+    return configure(
+        settings.resolved_data_dir,
+        uri.get_secret_value() if hasattr(uri, "get_secret_value") else uri,
+        settings.mongodb_database,
+    )
+
+
+class MongoBackend:
+    def __init__(self, uri: str, database: str):
+        if not isinstance(uri, str) or not uri.strip().startswith(
+            ("mongodb://", "mongodb+srv://")
+        ):
+            raise DatabaseUnavailable(
+                "MONGODB_URI must be a MongoDB connection string."
+            )
+        try:
+            self.client = MongoClient(
+                uri.strip(),
+                appname="TGDrive",
+                serverSelectionTimeoutMS=8000,
+                connectTimeoutMS=5000,
+                socketTimeoutMS=10000,
+                timeoutMS=15000,
+                maxPoolSize=12,
+                minPoolSize=0,
+                retryWrites=True,
+                retryReads=True,
+            )
+            self.db = self.client.get_database(
+                database,
+                write_concern=WriteConcern("majority", wtimeout=10000),
+                read_concern=ReadConcern("majority"),
+                codec_options=CodecOptions(
+                    tz_aware=True, type_registry=TypeRegistry([_IntegerDecoder()])
+                ),
+            )
+        except PyMongoError, TypeError, ValueError:
+            client = getattr(self, "client", None)
+            if client is not None:
+                client.close()
+            raise DatabaseUnavailable(
+                "MongoDB configuration is invalid. "
+                "Check MONGODB_URI and MONGODB_DATABASE."
+            ) from None
+        self._settings_lock = threading.RLock()
+        self._write_lock = threading.RLock()
+        self._writes_paused = False
+        self._settings_cached = False
+        self._settings_document = None
+        self.token: str | None = None
+        self._stop = threading.Event()
+        self._heartbeat: threading.Thread | None = None
+        self._healthy_until = 0.0
+        self._lost = False
+
+    def ping(self) -> None:
+        try:
+            self.db.command("ping")
+        except PyMongoError:
+            raise DatabaseUnavailable(
+                "MongoDB is unavailable. Check MONGODB_URI, authentication and "
+                "network access, including the Atlas IP access list when applicable."
+            ) from None
+
+    def acquire(self) -> None:
+        if self.token is not None:
+            raise DatabaseUnavailable(
+                "This process already has an active MongoDB owner."
+            )
+        token = uuid.uuid4().hex
+        try:
+            # The server's clock governs expiration. Updating this same document
+            # also serializes a takeover against every catalog transaction.
+            self.db.runtime.update_one(
+                {"_id": "owner"},
+                {
+                    "$setOnInsert": {
+                        "expires_at": datetime(1970, 1, 1, tzinfo=UTC),
+                        "epoch": 0,
+                    }
+                },
+                upsert=True,
+            )
+            result = self.db.runtime.find_one_and_update(
+                {
+                    "_id": "owner",
+                    "$expr": {
+                        "$lte": [
+                            {
+                                "$ifNull": [
+                                    "$expires_at",
+                                    datetime(1970, 1, 1, tzinfo=UTC),
+                                ]
+                            },
+                            "$$NOW",
+                        ]
+                    },
+                },
+                [
+                    {
+                        "$set": {
+                            "token": token,
+                            "expires_at": {
+                                "$dateAdd": {
+                                    "startDate": "$$NOW",
+                                    "unit": "second",
+                                    "amount": 60,
+                                }
+                            },
+                            "epoch": {"$add": [{"$ifNull": ["$epoch", 0]}, 1]},
+                        }
+                    }
+                ],
+                return_document=ReturnDocument.AFTER,
+            )
+        except DuplicateKeyError:
+            raise DatabaseUnavailable(
+                "Another TGDrive installation is using this MongoDB database. "
+                "Stop the other installation before restarting this one."
+            ) from None
+        except PyMongoError:
+            raise DatabaseUnavailable(
+                "Could not acquire MongoDB ownership. Check database connectivity, "
+                "authentication and write permissions."
+            ) from None
+        if not result or result.get("token") != token:
+            raise DatabaseUnavailable(
+                "Another TGDrive installation owns this MongoDB database. "
+                "Stop the other installation before restarting this one."
+            )
+        self.token = token
+        self._lost = False
+        self._healthy_until = time.monotonic() + 45
+        self._stop.clear()
+        self._heartbeat = threading.Thread(
+            target=self._renew_loop, name="mongodb-owner", daemon=True
+        )
+        self._heartbeat.start()
+
+    def _renew_loop(self) -> None:
+        while not self._stop.wait(15):
+            try:
+                result = self.db.runtime.update_one(
+                    {
+                        "_id": "owner",
+                        "token": self.token,
+                        "$expr": {"$gt": ["$expires_at", "$$NOW"]},
+                    },
+                    [
+                        {
+                            "$set": {
+                                "expires_at": {
+                                    "$dateAdd": {
+                                        "startDate": "$$NOW",
+                                        "unit": "second",
+                                        "amount": 60,
+                                    }
+                                }
+                            }
+                        }
+                    ],
+                )
+                if result.matched_count != 1:
+                    self._lost = True
+                    return
+                self._healthy_until = time.monotonic() + 45
+            except PyMongoError:
+                # Keep read-only cache available briefly; no remote side effect
+                # is admitted after the conservative local ownership deadline.
+                continue
+
+    def check_owner(self) -> None:
+        if not self.token or self._lost or time.monotonic() >= self._healthy_until:
+            raise DatabaseUnavailable(
+                "MongoDB ownership is unavailable. Transfers are paused; restart "
+                "after restoring database connectivity."
+            )
+
+    def fence(self, session: Any) -> None:
+        self.check_owner()
+        result = self.db.runtime.update_one(
+            {
+                "_id": "owner",
+                "token": self.token,
+                "$expr": {"$gt": ["$expires_at", "$$NOW"]},
+            },
+            {"$inc": {"commits": 1}},
+            session=session,
+        )
+        if result.matched_count != 1:
+            self._lost = True
+            raise DatabaseUnavailable("MongoDB ownership changed; writes are stopped.")
+
+    def release(self) -> None:
+        self._stop.set()
+        if self._heartbeat is not None:
+            self._heartbeat.join(timeout=16)
+            self._heartbeat = None
+        token, self.token = self.token, None
+        if token:
+            with suppress(PyMongoError):
+                self.db.runtime.delete_one({"_id": "owner", "token": token})
+
+    def write(self, collection, method, *args, **kwargs):
+        def apply(session):
+            self.fence(session)
+            return getattr(collection, method)(*args, session=session, **kwargs)
+
+        with self._write_lock:
+            return self.transaction(apply)
+
+    def pause_writes(self) -> None:
+        """Drain current transactions and keep normal writers stopped for restore."""
+        with self._write_lock:
+            self._writes_paused = True
+
+    def transaction(self, callback, *, allow_paused: bool = False):
+        with self._write_lock:
+            if self._writes_paused and not allow_paused:
+                raise DatabaseUnavailable(
+                    "Database restore has paused normal database access. "
+                    "Restart TGDrive before using this drive."
+                )
+            try:
+                with self.client.start_session() as session:
+                    return session.with_transaction(
+                        callback,
+                        read_concern=ReadConcern("snapshot"),
+                        write_concern=WriteConcern("majority", wtimeout=10000),
+                        max_commit_time_ms=10000,
+                    )
+            except PyMongoError:
+                raise DatabaseUnavailable(
+                    "MongoDB could not confirm a transaction. Check database "
+                    "connectivity, replica-set support and write permissions; "
+                    "refresh before retrying."
+                ) from None
+
+
+def bootstrap_values(settings: Any) -> dict[str, Any]:
+    """Prepare deployment preferences and owner auth without DB credentials/paths."""
+    from argon2 import PasswordHasher
+    from pydantic import SecretStr
+
+    values = {}
+    for key, value in settings.model_dump(by_alias=True).items():
+        if key in {
+            "MONGODB_URI",
+            "MONGODB_DATABASE",
+            "DATA_DIR",
+            "CACHE_DIR",
+            "DEMO_MODE",
+            "DEMO_ADMIN_PASSWORD",
+            "DEMO_ADMIN_PASSWORD_HASH",
+            "ADMIN_PASSWORD",
+            "managed_revision",
+            "managed_client_ids",
+            "managed_client_labels",
+        }:
+            continue
+        values[key] = (
+            value.get_secret_value() if isinstance(value, SecretStr) else value
+        )
+    if not values.get("ADMIN_PASSWORD_HASH"):
+        values["ADMIN_PASSWORD_HASH"] = PasswordHasher().hash(
+            settings.admin_password.get_secret_value()
+        )
+    return values
+
+
+def initialize_if_empty(settings: Any, backend: MongoBackend) -> bool:
+    """Initialize a pristine MongoDB under ownership; preserve prior drive state."""
+    from tgdrive.core.errors import CorruptStoreError
+    from tgdrive.recovery.mongo_backup import COLLECTIONS
+    from tgdrive.settings.managed_settings import (
+        ManagedDocument,
+        initial_clients,
+    )
+    from tgdrive.storage.mongo_store import MongoStore
+
+    def inspect(session):
+        backend.fence(session)
+        if backend.db.catalog.find_one({"_id": "catalog"}, session=session):
+            return False
+        if any(backend.db[name].find_one({}, session=session) for name in COLLECTIONS):
+            raise CorruptStoreError(
+                "MongoDB has saved drive state but no catalog. Preserve it and "
+                "recover the existing drive; it was not initialized again."
+            )
+        return True
+
+    if not backend.transaction(inspect):
+        return False
+    directory = settings.resolved_data_dir
+    if any(
+        (directory / name).exists()
+        for name in (
+            "mongodb-drive.json",
+            "replica-bootstrap.json",
+            "channel-activation.json",
+            "channel-backup.sqlite3",
+            "telegram-settings.json",
+            "drive.sqlite3",
+            "drive.json",
+        )
+    ):
+        raise CorruptStoreError(
+            "This installation has existing drive or recovery state, but MongoDB "
+            "has no catalog. Check the configured database or recover the drive; "
+            "existing state was preserved."
+        )
+    import json
+
+    document = ManagedDocument(
+        revision=1,
+        api_id=settings.api_id,
+        api_hash=settings.api_hash,
+        clients=initial_clients(settings),
+    )
+    store = MongoStore.create(
+        backend,
+        storage_channel=settings.storage_channel,
+        initial_settings=[
+            {"_id": "bootstrap", "document": bootstrap_values(settings)},
+            {
+                "_id": "telegram",
+                "revision": document.revision,
+                "document": json.loads(document.private_bytes()),
+            },
+        ],
+    )
+    try:
+        record_drive_open(settings, store)
+    finally:
+        store.close()
+    settings.managed_revision = document.revision
+    settings.managed_client_ids = tuple(row.id for row in document.clients)
+    settings.managed_client_labels = tuple(row.label for row in document.clients)
+    return True
+
+
+def record_drive_open(settings: Any, store: Any) -> None:
+    """Remember an opened drive so lost MongoDB data cannot look like first setup."""
+    import json
+
+    from tgdrive.replication.replica_state import atomic_private
+
+    path = settings.resolved_data_dir / "mongodb-drive.json"
+    if not path.exists():
+        atomic_private(path, json.dumps({"drive_id": store.drive_id}).encode())
diff --git a/tgdrive/storage/mongo_store.py b/tgdrive/storage/mongo_store.py
new file mode 100644
index 00000000..ae6e9c5d
--- /dev/null
+++ b/tgdrive/storage/mongo_store.py
@@ -0,0 +1,1357 @@
+"""Native MongoDB catalog with atomic commits and a single-owner read cache.
+
+The cache is rebuilt from MongoDB at startup. No local catalog file or SQL
+database participates in MongoDB operation. Mutations commit changed documents
+and the catalog generation together before the caller observes success.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import hmac
+import secrets
+import threading
+import unicodedata
+from contextlib import contextmanager
+from typing import Any
+
+from pymongo import DeleteOne, ReplaceOne
+
+from tgdrive.core.errors import (
+    CorruptStoreError,
+    DuplicateNameError,
+    InvalidPathError,
+    InvalidRevisionError,
+    NotDirectoryError,
+    NotFileError,
+    NotFoundError,
+    RootMutationError,
+    TrashedItemError,
+    ValidationError,
+)
+from tgdrive.storage.demo_files import DEMO_FILES_ID, DEMO_FILES_NAME, check_ids
+from tgdrive.storage.mongo import DatabaseUnavailable, MongoBackend
+from tgdrive.storage.store import (
+    _SHARE_UNSET,
+    MAX_NAME_LENGTH,
+    MAX_SEARCH_OFFSET,
+    MAX_SEARCH_RESULTS,
+    MAX_SHARE_TOKENS_PER_ITEM,
+    MAX_TREE_DEPTH,
+    MAX_TREE_ITEMS,
+    ROOT_ID,
+    SCHEMA_VERSION,
+    DriveStore,
+    FolderTreeConflictError,
+    _folder_manifest,
+    _join_path,
+    _manifest_json,
+    _name_key,
+    _normalize_name,
+    _normalize_path,
+    _share_label,
+    _strict_int,
+    _utc_now,
+    _validate_channel_id,
+    _validate_file_rename,
+    _validate_id,
+    _validate_timestamp,
+)
+
+_TABLES = ("nodes", "shares", "operations", "deletions", "preparations")
+
+
+class MongoStore(DriveStore):
+    backend_name = "mongodb"
+
+    def __init__(self, backend: MongoBackend):
+        self.backend = backend
+        self._lock = threading.RLock()
+        self._local = threading.local()
+        self._closed = False
+        self._committed: dict[str, Any] = {}
+        self._reload()
+        self._indexes(backend)
+
+    @property
+    def _state(self):
+        return getattr(
+            self._local, "working", getattr(self._local, "reader", self._committed)
+        )
+
+    @property
+    def _depth(self):
+        return getattr(self._local, "depth", 0)
+
+    @_depth.setter
+    def _depth(self, value):
+        self._local.depth = value
+
+    @classmethod
+    def create(
+        cls,
+        backend: MongoBackend,
+        *,
+        storage_channel: int | None = None,
+        initial_settings: list[dict[str, Any]] | None = None,
+    ) -> MongoStore:
+        backend.ping()
+        if storage_channel is not None:
+            storage_channel = _validate_channel_id(storage_channel)
+        bound = storage_channel is not None
+        metadata = {
+            "_id": "catalog",
+            "schema_version": SCHEMA_VERSION,
+            "drive_id": secrets.token_urlsafe(16),
+            "revision": 2 if bound else 1,
+            "backed_up_revision": 2 if bound else 1,
+            "generation": 1 if bound else 0,
+            "storage_channel_id": storage_channel,
+        }
+        root = cls._node(ROOT_ID, None, "/", "folder")
+
+        def initialize(session):
+            collections = _TABLES
+            if initial_settings is not None:
+                from tgdrive.recovery.mongo_backup import COLLECTIONS
+
+                collections = COLLECTIONS
+                backend.fence(session)
+            if backend.db.catalog.find_one({"_id": "catalog"}, session=session):
+                raise FileExistsError("MongoDB already contains a TGDrive catalog")
+            if any(
+                backend.db[name].find_one({}, session=session) for name in collections
+            ):
+                raise CorruptStoreError("MongoDB contains incomplete catalog state")
+            backend.db.catalog.insert_one(metadata, session=session)
+            backend.db.nodes.insert_one(root, session=session)
+            if initial_settings:
+                backend.db.settings.insert_many(
+                    copy.deepcopy(initial_settings), session=session
+                )
+
+        backend.transaction(initialize)
+        if initial_settings is not None:
+            with backend._settings_lock:
+                backend._settings_cached = False
+                backend._settings_document = None
+        cls._indexes(backend)
+        return cls(backend)
+
+    @staticmethod
+    def _indexes(backend):
+        backend.db.nodes.create_index(
+            [("parent_id", 1), ("name_key", 1)],
+            unique=True,
+            partialFilterExpression={"trashed": False},
+            name="active_sibling_names",
+        )
+        backend.db.nodes.create_index("parent_id")
+        backend.db.shares.create_index("token_hash", unique=True)
+        backend.db.shares.create_index("node_id")
+        backend.db.deletions.create_index("root_id")
+        backend.db.receipts.create_index("purge_at", expireAfterSeconds=0)
+
+    @staticmethod
+    def _node(identity, parent, name, kind, **values):
+        return {
+            "_id": identity,
+            "id": identity,
+            "parent_id": parent,
+            "name": name,
+            "name_key": _name_key(name),
+            "kind": kind,
+            "trashed": False,
+            "upload_date": _utc_now(),
+            "size": 0,
+            "message_id": None,
+            "part_count": 1,
+            "sha256": None,
+            **values,
+        }
+
+    def _reload(self):
+        def read(session):
+            metadata = self.backend.db.catalog.find_one(
+                {"_id": "catalog"}, session=session
+            )
+            if metadata is None:
+                raise CorruptStoreError(
+                    "MongoDB has no TGDrive catalog. Open owner recovery to "
+                    "restore a confirmed backup."
+                )
+            if metadata.get("schema_version") != SCHEMA_VERSION:
+                raise CorruptStoreError("Unsupported MongoDB catalog schema")
+            return {
+                "metadata": metadata,
+                **{
+                    name: {
+                        row["_id"]: row
+                        for row in self.backend.db[name].find({}, session=session)
+                    }
+                    for name in _TABLES
+                },
+            }
+
+        state = self.backend.transaction(read)
+        self._committed = state
+        if hasattr(self._local, "working"):
+            self._local.working = state
+        self._validate_state()
+
+    def _validate_state(self):
+        for key, row in self._state["nodes"].items():
+            if (
+                row.get("id") != key
+                or row.get("name_key") != _name_key(row["name"])
+                or type(row.get("starred", False)) is not bool
+                or type(row.get("part_count")) is not int
+                or row["part_count"] != len(row.get("parts") or [None])
+            ):
+                raise CorruptStoreError("Catalog node identity or index is invalid")
+        for name, identity in (
+            ("shares", "id"),
+            ("operations", "operation_id"),
+            ("deletions", "id"),
+            ("preparations", "request_id"),
+        ):
+            if any(row.get(identity) != key for key, row in self._state[name].items()):
+                raise CorruptStoreError("Catalog recovery record identity is invalid")
+        if ROOT_ID not in self._state["nodes"]:
+            raise CorruptStoreError("MongoDB catalog root is missing")
+        roots = [
+            row["id"]
+            for row in self._state["nodes"].values()
+            if row["parent_id"] is None
+        ]
+        if roots != [ROOT_ID] or len(self._subtree(ROOT_ID)) != len(
+            self._state["nodes"]
+        ):
+            raise CorruptStoreError(
+                "Catalog contains unreachable nodes or invalid roots"
+            )
+        # Reuse portable domain validation without creating a SQLite database.
+        self._validate_payload(self._export())
+
+    @classmethod
+    def validate_snapshot_records(cls, records):
+        """Validate archived domain records without opening or changing a database."""
+        catalogs = records["catalog"]
+        if len(catalogs) != 1 or catalogs[0].get("_id") != "catalog":
+            raise CorruptStoreError("Archive catalog metadata is invalid")
+        metadata = catalogs[0]
+        if (
+            metadata.get("schema_version") != SCHEMA_VERSION
+            or type(metadata.get("generation")) is not int
+            or metadata["generation"] < 0
+            or type(metadata.get("revision")) is not int
+            or metadata["revision"] < 1
+            or type(metadata.get("backed_up_revision")) is not int
+            or not 0 <= metadata["backed_up_revision"] <= metadata["revision"]
+        ):
+            raise CorruptStoreError("Archive catalog schema or revision is invalid")
+        view = object.__new__(cls)
+        view._local = threading.local()
+        view._committed = {
+            "metadata": metadata,
+            **{name: {row["_id"]: row for row in records[name]} for name in _TABLES},
+        }
+        if any(row["id"] != row["_id"] for row in records["nodes"]):
+            raise CorruptStoreError("Archive node identity is invalid")
+        view._validate_state()
+
+    @property
+    def storage_path(self):
+        return None
+
+    @property
+    def database_path(self):
+        return None
+
+    def close(self):
+        self._closed = True
+
+    @contextmanager
+    def _transaction(self, *, write=False):
+        if self._closed:
+            raise DatabaseUnavailable("The catalog is closed")
+        if not write:
+            previous = getattr(self._local, "reader", None)
+            self._local.reader = self._state
+            try:
+                yield self._state
+            finally:
+                if previous is None:
+                    del self._local.reader
+                else:
+                    self._local.reader = previous
+            return
+        with self._lock:
+            self.backend.check_owner()
+            outer = self._depth == 0
+            before = self._committed if outer else copy.deepcopy(self._state)
+            if outer:
+                self._local.working = copy.deepcopy(before)
+            self._depth += 1
+            try:
+                yield self._state
+                if outer and self._state != before:
+                    self._commit(before)
+                    self._committed = self._state
+            except BaseException:
+                if not outer:
+                    self._local.working = before
+                raise
+            finally:
+                self._depth -= 1
+                if outer:
+                    del self._local.working
+
+    @contextmanager
+    def metadata_batch(self):
+        with self._transaction(write=True):
+            yield
+
+    def _commit(self, before):
+        after = self._state
+        generation = before["metadata"]["generation"]
+        metadata = dict(after["metadata"], generation=generation + 1)
+        metadata["backed_up_revision"] = metadata["revision"]
+        changes = {}
+        for name in _TABLES:
+            old, new = before[name], after[name]
+            changes[name] = [
+                *[DeleteOne({"_id": key}) for key in old.keys() - new.keys()],
+                *[
+                    ReplaceOne({"_id": key}, value, upsert=True)
+                    for key, value in new.items()
+                    if old.get(key) != value
+                ],
+            ]
+
+        def commit(session):
+            self.backend.fence(session)
+            result = self.backend.db.catalog.replace_one(
+                {"_id": "catalog", "generation": generation},
+                metadata,
+                session=session,
+            )
+            if result.matched_count != 1:
+                raise DatabaseUnavailable(
+                    "The MongoDB catalog changed elsewhere. Restart to reload it."
+                )
+            renamed = [
+                key
+                for key in before["nodes"].keys() & after["nodes"].keys()
+                if any(
+                    before["nodes"][key].get(field) != after["nodes"][key].get(field)
+                    for field in ("name_key", "parent_id", "trashed")
+                )
+            ]
+            if renamed:
+                # Free changed uniqueness slots inside the transaction so a valid
+                # multi-rename/name swap is not rejected by intermediate ordering.
+                self.backend.db.nodes.update_many(
+                    {"_id": {"$in": renamed}},
+                    {"$set": {"trashed": True}},
+                    session=session,
+                )
+            for name, operations in changes.items():
+                if operations:
+                    self.backend.db[name].bulk_write(
+                        operations, ordered=True, session=session
+                    )
+
+        try:
+            self.backend.transaction(commit)
+        except Exception:
+            # A lost commit acknowledgement is not proof of rollback. Rebuild
+            # authority from MongoDB before admitting another operation.
+            try:
+                self._reload()
+            except Exception:
+                self._closed = True
+            raise
+        after["metadata"] = metadata
+
+    def _bump(self):
+        self._state["metadata"]["revision"] += 1
+
+    @property
+    def drive_id(self):
+        return self._state["metadata"]["drive_id"]
+
+    @property
+    def revision(self):
+        return self._state["metadata"]["revision"]
+
+    @property
+    def storage_channel_id(self):
+        return self._state["metadata"].get("storage_channel_id")
+
+    @property
+    def dirty(self):
+        return False
+
+    def bind_storage_channel(self, channel_id):
+        channel_id = _validate_channel_id(channel_id)
+        with self._transaction(write=True):
+            if self.storage_channel_id == channel_id:
+                return
+            if self.storage_channel_id is not None:
+                raise ValidationError(
+                    "The drive belongs to a different storage channel"
+                )
+            self._state["metadata"]["storage_channel_id"] = channel_id
+            self._bump()
+
+    def has_file_operation(self, operation_id):
+        _validate_id(operation_id)
+        return operation_id in self._state["operations"]
+
+    def _resolve(self, path):
+        parts, path = _normalize_path(path)
+        node = self._state["nodes"][ROOT_ID]
+        chain = [node]
+        for identity in parts:
+            if node["kind"] != "folder":
+                raise NotDirectoryError("A path component is not a folder")
+            child = self._state["nodes"].get(identity)
+            if child is None or child["parent_id"] != node["id"]:
+                raise NotFoundError("Item not found")
+            node = child
+            chain.append(node)
+        return node, path, chain
+
+    def _path(self, identity):
+        parts, visited = [], set()
+        while identity != ROOT_ID:
+            if identity in visited or len(parts) > MAX_TREE_DEPTH:
+                raise CorruptStoreError("Invalid catalog ancestry")
+            visited.add(identity)
+            node = self._state["nodes"].get(identity)
+            if node is None:
+                raise NotFoundError("Item does not exist")
+            parts.append(identity)
+            identity = node["parent_id"]
+        return "/" + "/".join(reversed(parts))
+
+    def resolve_id(self, item_id):
+        _validate_id(item_id, allow_root=True)
+        with self._transaction():
+            return self._path(item_id)
+
+    def _subtree(self, identity):
+        children = {}
+        for row in self._state["nodes"].values():
+            children.setdefault(row["parent_id"], []).append(row["id"])
+        result, pending, seen = [], [identity], set()
+        while pending:
+            current = pending.pop()
+            if current in seen:
+                raise CorruptStoreError("Catalog contains a cycle")
+            seen.add(current)
+            result.append(current)
+            pending.extend(children.get(current, []))
+        return result
+
+    def _mutable(self, chain, *, descendants=False):
+        self._demo_mutable(chain, descendants=descendants)
+        roots = {
+            row["root_id"]
+            for row in self._state["deletions"].values()
+            if row["state"] != "completed"
+        }
+        if roots.intersection(row["id"] for row in chain) or (
+            descendants and roots.intersection(self._subtree(chain[-1]["id"]))
+        ):
+            raise ValidationError("Item is pending permanent deletion")
+
+    def _demo_mutable(self, chain, *, descendants=False):
+        from tgdrive.storage.demo_files import restricted_writes
+
+        if not restricted_writes.get():
+            return
+        check_ids(row["id"] for row in chain)
+        if descendants:
+            check_ids(self._subtree(chain[-1]["id"]))
+
+    def ensure_demo_files(self):
+        with self._transaction(write=True):
+            node = self._state["nodes"].get(DEMO_FILES_ID)
+            if node is not None:
+                if node["kind"] != "folder":
+                    raise ValidationError(
+                        "The reserved Demo Files identity is not a folder"
+                    )
+                return self._record(node, self._path(DEMO_FILES_ID))
+            if not self._unique(ROOT_ID, DEMO_FILES_NAME):
+                raise DuplicateNameError(
+                    "A different item named Demo Files already exists. "
+                    "Disable demo mode and rename that item before enabling it again."
+                )
+            self._mutable(self._resolve("/")[2])
+            if len(self._state["nodes"]) >= MAX_TREE_ITEMS:
+                raise ValidationError("Maximum catalog size exceeded")
+            node = self._node(DEMO_FILES_ID, ROOT_ID, DEMO_FILES_NAME, "folder")
+            self._state["nodes"][DEMO_FILES_ID] = node
+            self._bump()
+            return self._record(node, "/" + DEMO_FILES_ID)
+
+    def _unique(self, parent, name, exclude=""):
+        return not any(
+            row["parent_id"] == parent
+            and row["name_key"] == _name_key(name)
+            and row["id"] != exclude
+            and not row["trashed"]
+            for row in self._state["nodes"].values()
+        )
+
+    def _available(self, parent, name, kind, exclude=""):
+        if self._unique(parent, name, exclude):
+            return name
+        from pathlib import Path
+
+        suffix = Path(name).suffix if kind == "file" else ""
+        stem = name[: -len(suffix)] if suffix else name
+        index = 1
+        while True:
+            label = f" ({index})"
+            ending = suffix[: MAX_NAME_LENGTH - len(label) - 1]
+            value = stem[: MAX_NAME_LENGTH - len(label) - len(ending)] + label + ending
+            if self._unique(parent, value, exclude):
+                return value
+            index += 1
+
+    def _file(self, node, path):
+        result = self._record(node, path, message=True)
+        if node.get("parts"):
+            result["parts"] = copy.deepcopy(node["parts"])
+        return result
+
+    def transfer_location(self, operation_id, destination="/", *, completed=False):
+        """Resolve committed upload identities against the current read snapshot."""
+        if operation_id is not None:
+            _validate_id(operation_id)
+        with self._transaction():
+            operation = self._state["operations"].get(operation_id)
+            if operation is not None:
+                path = self._path(operation["node_id"])
+            elif completed:
+                raise NotFoundError("Uploaded item is unavailable")
+            else:
+                parts, _ = _normalize_path(destination)
+                path = self._path(parts[-1] if parts else ROOT_ID)
+            node, path, chain = self._resolve(path)
+            self._visible(chain)
+            from tgdrive.transfers.transfer_locations import location_record
+
+            return location_record(node, path, chain, stored=operation is not None)
+
+    def upload_destination(self, path, *, directory_id=None):
+        with self._transaction():
+            if directory_id is not None:
+                _validate_id(directory_id, allow_root=True)
+                path = self._path(directory_id)
+            node, path, chain = self._resolve(path)
+            if node["kind"] != "folder":
+                raise NotDirectoryError("Upload destination must be a folder")
+            self._visible(chain)
+            self._mutable(chain)
+            return {"id": node["id"], "path": path}
+
+    def get_directory(self, path, *, include_trashed=False):
+        with self._transaction():
+            node, path, chain = self._resolve(path)
+            if node["kind"] != "folder":
+                raise NotDirectoryError("Not a directory")
+            self._visible(chain, include_trashed)
+            result = self._record(node, path)
+            result["contents"] = {
+                row["id"]: self._record(row, _join_path(path, row["id"]))
+                for row in self._state["nodes"].values()
+                if row["parent_id"] == node["id"]
+                and (include_trashed or not row["trashed"])
+            }
+            return result
+
+    def list_directory(self, path, *, include_trashed=False):
+        return self.get_directory(path, include_trashed=include_trashed)["contents"]
+
+    def get_file(self, path, *, include_trashed=False):
+        with self._transaction():
+            node, path, chain = self._resolve(path)
+            if node["kind"] != "file":
+                raise NotFileError("Not a file")
+            self._visible(chain, include_trashed)
+            return self._file(node, path)
+
+    def _add(
+        self,
+        parent_path,
+        name,
+        message_id,
+        size=0,
+        operation_id=None,
+        keep_both=False,
+        parts=None,
+        sha256=None,
+    ):
+        name = _normalize_name(name)
+        if operation_id is not None:
+            _validate_id(operation_id)
+        with self._transaction(write=True):
+            if operation_id in self._state["operations"]:
+                previous = self._state["operations"][operation_id]
+                node = self._state["nodes"].get(previous["node_id"])
+                if node is None:
+                    raise ValidationError("This operation's file was already deleted")
+                result = self._file(node, self._path(node["id"]))
+                if (
+                    node["message_id"] != message_id
+                    or node["size"] != size
+                    or result.get("parts") != parts
+                    or result.get("sha256") != sha256
+                ):
+                    raise ValidationError("Operation already committed different media")
+                return result
+            parent, parent_path, chain = self._resolve(parent_path)
+            if parent["kind"] != "folder":
+                raise NotDirectoryError("Destination must be a folder")
+            self._visible(chain)
+            self._mutable(chain)
+            if (
+                len(chain) > MAX_TREE_DEPTH
+                or len(self._state["nodes"]) >= MAX_TREE_ITEMS
+            ):
+                raise ValidationError("Maximum catalog depth or item count exceeded")
+            kind = "folder" if message_id is None else "file"
+            if keep_both:
+                name = self._available(parent["id"], name, kind)
+            elif not self._unique(parent["id"], name):
+                raise DuplicateNameError("An item with this name already exists")
+            identity = secrets.token_urlsafe(16)
+            row = self._node(
+                identity,
+                parent["id"],
+                name,
+                kind,
+                message_id=message_id,
+                size=size,
+                sha256=sha256,
+                part_count=len(parts) if parts else 1,
+            )
+            if parts:
+                row["parts"] = copy.deepcopy(parts)
+            self._state["nodes"][identity] = row
+            if operation_id is not None:
+                self._state["operations"][operation_id] = {
+                    "_id": operation_id,
+                    "operation_id": operation_id,
+                    "node_id": identity,
+                }
+            self._bump()
+            path = _join_path(parent_path, identity)
+            return (
+                self._file(row, path)
+                if message_id is not None
+                else self._record(row, path)
+            )
+
+    def prepare_folder_tree(self, destination, root_name, folders, client_request_id):
+        manifest = _folder_manifest(destination, root_name, folders)
+        request_id = _validate_id(client_request_id)
+        if len(request_id) < 16:
+            raise ValidationError(
+                "Folder request id must contain at least 16 characters"
+            )
+        fingerprint = hashlib.sha256(_manifest_json(manifest).encode()).hexdigest()
+        with self._transaction(write=True):
+            prior = self._state["preparations"].get(request_id)
+            if prior:
+                if not hmac.compare_digest(prior["fingerprint"], fingerprint):
+                    raise FolderTreeConflictError("Folder request id was already used")
+                result = prior["result"]
+                try:
+                    for relative, path in result["folders"].items():
+                        node, _, chain = self._resolve(path)
+                        self._visible(chain)
+                        self._mutable(chain)
+                        expected = (
+                            relative.rsplit("/", 1)[-1]
+                            if relative
+                            else result["root"]["name"]
+                        )
+                        if node["kind"] != "folder" or node["name"] != expected:
+                            raise ValidationError("Prepared folder changed")
+                except (
+                    NotFoundError,
+                    NotDirectoryError,
+                    ValidationError,
+                    TrashedItemError,
+                ):
+                    raise FolderTreeConflictError(
+                        "The prepared folder tree changed"
+                    ) from None
+                return copy.deepcopy(result)
+            parent = self.upload_destination(manifest["destination"])
+            chain = self._resolve(parent["path"])[2]
+            depth = 1 + max((len(parts) for parts in manifest["folders"]), default=0)
+            if len(chain) - 1 + depth > MAX_TREE_DEPTH:
+                raise ValidationError("Maximum tree depth exceeded")
+            if (
+                len(self._state["nodes"]) + 1 + len(manifest["folders"])
+                > MAX_TREE_ITEMS
+            ):
+                raise ValidationError("Maximum catalog size exceeded")
+            root_name = self._available(parent["id"], manifest["root_name"], "folder")
+            mapping = {}
+            root = None
+            for segments in [[], *manifest["folders"]]:
+                parent_path = (
+                    mapping["/".join(segments[:-1])] if segments else parent["path"]
+                )
+                parent_id = (
+                    parent_path.rsplit("/", 1)[-1] if parent_path != "/" else ROOT_ID
+                )
+                identity = secrets.token_urlsafe(16)
+                node = self._node(
+                    identity,
+                    parent_id,
+                    segments[-1] if segments else root_name,
+                    "folder",
+                )
+                self._state["nodes"][identity] = node
+                mapping["/".join(segments)] = _join_path(parent_path, identity)
+                if not segments:
+                    root = self._record(node, mapping[""])
+            result = {"root": root, "folders": mapping}
+            self._bump()
+            self._state["preparations"][request_id] = {
+                "_id": request_id,
+                "request_id": request_id,
+                "fingerprint": fingerprint,
+                "manifest": manifest,
+                "result": result,
+                "created_at": _utc_now(),
+            }
+            return copy.deepcopy(result)
+
+    def rename(self, path, new_name):
+        name = _normalize_name(new_name)
+        with self._transaction(write=True):
+            node, path, chain = self._resolve(path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("The root folder cannot be renamed")
+            self._demo_mutable(chain, descendants=True)
+            self._mutable(chain)
+            if node["kind"] == "file":
+                _validate_file_rename(node["name"], name)
+            if not self._unique(node["parent_id"], name, node["id"]):
+                raise DuplicateNameError("An item with this name already exists")
+            if node["name"] != name:
+                node.update(name=name, name_key=_name_key(name))
+                self._bump()
+            return self._record(node, path)
+
+    def _revoke(self, identities):
+        ids = set(identities)
+        for key, row in list(self._state["shares"].items()):
+            if row["node_id"] in ids:
+                del self._state["shares"][key]
+
+    def set_trashed(self, path, trashed):
+        with self._transaction(write=True):
+            return self._set_trashed(path, trashed)
+
+    def set_trashed_many(self, paths, trashed):
+        with self._transaction(write=True):
+            return [self._set_trashed(path, trashed) for path in paths]
+
+    def _set_trashed(self, path, trashed):
+        if type(trashed) is not bool:
+            raise ValidationError("trashed must be a boolean")
+        node, path, chain = self._resolve(path)
+        if node["id"] == ROOT_ID:
+            raise RootMutationError("The root folder cannot be trashed")
+        self._mutable(chain, descendants=True)
+        if not trashed:
+            self._visible(chain[:-1])
+        if node["trashed"] != trashed:
+            name = (
+                node["name"]
+                if trashed
+                else self._available(
+                    node["parent_id"], node["name"], node["kind"], node["id"]
+                )
+            )
+            node.update(trashed=trashed, name=name, name_key=_name_key(name))
+            if trashed:
+                self._revoke(self._subtree(node["id"]))
+            self._bump()
+        return self._record(node, path)
+
+    def list_trash(self, query=""):
+        with self._transaction():
+            result = {}
+            for node in self._state["nodes"].values():
+                if node["trashed"] and query.casefold() in node["name"].casefold():
+                    path = self._path(node["id"])
+                    chain = self._resolve(path)[2]
+                    if not any(row["trashed"] for row in chain[:-1]):
+                        result[node["id"]] = self._record(node, path) | {
+                            "parent_names": [item["name"] for item in chain[1:-1]]
+                        }
+            return result
+
+    def set_starred(self, path, starred):
+        if type(starred) is not bool:
+            raise ValidationError("starred must be a boolean")
+        with self._transaction(write=True):
+            node, path, chain = self._resolve(path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the drive root cannot be starred")
+            self._mutable(chain)
+            self._visible(chain)
+            if bool(node.get("starred", False)) != starred:
+                node["starred"] = starred
+                self._bump()
+            return self._record(node, path)
+
+    def list_starred(self, query=""):
+        if not isinstance(query, str) or len(query) > MAX_NAME_LENGTH:
+            raise ValidationError("invalid starred search")
+        with self._transaction():
+            results = {}
+            for node in self._state["nodes"].values():
+                if (
+                    not node.get("starred")
+                    or node["id"] == ROOT_ID
+                    or _name_key(query.strip()) not in node["name_key"]
+                ):
+                    continue
+                path = self._path(node["id"])
+                chain = self._resolve(path)[2]
+                if any(item["trashed"] for item in chain):
+                    continue
+                results[node["id"]] = self._record(node, path) | {
+                    "parent_names": [row["name"] for row in chain[1:-1]]
+                }
+            return results
+
+    def search_page(
+        self,
+        query,
+        *,
+        offset=0,
+        limit=100,
+        sort="name",
+        order=None,
+        include_trashed=False,
+    ):
+        if not isinstance(query, str):
+            raise ValidationError("Search query must be a string")
+        query = unicodedata.normalize("NFC", query).strip()
+        if (
+            not query
+            or len(query) > MAX_NAME_LENGTH
+            or any(unicodedata.category(c) in {"Cc", "Cs"} for c in query)
+        ):
+            raise ValidationError("Search query is empty, too long or invalid")
+        if (
+            type(offset) is not int
+            or not 0 <= offset <= MAX_SEARCH_OFFSET
+            or type(limit) is not int
+            or not 1 <= limit <= MAX_SEARCH_RESULTS
+            or type(include_trashed) is not bool
+            or sort not in {"name", "date", "size"}
+            or (
+                order is not None
+                and (not isinstance(order, str) or order not in {"asc", "desc"})
+            )
+        ):
+            raise ValidationError("Invalid search pagination or sort")
+        direction = order or ("asc" if sort == "name" else "desc")
+        with self._transaction():
+            found = []
+            for node in self._state["nodes"].values():
+                if node["id"] == ROOT_ID or query.casefold() not in node["name_key"]:
+                    continue
+                path = self._path(node["id"])
+                chain = self._resolve(path)[2]
+                if not include_trashed and any(row["trashed"] for row in chain):
+                    continue
+                row = self._record(node, path)
+                row["parent_names"] = [item["name"] for item in chain[1:-1]]
+                found.append(row)
+            found.sort(key=lambda r: (_name_key(r["name"]), r["id"]))
+            found.sort(
+                key=lambda r: (
+                    _name_key(r["name"])
+                    if sort == "name"
+                    else r["size"]
+                    if sort == "size"
+                    else r["upload_date"]
+                ),
+                reverse=direction == "desc",
+            )
+            found.sort(key=lambda r: r["type"] != "folder")
+            items = found[offset : offset + limit]
+            more = len(found) > offset + limit
+            return {
+                "items": items,
+                "query": query,
+                "has_more": more,
+                "next_offset": offset + len(items) if more else None,
+            }
+
+    def _messages(self, identity):
+        result = set()
+        for key in self._subtree(identity):
+            row = self._state["nodes"][key]
+            if row["kind"] == "file":
+                result.add(row["message_id"])
+                result.update(part["message_id"] for part in row.get("parts", []))
+        return sorted(result)
+
+    def message_ids(self, path, *, include_trashed=False):
+        with self._transaction():
+            node, _, chain = self._resolve(path)
+            self._visible(chain, include_trashed)
+            return self._messages(node["id"])
+
+    def _remove_subtree(self, identity):
+        ids = self._subtree(identity)
+        self._revoke(ids)
+        for key in ids:
+            del self._state["nodes"][key]
+
+    def delete(self, path):
+        with self._transaction(write=True):
+            node, _, chain = self._resolve(path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("The root folder cannot be deleted")
+            self._mutable(chain, descendants=True)
+            if self._messages(node["id"]):
+                raise ValidationError("Files require a permanent deletion intent")
+            self._remove_subtree(node["id"])
+            self._bump()
+            return []
+
+    def move(self, path, destination, *, conflict="keep_both"):
+        with self._transaction(write=True):
+            return self._move(path, destination, conflict=conflict)
+
+    def move_many(self, paths, destination, *, conflict="keep_both"):
+        with self._transaction(write=True):
+            return [self._move(path, destination, conflict=conflict) for path in paths]
+
+    def _move(self, path, destination, *, conflict="keep_both"):
+        if conflict not in {"keep_both", "skip"}:
+            raise ValidationError("Invalid conflict policy")
+        node, path, chain = self._resolve(path)
+        parent, destination, parent_chain = self._resolve(destination)
+        if node["id"] == ROOT_ID:
+            raise RootMutationError("The root folder cannot be moved")
+        if parent["kind"] != "folder":
+            raise NotDirectoryError("Destination must be a folder")
+        self._visible(chain)
+        self._visible(parent_chain)
+        self._mutable(chain, descendants=True)
+        self._mutable(parent_chain)
+        if node["id"] in {row["id"] for row in parent_chain}:
+            raise InvalidPathError("A folder cannot move into its subtree")
+        if node["parent_id"] == parent["id"]:
+            return self._record(node, path)
+        for key in self._subtree(node["id"]):
+            depth = len(self._path(key).split("/")) - len(path.split("/"))
+            if len(parent_chain) + depth > MAX_TREE_DEPTH:
+                raise ValidationError("Move would exceed maximum tree depth")
+        name = node["name"]
+        if not self._unique(parent["id"], name):
+            if conflict == "skip":
+                return None
+            name = self._available(parent["id"], name, node["kind"])
+        node.update(parent_id=parent["id"], name=name, name_key=_name_key(name))
+        self._bump()
+        return self._record(node, _join_path(destination, node["id"]))
+
+    def create_share(
+        self,
+        path,
+        *,
+        expires_at=DriveStore._DEFAULT_EXPIRY,
+        token_factory=None,
+        label="",
+        replace_existing=False,
+    ):
+        expiry = (
+            self._default_share_expiry()
+            if expires_at is DriveStore._DEFAULT_EXPIRY
+            else _validate_timestamp(expires_at)
+            if expires_at is not None
+            else None
+        )
+        label = _share_label(label)
+        created = _utc_now()
+        if expiry is not None and expiry <= created:
+            raise ValidationError("Share expiry must be in the future")
+        with self._transaction(write=True):
+            node, _, chain = self._resolve(path)
+            self._visible(chain)
+            self._demo_mutable(chain, descendants=True)
+            self._mutable(chain)
+            if replace_existing:
+                self._revoke([node["id"]])
+            if (
+                sum(
+                    row["node_id"] == node["id"]
+                    for row in self._state["shares"].values()
+                )
+                >= MAX_SHARE_TOKENS_PER_ITEM
+            ):
+                raise ValidationError(
+                    "This item has 100 links. Remove an old link first."
+                )
+            identity = secrets.token_urlsafe(16)
+            token = (
+                token_factory(identity) if token_factory else secrets.token_urlsafe(32)
+            )
+            self._state["shares"][identity] = {
+                "_id": identity,
+                "id": identity,
+                "node_id": node["id"],
+                "token_hash": hashlib.sha256(token.encode()).hexdigest(),
+                "created_at": created,
+                "expires_at": expiry,
+                **({"label": label} if label else {}),
+            }
+            self._bump()
+            return token
+
+    def list_shares(self, path=None, *, include_expired=False, token_factory=None):
+        with self._transaction():
+            identity = self._resolve(path)[0]["id"] if path is not None else None
+            return [
+                {
+                    "id": row["id"],
+                    "label": row.get("label", ""),
+                    "node_id": row["node_id"],
+                    "path": self._path(row["node_id"]),
+                    **self._share_details(row, token_factory),
+                    "created_at": row["created_at"],
+                    "expires_at": row["expires_at"],
+                }
+                for row in self._state["shares"].values()
+                if (identity is None or row["node_id"] == identity)
+                and (
+                    include_expired
+                    or row["expires_at"] is None
+                    or row["expires_at"] > _utc_now()
+                )
+            ]
+
+    def _share_details(self, row, factory):
+        node, path, chain = self._resolve(self._path(row["node_id"]))
+        return {
+            "name": node["name"],
+            "type": node["kind"],
+            "size": node.get("size"),
+            "folder_path": path.rsplit("/", 1)[0] or "/",
+            "folder_label": " / ".join(["My Files", *(n["name"] for n in chain[1:-1])]),
+            "copyable": bool(
+                factory
+                and hmac.compare_digest(
+                    row["token_hash"],
+                    hashlib.sha256(factory(row["id"]).encode()).hexdigest(),
+                )
+            ),
+        }
+
+    def update_share(self, share_id, *, label=_SHARE_UNSET, expires_at=_SHARE_UNSET):
+        if label is not _SHARE_UNSET:
+            label = _share_label(label)
+        expiry = expires_at
+        if expires_at is not _SHARE_UNSET and expires_at is not None:
+            expiry = _validate_timestamp(expires_at)
+        if expiry is not _SHARE_UNSET and expiry is not None and expiry <= _utc_now():
+            raise ValidationError("Link expiry must be in the future")
+        with self._transaction(write=True):
+            row = self._state["shares"].get(share_id)
+            if row is None:
+                raise NotFoundError("Link not found")
+            _, _, chain = self._resolve(self._path(row["node_id"]))
+            self._visible(chain)
+            self._demo_mutable(chain, descendants=True)
+            self._mutable(chain)
+            if label is _SHARE_UNSET and expiry is _SHARE_UNSET:
+                return
+            if expiry is not _SHARE_UNSET:
+                row["expires_at"] = expiry
+            if label is not _SHARE_UNSET:
+                if label:
+                    row["label"] = label
+                else:
+                    row.pop("label", None)
+            self._bump()
+
+    def revoke_share(self, share_id):
+        with self._transaction(write=True):
+            if share_id.startswith("/"):
+                self._demo_mutable(self._resolve(share_id)[2], descendants=True)
+            elif share_id in self._state["shares"]:
+                node_id = self._state["shares"][share_id]["node_id"]
+                self._demo_mutable(
+                    self._resolve(self._path(node_id))[2], descendants=True
+                )
+            keys = (
+                [
+                    key
+                    for key, row in self._state["shares"].items()
+                    if row["node_id"] == self._resolve(share_id)[0]["id"]
+                ]
+                if share_id.startswith("/")
+                else [share_id]
+            )
+            removed = False
+            for key in keys:
+                removed |= self._state["shares"].pop(key, None) is not None
+            if removed:
+                self._bump()
+            return removed
+
+    def _authorized(self, chain, token):
+        if (
+            not isinstance(token, str)
+            or not token
+            or len(token) > 1024
+            or any(row["trashed"] for row in chain)
+        ):
+            return None
+        digest = hashlib.sha256(token.encode()).hexdigest()
+        ids = {row["id"] for row in chain}
+        for row in self._state["shares"].values():
+            if (
+                row["node_id"] in ids
+                and (row["expires_at"] is None or row["expires_at"] > _utc_now())
+                and hmac.compare_digest(row["token_hash"], digest)
+            ):
+                return self._path(row["node_id"])
+        return None
+
+    def authorize_directory(self, path, token):
+        with self._transaction():
+            node, _, chain = self._resolve(path)
+            if node["kind"] != "folder":
+                raise NotDirectoryError("Not a directory")
+            return self._authorized(chain, token)
+
+    def authorize_file(self, path, token):
+        with self._transaction():
+            node, _, chain = self._resolve(path)
+            if node["kind"] != "file":
+                raise NotFileError("Not a file")
+            return self._authorized(chain, token) is not None
+
+    def _pending_for(self, identity):
+        return next(
+            (
+                row
+                for row in self._state["deletions"].values()
+                if row["root_id"] == identity and row["state"] != "completed"
+            ),
+            None,
+        )
+
+    def validate_deletion(self, path):
+        with self._transaction():
+            node, path, chain = self._resolve(path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("The root folder cannot be deleted")
+            self._demo_mutable(chain, descendants=True)
+            if not self._pending_for(node["id"]):
+                self._mutable(chain, descendants=True)
+                if not node["trashed"] or any(row["trashed"] for row in chain[:-1]):
+                    raise TrashedItemError(
+                        "Permanent deletion requires a top-level trash item"
+                    )
+            return self._record(node, path)
+
+    def begin_deletion(self, path, *, channel_id=None):
+        if channel_id is not None:
+            _validate_channel_id(channel_id)
+        with self._transaction(write=True):
+            node, path, chain = self._resolve(path)
+            self.validate_deletion(path)
+            prior = self._pending_for(node["id"])
+            if prior:
+                if channel_id is not None and prior["channel_id"] != channel_id:
+                    raise ValidationError("Deletion channel does not match")
+                return self._deletion(prior)
+            self._mutable(chain, descendants=True)
+            identity = secrets.token_urlsafe(16)
+            messages = self._messages(node["id"])
+            row = {
+                "_id": identity,
+                "id": identity,
+                "root_id": node["id"],
+                "path": path,
+                "channel_id": channel_id,
+                "state": "pending",
+                "created_at": _utc_now(),
+                "error": None,
+                "message_ids": messages,
+                "pending_message_ids": messages.copy(),
+            }
+            self._state["deletions"][identity] = row
+            self._revoke(self._subtree(node["id"]))
+            self._bump()
+            return self._deletion(row)
+
+    @staticmethod
+    def _deletion(row):
+        return copy.deepcopy({key: value for key, value in row.items() if key != "_id"})
+
+    def pending_deletions(self):
+        with self._transaction():
+            return [
+                self._deletion(row)
+                for row in self._state["deletions"].values()
+                if row["state"] != "completed"
+            ]
+
+    def confirm_deletion_messages(self, intent_id, message_ids):
+        validated = {_strict_int(value, "message_id", 1) for value in message_ids}
+        with self._transaction(write=True):
+            row = self._state["deletions"].get(intent_id)
+            if row is None:
+                raise NotFoundError("Deletion intent not found")
+            if not validated <= set(row["message_ids"]):
+                raise ValidationError("Confirmation contains unrelated messages")
+            if row["state"] == "completed":
+                return
+            row.update(
+                pending_message_ids=sorted(set(row["pending_message_ids"]) - validated),
+                state="pending",
+                error=None,
+            )
+            self._bump()
+
+    def fail_deletion(self, intent_id, error):
+        with self._transaction(write=True):
+            row = self._state["deletions"].get(intent_id)
+            if row is None or row["state"] == "completed":
+                raise NotFoundError("Active deletion intent not found")
+            row.update(state="failed", error=str(error)[:500])
+            self._bump()
+
+    def finish_deletion(self, intent_id):
+        """Atomically forget a trashed subtree; retain its Telegram documents."""
+        with self._transaction(write=True):
+            row = self._state["deletions"].get(intent_id)
+            if row is None:
+                raise NotFoundError("Deletion intent not found")
+            messages = row["message_ids"].copy()
+            if row["state"] != "completed":
+                self._demo_mutable(
+                    self._resolve(self._path(row["root_id"]))[2], descendants=True
+                )
+                self._remove_subtree(row["root_id"])
+                row.update(
+                    state="completed",
+                    error=None,
+                    message_ids=[],
+                    pending_message_ids=[],
+                )
+                self._bump()
+            return messages
+
+    def _export(self):
+        nodes = {}
+        for key, row in self._state["nodes"].items():
+            value = {
+                "id": key,
+                "name": row["name"],
+                "type": row["kind"],
+                "upload_date": row["upload_date"],
+                "trashed": row["trashed"],
+                "share_hashes": [],
+            }
+            if row.get("starred"):
+                value["starred"] = True
+            if row["kind"] == "file":
+                value.update(message_id=row["message_id"], size=row["size"])
+                if row.get("parts"):
+                    value["parts"] = copy.deepcopy(row["parts"])
+                if row.get("sha256"):
+                    value["sha256"] = row["sha256"]
+            else:
+                value["children"] = {}
+            nodes[key] = value
+        for row in self._state["shares"].values():
+            nodes[row["node_id"]]["share_hashes"].append(row["token_hash"])
+        for key, row in self._state["nodes"].items():
+            if row["parent_id"] is not None:
+                parent = nodes.get(row["parent_id"])
+                if parent is None or parent["type"] != "folder":
+                    raise CorruptStoreError("Invalid catalog parent")
+                parent["children"][key] = nodes[key]
+        metadata = self._state["metadata"]
+        result = {
+            "schema_version": SCHEMA_VERSION,
+            "drive_id": metadata["drive_id"],
+            "revision": metadata["revision"],
+            "backed_up_revision": metadata["revision"],
+            "root": nodes[ROOT_ID],
+            "shares": [
+                {k: v for k, v in row.items() if k != "_id"}
+                for row in self._state["shares"].values()
+            ],
+            "operations": [
+                {k: v for k, v in row.items() if k != "_id"}
+                for row in self._state["operations"].values()
+            ],
+            "deletions": [
+                self._deletion(row) for row in self._state["deletions"].values()
+            ],
+        }
+        if metadata.get("storage_channel_id") is not None:
+            result["storage_channel_id"] = metadata["storage_channel_id"]
+        if self._state["preparations"]:
+            result["folder_preparations"] = [
+                {k: copy.deepcopy(v) for k, v in row.items() if k != "_id"}
+                for row in self._state["preparations"].values()
+            ]
+        return result
+
+    def export(self):
+        with self._transaction():
+            return self._export()
+
+    def mark_backed_up(self, revision):
+        if type(revision) is not int or not 0 <= revision <= self.revision:
+            raise InvalidRevisionError("Invalid catalog revision")
+        return False
+
+    def statistics(self):
+        with self._transaction():
+            result = {
+                "files": 0,
+                "folders": 0,
+                "total_bytes": 0,
+                "trashed_files": 0,
+                "trashed_bytes": 0,
+            }
+            for row in self._state["nodes"].values():
+                if row["id"] == ROOT_ID:
+                    continue
+                hidden = any(
+                    item["trashed"] for item in self._resolve(self._path(row["id"]))[2]
+                )
+                if row["kind"] == "file":
+                    result["trashed_files" if hidden else "files"] += 1
+                    result["trashed_bytes" if hidden else "total_bytes"] += row["size"]
+                elif not hidden:
+                    result["folders"] += 1
+            return result
diff --git a/tgdrive/storage/store.py b/tgdrive/storage/store.py
new file mode 100644
index 00000000..7ed4e990
--- /dev/null
+++ b/tgdrive/storage/store.py
@@ -0,0 +1,2679 @@
+"""SQLite catalog and shared validation for portable drive snapshots.
+
+MongoStore reuses the snapshot schemas and catalog helpers while persisting its
+own catalog in MongoDB. SQLite transactions protect this catalog implementation;
+public reads return independent records.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import re
+import secrets
+import sqlite3
+import threading
+import unicodedata
+import weakref
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from tgdrive.core.errors import (
+    CorruptStoreError,
+    DuplicateNameError,
+    InvalidNameError,
+    InvalidPathError,
+    InvalidRevisionError,
+    NotDirectoryError,
+    NotFileError,
+    NotFoundError,
+    PersistenceError,
+    RootMutationError,
+    TrashedItemError,
+    UnsupportedSchemaError,
+    ValidationError,
+)
+from tgdrive.storage.demo_files import DEMO_FILES_ID, DEMO_FILES_NAME, check_ids
+from tgdrive.storage.file_parts import validate_parts, validate_sha256
+
+SCHEMA_VERSION = 4
+ROOT_ID = "root"
+MAX_NAME_LENGTH = 255
+MAX_STORE_BYTES = 64 * 1024 * 1024
+MAX_TREE_DEPTH = 128
+MAX_TREE_ITEMS = 250_000
+MAX_FOLDER_TREE_ITEMS = 1000
+MAX_FOLDER_TREE_DEPTH = 64
+MAX_SEARCH_RESULTS = 500
+MAX_SEARCH_OFFSET = MAX_TREE_ITEMS
+# Bound independent capabilities without evicting somebody else's link.
+MAX_SHARE_TOKENS_PER_ITEM = 100
+_SHARE_UNSET = object()
+
+_ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+_HASH_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _utc_now() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def _validate_timestamp(value: object) -> str:
+    if not isinstance(value, str) or not value:
+        raise ValidationError("upload_date must be a non-empty ISO-8601 string")
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ValidationError("upload_date must be valid ISO-8601") from exc
+    if parsed.tzinfo is None:
+        raise ValidationError("upload_date must include a timezone")
+    return parsed.astimezone(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def _share_label(value: object) -> str:
+    if (
+        not isinstance(value, str)
+        or len(value) > 80
+        or any(unicodedata.category(char) in {"Cc", "Cs"} for char in value)
+    ):
+        raise ValidationError(
+            "Link label must be at most 80 characters without controls"
+        )
+    return unicodedata.normalize("NFC", value).strip()
+
+
+def _validate_id(value: object, *, allow_root: bool = False) -> str:
+    if not isinstance(value, str) or not _ID_RE.fullmatch(value):
+        raise ValidationError("item id must contain only URL-safe opaque characters")
+    if value == ROOT_ID and not allow_root:
+        raise ValidationError("the reserved root id cannot be used by a child")
+    return value
+
+
+def _validate_channel_id(value: object) -> int:
+    if type(value) is not int or value == 0 or not -(2**63) <= value < 2**63:
+        raise ValidationError("storage_channel_id must be a non-zero 64-bit integer")
+    return value
+
+
+def _normalize_name(value: object) -> str:
+    if not isinstance(value, str):
+        raise InvalidNameError("name must be a string")
+    normalized = unicodedata.normalize("NFC", value)
+    if not normalized or normalized in {".", ".."}:
+        raise InvalidNameError("name cannot be empty, '.' or '..'")
+    if normalized != normalized.strip():
+        raise InvalidNameError("name cannot start or end with whitespace")
+    if len(normalized) > MAX_NAME_LENGTH:
+        raise InvalidNameError(f"name cannot exceed {MAX_NAME_LENGTH} characters")
+    if "/" in normalized or "\\" in normalized or "\x00" in normalized:
+        raise InvalidNameError("name cannot contain path separators or NUL")
+    if any(unicodedata.category(character) in {"Cc", "Cs"} for character in normalized):
+        raise InvalidNameError("name cannot contain control characters or surrogates")
+    return normalized
+
+
+def _name_key(value: str) -> str:
+    return unicodedata.normalize("NFC", value).casefold()
+
+
+def _validate_file_rename(current_name: str, new_name: str) -> None:
+    """Keep an existing file suffix when changing its display name."""
+    separator = current_name.rfind(".")
+    if 0 < separator < len(current_name) - 1:
+        extension = current_name[separator:]
+        new_separator = new_name.rfind(".")
+        new_extension = (
+            new_name[new_separator:] if 0 < new_separator < len(new_name) - 1 else ""
+        )
+        if extension.lower() != new_extension.lower():
+            raise InvalidNameError(
+                f"The file extension cannot be changed. Keep the {extension} extension."
+            )
+
+
+def _validate_share_hashes(value: object) -> list[str]:
+    if not isinstance(value, list):
+        raise ValidationError("share_hashes must be a list")
+    hashes: list[str] = []
+    for token_hash in value:
+        if not isinstance(token_hash, str) or not _HASH_RE.fullmatch(token_hash):
+            raise ValidationError("share token hashes must be lowercase SHA-256 hex")
+        if token_hash in hashes:
+            raise ValidationError("duplicate share token hash on item")
+        hashes.append(token_hash)
+    return hashes
+
+
+def _strict_int(value: object, field_name: str, minimum: int = 0) -> int:
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, int)
+        or not minimum <= value <= (1 << 63) - 1
+    ):
+        raise ValidationError(
+            f"{field_name} must be a signed 64-bit integer >= {minimum}"
+        )
+    return value
+
+
+@dataclass(slots=True)
+class _FileNode:
+    id: str
+    name: str
+    message_id: int
+    size: int
+    upload_date: str
+    trashed: bool = False
+    starred: bool = False
+    share_hashes: list[str] = field(default_factory=list)
+    parts: list[dict[str, Any]] | None = None
+    sha256: str | None = None
+
+    def __post_init__(self) -> None:
+        self.id = _validate_id(self.id)
+        self.name = _normalize_name(self.name)
+        self.message_id = _strict_int(self.message_id, "message_id", 1)
+        self.size = _strict_int(self.size, "size", 0)
+        self.upload_date = _validate_timestamp(self.upload_date)
+        if not isinstance(self.trashed, bool):
+            raise ValidationError("trashed must be a boolean")
+        if type(self.starred) is not bool:
+            raise ValidationError("starred must be a boolean")
+        self.share_hashes = _validate_share_hashes(self.share_hashes)
+        self.sha256 = validate_sha256(self.sha256)
+        if self.parts is not None:
+            self.parts = validate_parts(
+                self.parts, size=self.size, message_id=self.message_id
+            )
+
+
+@dataclass(slots=True)
+class _FolderNode:
+    id: str
+    name: str
+    upload_date: str
+    trashed: bool = False
+    starred: bool = False
+    share_hashes: list[str] = field(default_factory=list)
+    children: dict[str, _Node] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.id = _validate_id(self.id, allow_root=self.id == ROOT_ID)
+        if self.id == ROOT_ID:
+            if self.name != "/":
+                raise ValidationError("root folder name must be '/'")
+        else:
+            self.name = _normalize_name(self.name)
+        self.upload_date = _validate_timestamp(self.upload_date)
+        if not isinstance(self.trashed, bool):
+            raise ValidationError("trashed must be a boolean")
+        if type(self.starred) is not bool:
+            raise ValidationError("starred must be a boolean")
+        self.share_hashes = _validate_share_hashes(self.share_hashes)
+        if not isinstance(self.children, dict):
+            raise ValidationError("folder children must be an object")
+
+
+_Node = _FolderNode | _FileNode
+
+
+def _parse_node(data: object, *, depth: int = 0) -> _Node:
+    if depth > MAX_TREE_DEPTH:
+        raise ValidationError(f"tree exceeds maximum depth of {MAX_TREE_DEPTH}")
+    if not isinstance(data, dict):
+        raise ValidationError("each tree node must be an object")
+    item_type = data.get("type")
+    common_keys = {
+        "id",
+        "name",
+        "share_hashes",
+        "trashed",
+        "type",
+        "upload_date",
+    }
+    if item_type == "file":
+        expected = common_keys | {"message_id", "size"}
+        optional = {"parts", "sha256", "starred"}
+        if not expected <= set(data) or set(data) - expected - optional:
+            raise ValidationError("file node has missing or unknown fields")
+        if "parts" in data and not isinstance(data["parts"], list):
+            raise ValidationError("file parts must be an array")
+        if "sha256" in data:
+            validate_sha256(data["sha256"], optional=False)
+        return _FileNode(
+            id=data["id"],
+            name=data["name"],
+            message_id=data["message_id"],
+            size=data["size"],
+            upload_date=data["upload_date"],
+            trashed=data["trashed"],
+            starred=data.get("starred", False),
+            share_hashes=data["share_hashes"],
+            parts=data.get("parts"),
+            sha256=data.get("sha256"),
+        )
+    if item_type == "folder":
+        expected = common_keys | {"children"}
+        optional = {"starred"}
+        if not expected <= set(data) or set(data) - expected - optional:
+            raise ValidationError("folder node has missing or unknown fields")
+        raw_children = data["children"]
+        if not isinstance(raw_children, dict):
+            raise ValidationError("folder children must be an object")
+        children: dict[str, _Node] = {}
+        for child_id, raw_child in raw_children.items():
+            if not isinstance(child_id, str):
+                raise ValidationError("child map keys must be strings")
+            child = _parse_node(raw_child, depth=depth + 1)
+            if child.id != child_id:
+                raise ValidationError("child map key does not match child id")
+            children[child_id] = child
+        return _FolderNode(
+            id=data["id"],
+            name=data["name"],
+            upload_date=data["upload_date"],
+            trashed=data["trashed"],
+            starred=data.get("starred", False),
+            share_hashes=data["share_hashes"],
+            children=children,
+        )
+    raise ValidationError("node type must be 'file' or 'folder'")
+
+
+def _validate_tree(root: _FolderNode) -> None:
+    if root.id != ROOT_ID or root.name != "/" or root.trashed:
+        raise ValidationError(
+            "root must be an active folder with id 'root' and name '/'"
+        )
+
+    seen_ids: set[str] = {ROOT_ID}
+    seen_hashes: set[str] = set()
+    item_count = 1
+
+    def visit(folder: _FolderNode, depth: int) -> None:
+        nonlocal item_count
+        if depth > MAX_TREE_DEPTH:
+            raise ValidationError(f"tree exceeds maximum depth of {MAX_TREE_DEPTH}")
+        sibling_names: set[str] = set()
+        for child_id, child in folder.children.items():
+            item_count += 1
+            if item_count > MAX_TREE_ITEMS:
+                raise ValidationError(
+                    f"tree exceeds maximum item count of {MAX_TREE_ITEMS}"
+                )
+            if child_id != child.id:
+                raise ValidationError("child map key does not match child id")
+            if child.id in seen_ids:
+                raise ValidationError(f"duplicate item id: {child.id}")
+            seen_ids.add(child.id)
+            key = _name_key(child.name)
+            if not child.trashed and key in sibling_names:
+                raise DuplicateNameError(
+                    f"duplicate case-insensitive sibling name: {child.name}"
+                )
+            if not child.trashed:
+                sibling_names.add(key)
+            for token_hash in child.share_hashes:
+                if token_hash in seen_hashes:
+                    raise ValidationError(
+                        "share token hash is assigned to multiple items"
+                    )
+                seen_hashes.add(token_hash)
+            if isinstance(child, _FolderNode):
+                visit(child, depth + 1)
+
+    for token_hash in root.share_hashes:
+        if token_hash in seen_hashes:
+            raise ValidationError("duplicate root share token hash")
+        seen_hashes.add(token_hash)
+    visit(root, 0)
+
+
+def _normalize_path(path: object) -> tuple[tuple[str, ...], str]:
+    if not isinstance(path, str) or not path:
+        raise InvalidPathError("path must be a non-empty string")
+    if not path.startswith("/"):
+        raise InvalidPathError("path must be absolute")
+    if "\\" in path or "\x00" in path or "//" in path:
+        raise InvalidPathError("path contains a forbidden separator or NUL")
+    if path == "/":
+        return (), "/"
+    normalized = path[:-1] if path.endswith("/") else path
+    parts = tuple(normalized[1:].split("/"))
+    if not parts or any(part in {"", ".", ".."} for part in parts):
+        raise InvalidPathError("path contains an empty or traversal component")
+    for part in parts:
+        if not _ID_RE.fullmatch(part):
+            raise InvalidPathError("path components must be item ids")
+        if part == ROOT_ID:
+            raise InvalidPathError("root is represented by '/', not '/root'")
+    return parts, "/" + "/".join(parts)
+
+
+def _join_path(parent_path: str, child_id: str) -> str:
+    return f"/{child_id}" if parent_path == "/" else f"{parent_path}/{child_id}"
+
+
+def _parent_path(full_path: str) -> str:
+    if full_path == "/":
+        return "/"
+    parent = full_path.rsplit("/", 1)[0]
+    return parent or "/"
+
+
+class FolderTreeConflictError(ValidationError):
+    """An idempotent folder preparation cannot safely be reused."""
+
+
+def _folder_manifest(
+    destination: object, root_name: object, folders: object
+) -> dict[str, Any]:
+    _, destination = _normalize_path(destination)
+    root_name = _normalize_name(root_name)
+    if not isinstance(folders, list) or len(folders) >= MAX_FOLDER_TREE_ITEMS:
+        raise ValidationError(
+            "folder tree supports at most 1000 folders including root"
+        )
+    paths: set[tuple[str, ...]] = set()
+    siblings: set[tuple[tuple[str, ...], str]] = set()
+    for segments in folders:
+        if not isinstance(segments, list) or not segments:
+            raise ValidationError(
+                "relative folder paths must be non-empty segment arrays"
+            )
+        if len(segments) >= MAX_FOLDER_TREE_DEPTH:
+            raise ValidationError("folder tree cannot exceed 64 levels including root")
+        path = tuple(_normalize_name(segment) for segment in segments)
+        key = (path[:-1], _name_key(path[-1]))
+        if path in paths or key in siblings:
+            raise DuplicateNameError(
+                "folder tree has duplicate normalized sibling names"
+            )
+        paths.add(path)
+        siblings.add(key)
+    if any(path[:-1] and path[:-1] not in paths for path in paths):
+        raise ValidationError("folder tree must include every ancestor folder")
+    return {
+        "destination": destination,
+        "root_name": root_name,
+        "folders": [
+            list(path) for path in sorted(paths, key=lambda path: (len(path), path))
+        ],
+    }
+
+
+def _manifest_json(manifest: dict[str, Any]) -> str:
+    return json.dumps(
+        manifest, ensure_ascii=False, separators=(",", ":"), sort_keys=True
+    )
+
+
+class DriveStore:
+    """SQLite metadata whose paths are presentations of stable parent IDs."""
+
+    DATABASE_VERSION = 6
+    APPLICATION_ID = 0x54474456
+    _DEFAULT_EXPIRY = object()
+
+    def __init__(self, connection: sqlite3.Connection, path: Path | None) -> None:
+        self._db = connection
+        self._storage_path = path
+        self._lock = threading.RLock()
+        self._transaction_writes: list[bool] = []
+        self._savepoint_serial = 0
+        self._finalizer = weakref.finalize(self, connection.close)
+
+    @staticmethod
+    def _connect(path: Path | None) -> sqlite3.Connection:
+        connection = sqlite3.connect(
+            str(path) if path is not None else ":memory:",
+            timeout=5,
+            isolation_level=None,
+            check_same_thread=False,
+        )
+        try:
+            connection.row_factory = sqlite3.Row
+            connection.execute("PRAGMA foreign_keys=ON")
+            connection.execute("PRAGMA busy_timeout=5000")
+            connection.execute("PRAGMA synchronous=FULL")
+            if path is not None:
+                connection.execute("PRAGMA journal_mode=WAL")
+        except BaseException:
+            connection.close()
+            raise
+        return connection
+
+    @classmethod
+    def create(
+        cls, path: str | os.PathLike[str] | None = None, *, overwrite: bool = False
+    ) -> DriveStore:
+        """Create a database; never unlink an existing database or its WAL."""
+        target = Path(path) if path is not None else None
+        if target is not None:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            if target.exists():
+                raise FileExistsError(target)
+            descriptor = os.open(target, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            os.close(descriptor)
+        connection = cls._connect(target)
+        store = cls(connection, target)
+        try:
+            store._initialize_schema()
+            with store._transaction(write=True) as db:
+                db.execute(
+                    "INSERT INTO nodes(id,parent_id,kind,name,name_key,upload_date) "
+                    "VALUES(?,NULL,'folder','/','/',?)",
+                    (ROOT_ID, _utc_now()),
+                )
+                db.execute(
+                    "INSERT INTO metadata VALUES(1,1,0,?)", (secrets.token_urlsafe(16),)
+                )
+            if target is not None:
+                store._fsync_directory(target.parent)
+            return store
+        except BaseException:
+            connection.close()
+            if target is not None:
+                for candidate in (
+                    target,
+                    Path(str(target) + "-wal"),
+                    Path(str(target) + "-shm"),
+                ):
+                    candidate.unlink(missing_ok=True)
+            raise
+
+    def _initialize_schema(self) -> None:
+        self._db.executescript("""
+            BEGIN IMMEDIATE;
+            CREATE TABLE metadata (
+                singleton INTEGER PRIMARY KEY CHECK(singleton=1),
+                revision INTEGER NOT NULL CHECK(revision>=1),
+                backed_up_revision INTEGER NOT NULL
+                    CHECK(backed_up_revision>=0 AND backed_up_revision<=revision),
+                drive_id TEXT NOT NULL
+            );
+            CREATE TABLE drive_settings (
+                key TEXT PRIMARY KEY, value TEXT NOT NULL
+            );
+            CREATE TABLE nodes (
+                id TEXT PRIMARY KEY,
+                parent_id TEXT REFERENCES nodes(id) ON DELETE CASCADE,
+                kind TEXT NOT NULL CHECK(kind IN ('file','folder')),
+                name TEXT NOT NULL,
+                name_key TEXT NOT NULL,
+                upload_date TEXT NOT NULL,
+                trashed INTEGER NOT NULL DEFAULT 0 CHECK(trashed IN (0,1)),
+                starred INTEGER NOT NULL DEFAULT 0 CHECK(starred IN (0,1)),
+                message_id INTEGER,
+                size INTEGER NOT NULL DEFAULT 0 CHECK(size>=0),
+                part_count INTEGER NOT NULL DEFAULT 1
+                    CHECK(part_count BETWEEN 1 AND 4096),
+                sha256 TEXT CHECK(sha256 IS NULL OR
+                    (length(sha256)=64 AND sha256 NOT GLOB '*[^0-9a-f]*')),
+                CHECK((id='root' AND parent_id IS NULL AND kind='folder'
+                       AND name='/' AND trashed=0)
+                      OR (id!='root' AND parent_id IS NOT NULL)),
+                CHECK((kind='file' AND message_id>0)
+                      OR (kind='folder' AND message_id IS NULL AND size=0))
+            );
+            CREATE INDEX nodes_parent ON nodes(parent_id);
+            CREATE UNIQUE INDEX visible_sibling_name ON nodes(parent_id,name_key)
+                WHERE trashed=0;
+            CREATE TABLE file_parts (
+                node_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+                part_index INTEGER NOT NULL
+                        CHECK(part_index>=0 AND part_index<4096),
+                offset INTEGER NOT NULL CHECK(offset>=0),
+                size INTEGER NOT NULL CHECK(size>0),
+                message_id INTEGER NOT NULL CHECK(message_id>0),
+                sha256 TEXT NOT NULL CHECK(length(sha256)=64
+                    AND sha256 NOT GLOB '*[^0-9a-f]*'),
+                document_id INTEGER CHECK(document_id IS NULL OR document_id!=0),
+                PRIMARY KEY(node_id,part_index), UNIQUE(node_id,message_id)
+            );
+            CREATE TABLE file_operations (
+                operation_id TEXT PRIMARY KEY,
+                node_id TEXT NOT NULL UNIQUE
+            );
+            CREATE TABLE folder_preparations (
+                request_id TEXT PRIMARY KEY,
+                fingerprint TEXT NOT NULL,
+                manifest TEXT NOT NULL,
+                result TEXT NOT NULL,
+                created_at TEXT NOT NULL
+            );
+            CREATE TABLE shares (
+                id TEXT PRIMARY KEY,
+                node_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+                token_hash TEXT NOT NULL UNIQUE,
+                created_at TEXT NOT NULL,
+                expires_at TEXT,
+                label TEXT NOT NULL DEFAULT ''
+            );
+            CREATE INDEX shares_node ON shares(node_id);
+            CREATE TABLE deletion_intents (
+                id TEXT PRIMARY KEY,
+                root_id TEXT NOT NULL,
+                path TEXT NOT NULL,
+                channel_id INTEGER,
+                state TEXT NOT NULL CHECK(state IN ('pending','failed','completed')),
+                created_at TEXT NOT NULL,
+                error TEXT
+            );
+            CREATE UNIQUE INDEX active_deletion_root ON deletion_intents(root_id)
+                WHERE state!='completed';
+            CREATE TABLE deletion_messages (
+                intent_id TEXT NOT NULL REFERENCES deletion_intents(id)
+                    ON DELETE CASCADE,
+                message_id INTEGER NOT NULL CHECK(message_id>0),
+                confirmed INTEGER NOT NULL DEFAULT 0 CHECK(confirmed IN (0,1)),
+                PRIMARY KEY(intent_id,message_id)
+            );
+            CREATE TRIGGER node_parent_is_folder BEFORE INSERT ON nodes
+                WHEN NEW.parent_id IS NOT NULL AND NOT EXISTS(
+                    SELECT 1 FROM nodes WHERE id=NEW.parent_id AND kind='folder')
+                BEGIN SELECT RAISE(ABORT,'parent must be a folder'); END;
+            PRAGMA application_id=1413956694;
+            PRAGMA user_version=6;
+            COMMIT;
+        """)
+
+    @classmethod
+    def load(cls, path: str | os.PathLike[str]) -> DriveStore:
+        """Open a current-schema database without upgrading or replacing state."""
+        target = Path(path)
+        if not target.is_file():
+            raise FileNotFoundError(target)
+        with target.open("rb") as handle:
+            header = handle.read(16)
+        if header != b"SQLite format 3\x00":
+            raise CorruptStoreError("metadata is not a TGDrive SQLite database")
+        connection = None
+        try:
+            connection = cls._connect(target)
+            if (
+                connection.execute("PRAGMA application_id").fetchone()[0]
+                != cls.APPLICATION_ID
+            ):
+                raise CorruptStoreError("database is not a TGDrive database")
+            version = connection.execute("PRAGMA user_version").fetchone()[0]
+            if version != cls.DATABASE_VERSION:
+                raise UnsupportedSchemaError(f"unsupported database schema {version}")
+            if connection.execute("PRAGMA quick_check").fetchone()[0] != "ok":
+                raise CorruptStoreError("SQLite integrity check failed")
+            if connection.execute("PRAGMA foreign_key_check").fetchone() is not None:
+                raise CorruptStoreError("SQLite foreign key validation failed")
+            store = cls(connection, target)
+            for row in connection.execute("SELECT name,name_key FROM nodes"):
+                if row["name_key"] != _name_key(row["name"]):
+                    raise CorruptStoreError("node name index is inconsistent")
+            validated = cls._from_payload(store.export())
+            validated.close()
+            return store
+        except (
+            sqlite3.Error,
+            json.JSONDecodeError,
+            ValidationError,
+            KeyError,
+            TypeError,
+            RecursionError,
+        ) as exc:
+            if connection is not None:
+                connection.close()
+            raise CorruptStoreError(f"metadata validation failed: {exc}") from exc
+        except BaseException:
+            if connection is not None:
+                connection.close()
+            raise
+
+    @classmethod
+    def _validate_payload(cls, payload: object) -> tuple[_FolderNode, dict[str, Any]]:
+        try:
+            if not isinstance(payload, dict):
+                raise ValidationError("top-level metadata must be an object")
+            required = {
+                "backed_up_revision",
+                "revision",
+                "root",
+                "schema_version",
+                "drive_id",
+                "shares",
+            }
+            optional = {
+                "deletions",
+                "operations",
+                "folder_preparations",
+                "storage_channel_id",
+            }
+            if not required <= set(payload) or set(payload) - required - optional:
+                raise ValidationError(
+                    "top-level metadata has missing or unknown fields"
+                )
+            version = payload["schema_version"]
+            if type(version) is not int or version != SCHEMA_VERSION:
+                raise UnsupportedSchemaError(f"unsupported metadata schema {version}")
+            _validate_id(payload["drive_id"])
+            if "storage_channel_id" in payload:
+                _validate_channel_id(payload["storage_channel_id"])
+            revision = _strict_int(payload["revision"], "revision", 1)
+            backed_up = _strict_int(payload["backed_up_revision"], "backed_up_revision")
+            if backed_up > revision:
+                raise ValidationError("backed_up_revision cannot exceed revision")
+            root = _parse_node(payload["root"])
+            if not isinstance(root, _FolderNode):
+                raise ValidationError("root node must be a folder")
+            _validate_tree(root)
+            cls._validate_records(root, payload)
+            return root, payload
+        except UnsupportedSchemaError:
+            raise
+        except (ValidationError, TypeError, RecursionError) as exc:
+            raise CorruptStoreError(f"metadata validation failed: {exc}") from exc
+
+    @classmethod
+    def _validate_records(cls, root: _FolderNode, payload: dict[str, Any]) -> None:
+        """Check recovery records against the tree without opening a database."""
+        nodes, parents, expected_hashes = {}, {}, {}
+        stack = [(root, None)]
+        while stack:
+            node, parent = stack.pop()
+            nodes[node.id], parents[node.id] = node, parent
+            expected_hashes.update((value, node.id) for value in node.share_hashes)
+            if isinstance(node, _FolderNode):
+                stack.extend((child, node.id) for child in node.children.values())
+
+        shares = payload["shares"]
+        if not isinstance(shares, list):
+            raise ValidationError("shares must be a list")
+        actual_hashes, share_ids = {}, set()
+        for raw in shares:
+            share = cls._validate_share_record(raw)
+            if share["id"] in share_ids or share["token_hash"] in actual_hashes:
+                raise ValidationError("duplicate share identity or credential")
+            share_ids.add(share["id"])
+            actual_hashes[share["token_hash"]] = share["node_id"]
+        if actual_hashes != expected_hashes:
+            raise ValidationError("share records do not match node credentials")
+
+        operations = payload.get("operations", [])
+        if not isinstance(operations, list):
+            raise ValidationError("operations must be a list")
+        operation_ids, operation_nodes = set(), set()
+        for operation in operations:
+            if not isinstance(operation, dict) or set(operation) != {
+                "operation_id",
+                "node_id",
+            }:
+                raise ValidationError("invalid file operation")
+            identity = _validate_id(operation["operation_id"])
+            node_id = _validate_id(operation["node_id"])
+            if identity in operation_ids or node_id in operation_nodes:
+                raise ValidationError("duplicate file operation")
+            operation_ids.add(identity)
+            operation_nodes.add(node_id)
+            if node_id in nodes and not isinstance(nodes[node_id], _FileNode):
+                raise ValidationError("file operation must reference a file")
+
+        deletions = payload.get("deletions", [])
+        if not isinstance(deletions, list):
+            raise ValidationError("deletions must be a list")
+        deletion_ids, active_roots = set(), set()
+        for raw in deletions:
+            intent = cls._validate_deletion_record(raw)
+            if intent["id"] in deletion_ids:
+                raise ValidationError("duplicate deletion identity")
+            deletion_ids.add(intent["id"])
+            node = nodes.get(intent["root_id"])
+            if intent["state"] == "completed":
+                if node is not None:
+                    raise ValidationError("completed deletion still has a live root")
+                continue
+            if node is None or not node.trashed or node.id in active_roots:
+                raise ValidationError("invalid active deletion root")
+            active_roots.add(node.id)
+            ancestry, parent = [node.id], parents[node.id]
+            while parent != ROOT_ID:
+                if parent is None or nodes[parent].trashed:
+                    raise ValidationError("deletion root has invalid ancestry")
+                ancestry.append(parent)
+                parent = parents[parent]
+            if "/" + "/".join(reversed(ancestry)) != intent["path"]:
+                raise ValidationError("deletion root has invalid ancestry")
+            messages, pending = set(), [node]
+            while pending:
+                current = pending.pop()
+                if isinstance(current, _FolderNode):
+                    pending.extend(current.children.values())
+                else:
+                    messages.add(current.message_id)
+                    messages.update(part["message_id"] for part in current.parts or [])
+            if messages != set(intent["message_ids"]):
+                raise ValidationError(
+                    "deletion references do not match retained subtree"
+                )
+        for identity in active_roots:
+            parent = parents[identity]
+            while parent is not None:
+                if parent in active_roots:
+                    raise ValidationError("overlapping active deletion roots")
+                parent = parents[parent]
+
+        preparations = payload.get("folder_preparations", [])
+        if not isinstance(preparations, list):
+            raise ValidationError("folder_preparations must be a list")
+        preparation_ids = set()
+        for preparation in preparations:
+            cls._validate_folder_preparation(preparation)
+            if preparation["request_id"] in preparation_ids:
+                raise ValidationError("duplicate folder preparation")
+            preparation_ids.add(preparation["request_id"])
+
+    @classmethod
+    def _from_payload(
+        cls,
+        payload: object,
+        *,
+        storage_path: str | os.PathLike[str] | Path | None = None,
+        persist: bool = False,
+        overwrite: bool = False,
+        revoke_shares: bool = False,
+    ) -> DriveStore:
+        root, data = cls._validate_payload(payload)
+        if persist and storage_path is None:
+            raise ValueError("storage_path is required when persist=True")
+        target = Path(storage_path) if persist and storage_path is not None else None
+        staged = None
+        if target is not None:
+            if target.exists():
+                raise FileExistsError(target)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            staged = target.parent / f".restore-{secrets.token_urlsafe(16)}.sqlite3"
+        store = cls.create(staged)
+        try:
+            with store._transaction(write=True) as db:
+                db.execute("DELETE FROM nodes")
+                expected_hashes: dict[str, str] = {}
+                stack: list[tuple[_Node, str | None]] = [(root, None)]
+                while stack:
+                    node, parent_id = stack.pop()
+                    db.execute(
+                        "INSERT INTO nodes(id,parent_id,kind,name,name_key,upload_date,"
+                        "trashed,message_id,size,part_count,sha256) "
+                        "VALUES(?,?,?,?,?,?,?,?,?,?,?)",
+                        (
+                            node.id,
+                            parent_id,
+                            "file" if isinstance(node, _FileNode) else "folder",
+                            node.name,
+                            _name_key(node.name),
+                            node.upload_date,
+                            int(node.trashed),
+                            node.message_id if isinstance(node, _FileNode) else None,
+                            node.size if isinstance(node, _FileNode) else 0,
+                            len(node.parts)
+                            if isinstance(node, _FileNode) and node.parts
+                            else 1,
+                            node.sha256 if isinstance(node, _FileNode) else None,
+                        ),
+                    )
+                    if node.starred:
+                        db.execute("UPDATE nodes SET starred=1 WHERE id=?", (node.id,))
+                    if isinstance(node, _FileNode) and node.parts:
+                        store._insert_parts(db, node.id, node.parts)
+                    for token_hash in node.share_hashes:
+                        expected_hashes[token_hash] = node.id
+                    if isinstance(node, _FolderNode):
+                        stack.extend(
+                            (child, node.id)
+                            for child in reversed(list(node.children.values()))
+                        )
+                store._import_shares(db, data["shares"], expected_hashes)
+                intents = data.get("deletions", [])
+                if not isinstance(intents, list):
+                    raise ValidationError("deletions must be a list")
+                for intent in intents:
+                    store._import_deletion_locked(db, intent)
+                operations = data.get("operations", [])
+                if not isinstance(operations, list):
+                    raise ValidationError("operations must be a list")
+                for operation in operations:
+                    if not isinstance(operation, dict) or set(operation) != {
+                        "operation_id",
+                        "node_id",
+                    }:
+                        raise ValidationError("invalid file operation")
+                    _validate_id(operation["operation_id"])
+                    node = db.execute(
+                        "SELECT kind FROM nodes WHERE id=?", (operation["node_id"],)
+                    ).fetchone()
+                    _validate_id(operation["node_id"])
+                    if node is not None and node["kind"] != "file":
+                        raise ValidationError("file operation must reference a file")
+                    db.execute(
+                        "INSERT INTO file_operations VALUES(?,?)",
+                        (operation["operation_id"], operation["node_id"]),
+                    )
+                preparations = data.get("folder_preparations", [])
+                if not isinstance(preparations, list):
+                    raise ValidationError("folder_preparations must be a list")
+                for preparation in preparations:
+                    store._import_folder_preparation(db, preparation)
+                if "storage_channel_id" in data:
+                    db.execute(
+                        "INSERT INTO drive_settings VALUES('storage_channel_id',?)",
+                        (str(data["storage_channel_id"]),),
+                    )
+                revision = data["revision"]
+                if revoke_shares:
+                    # Recovery must not resurrect credentials revoked since the
+                    # checkpoint. Validate their records first, then remove them
+                    # inside the import transaction before publishing this file.
+                    removed = db.execute("DELETE FROM shares").rowcount
+                    if removed:
+                        revision = _strict_int(revision + 1, "revision", 1)
+                db.execute(
+                    "UPDATE metadata SET revision=?,backed_up_revision=?,drive_id=?",
+                    (
+                        revision,
+                        data["backed_up_revision"],
+                        data["drive_id"],
+                    ),
+                )
+            if target is not None and staged is not None:
+                # Close checkpoints the WAL before publication. A crash while
+                # importing leaves no valid-looking empty destination database.
+                store.close()
+                descriptor = os.open(staged, os.O_RDONLY)
+                try:
+                    os.fsync(descriptor)
+                finally:
+                    os.close(descriptor)
+                os.link(staged, target)
+                cls._fsync_directory(target.parent)
+                staged.unlink()
+                return cls.load(target)
+            return store
+        except BaseException as exc:
+            store.close()
+            if staged is not None:
+                for candidate in (
+                    staged,
+                    Path(str(staged) + "-wal"),
+                    Path(str(staged) + "-shm"),
+                ):
+                    candidate.unlink(missing_ok=True)
+            if isinstance(exc, (ValidationError, PersistenceError)):
+                raise CorruptStoreError(f"metadata validation failed: {exc}") from exc
+            raise
+
+    @staticmethod
+    def _validate_share_record(share: object) -> dict[str, Any]:
+        if not isinstance(share, dict) or set(share) - {"label"} != {
+            "id",
+            "node_id",
+            "token_hash",
+            "created_at",
+            "expires_at",
+        }:
+            raise ValidationError("invalid share record")
+        _validate_id(share["id"])
+        _validate_id(share["node_id"], allow_root=True)
+        _validate_share_hashes([share["token_hash"]])
+        created = _validate_timestamp(share["created_at"])
+        expiry = (
+            _validate_timestamp(share["expires_at"])
+            if share["expires_at"] is not None
+            else None
+        )
+        if expiry is not None and expiry <= created:
+            raise ValidationError("invalid share expiry")
+        return dict(
+            share,
+            created_at=created,
+            expires_at=expiry,
+            label=_share_label(share.get("label", "")),
+        )
+
+    def _import_shares(
+        self, db: sqlite3.Connection, shares: object, expected_hashes: dict[str, str]
+    ) -> None:
+        if not isinstance(shares, list):
+            raise ValidationError("shares must be a list")
+        actual_hashes = {}
+        for raw in shares:
+            share = self._validate_share_record(raw)
+            if share["token_hash"] in actual_hashes:
+                raise ValidationError("duplicate share hash")
+            actual_hashes[share["token_hash"]] = share["node_id"]
+            db.execute(
+                "INSERT INTO shares VALUES(?,?,?,?,?,?)",
+                (
+                    share["id"],
+                    share["node_id"],
+                    share["token_hash"],
+                    share["created_at"],
+                    share["expires_at"],
+                    share["label"],
+                ),
+            )
+        if actual_hashes != expected_hashes:
+            raise ValidationError("share records do not match node credentials")
+
+    @property
+    def storage_path(self) -> Path | None:
+        return self._storage_path
+
+    @property
+    def database_path(self) -> Path | None:
+        return self._storage_path
+
+    def close(self) -> None:
+        with self._lock:
+            self._finalizer()
+
+    @contextmanager
+    def _transaction(self, *, write: bool = False) -> Iterator[sqlite3.Connection]:
+        with self._lock:
+            nested = bool(self._transaction_writes)
+            if nested and write and not self._transaction_writes[0]:
+                raise PersistenceError("A read transaction cannot become writable")
+            savepoint = None
+            if nested:
+                self._savepoint_serial += 1
+                savepoint = f"tgdrive_{self._savepoint_serial}"
+            entered = False
+            try:
+                self._db.execute(
+                    f"SAVEPOINT {savepoint}"
+                    if nested
+                    else "BEGIN IMMEDIATE"
+                    if write
+                    else "BEGIN"
+                )
+                self._transaction_writes.append(write)
+                entered = True
+                yield self._db
+                if nested:
+                    self._db.execute(f"RELEASE SAVEPOINT {savepoint}")
+                else:
+                    self._db.commit()
+            except BaseException as exc:
+                with suppress(sqlite3.Error):
+                    if nested and entered:
+                        self._db.execute(f"ROLLBACK TO SAVEPOINT {savepoint}")
+                        self._db.execute(f"RELEASE SAVEPOINT {savepoint}")
+                    elif not nested:
+                        self._db.rollback()
+                if isinstance(exc, sqlite3.Error):
+                    raise PersistenceError(f"SQLite transaction failed: {exc}") from exc
+                raise
+            finally:
+                if entered:
+                    self._transaction_writes.pop()
+
+    @contextmanager
+    def metadata_batch(self) -> Iterator[None]:
+        """Group catalog mutations atomically; never await or do remote effects here."""
+        with self._transaction(write=True):
+            yield
+
+    @staticmethod
+    def _bump(db: sqlite3.Connection) -> None:
+        db.execute("UPDATE metadata SET revision=revision+1 WHERE singleton=1")
+
+    @property
+    def drive_id(self) -> str:
+        with self._transaction() as db:
+            return _validate_id(
+                db.execute(
+                    "SELECT drive_id FROM metadata WHERE singleton=1"
+                ).fetchone()[0]
+            )
+
+    @property
+    def storage_channel_id(self) -> int | None:
+        with self._transaction() as db:
+            row = db.execute(
+                "SELECT value FROM drive_settings WHERE key='storage_channel_id'"
+            ).fetchone()
+            if row is None:
+                return None
+            return _validate_channel_id(json.loads(row[0]))
+
+    def bind_storage_channel(self, channel_id: int) -> None:
+        """Bind message IDs to their channel once; never silently rebind them."""
+        channel_id = _validate_channel_id(channel_id)
+        with self._transaction(write=True) as db:
+            row = db.execute(
+                "SELECT value FROM drive_settings WHERE key='storage_channel_id'"
+            ).fetchone()
+            if row is not None:
+                if _validate_channel_id(json.loads(row[0])) != channel_id:
+                    raise ValidationError("drive is bound to another storage channel")
+                return
+            db.execute(
+                "INSERT INTO drive_settings VALUES('storage_channel_id',?)",
+                (str(channel_id),),
+            )
+            self._bump(db)
+
+    def has_file_operation(self, operation_id: str) -> bool:
+        """Include tombstones so cleanup never deletes an already committed upload."""
+        _validate_id(operation_id)
+        with self._transaction() as db:
+            return (
+                db.execute(
+                    "SELECT 1 FROM file_operations WHERE operation_id=?",
+                    (operation_id,),
+                ).fetchone()
+                is not None
+            )
+
+    @property
+    def revision(self) -> int:
+        with self._transaction() as db:
+            return db.execute(
+                "SELECT revision FROM metadata WHERE singleton=1"
+            ).fetchone()[0]
+
+    @property
+    def dirty(self) -> bool:
+        with self._transaction() as db:
+            row = db.execute(
+                "SELECT revision,backed_up_revision FROM metadata WHERE singleton=1"
+            ).fetchone()
+            return row[1] < row[0]
+
+    def _payload_locked(self, db: sqlite3.Connection) -> dict[str, Any]:
+        rows = db.execute("SELECT * FROM nodes ORDER BY rowid").fetchall()
+        if len(rows) > MAX_TREE_ITEMS:
+            raise CorruptStoreError("metadata contains too many nodes")
+        nodes: dict[str, dict[str, Any]] = {}
+        shares = [
+            {key: value for key, value in dict(row).items() if key != "label" or value}
+            for row in db.execute("SELECT * FROM shares ORDER BY rowid")
+        ]
+        parts_by_node: dict[str, list[dict[str, Any]]] = {}
+        for part in db.execute("SELECT * FROM file_parts ORDER BY node_id,part_index"):
+            parts_by_node.setdefault(part["node_id"], []).append(
+                {
+                    "index": part["part_index"],
+                    "offset": part["offset"],
+                    "size": part["size"],
+                    "message_id": part["message_id"],
+                    "sha256": part["sha256"],
+                }
+                | (
+                    {"document_id": part["document_id"]}
+                    if part["document_id"] is not None
+                    else {}
+                )
+            )
+        for row in rows:
+            node = dict(
+                id=row["id"],
+                name=row["name"],
+                upload_date=row["upload_date"],
+                trashed=bool(row["trashed"]),
+                share_hashes=[],
+                type=row["kind"],
+            )
+            if row["starred"]:
+                node["starred"] = True
+            if row["kind"] == "file":
+                node.update(message_id=row["message_id"], size=row["size"])
+                parts = parts_by_node.pop(row["id"], None)
+                if row["part_count"] != (len(parts) if parts else 1):
+                    raise CorruptStoreError("file part count is inconsistent")
+                if parts:
+                    node["parts"] = parts
+                if row["sha256"] is not None:
+                    node["sha256"] = row["sha256"]
+            else:
+                node["children"] = {}
+            nodes[row["id"]] = node
+        if parts_by_node:
+            raise CorruptStoreError("file parts reference a folder or missing file")
+        for share in shares:
+            nodes[share["node_id"]]["share_hashes"].append(share["token_hash"])
+        roots = []
+        for row in rows:
+            if row["parent_id"] is None:
+                roots.append(row["id"])
+            else:
+                nodes[row["parent_id"]]["children"][row["id"]] = nodes[row["id"]]
+        if roots != [ROOT_ID]:
+            raise CorruptStoreError("database must have exactly one root")
+        if len(self._subtree_ids(db, ROOT_ID)) != len(rows):
+            raise CorruptStoreError("database contains unreachable or cyclic nodes")
+        metadata = db.execute("SELECT * FROM metadata WHERE singleton=1").fetchone()
+        if metadata is None:
+            raise CorruptStoreError("database metadata is missing")
+        payload = dict(
+            schema_version=SCHEMA_VERSION,
+            drive_id=_validate_id(metadata["drive_id"]),
+            revision=metadata["revision"],
+            backed_up_revision=metadata["backed_up_revision"],
+            root=nodes[ROOT_ID],
+            shares=shares,
+            operations=[
+                dict(row)
+                for row in db.execute("SELECT * FROM file_operations ORDER BY rowid")
+            ],
+            deletions=[
+                self._deletion_record(db, row)
+                for row in db.execute("SELECT * FROM deletion_intents ORDER BY rowid")
+            ],
+        )
+
+        binding = db.execute(
+            "SELECT value FROM drive_settings WHERE key='storage_channel_id'"
+        ).fetchone()
+        if binding is not None:
+            payload["storage_channel_id"] = _validate_channel_id(json.loads(binding[0]))
+        preparations = [
+            {
+                "request_id": row["request_id"],
+                "fingerprint": row["fingerprint"],
+                "manifest": json.loads(row["manifest"]),
+                "result": json.loads(row["result"]),
+                "created_at": row["created_at"],
+            }
+            for row in db.execute("SELECT * FROM folder_preparations ORDER BY rowid")
+        ]
+        if preparations:
+            payload["folder_preparations"] = preparations
+        return payload
+
+    def statistics(self) -> dict[str, int]:
+        with self._transaction() as db:
+            row = db.execute(
+                "WITH RECURSIVE tree(id,kind,size,hidden) AS ("
+                "SELECT id,kind,size,trashed FROM nodes WHERE id='root' UNION ALL "
+                "SELECT n.id,n.kind,n.size,(n.trashed OR t.hidden) "
+                "FROM nodes n JOIN tree t ON n.parent_id=t.id) "
+                "SELECT COALESCE(SUM(kind='file' AND NOT hidden),0), "
+                "COALESCE(SUM(kind='folder' AND id!='root' AND NOT hidden),0), "
+                "COALESCE(SUM(CASE WHEN kind='file' AND NOT hidden "
+                "THEN size ELSE 0 END),0), "
+                "COALESCE(SUM(kind='file' AND hidden),0), "
+                "COALESCE(SUM(CASE WHEN kind='file' AND hidden "
+                "THEN size ELSE 0 END),0) "
+                "FROM tree"
+            ).fetchone()
+            shares = db.execute("SELECT COUNT(*) FROM shares").fetchone()[0]
+            return dict(
+                zip(
+                    (
+                        "files",
+                        "folders",
+                        "total_bytes",
+                        "trashed_files",
+                        "trashed_bytes",
+                    ),
+                    row,
+                    strict=True,
+                )
+            ) | {"shares": shares}
+
+    def export(self) -> dict[str, Any]:
+        with self._transaction() as db:
+            return self._payload_locked(db)
+
+    @staticmethod
+    def _json_bytes(payload: dict[str, Any]) -> bytes:
+        content = (
+            json.dumps(
+                payload,
+                allow_nan=False,
+                ensure_ascii=False,
+                separators=(",", ":"),
+                sort_keys=True,
+            )
+            + "\n"
+        ).encode("utf-8")
+        if len(content) > MAX_STORE_BYTES:
+            raise PersistenceError("metadata snapshot exceeds the safe size limit")
+        return content
+
+    def snapshot(self) -> tuple[int, bytes]:
+        payload = self.export()
+        return payload["revision"], self._json_bytes(payload)
+
+    def backup_snapshot(self) -> tuple[int, bytes]:
+        payload = self.export()
+        payload["backed_up_revision"] = payload["revision"]
+        return payload["revision"], self._json_bytes(payload)
+
+    def mark_backed_up(self, revision: int) -> bool:
+        with self._transaction(write=True) as db:
+            row = db.execute("SELECT * FROM metadata WHERE singleton=1").fetchone()
+            if type(revision) is not int or not 0 <= revision <= row["revision"]:
+                raise InvalidRevisionError(
+                    f"backup revision must be between 0 and {row['revision']}"
+                )
+            db.execute(
+                "UPDATE metadata SET backed_up_revision=max(backed_up_revision,?)",
+                (revision,),
+            )
+            return max(revision, row["backed_up_revision"]) < row["revision"]
+
+    @staticmethod
+    def _resolve(
+        db: sqlite3.Connection, path: str
+    ) -> tuple[sqlite3.Row, str, list[sqlite3.Row]]:
+        parts, normalized = _normalize_path(path)
+        node = db.execute("SELECT * FROM nodes WHERE id=?", (ROOT_ID,)).fetchone()
+        if node is None:
+            raise CorruptStoreError("root is missing")
+        chain = [node]
+        for part in parts:
+            if node["kind"] != "folder":
+                raise NotDirectoryError(f"path component is not a folder: {node['id']}")
+            node = db.execute(
+                "SELECT * FROM nodes WHERE id=? AND parent_id=?", (part, node["id"])
+            ).fetchone()
+            if node is None:
+                raise NotFoundError(f"item not found: {normalized}")
+            chain.append(node)
+        return node, normalized, chain
+
+    @staticmethod
+    def _visible(chain: list[sqlite3.Row], include_trashed: bool = False) -> None:
+        if not include_trashed and any(row["trashed"] for row in chain):
+            raise TrashedItemError("item or one of its ancestors is trashed")
+
+    @staticmethod
+    def _mutable(
+        db: sqlite3.Connection, chain: list[sqlite3.Row], *, descendants: bool = False
+    ) -> None:
+        DriveStore._demo_mutable(db, chain, descendants=descendants)
+        roots = {
+            row[0]
+            for row in db.execute(
+                "SELECT root_id FROM deletion_intents WHERE state!='completed'"
+            )
+        }
+        if roots.intersection(row["id"] for row in chain) or (
+            descendants
+            and roots.intersection(DriveStore._subtree_ids(db, chain[-1]["id"]))
+        ):
+            raise ValidationError("item is pending permanent deletion")
+
+    @staticmethod
+    def _demo_mutable(db, chain, *, descendants=False):
+        from tgdrive.storage.demo_files import restricted_writes
+
+        if not restricted_writes.get():
+            return
+        check_ids(row["id"] for row in chain)
+        if descendants:
+            check_ids(DriveStore._subtree_ids(db, chain[-1]["id"]))
+
+    @staticmethod
+    def _record(
+        row: sqlite3.Row, full_path: str, *, message: bool = False
+    ) -> dict[str, Any]:
+        result = dict(
+            id=row["id"],
+            name=row["name"],
+            path=_parent_path(full_path),
+            size=row["size"],
+            type=row["kind"],
+            upload_date=row["upload_date"],
+        )
+        if "starred" in row.keys() and row["starred"]:  # noqa: SIM118 - sqlite Row membership checks values
+            result["starred"] = True
+        if row["kind"] == "file":
+            result["part_count"] = row["part_count"]
+        if message:
+            result["message_id"] = row["message_id"]
+            if row["sha256"] is not None:
+                result["sha256"] = row["sha256"]
+        return result
+
+    @classmethod
+    def _file_record(
+        cls, db: sqlite3.Connection, row: sqlite3.Row, path: str
+    ) -> dict[str, Any]:
+        result = cls._record(row, path, message=True)
+        parts = [
+            {
+                "index": item["part_index"],
+                "offset": item["offset"],
+                "size": item["size"],
+                "message_id": item["message_id"],
+                "sha256": item["sha256"],
+            }
+            | (
+                {"document_id": item["document_id"]}
+                if item["document_id"] is not None
+                else {}
+            )
+            for item in db.execute(
+                "SELECT * FROM file_parts WHERE node_id=? ORDER BY part_index",
+                (row["id"],),
+            )
+        ]
+        if parts:
+            result["parts"] = parts
+        return result
+
+    @staticmethod
+    def _insert_parts(
+        db: sqlite3.Connection, item_id: str, parts: list[dict[str, Any]]
+    ) -> None:
+        db.executemany(
+            "INSERT INTO file_parts(node_id,part_index,offset,size,message_id,"
+            "sha256,document_id) "
+            "VALUES(?,?,?,?,?,?,?)",
+            (
+                (
+                    item_id,
+                    part["index"],
+                    part["offset"],
+                    part["size"],
+                    part["message_id"],
+                    part["sha256"],
+                    part.get("document_id"),
+                )
+                for part in parts
+            ),
+        )
+
+    @staticmethod
+    def _path_for_id(db: sqlite3.Connection, item_id: str) -> str:
+        parts = []
+        visited = set()
+        while item_id != ROOT_ID:
+            if item_id in visited or len(parts) > MAX_TREE_DEPTH:
+                raise CorruptStoreError("invalid node ancestry")
+            visited.add(item_id)
+            row = db.execute(
+                "SELECT id,parent_id FROM nodes WHERE id=?", (item_id,)
+            ).fetchone()
+            if row is None:
+                raise NotFoundError("item does not exist")
+            parts.append(row["id"])
+            item_id = row["parent_id"]
+        return "/" + "/".join(reversed(parts))
+
+    def resolve_id(self, item_id: str) -> str:
+        _validate_id(item_id, allow_root=True)
+        with self._transaction() as db:
+            return self._path_for_id(db, item_id)
+
+    def transfer_location(self, operation_id, destination="/", *, completed=False):
+        """Resolve an upload's exact current item, never a same-named sibling."""
+        if operation_id is not None:
+            _validate_id(operation_id)
+        with self._transaction() as db:
+            operation = (
+                db.execute(
+                    "SELECT node_id FROM file_operations WHERE operation_id=?",
+                    (operation_id,),
+                ).fetchone()
+                if operation_id is not None
+                else None
+            )
+            if operation is not None:
+                path = self._path_for_id(db, operation["node_id"])
+            elif completed:
+                raise NotFoundError("Uploaded item is unavailable")
+            else:
+                parts, _ = _normalize_path(destination)
+                path = self._path_for_id(db, parts[-1] if parts else ROOT_ID)
+            node, path, chain = self._resolve(db, path)
+            self._visible(chain)
+            from tgdrive.transfers.transfer_locations import location_record
+
+            return location_record(node, path, chain, stored=operation is not None)
+
+    def upload_destination(
+        self,
+        path: str,
+        *,
+        directory_id: str | None = None,
+    ) -> dict[str, str]:
+        """Bind a writable folder by its current path or a persisted identity."""
+        with self._transaction() as db:
+            if directory_id is not None:
+                _validate_id(directory_id, allow_root=True)
+                path = self._path_for_id(db, directory_id)
+            node, path, chain = self._resolve(db, path)
+            if node["kind"] != "folder":
+                raise NotDirectoryError("upload destination must be a folder")
+            self._visible(chain)
+            self._mutable(db, chain)
+            return {"id": node["id"], "path": path}
+
+    @staticmethod
+    def _subtree_ids(db: sqlite3.Connection, root_id: str) -> list[str]:
+        return [
+            row[0]
+            for row in db.execute(
+                "WITH RECURSIVE subtree(id) AS (SELECT id FROM nodes WHERE id=? "
+                "UNION SELECT nodes.id FROM nodes JOIN subtree ON "
+                "nodes.parent_id=subtree.id) "
+                "SELECT id FROM subtree",
+                (root_id,),
+            )
+        ]
+
+    @staticmethod
+    def _unique(
+        db: sqlite3.Connection, parent_id: str, name: str, exclude_id: str = ""
+    ) -> bool:
+        return (
+            db.execute(
+                "SELECT 1 FROM nodes WHERE parent_id=? AND name_key=? AND id!=? AND "
+                "trashed=0",
+                (parent_id, _name_key(name), exclude_id),
+            ).fetchone()
+            is None
+        )
+
+    def _available_name(
+        self,
+        db: sqlite3.Connection,
+        parent_id: str,
+        name: str,
+        *,
+        kind: str,
+        exclude_id: str = "",
+    ) -> str:
+        if self._unique(db, parent_id, name, exclude_id):
+            return name
+        suffix = Path(name).suffix if kind == "file" else ""
+        stem = name[: -len(suffix)] if suffix else name
+        index = 1
+        while True:
+            label = f" ({index})"
+            ending = suffix[: MAX_NAME_LENGTH - len(label) - 1]
+            candidate = (
+                stem[: MAX_NAME_LENGTH - len(label) - len(ending)] + label + ending
+            )
+            if self._unique(db, parent_id, candidate, exclude_id):
+                return candidate
+            index += 1
+
+    def _ensure_unique(
+        self, db: sqlite3.Connection, parent_id: str, name: str, exclude_id: str = ""
+    ) -> None:
+        if not self._unique(db, parent_id, name, exclude_id):
+            raise DuplicateNameError(
+                f"an item named '{name}' already exists in this folder"
+            )
+
+    def _children(
+        self, db: sqlite3.Connection, node_id: str, path: str, include_trashed: bool
+    ) -> dict[str, dict[str, Any]]:
+        return {
+            row["id"]: self._record(row, _join_path(path, row["id"]))
+            for row in db.execute(
+                "SELECT * FROM nodes WHERE parent_id=? ORDER BY rowid", (node_id,)
+            )
+            if include_trashed or not row["trashed"]
+        }
+
+    def get_directory(
+        self, path: str, *, include_trashed: bool = False
+    ) -> dict[str, Any]:
+        with self._transaction() as db:
+            node, normalized, chain = self._resolve(db, path)
+            if node["kind"] != "folder":
+                raise NotDirectoryError(f"not a directory: {normalized}")
+            self._visible(chain, include_trashed)
+            result = self._record(node, normalized)
+            result["contents"] = self._children(
+                db, node["id"], normalized, include_trashed
+            )
+            return result
+
+    def list_directory(
+        self, path: str, *, include_trashed: bool = False
+    ) -> dict[str, dict[str, Any]]:
+        return self.get_directory(path, include_trashed=include_trashed)["contents"]
+
+    def get_file(self, path: str, *, include_trashed: bool = False) -> dict[str, Any]:
+        with self._transaction() as db:
+            node, normalized, chain = self._resolve(db, path)
+            if node["kind"] != "file":
+                raise NotFileError(f"not a file: {normalized}")
+            self._visible(chain, include_trashed)
+            return self._file_record(db, node, normalized)
+
+    def _add(
+        self,
+        parent_path: str,
+        name: str,
+        message_id: int | None,
+        size: int = 0,
+        operation_id: str | None = None,
+        keep_both: bool = False,
+        parts: list[dict[str, Any]] | None = None,
+        sha256: str | None = None,
+    ) -> dict[str, Any]:
+        name = _normalize_name(name)
+        if operation_id is not None:
+            _validate_id(operation_id)
+        with self._transaction(write=True) as db:
+            if operation_id is not None:
+                committed = db.execute(
+                    "SELECT node_id FROM file_operations WHERE operation_id=?",
+                    (operation_id,),
+                ).fetchone()
+                if (
+                    committed is not None
+                    and db.execute(
+                        "SELECT 1 FROM nodes WHERE id=?", (committed["node_id"],)
+                    ).fetchone()
+                    is None
+                ):
+                    raise ValidationError(
+                        "operation_id was completed and its file was deleted"
+                    )
+                existing = db.execute(
+                    "SELECT nodes.* FROM nodes JOIN file_operations ON "
+                    "nodes.id=file_operations.node_id WHERE operation_id=?",
+                    (operation_id,),
+                ).fetchone()
+                if existing is not None:
+                    if existing["message_id"] != message_id or existing["size"] != size:
+                        raise ValidationError(
+                            "operation_id already committed different media"
+                        )
+                    result = self._file_record(
+                        db, existing, self._path_for_id(db, existing["id"])
+                    )
+                    if result.get("parts") != parts or result.get("sha256") != sha256:
+                        raise ValidationError(
+                            "operation_id already committed different file parts"
+                        )
+                    return result
+            parent, parent_path, chain = self._resolve(db, parent_path)
+            if parent["kind"] != "folder":
+                raise NotDirectoryError("destination must be a folder")
+            self._visible(chain)
+            self._mutable(db, chain)
+            if len(chain) > MAX_TREE_DEPTH:
+                raise ValidationError("maximum tree depth exceeded")
+            if db.execute("SELECT count(*) FROM nodes").fetchone()[0] >= MAX_TREE_ITEMS:
+                raise ValidationError("maximum item count exceeded")
+            if keep_both:
+                name = self._available_name(
+                    db,
+                    parent["id"],
+                    name,
+                    kind="file" if message_id is not None else "folder",
+                )
+            else:
+                self._ensure_unique(db, parent["id"], name)
+            item_id = secrets.token_urlsafe(16)
+            db.execute(
+                "INSERT INTO "
+                "nodes(id,parent_id,kind,name,name_key,upload_date,message_id,"
+                "size,part_count,sha256) "
+                "VALUES(?,?,?,?,?,?,?,?,?,?)",
+                (
+                    item_id,
+                    parent["id"],
+                    "folder" if message_id is None else "file",
+                    name,
+                    _name_key(name),
+                    _utc_now(),
+                    message_id,
+                    size,
+                    len(parts) if parts else 1,
+                    sha256,
+                ),
+            )
+            if parts:
+                self._insert_parts(db, item_id, parts)
+            if operation_id is not None:
+                db.execute(
+                    "INSERT INTO file_operations VALUES(?,?)", (operation_id, item_id)
+                )
+            self._bump(db)
+            row = db.execute("SELECT * FROM nodes WHERE id=?", (item_id,)).fetchone()
+            full_path = _join_path(parent_path, item_id)
+            return (
+                self._file_record(db, row, full_path)
+                if message_id is not None
+                else self._record(row, full_path)
+            )
+
+    @staticmethod
+    def _validate_folder_preparation(record: object) -> dict[str, Any]:
+        if not isinstance(record, dict) or set(record) != {
+            "request_id",
+            "fingerprint",
+            "manifest",
+            "result",
+            "created_at",
+        }:
+            raise ValidationError("invalid folder preparation")
+        request_id = _validate_id(record["request_id"])
+        if len(request_id) < 16:
+            raise ValidationError(
+                "folder request id must contain at least 16 characters"
+            )
+        manifest = record["manifest"]
+        if not isinstance(manifest, dict) or set(manifest) != {
+            "destination",
+            "root_name",
+            "folders",
+        }:
+            raise ValidationError("invalid folder preparation manifest")
+        normalized = _folder_manifest(**manifest)
+        if normalized != manifest:
+            raise ValidationError("folder preparation manifest is not canonical")
+        encoded = _manifest_json(normalized)
+        fingerprint = hashlib.sha256(encoded.encode()).hexdigest()
+        if record["fingerprint"] != fingerprint:
+            raise ValidationError("folder preparation fingerprint does not match")
+        result = record["result"]
+        if not isinstance(result, dict) or set(result) != {"root", "folders"}:
+            raise ValidationError("invalid folder preparation result")
+        root = result["root"]
+        if not isinstance(root, dict) or set(root) != {
+            "id",
+            "name",
+            "path",
+            "size",
+            "type",
+            "upload_date",
+        }:
+            raise ValidationError("invalid prepared root")
+        _validate_id(root["id"])
+        if (
+            _normalize_name(root["name"]) != root["name"]
+            or root["path"] != normalized["destination"]
+            or type(root["size"]) is not int
+            or root["size"] != 0
+            or root["type"] != "folder"
+        ):
+            raise ValidationError("invalid prepared root fields")
+        _validate_timestamp(root["upload_date"])
+        mapping = result["folders"]
+        expected = {"", *("/".join(path) for path in normalized["folders"])}
+        if not isinstance(mapping, dict) or set(mapping) != expected:
+            raise ValidationError("prepared folder map does not match manifest")
+        if mapping[""] != _join_path(root["path"], root["id"]):
+            raise ValidationError("prepared root path does not match")
+        ids = {root["id"]}
+        for segments in normalized["folders"]:
+            relative = "/".join(segments)
+            parts, full_path = _normalize_path(mapping[relative])
+            parent = mapping["/".join(segments[:-1])]
+            if (
+                not parts
+                or full_path != mapping[relative]
+                or full_path != _join_path(parent, parts[-1])
+                or parts[-1] in ids
+            ):
+                raise ValidationError("invalid prepared folder ancestry")
+            ids.add(parts[-1])
+        _validate_timestamp(record["created_at"])
+        return record
+
+    @staticmethod
+    def _import_folder_preparation(db: sqlite3.Connection, record: object) -> None:
+        record = DriveStore._validate_folder_preparation(record)
+        db.execute(
+            "INSERT INTO folder_preparations VALUES(?,?,?,?,?)",
+            (
+                record["request_id"],
+                record["fingerprint"],
+                _manifest_json(record["manifest"]),
+                _manifest_json(record["result"]),
+                _validate_timestamp(record["created_at"]),
+            ),
+        )
+
+    def prepare_folder_tree(
+        self,
+        destination: str,
+        root_name: str,
+        folders: list[list[str]],
+        client_request_id: str,
+    ) -> dict[str, Any]:
+        """Prepare a fresh tree atomically and retain its safe retry result."""
+        manifest = _folder_manifest(destination, root_name, folders)
+        request_id = _validate_id(client_request_id)
+        if len(request_id) < 16:
+            raise ValidationError(
+                "folder request id must contain at least 16 characters"
+            )
+        encoded = _manifest_json(manifest)
+        fingerprint = hashlib.sha256(encoded.encode()).hexdigest()
+        destination = manifest["destination"]
+        folders = manifest["folders"]
+        with self._transaction(write=True) as db:
+            prior = db.execute(
+                "SELECT fingerprint,result FROM folder_preparations WHERE request_id=?",
+                (request_id,),
+            ).fetchone()
+            if prior is not None:
+                if not hmac.compare_digest(prior["fingerprint"], fingerprint):
+                    raise FolderTreeConflictError(
+                        "This folder request id already prepared a different tree"
+                    )
+                result = json.loads(prior["result"])
+                try:
+                    for relative, path in result["folders"].items():
+                        node, _, chain = self._resolve(db, path)
+                        self._visible(chain)
+                        self._mutable(db, chain)
+                        name = (
+                            relative.rsplit("/", 1)[-1]
+                            if relative
+                            else result["root"]["name"]
+                        )
+                        if node["kind"] != "folder" or node["name"] != name:
+                            raise ValidationError("prepared folder changed")
+                except (
+                    NotFoundError,
+                    NotDirectoryError,
+                    ValidationError,
+                    TrashedItemError,
+                ) as exc:
+                    raise FolderTreeConflictError(
+                        "The prepared folder tree changed. "
+                        "Review it before starting again"
+                    ) from exc
+                return result
+            parent, destination, chain = self._resolve(db, destination)
+            if parent["kind"] != "folder":
+                raise NotDirectoryError("destination must be a folder")
+            self._visible(chain)
+            self._mutable(db, chain)
+            count = 1 + len(folders)
+            depth = 1 + max((len(path) for path in folders), default=0)
+            if len(chain) - 1 + depth > MAX_TREE_DEPTH:
+                raise ValidationError("maximum tree depth exceeded")
+            if (
+                db.execute("SELECT count(*) FROM nodes").fetchone()[0] + count
+                > MAX_TREE_ITEMS
+            ):
+                raise ValidationError("maximum item count exceeded")
+            root_name = self._available_name(
+                db, parent["id"], manifest["root_name"], kind="folder"
+            )
+            created = _utc_now()
+            mapping: dict[str, str] = {}
+            root: dict[str, Any] | None = None
+            for segments in [[], *folders]:
+                relative = "/".join(segments)
+                parent_path = (
+                    mapping["/".join(segments[:-1])] if segments else destination
+                )
+                parent_id = (
+                    parent_path.rsplit("/", 1)[-1] if parent_path != "/" else ROOT_ID
+                )
+                name = segments[-1] if segments else root_name
+                item_id = secrets.token_urlsafe(16)
+                db.execute(
+                    "INSERT INTO nodes(id,parent_id,kind,name,name_key,upload_date) "
+                    "VALUES(?,?,'folder',?,?,?)",
+                    (item_id, parent_id, name, _name_key(name), created),
+                )
+                path = _join_path(parent_path, item_id)
+                mapping[relative] = path
+                if not segments:
+                    node = db.execute(
+                        "SELECT * FROM nodes WHERE id=?", (item_id,)
+                    ).fetchone()
+                    root = self._record(node, path)
+            result = {"root": root, "folders": mapping}
+            self._import_folder_preparation(
+                db,
+                {
+                    "request_id": request_id,
+                    "fingerprint": fingerprint,
+                    "manifest": manifest,
+                    "result": result,
+                    "created_at": created,
+                },
+            )
+            self._bump(db)
+            return result
+
+    def create_folder(self, parent_path: str, name: str) -> dict[str, Any]:
+        return self._add(parent_path, name, None)
+
+    def ensure_demo_files(self) -> dict[str, Any]:
+        """Create the reserved demo folder once; preserve its stable identity."""
+        with self._transaction(write=True) as db:
+            node = db.execute(
+                "SELECT * FROM nodes WHERE id=?", (DEMO_FILES_ID,)
+            ).fetchone()
+            if node is not None:
+                if node["kind"] != "folder":
+                    raise ValidationError(
+                        "The reserved Demo Files identity is not a folder"
+                    )
+                return self._record(node, self._path_for_id(db, DEMO_FILES_ID))
+            if not self._unique(db, ROOT_ID, DEMO_FILES_NAME):
+                raise DuplicateNameError(
+                    "A different item named Demo Files already exists. "
+                    "Disable demo mode and rename that item before enabling it again."
+                )
+            self._mutable(db, self._resolve(db, "/")[2])
+            if db.execute("SELECT count(*) FROM nodes").fetchone()[0] >= MAX_TREE_ITEMS:
+                raise ValidationError("maximum item count exceeded")
+            db.execute(
+                "INSERT INTO nodes(id,parent_id,kind,name,name_key,upload_date) "
+                "VALUES(?,?,?,?,?,?)",
+                (
+                    DEMO_FILES_ID,
+                    ROOT_ID,
+                    "folder",
+                    DEMO_FILES_NAME,
+                    _name_key(DEMO_FILES_NAME),
+                    _utc_now(),
+                ),
+            )
+            self._bump(db)
+            return self._record(
+                db.execute(
+                    "SELECT * FROM nodes WHERE id=?", (DEMO_FILES_ID,)
+                ).fetchone(),
+                "/" + DEMO_FILES_ID,
+            )
+
+    def add_file(
+        self,
+        parent_path: str,
+        name: str,
+        message_id: int,
+        size: int,
+        *,
+        operation_id: str | None = None,
+        keep_both: bool = False,
+        parts: list[dict[str, Any]] | None = None,
+        sha256: str | None = None,
+    ) -> dict[str, Any]:
+        if type(keep_both) is not bool:
+            raise ValidationError("keep_both must be a boolean")
+        message_id = _strict_int(message_id, "message_id", 1)
+        size = _strict_int(size, "size")
+        sha256 = validate_sha256(sha256)
+        if parts is not None:
+            parts = validate_parts(parts, size=size, message_id=message_id)
+        return self._add(
+            parent_path,
+            name,
+            message_id,
+            size,
+            operation_id,
+            keep_both,
+            parts,
+            sha256,
+        )
+
+    def rename(self, path: str, new_name: str) -> dict[str, Any]:
+        name = _normalize_name(new_name)
+        with self._transaction(write=True) as db:
+            node, path, chain = self._resolve(db, path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the root folder cannot be renamed")
+            self._demo_mutable(db, chain, descendants=True)
+            self._mutable(db, chain)
+            if node["kind"] == "file":
+                _validate_file_rename(node["name"], name)
+            self._ensure_unique(db, node["parent_id"], name, node["id"])
+            if node["name"] != name:
+                db.execute(
+                    "UPDATE nodes SET name=?,name_key=? WHERE id=?",
+                    (name, _name_key(name), node["id"]),
+                )
+                self._bump(db)
+            return self._record(
+                db.execute("SELECT * FROM nodes WHERE id=?", (node["id"],)).fetchone(),
+                path,
+            )
+
+    def set_trashed_many(self, paths: list[str], trashed: bool) -> list[dict[str, Any]]:
+        with self.metadata_batch():
+            return [self.set_trashed(path, trashed) for path in paths]
+
+    def set_trashed(self, path: str, trashed: bool) -> dict[str, Any]:
+        if type(trashed) is not bool:
+            raise ValidationError("trashed must be a boolean")
+        with self._transaction(write=True) as db:
+            node, path, chain = self._resolve(db, path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the root folder cannot be trashed")
+            self._mutable(db, chain, descendants=True)
+            if not trashed:
+                self._visible(chain[:-1])
+            if bool(node["trashed"]) != trashed:
+                name = (
+                    node["name"]
+                    if trashed
+                    else self._available_name(
+                        db,
+                        node["parent_id"],
+                        node["name"],
+                        kind=node["kind"],
+                        exclude_id=node["id"],
+                    )
+                )
+                db.execute(
+                    "UPDATE nodes SET trashed=?,name=?,name_key=? WHERE id=?",
+                    (int(trashed), name, _name_key(name), node["id"]),
+                )
+                if trashed:
+                    self._revoke_subtree(db, node["id"])
+                self._bump(db)
+            updated = db.execute(
+                "SELECT * FROM nodes WHERE id=?", (node["id"],)
+            ).fetchone()
+            return self._record(updated, path)
+
+    def list_trash(self, query: str = "") -> dict[str, dict[str, Any]]:
+        with self._transaction() as db:
+            result = {}
+            for row in db.execute("SELECT * FROM nodes WHERE trashed=1 ORDER BY rowid"):
+                if query.casefold() not in row["name"].casefold():
+                    continue
+                path = self._path_for_id(db, row["id"])
+                _, _, chain = self._resolve(db, path)
+                if not any(item["trashed"] for item in chain[:-1]):
+                    result[row["id"]] = self._record(row, path) | {
+                        "parent_names": [item["name"] for item in chain[1:-1]]
+                    }
+            return result
+
+    def set_starred(self, path: str, starred: bool) -> dict[str, Any]:
+        if type(starred) is not bool:
+            raise ValidationError("starred must be a boolean")
+        with self._transaction(write=True) as db:
+            node, path, chain = self._resolve(db, path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the drive root cannot be starred")
+            self._mutable(db, chain)
+            self._visible(chain)
+            if bool(node["starred"]) != starred:
+                db.execute(
+                    "UPDATE nodes SET starred=? WHERE id=?", (int(starred), node["id"])
+                )
+                self._bump(db)
+            row = db.execute("SELECT * FROM nodes WHERE id=?", (node["id"],)).fetchone()
+            return self._record(row, path)
+
+    def list_starred(self, query: str = "") -> dict[str, dict[str, Any]]:
+        if not isinstance(query, str) or len(query) > MAX_NAME_LENGTH:
+            raise ValidationError("invalid starred search")
+        with self._transaction() as db:
+            rows = db.execute(
+                "WITH RECURSIVE visible(id,full_path,parent_names) AS ("
+                "SELECT id,'','[]' FROM nodes WHERE id='root' UNION ALL "
+                "SELECT n.id,v.full_path||'/'||n.id,CASE WHEN v.id='root' THEN '[]' "
+                "ELSE json_insert(v.parent_names,'$[#]',p.name) END "
+                "FROM nodes n JOIN visible v ON n.parent_id=v.id "
+                "JOIN nodes p ON p.id=v.id WHERE n.trashed=0) "
+                "SELECT n.*,v.full_path,v.parent_names FROM visible v "
+                "JOIN nodes n ON n.id=v.id WHERE n.id!='root' AND n.starred=1 "
+                "AND instr(n.name_key,?)>0 ORDER BY n.name_key,n.id",
+                (_name_key(query.strip()),),
+            ).fetchall()
+            return {
+                row["id"]: self._record(row, row["full_path"])
+                | {"parent_names": json.loads(row["parent_names"])}
+                for row in rows
+            }
+
+    def search(
+        self, query: str, *, include_trashed: bool = False
+    ) -> dict[str, dict[str, Any]]:
+        """Compatibility lookup: at most 500 literal filename matches."""
+        page = self.search_page(
+            query, include_trashed=include_trashed, limit=MAX_SEARCH_RESULTS
+        )
+        return {row["id"]: row for row in page["items"]}
+
+    def search_page(
+        self,
+        query: str,
+        *,
+        offset: int = 0,
+        limit: int = 100,
+        sort: str = "name",
+        order: str | None = None,
+        include_trashed: bool = False,
+    ) -> dict[str, Any]:
+        """Search one consistent snapshot without per-result ancestry queries.
+
+        ``instr`` treats SQL wildcard and quote characters literally. Names and
+        the query use the same NFC/casefold key. The recursive walk removes an
+        entire trashed subtree before matching or pagination, and builds human
+        parent names alongside the opaque ID path in the same query.
+        """
+        if not isinstance(query, str):
+            raise ValidationError("search query must be a string")
+        query = unicodedata.normalize("NFC", query).strip()
+        if (
+            not query
+            or len(query) > MAX_NAME_LENGTH
+            or any(unicodedata.category(c) in {"Cc", "Cs"} for c in query)
+        ):
+            raise ValidationError(
+                "search query is empty, too long, or contains forbidden characters"
+            )
+        if (
+            type(offset) is not int
+            or not 0 <= offset <= MAX_SEARCH_OFFSET
+            or type(limit) is not int
+            or not 1 <= limit <= MAX_SEARCH_RESULTS
+            or type(include_trashed) is not bool
+            or sort not in {"name", "date", "size"}
+            or (
+                order is not None
+                and (not isinstance(order, str) or order not in {"asc", "desc"})
+            )
+        ):
+            raise ValidationError("invalid search pagination or sort")
+        # Secondary name/ID keys remain ascending so equal dates and sizes
+        # paginate deterministically in either primary direction.
+        direction = order or ("asc" if sort == "name" else "desc")
+        with self._transaction() as db:
+            rows = db.execute(
+                "WITH RECURSIVE visible(id,name,full_path,parent_names) AS ("
+                "SELECT id,name,'','[]' FROM nodes WHERE id='root' UNION ALL "
+                "SELECT n.id,n.name,v.full_path||'/'||n.id,"
+                "CASE WHEN v.id='root' THEN '[]' ELSE "
+                "json_insert(v.parent_names,'$[#]',v.name) END "
+                "FROM nodes n JOIN visible v ON n.parent_id=v.id "
+                "WHERE (? OR n.trashed=0)) "
+                "SELECT n.*,v.full_path,v.parent_names FROM visible v "
+                "JOIN nodes n ON n.id=v.id WHERE n.id!='root' "
+                "AND instr(n.name_key,?)>0 ORDER BY (n.kind='folder') DESC,"
+                "CASE WHEN ?='asc' THEN CASE ? "
+                "WHEN 'name' THEN n.name_key WHEN 'date' THEN n.upload_date "
+                "ELSE n.size END END ASC,"
+                "CASE WHEN ?='desc' THEN CASE ? "
+                "WHEN 'name' THEN n.name_key WHEN 'date' THEN n.upload_date "
+                "ELSE n.size END END DESC,"
+                "n.name_key,n.id LIMIT ? OFFSET ?",
+                (
+                    int(include_trashed),
+                    query.casefold(),
+                    direction,
+                    sort,
+                    direction,
+                    sort,
+                    limit + 1,
+                    offset,
+                ),
+            ).fetchall()
+            items = [
+                self._record(row, row["full_path"])
+                | {"parent_names": json.loads(row["parent_names"])}
+                for row in rows[:limit]
+            ]
+        has_more = len(rows) > limit
+        return {
+            "items": items,
+            "query": query,
+            "has_more": has_more,
+            "next_offset": offset + len(items) if has_more else None,
+        }
+
+    def message_ids(self, path: str, *, include_trashed: bool = False) -> list[int]:
+        with self._transaction() as db:
+            node, _, chain = self._resolve(db, path)
+            self._visible(chain, include_trashed)
+            return self._messages(db, node["id"])
+
+    @staticmethod
+    def _messages(db: sqlite3.Connection, node_id: str) -> list[int]:
+        return [
+            row[0]
+            for row in db.execute(
+                "WITH RECURSIVE subtree(id) AS (SELECT id FROM nodes WHERE id=? "
+                "UNION SELECT nodes.id FROM nodes JOIN subtree ON "
+                "nodes.parent_id=subtree.id) "
+                "SELECT message_id FROM nodes JOIN subtree USING(id) WHERE kind='file' "
+                "UNION SELECT p.message_id FROM file_parts p "
+                "JOIN subtree s ON p.node_id=s.id "
+                "ORDER BY message_id",
+                (node_id,),
+            )
+        ]
+
+    def delete(self, path: str) -> list[int]:
+        """Remove empty metadata only; files require a durable deletion intent."""
+        with self._transaction(write=True) as db:
+            node, _, chain = self._resolve(db, path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the root folder cannot be deleted")
+            self._mutable(db, chain, descendants=True)
+            if self._messages(db, node["id"]):
+                raise ValidationError("files require a permanent deletion intent")
+            db.execute("DELETE FROM nodes WHERE id=?", (node["id"],))
+            self._bump(db)
+            return []
+
+    def move_many(
+        self, paths: list[str], destination: str, *, conflict: str = "keep_both"
+    ) -> list[dict[str, Any] | None]:
+        with self.metadata_batch():
+            return [self.move(path, destination, conflict=conflict) for path in paths]
+
+    def move(
+        self, path: str, destination: str, *, conflict: str = "keep_both"
+    ) -> dict[str, Any] | None:
+        if conflict not in {"keep_both", "skip"}:
+            raise ValidationError("conflict must be 'keep_both' or 'skip'")
+        with self._transaction(write=True) as db:
+            node, path, chain = self._resolve(db, path)
+            parent, destination, parent_chain = self._resolve(db, destination)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the root folder cannot be moved")
+            if parent["kind"] != "folder":
+                raise NotDirectoryError("destination must be a folder")
+            self._visible(chain)
+            self._visible(parent_chain)
+            self._mutable(db, chain, descendants=True)
+            self._mutable(db, parent_chain)
+            if node["id"] in {item["id"] for item in parent_chain}:
+                raise InvalidPathError("a folder cannot be moved into its own subtree")
+            if node["parent_id"] == parent["id"]:
+                return self._record(node, path)
+            descendants = self._subtree_ids(db, node["id"])
+            for item_id in descendants:
+                relative_depth = len(self._path_for_id(db, item_id).split("/")) - len(
+                    path.split("/")
+                )
+                if len(parent_chain) + relative_depth > MAX_TREE_DEPTH:
+                    raise ValidationError("move would exceed maximum tree depth")
+            name = node["name"]
+            if not self._unique(db, parent["id"], name):
+                if conflict == "skip":
+                    return None
+                name = self._available_name(db, parent["id"], name, kind=node["kind"])
+            db.execute(
+                "UPDATE nodes SET parent_id=?,name=?,name_key=? WHERE id=?",
+                (parent["id"], name, _name_key(name), node["id"]),
+            )
+            self._bump(db)
+            moved = db.execute(
+                "SELECT * FROM nodes WHERE id=?", (node["id"],)
+            ).fetchone()
+            return self._record(moved, _join_path(destination, node["id"]))
+
+    @staticmethod
+    def _default_share_expiry() -> str:
+        return (
+            (datetime.now(UTC) + timedelta(days=7))
+            .isoformat(timespec="seconds")
+            .replace("+00:00", "Z")
+        )
+
+    def create_share(
+        self,
+        path: str,
+        *,
+        expires_at: object = _DEFAULT_EXPIRY,
+        token_factory=None,
+        label: str = "",
+        replace_existing: bool = False,
+    ) -> str:
+        if expires_at is self._DEFAULT_EXPIRY:
+            expiry = self._default_share_expiry()
+        else:
+            expiry = _validate_timestamp(expires_at) if expires_at is not None else None
+        label = _share_label(label)
+        created = _utc_now()
+        if expiry is not None and expiry <= created:
+            raise ValidationError("share expiry must be in the future")
+        with self._transaction(write=True) as db:
+            node, _, chain = self._resolve(db, path)
+            self._visible(chain)
+            self._demo_mutable(db, chain, descendants=True)
+            self._mutable(db, chain)
+            identity = secrets.token_urlsafe(16)
+            token = (
+                token_factory(identity) if token_factory else secrets.token_urlsafe(32)
+            )
+            if replace_existing:
+                db.execute("DELETE FROM shares WHERE node_id=?", (node["id"],))
+            if (
+                db.execute(
+                    "SELECT COUNT(*) FROM shares WHERE node_id=?", (node["id"],)
+                ).fetchone()[0]
+                >= MAX_SHARE_TOKENS_PER_ITEM
+            ):
+                raise ValidationError(
+                    "This item has 100 links. Remove an old link first."
+                )
+            db.execute(
+                "INSERT INTO shares VALUES(?,?,?,?,?,?)",
+                (
+                    identity,
+                    node["id"],
+                    hashlib.sha256(token.encode()).hexdigest(),
+                    created,
+                    expiry,
+                    label,
+                ),
+            )
+            self._bump(db)
+            return token
+
+    def list_shares(
+        self, path: str | None = None, *, include_expired=False, token_factory=None
+    ) -> list[dict[str, Any]]:
+        with self._transaction() as db:
+            node_id = self._resolve(db, path)[0]["id"] if path is not None else None
+            result = []
+            for row in db.execute("SELECT * FROM shares ORDER BY rowid"):
+                if node_id is not None and row["node_id"] != node_id:
+                    continue
+                if (
+                    not include_expired
+                    and row["expires_at"] is not None
+                    and row["expires_at"] <= _utc_now()
+                ):
+                    continue
+                current_path = self._path_for_id(db, row["node_id"])
+                node, _, chain = self._resolve(db, current_path)
+                result.append(
+                    dict(
+                        id=row["id"],
+                        label=row["label"],
+                        node_id=row["node_id"],
+                        path=current_path,
+                        created_at=row["created_at"],
+                        expires_at=row["expires_at"],
+                        name=node["name"],
+                        type=node["kind"],
+                        size=node["size"],
+                        folder_path=current_path.rsplit("/", 1)[0] or "/",
+                        folder_label=" / ".join(
+                            ["My Files", *(n["name"] for n in chain[1:-1])]
+                        ),
+                        copyable=bool(
+                            token_factory
+                            and hmac.compare_digest(
+                                row["token_hash"],
+                                hashlib.sha256(
+                                    token_factory(row["id"]).encode()
+                                ).hexdigest(),
+                            )
+                        ),
+                    )
+                )
+            return result
+
+    def update_share(
+        self, share_id: str, *, label=_SHARE_UNSET, expires_at=_SHARE_UNSET
+    ):
+        # Omission preserves the current value; explicit None removes expiry.
+        if label is not _SHARE_UNSET:
+            label = _share_label(label)
+        expiry = expires_at
+        if expires_at is not _SHARE_UNSET and expires_at is not None:
+            expiry = _validate_timestamp(expires_at)
+        if expiry is not _SHARE_UNSET and expiry is not None and expiry <= _utc_now():
+            raise ValidationError("Link expiry must be in the future")
+        with self._transaction(write=True) as db:
+            row = db.execute("SELECT * FROM shares WHERE id=?", (share_id,)).fetchone()
+            if row is None:
+                raise NotFoundError("Link not found")
+            _, _, chain = self._resolve(db, self._path_for_id(db, row["node_id"]))
+            self._visible(chain)
+            self._demo_mutable(db, chain, descendants=True)
+            self._mutable(db, chain)
+            if label is _SHARE_UNSET and expiry is _SHARE_UNSET:
+                return
+            db.execute(
+                "UPDATE shares SET label=?,expires_at=? WHERE id=?",
+                (
+                    row["label"] if label is _SHARE_UNSET else label,
+                    row["expires_at"] if expiry is _SHARE_UNSET else expiry,
+                    share_id,
+                ),
+            )
+            self._bump(db)
+
+    def revoke_share(self, share_id: str) -> bool:
+        with self._transaction(write=True) as db:
+            if share_id.startswith("/"):
+                node, _, chain = self._resolve(db, share_id)
+                self._demo_mutable(db, chain, descendants=True)
+                cursor = db.execute("DELETE FROM shares WHERE node_id=?", (node["id"],))
+            else:
+                share = db.execute(
+                    "SELECT node_id FROM shares WHERE id=?", (share_id,)
+                ).fetchone()
+                if share is not None:
+                    _, _, chain = self._resolve(
+                        db, self._path_for_id(db, share["node_id"])
+                    )
+                    self._demo_mutable(db, chain, descendants=True)
+                cursor = db.execute("DELETE FROM shares WHERE id=?", (share_id,))
+            if cursor.rowcount:
+                self._bump(db)
+            return bool(cursor.rowcount)
+
+    @staticmethod
+    def _revoke_subtree(db: sqlite3.Connection, node_id: str) -> None:
+        db.execute(
+            "WITH RECURSIVE subtree(id) AS (SELECT id FROM nodes WHERE id=? UNION "
+            "SELECT nodes.id FROM nodes JOIN subtree ON nodes.parent_id=subtree.id) "
+            "DELETE FROM shares WHERE node_id IN subtree",
+            (node_id,),
+        )
+
+    def _authorized(
+        self, db: sqlite3.Connection, chain: list[sqlite3.Row], token: object
+    ) -> str | None:
+        if (
+            not isinstance(token, str)
+            or not token
+            or len(token) > 1024
+            or any(row["trashed"] for row in chain)
+        ):
+            return None
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
+        for share in db.execute(
+            "SELECT * FROM shares WHERE expires_at IS NULL OR expires_at>?",
+            (_utc_now(),),
+        ):
+            if hmac.compare_digest(share["token_hash"], token_hash) and (
+                share["node_id"] in {row["id"] for row in chain}
+            ):
+                return self._path_for_id(db, share["node_id"])
+        return None
+
+    def authorize_directory(self, path: str, token: str) -> str | None:
+        with self._transaction() as db:
+            node, path, chain = self._resolve(db, path)
+            if node["kind"] != "folder":
+                raise NotDirectoryError(f"not a directory: {path}")
+            return self._authorized(db, chain, token)
+
+    def authorize_file(self, path: str, token: str) -> bool:
+        with self._transaction() as db:
+            node, path, chain = self._resolve(db, path)
+            if node["kind"] != "file":
+                raise NotFileError(f"not a file: {path}")
+            return self._authorized(db, chain, token) is not None
+
+    def validate_deletion(self, path: str) -> dict[str, Any]:
+        """Read-only preflight for a top-level trash item, including pending retries."""
+        with self._transaction() as db:
+            node, path, chain = self._resolve(db, path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the root folder cannot be deleted")
+            self._demo_mutable(db, chain, descendants=True)
+            existing = db.execute(
+                "SELECT 1 FROM deletion_intents WHERE root_id=? AND state!='completed'",
+                (node["id"],),
+            ).fetchone()
+            if not existing:
+                self._mutable(db, chain, descendants=True)
+                if not node["trashed"] or any(row["trashed"] for row in chain[:-1]):
+                    raise TrashedItemError(
+                        "permanent deletion must target a top-level trashed item"
+                    )
+            return self._record(node, path)
+
+    def begin_deletion(
+        self, path: str, *, channel_id: int | None = None
+    ) -> dict[str, Any]:
+        if channel_id is not None and (type(channel_id) is not int or channel_id == 0):
+            raise ValidationError("channel_id must be a non-zero integer")
+        with self._transaction(write=True) as db:
+            node, path, chain = self._resolve(db, path)
+            if node["id"] == ROOT_ID:
+                raise RootMutationError("the root folder cannot be deleted")
+            self._demo_mutable(db, chain, descendants=True)
+            existing = db.execute(
+                "SELECT * FROM deletion_intents WHERE root_id=? AND state!='completed'",
+                (node["id"],),
+            ).fetchone()
+            if existing:
+                if channel_id is not None and existing["channel_id"] != channel_id:
+                    raise ValidationError(
+                        "deletion channel does not match existing intent"
+                    )
+                return self._deletion_record(db, existing)
+            self._mutable(db, chain)
+            if not node["trashed"] or any(row["trashed"] for row in chain[:-1]):
+                raise TrashedItemError(
+                    "permanent deletion must target a top-level trashed item"
+                )
+            descendants = set(self._subtree_ids(db, node["id"]))
+            if descendants.intersection(
+                row[0]
+                for row in db.execute(
+                    "SELECT root_id FROM deletion_intents WHERE state!='completed'"
+                )
+            ):
+                raise ValidationError("a descendant has a pending deletion")
+            intent_id = secrets.token_urlsafe(16)
+            db.execute(
+                "INSERT INTO deletion_intents VALUES(?,?,?,?,?,?,NULL)",
+                (intent_id, node["id"], path, channel_id, "pending", _utc_now()),
+            )
+            db.executemany(
+                "INSERT INTO deletion_messages(intent_id,message_id) VALUES(?,?)",
+                (
+                    (intent_id, message_id)
+                    for message_id in self._messages(db, node["id"])
+                ),
+            )
+            self._revoke_subtree(db, node["id"])
+            self._bump(db)
+            return self._deletion_record(
+                db,
+                db.execute(
+                    "SELECT * FROM deletion_intents WHERE id=?", (intent_id,)
+                ).fetchone(),
+            )
+
+    @staticmethod
+    def _deletion_record(db: sqlite3.Connection, row: sqlite3.Row) -> dict[str, Any]:
+        result = dict(row)
+        messages = db.execute(
+            "SELECT * FROM deletion_messages WHERE intent_id=? ORDER BY message_id",
+            (row["id"],),
+        ).fetchall()
+        result["message_ids"] = [item["message_id"] for item in messages]
+        result["pending_message_ids"] = [
+            item["message_id"] for item in messages if not item["confirmed"]
+        ]
+        return result
+
+    def pending_deletions(self) -> list[dict[str, Any]]:
+        with self._transaction() as db:
+            return [
+                self._deletion_record(db, row)
+                for row in db.execute(
+                    "SELECT * FROM deletion_intents WHERE state!='completed' ORDER BY "
+                    "rowid"
+                )
+            ]
+
+    def confirm_deletion_messages(self, intent_id: str, message_ids: list[int]) -> None:
+        validated = {
+            _strict_int(message_id, "message_id", 1) for message_id in message_ids
+        }
+        with self._transaction(write=True) as db:
+            intent = db.execute(
+                "SELECT * FROM deletion_intents WHERE id=?", (intent_id,)
+            ).fetchone()
+            if intent is None:
+                raise NotFoundError("deletion intent not found")
+            known = {
+                row[0]
+                for row in db.execute(
+                    "SELECT message_id FROM deletion_messages WHERE intent_id=?",
+                    (intent_id,),
+                )
+            }
+            if not validated <= known:
+                raise ValidationError(
+                    "confirmation contains messages outside the deletion intent"
+                )
+            if intent["state"] == "completed":
+                return
+            db.executemany(
+                "UPDATE deletion_messages SET confirmed=1 WHERE intent_id=? AND "
+                "message_id=?",
+                ((intent_id, message_id) for message_id in validated),
+            )
+            db.execute(
+                "UPDATE deletion_intents SET state='pending',error=NULL WHERE id=?",
+                (intent_id,),
+            )
+            self._bump(db)
+
+    def fail_deletion(self, intent_id: str, error: str) -> None:
+        with self._transaction(write=True) as db:
+            cursor = db.execute(
+                "UPDATE deletion_intents SET state='failed',error=? WHERE id=? AND "
+                "state!='completed'",
+                (str(error)[:500], intent_id),
+            )
+            if not cursor.rowcount:
+                raise NotFoundError("active deletion intent not found")
+            self._bump(db)
+
+    def finish_deletion(self, intent_id: str) -> list[int]:
+        """Atomically forget a trashed subtree; retain its Telegram documents."""
+        with self._transaction(write=True) as db:
+            intent = db.execute(
+                "SELECT * FROM deletion_intents WHERE id=?", (intent_id,)
+            ).fetchone()
+            if intent is None:
+                raise NotFoundError("deletion intent not found")
+            record = self._deletion_record(db, intent)
+            if intent["state"] != "completed":
+                _, _, chain = self._resolve(
+                    db, self._path_for_id(db, intent["root_id"])
+                )
+                self._demo_mutable(db, chain, descendants=True)
+                db.execute("DELETE FROM nodes WHERE id=?", (intent["root_id"],))
+                db.execute(
+                    "DELETE FROM deletion_messages WHERE intent_id=?", (intent_id,)
+                )
+                db.execute(
+                    "UPDATE deletion_intents SET state='completed',error=NULL WHERE "
+                    "id=?",
+                    (intent_id,),
+                )
+                self._bump(db)
+            return record["message_ids"]
+
+    @staticmethod
+    def _validate_deletion_record(intent: object) -> dict[str, Any]:
+        keys = {
+            "id",
+            "root_id",
+            "path",
+            "channel_id",
+            "state",
+            "created_at",
+            "error",
+            "message_ids",
+            "pending_message_ids",
+        }
+        if not isinstance(intent, dict) or set(intent) != keys:
+            raise ValidationError("invalid deletion intent")
+        _validate_id(intent["id"])
+        _validate_id(intent["root_id"])
+        _normalize_path(intent["path"])
+        created = _validate_timestamp(intent["created_at"])
+        if intent["state"] not in {"pending", "failed", "completed"}:
+            raise ValidationError("invalid deletion state")
+        if intent["channel_id"] is not None and (
+            type(intent["channel_id"]) is not int or intent["channel_id"] == 0
+        ):
+            raise ValidationError("invalid deletion channel")
+        if intent["error"] is not None and (
+            not isinstance(intent["error"], str) or len(intent["error"]) > 500
+        ):
+            raise ValidationError("invalid deletion error")
+        if not isinstance(intent["message_ids"], list) or not isinstance(
+            intent["pending_message_ids"], list
+        ):
+            raise ValidationError("invalid deletion message list")
+        messages = {
+            _strict_int(value, "message_id", 1) for value in intent["message_ids"]
+        }
+        pending = {
+            _strict_int(value, "message_id", 1)
+            for value in intent["pending_message_ids"]
+        }
+        if not pending <= messages or len(messages) != len(intent["message_ids"]):
+            raise ValidationError("invalid deletion confirmations")
+        if intent["state"] == "completed" and pending:
+            raise ValidationError("completed deletion has pending messages")
+        return dict(intent, created_at=created)
+
+    def _import_deletion_locked(self, db: sqlite3.Connection, intent: object) -> None:
+        intent = self._validate_deletion_record(intent)
+        messages = set(intent["message_ids"])
+        pending = set(intent["pending_message_ids"])
+        if intent["state"] != "completed":
+            node = db.execute(
+                "SELECT * FROM nodes WHERE id=?", (intent["root_id"],)
+            ).fetchone()
+            if (
+                node is None
+                or not node["trashed"]
+                or set(self._messages(db, node["id"])) != messages
+            ):
+                raise ValidationError(
+                    "deletion references do not match retained subtree"
+                )
+            actual_path = self._path_for_id(db, node["id"])
+            _, _, chain = self._resolve(db, actual_path)
+            if actual_path != intent["path"] or any(
+                item["trashed"] for item in chain[:-1]
+            ):
+                raise ValidationError("deletion root has invalid ancestry")
+            self._mutable(db, chain, descendants=True)
+        elif db.execute(
+            "SELECT 1 FROM nodes WHERE id=?", (intent["root_id"],)
+        ).fetchone():
+            raise ValidationError("completed deletion still has a live root")
+        db.execute(
+            "INSERT INTO deletion_intents VALUES(?,?,?,?,?,?,?)",
+            (
+                intent["id"],
+                intent["root_id"],
+                intent["path"],
+                intent["channel_id"],
+                intent["state"],
+                intent["created_at"],
+                intent["error"],
+            ),
+        )
+        db.executemany(
+            "INSERT INTO deletion_messages VALUES(?,?,?)",
+            (
+                (intent["id"], message_id, int(message_id not in pending))
+                for message_id in messages
+            ),
+        )
+
+    @staticmethod
+    def _fsync_directory(directory: Path) -> None:
+        descriptor = os.open(directory, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
diff --git a/tgdrive/telegram/__init__.py b/tgdrive/telegram/__init__.py
new file mode 100644
index 00000000..8e8bebf8
--- /dev/null
+++ b/tgdrive/telegram/__init__.py
@@ -0,0 +1 @@
+"""Telegram connections, account identity, and bot ingestion."""
diff --git a/tgdrive/telegram/bot_mode.py b/tgdrive/telegram/bot_mode.py
new file mode 100644
index 00000000..91fa2473
--- /dev/null
+++ b/tgdrive/telegram/bot_mode.py
@@ -0,0 +1,280 @@
+"""Forward-to-save Telegram interface with a website-managed upload folder."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import inspect
+import logging
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from types import SimpleNamespace
+from typing import Any
+
+from telethon import Button
+from telethon.errors import ChatForwardsRestrictedError, FloodWaitError
+
+from tgdrive.core.config import Settings
+from tgdrive.core.security import safe_name
+from tgdrive.recovery.backup import BackupError
+from tgdrive.settings.bot_settings import BotSettings
+from tgdrive.settings.managed_settings import SettingsProblem
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.clients import Client
+
+Message = Any
+
+logger = logging.getLogger(__name__)
+_MEDIA_ATTRIBUTES = (
+    "document",
+    "video",
+    "audio",
+    "photo",
+    "sticker",
+    "animation",
+    "voice",
+    "video_note",
+)
+
+
+class BotMode:
+    def __init__(
+        self,
+        *,
+        client: Client,
+        settings: Settings,
+        store: DriveStore,
+        before_write: Callable[[], Awaitable[None] | None] | None = None,
+        before_delete: Callable[[], Awaitable[None]] | None = None,
+        folder_settings: BotSettings | None = None,
+    ) -> None:
+        self.client = client
+        self.settings = settings
+        self.store = store
+        self.before_write = before_write
+        self.before_delete = before_delete
+        self.active_imports = 0
+        if folder_settings is None:
+            from tgdrive.storage.mongo import for_settings
+
+            folder_settings = BotSettings(
+                settings, SimpleNamespace(store=store, mongo=for_settings(settings))
+            )
+        self.folder_settings = folder_settings
+        self._registered = False
+        self._started = False
+
+    async def start(self) -> None:
+        if self._started:
+            return
+        if not self._registered:
+            self.client.register_bot(self)
+            self._registered = True
+        await self.client.start()
+        self._started = True
+        logger.info("Telegram bot mode started")
+
+    async def stop(self) -> None:
+        if getattr(self.client, "is_connected", False):
+            await self.client.stop()
+        self._started = False
+        logger.info("Telegram bot mode stopped")
+
+    def close(self) -> None:
+        """Folder preferences have no open local handles."""
+
+    @staticmethod
+    def _menu() -> list[list[Any]]:
+        return [
+            [
+                Button.text("Current folder", resize=True, persistent=True),
+                Button.text("Help", resize=True, persistent=True),
+            ]
+        ]
+
+    async def _help(self, _client: Client, message: Message) -> None:
+        value = await self.folder_settings.snapshot()
+        await message.reply_text(
+            "Save files to TGDrive\n\n"
+            "Send or forward files, photos, videos or audio here. "
+            "They will appear in your drive once saved.\n\n"
+            f"Saving to: {value['folder_label']}\n\n"
+            "Use /set_folder to change the upload folder on the TGDrive website.\n"
+            "Tip: send photos as files to keep their original quality.",
+            reply_markup=self._menu(),
+        )
+
+    async def _set_folder(self, _client: Client, message: Message) -> None:
+        value = await self.folder_settings.snapshot()
+        text = (
+            f"Bot upload folder: {value['folder_label']}\n\n"
+            "Choose the upload folder on the TGDrive website under "
+            "Configuration → Transfer limits → Bot uploads. "
+            "Your next forwarded file will be saved there."
+        )
+        if value["settings_url"]:
+            text += "\n\n" + value["settings_url"]
+        await message.reply_text(
+            text,
+            reply_markup=(
+                [[Button.url("Set upload folder", value["settings_url"])]]
+                if value["settings_url"]
+                else self._menu()
+            ),
+        )
+
+    async def _cancel(self, _client: Client, message: Message) -> None:
+        await message.reply_text(
+            "There is no folder selection to cancel. "
+            "Use /set_folder to manage the upload folder on the website.",
+            reply_markup=self._menu(),
+        )
+
+    async def _folder_query(self, _client: Client, message: Message) -> None:
+        await message.reply_text(
+            "Send or forward a file to save it. "
+            "Use /set_folder to change its destination on the website.",
+            reply_markup=self._menu(),
+        )
+
+    async def _current_folder(self, _client: Client, message: Message) -> None:
+        value = await self.folder_settings.snapshot()
+        await message.reply_text(
+            f"Saving new files to: {value['folder_label']}\n\n"
+            "Use /set_folder to change it on the website.",
+            reply_markup=self._menu(),
+        )
+
+    async def _feedback(
+        self, message: Message, status: Message | None, text: str
+    ) -> None:
+        if status is not None:
+            try:
+                await status.edit_text(text)
+                return
+            except Exception:
+                logger.warning("Could not update bot upload feedback", exc_info=True)
+        await message.reply_text(text, reply_markup=self._menu())
+
+    async def _file(self, _client: Client, message: Message) -> None:
+        self.active_imports += 1
+        try:
+            await self._import_file(_client, message)
+        finally:
+            self.active_imports -= 1
+
+    async def _import_file(self, _client: Client, message: Message) -> None:
+        source_chat = getattr(
+            getattr(message, "native", None), "chat_id", message.from_user.id
+        )
+        copied: Message | None = None
+        status: Message | None = None
+        try:
+            if self.before_write is not None:
+                check = self.before_write()
+                if inspect.isawaitable(check):
+                    await check
+            path, folder_name = await self.folder_settings.destination()
+            status = await message.reply_text(
+                f"Saving your file to: {folder_name}…",
+                reply_markup=self._menu(),
+            )
+            copied = await message.copy(
+                self.settings.storage_channel,
+                disable_notification=True,
+            )
+            media = self._media(copied)
+            if media is None:
+                raise RuntimeError("copied message contains no media")
+            filename = self._media_name(media, copied)
+            if self.before_write is not None:
+                check = self.before_write()
+                if inspect.isawaitable(check):
+                    await check
+            item = await asyncio.to_thread(
+                self.store.add_file,
+                path,
+                filename,
+                copied.id,
+                getattr(media, "file_size", 0) or 0,
+                operation_id=hashlib.sha256(
+                    f"bot:{source_chat}:{message.id}".encode()
+                ).hexdigest(),
+                keep_both=True,
+            )
+        except Exception as error:
+            rolled_back = copied is None
+            if copied is not None:
+                try:
+                    if self.before_delete is not None:
+                        await self.before_delete()
+                    await self.client.delete_messages(
+                        self.settings.storage_channel, copied.id
+                    )
+                    rolled_back = True
+                except Exception:
+                    logger.exception("Failed to roll back copied bot-mode media")
+            logger.exception("Bot-mode upload failed")
+            if not rolled_back:
+                text = (
+                    "Upload could not be confirmed. Check your drive in TGDrive "
+                    "before sending this file again."
+                )
+            elif isinstance(error, SettingsProblem):
+                text = (
+                    f"Upload paused. {error}\n"
+                    "Open TGDrive to resolve this, then resend."
+                )
+            elif isinstance(error, BackupError):
+                text = (
+                    "Upload paused while drive protection needs attention. "
+                    "Open TGDrive → Storage & Backups, then send this file again."
+                )
+            elif isinstance(error, FloodWaitError):
+                text = (
+                    f"Telegram needs a pause. Wait {max(1, error.seconds)} seconds, "
+                    "then send this file again."
+                )
+            elif isinstance(error, ChatForwardsRestrictedError):
+                text = (
+                    "This chat protects its files from copying. "
+                    "If you have the original file, send it here as a new attachment."
+                )
+            else:
+                text = (
+                    "Upload failed. Try sending this file again. "
+                    "If it keeps failing, check Telegram connections in TGDrive."
+                )
+            await self._feedback(message, status, text)
+            return
+        await self._feedback(
+            message,
+            status,
+            f"Uploaded {item['name']}\nSaved to: {folder_name}\n\n"
+            "Send another file to save it here, or use /set_folder.",
+        )
+
+    @staticmethod
+    def _media(message: Message) -> Any | None:
+        for attribute in _MEDIA_ATTRIBUTES:
+            media = getattr(message, attribute, None)
+            if media is not None:
+                return media
+        return None
+
+    @staticmethod
+    def _media_name(media: Any, message: Message) -> str:
+        explicit = getattr(media, "file_name", None)
+        if explicit:
+            return safe_name(explicit)
+        kind = getattr(getattr(message, "media", None), "value", "file")
+        timestamp = datetime.now(UTC).strftime("%Y%m%d-%H%M%S")
+        extensions = {
+            "photo": ".jpg",
+            "voice": ".ogg",
+            "video": ".mp4",
+            "video_note": ".mp4",
+            "animation": ".mp4",
+            "sticker": ".webp",
+        }
+        return f"{kind}-{timestamp}-{message.id}{extensions.get(kind, '')}"
diff --git a/tgdrive/telegram/channel_state.py b/tgdrive/telegram/channel_state.py
new file mode 100644
index 00000000..0033db6e
--- /dev/null
+++ b/tgdrive/telegram/channel_state.py
@@ -0,0 +1,53 @@
+"""Read-only checks for a private, durable Telegram storage channel."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def storage_channel_problem(chat: Any, full_chat: Any) -> tuple[str, str] | None:
+    """Return safe setup guidance without exposing channel identifiers."""
+    if not getattr(chat, "broadcast", False):
+        return (
+            "CHANNEL_TYPE",
+            "Use a dedicated Telegram channel, rather than a group.",
+        )
+    usernames = getattr(chat, "usernames", None) or ()
+    if getattr(chat, "username", None) or any(
+        getattr(username, "active", False) for username in usernames
+    ):
+        return (
+            "CHANNEL_PUBLIC",
+            "The storage channel is public. In Telegram, change Channel Type "
+            "to Private and remove active public usernames before continuing.",
+        )
+    if getattr(full_chat, "ttl_period", None):
+        return (
+            "CHANNEL_AUTO_DELETE",
+            "Telegram auto-delete is enabled for the storage channel. Turn "
+            "auto-delete off before continuing so stored files are retained.",
+        )
+    return None
+
+
+def storage_bot_rights_problem(
+    chat: Any, *, require_pin: bool
+) -> tuple[str, str] | None:
+    """Every storage bot can publish and clean up any pooled bot's messages."""
+    rights = getattr(chat, "admin_rights", None)
+    required = ("post_messages", "delete_messages")
+    if require_pin:
+        required += ("edit_messages",)
+    if rights is None or not all(getattr(rights, key, False) for key in required):
+        return (
+            "CHANNEL_RIGHTS",
+            "Every storage bot must be a channel administrator with Post Messages "
+            "and Delete Messages enabled."
+            + (
+                " Also enable Edit Messages so TGDrive can pin its recovery "
+                "checkpoints."
+                if require_pin
+                else ""
+            ),
+        )
+    return None
diff --git a/tgdrive/telegram/client_identity.py b/tgdrive/telegram/client_identity.py
new file mode 100644
index 00000000..54b0f7ca
--- /dev/null
+++ b/tgdrive/telegram/client_identity.py
@@ -0,0 +1,70 @@
+"""Disposable Telegram account names cached in MongoDB."""
+
+from __future__ import annotations
+
+import math
+import time
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+
+def account_identity(account: Any) -> dict[str, str | None]:
+    parts = (getattr(account, "first_name", None), getattr(account, "last_name", None))
+    display_name = " ".join(
+        "".join(c for c in " ".join(part.split()) if c.isprintable())
+        for part in parts
+        if isinstance(part, str) and part.strip()
+    )[:160].strip()
+    username = getattr(account, "username", None)
+    if not (
+        isinstance(username, str)
+        and 1 <= len(username) <= 64
+        and all(c.isascii() and (c.isalnum() or c == "_") for c in username)
+    ):
+        username = None
+    return {"display_name": display_name or None, "username": username}
+
+
+class IdentityCache:
+    def __init__(self, data_dir: Path):
+        from tgdrive.storage.mongo import DatabaseUnavailable, for_directory
+
+        self._mongo = for_directory(data_dir)
+        if self._mongo is None:
+            raise DatabaseUnavailable("MongoDB is required for account identities.")
+
+    def defer(self, account: str, deadline: float) -> None:
+        self._mongo.db.identities.update_one(
+            {"_id": account}, {"$max": {"retry_at": deadline}}, upsert=True
+        )
+
+    def retry_at(self, account: str) -> float:
+        row = self._mongo.db.identities.find_one({"_id": account}) or {}
+        deadline = row.get("retry_at", 0.0)
+        return (
+            deadline
+            if isinstance(deadline, (int, float)) and math.isfinite(deadline)
+            else 0.0
+        )
+
+    def read(self, account: str) -> dict[str, str | None] | None:
+        return self.read_many([account]).get(account)
+
+    def read_many(self, accounts: list[str]) -> dict[str, dict[str, str | None]]:
+        return {
+            row["_id"]: account_identity(
+                SimpleNamespace(
+                    first_name=row.get("display_name"), username=row.get("username")
+                )
+            )
+            for row in self._mongo.db.identities.find({"_id": {"$in": accounts}})
+            if row.get("updated_at") is not None
+        }
+
+    def write(self, account: str, identity: dict[str, str | None]) -> None:
+        self._mongo.db.identities.update_one(
+            {"_id": account},
+            {"$set": {**identity, "updated_at": time.time()}},
+            upsert=True,
+        )
diff --git a/tgdrive/telegram/client_pool.py b/tgdrive/telegram/client_pool.py
new file mode 100644
index 00000000..3a87d65a
--- /dev/null
+++ b/tgdrive/telegram/client_pool.py
@@ -0,0 +1,1131 @@
+"""Lifecycle-safe leasing for Telegram bot and user clients."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from collections import deque
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterable
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+from tgdrive.media.media_scheduler import (
+    MediaPriority,
+    MediaPriorityScope,
+    effective_priority,
+)
+from tgdrive.telegram.connection_errors import (
+    TelegramConnectionError,
+    connection_problem,
+    removed_sender,
+)
+
+if TYPE_CHECKING:
+    from tgdrive.core.config import Settings
+
+type ClientKind = Literal["bot", "user"]
+
+
+class TelegramClientLifecycle(Protocol):
+    """The small portion of the Telegram client lifecycle used by the pool."""
+
+    def start(self) -> Any | Awaitable[Any]: ...
+
+    def stop(self) -> Any | Awaitable[Any]: ...
+
+
+type ClientFactory = Callable[
+    [], TelegramClientLifecycle | Awaitable[TelegramClientLifecycle]
+]
+type ClientSource = TelegramClientLifecycle | ClientFactory
+
+
+class PoolState(StrEnum):
+    NEW = "new"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    FAILED = "failed"
+
+
+class ClientPoolError(RuntimeError):
+    """Base class for client-pool failures."""
+
+
+class ClientPoolNotRunning(ClientPoolError):
+    """A lease was requested while the pool was not accepting work."""
+
+
+class NoClientAvailable(ClientPoolError):
+    """No started, healthy client satisfies a lease request."""
+
+
+class MediaQueueFull(NoClientAvailable):
+    """Retryable origin overload; cached delivery does not enter this queue."""
+
+    code = "TELEGRAM_QUEUE_FULL"
+
+    def __init__(self, retry_after: int = 1) -> None:
+        self.retry_after = max(1, retry_after)
+        super().__init__("Telegram origin queue is full; retry shortly")
+
+
+class DuplicateClientIdentity(ClientPoolError):
+    """A second configured connection resolves to an already pooled account."""
+
+
+class NoPremiumClientAvailable(NoClientAvailable):
+    """A premium lease was requested without a usable user client."""
+
+
+class ClientPoolStartError(ClientPoolError):
+    """One or more clients failed to start.
+
+    All clients that were materialized are asked to stop before this exception
+    is raised.  The original exceptions remain available in ``failures``.
+    """
+
+    def __init__(
+        self,
+        failures: tuple[tuple[str, BaseException], ...],
+        cleanup_failures: tuple[tuple[str, BaseException], ...] = (),
+    ) -> None:
+        self.failures = failures
+        self.cleanup_failures = cleanup_failures
+        labels = ", ".join(
+            f"{name} ({type(error).__name__})" for name, error in failures
+        )
+        message = f"failed to start client pool: {labels}"
+        if cleanup_failures:
+            message += f"; {len(cleanup_failures)} cleanup operation(s) also failed"
+        super().__init__(message)
+
+
+@dataclass(frozen=True, slots=True)
+class ClientStatus:
+    name: str
+    kind: ClientKind
+    started: bool
+    healthy: bool
+    connected: bool | None
+    active_leases: int
+    last_error_type: str | None
+    display_name: str | None = None
+    username: str | None = None
+    identity_refreshing: bool = False
+    identity_retry_at: float | None = None
+    error: str | None = None
+    error_code: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PoolHealth:
+    state: PoolState
+    ready: bool
+    total_clients: int
+    started_clients: int
+    healthy_clients: int
+    active_leases: int
+    bot_clients: int
+    premium_clients: int
+
+
+@dataclass(slots=True)
+class _ClientSlot:
+    source: ClientSource
+    kind: ClientKind
+    index: int
+    is_factory: bool
+    client: TelegramClientLifecycle | None = None
+    started: bool = False
+    healthy: bool = False
+    active: int = 0
+    selected_at: int = 0
+    media_active: int = 0
+    download_active: int = 0
+    cooldown_until: float = 0
+    error: BaseException | None = None
+    needs_stop: bool = False
+
+    @property
+    def fallback_name(self) -> str:
+        return f"{self.kind}-{self.index + 1}"
+
+    @property
+    def name(self) -> str:
+        value = getattr(self.client, "name", None)
+        return str(value) if value not in (None, "") else self.fallback_name
+
+
+async def _maybe_await(value: Any) -> Any:
+    return await value if inspect.isawaitable(value) else value
+
+
+class ClientPool:
+    """Own and fairly lease bot and premium-user clients.
+
+    Sources may be already-created Telegram clients or zero-argument
+    synchronous/asynchronous factories.  ``start`` and ``stop`` are
+    idempotent; clients start and stop concurrently.
+    """
+
+    def __init__(
+        self,
+        bot_clients: Iterable[ClientSource] = (),
+        user_clients: Iterable[ClientSource] = (),
+        *,
+        allow_partial_start: bool = False,
+        media_send_interval: float = 0.0,
+        uploads_per_bot: int = 1,
+        media_cache_dir: Any = None,
+        media_per_bot: int = 3,
+        max_media_queue: int = 256,
+    ) -> None:
+        self._allow_partial_start = allow_partial_start
+        self.media_cache_dir = media_cache_dir
+        self._media_read_cache: Any = None
+        self._validate_upload_limit(uploads_per_bot)
+        self._uploads_per_bot = uploads_per_bot
+        self._validate_media_limit(media_per_bot)
+        self._media_per_bot = media_per_bot
+        self._validate_queue_limit(max_media_queue)
+        self._max_media_queue = max_media_queue
+        self._origin_waiters: list[dict[str, Any]] = []
+        self._origin_active: dict[object, dict[str, Any]] = {}
+        self._origin_sequence = 0
+        self._origin_durations: deque[float] = deque(maxlen=128)
+        self._load_history: deque[dict[str, Any]] = deque(maxlen=120)
+        self._last_load_sample = 0.0
+        self._slots: list[_ClientSlot] = []
+        for kind, sources in (("bot", bot_clients), ("user", user_clients)):
+            for index, source in enumerate(sources):
+                is_factory = callable(source) and not callable(
+                    getattr(source, "start", None)
+                )
+                self._slots.append(
+                    _ClientSlot(
+                        source=source,
+                        kind=kind,
+                        index=index,
+                        is_factory=is_factory,
+                        client=None if is_factory else source,
+                    )
+                )
+
+        self._state = PoolState.NEW
+        self._lifecycle_lock = asyncio.Lock()
+        self._leases = asyncio.Condition()
+        self._selection_counter = 0
+        self._send_interval = max(0.0, media_send_interval)
+        self._send_lock = asyncio.Lock()
+        self._next_send = 0.0
+        self._channel_cooldown_until = 0.0
+        self._account_cooldowns: dict[str, float] = {}
+
+    @staticmethod
+    def _validate_upload_limit(value: int) -> None:
+        if type(value) is not int or not 1 <= value <= 4:
+            raise ValueError("Uploads per bot must be between 1 and 4")
+
+    @property
+    def uploads_per_bot(self) -> int:
+        return self._uploads_per_bot
+
+    @staticmethod
+    def _validate_media_limit(value: int) -> None:
+        if type(value) is not int or not 1 <= value <= 32:
+            raise ValueError("Combined media activity must be between 1 and 32")
+
+    @property
+    def media_per_bot(self) -> int:
+        return self._media_per_bot
+
+    async def set_media_per_bot(self, value: int) -> None:
+        self._validate_media_limit(value)
+        async with self._leases:
+            self._media_per_bot = value
+            self._leases.notify_all()
+
+    @staticmethod
+    def _validate_queue_limit(value: int) -> None:
+        if type(value) is not int or not 1 <= value <= 4096:
+            raise ValueError("Telegram queue limit must be between 1 and 4096")
+
+    async def set_media_queue_limit(self, value: int) -> None:
+        self._validate_queue_limit(value)
+        async with self._leases:
+            self._max_media_queue = value
+            self._leases.notify_all()
+
+    async def set_uploads_per_bot(self, value: int) -> None:
+        """Change admission without cancelling leases already in progress."""
+        self._validate_upload_limit(value)
+        async with self._leases:
+            self._uploads_per_bot = value
+            self._leases.notify_all()
+
+    @property
+    def state(self) -> PoolState:
+        return self._state
+
+    async def __aenter__(self) -> ClientPool:
+        return await self.start()
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.stop()
+
+    async def start(self) -> ClientPool:
+        """Materialize and concurrently start every configured client."""
+
+        async with self._lifecycle_lock:
+            if self._state is PoolState.RUNNING:
+                return self
+
+            self._state = PoolState.STARTING
+            for slot in self._slots:
+                slot.error = None
+                slot.healthy = False
+
+            try:
+                results = await asyncio.gather(
+                    *(self._start_slot(slot) for slot in self._slots),
+                    return_exceptions=True,
+                )
+            except BaseException:
+                await self._stop_materialized()
+                self._state = PoolState.FAILED
+                raise
+
+            failures = tuple(
+                (slot.name, result)
+                for slot, result in zip(self._slots, results, strict=True)
+                if isinstance(result, BaseException)
+            )
+            if failures:
+                usable_bot = any(
+                    slot.kind == "bot" and slot.started and self._slot_is_healthy(slot)
+                    for slot in self._slots
+                )
+                if self._allow_partial_start and usable_bot:
+                    # Optional accounts must not take working storage bots down.
+                    # Failed clients may have opened connections before failing.
+                    await asyncio.gather(
+                        *(
+                            self._stop_slot(slot)
+                            for slot, result in zip(self._slots, results, strict=True)
+                            if isinstance(result, BaseException) and slot.needs_stop
+                        ),
+                        return_exceptions=True,
+                    )
+                else:
+                    cleanup_failures = await self._stop_materialized()
+                    self._state = PoolState.FAILED
+                    raise ClientPoolStartError(failures, cleanup_failures)
+
+            seen: dict[str, _ClientSlot] = {}
+            for slot in self._slots:
+                if not slot.started or not self._slot_is_healthy(slot):
+                    continue
+                previous = seen.get(slot.name)
+                if previous is None:
+                    seen[slot.name] = slot
+                    continue
+                error = DuplicateClientIdentity(
+                    "This Telegram account already has a usable connection"
+                )
+                if slot.client is previous.client:
+                    # A shared instance must only be stopped by its owning slot.
+                    slot.started = False
+                    slot.needs_stop = False
+                else:
+                    # Failed disconnects remain unhealthy and are retried at stop.
+                    await asyncio.gather(self._stop_slot(slot), return_exceptions=True)
+                slot.healthy = False
+                slot.error = error
+
+            self._state = PoolState.RUNNING
+            return self
+
+    async def stop(
+        self,
+        *,
+        drain_timeout: float | None = None,
+    ) -> tuple[tuple[str, BaseException], ...]:
+        """Stop accepting leases, drain active leases, and stop all clients.
+
+        The returned tuple contains any stop errors after every client has
+        been attempted.  Repeated calls after shutdown are no-ops.
+        """
+
+        async with self._lifecycle_lock:
+            if self._state in (PoolState.NEW, PoolState.STOPPED):
+                self._state = PoolState.STOPPED
+                return ()
+
+            previous_state = self._state
+            self._state = PoolState.STOPPING
+            async with self._leases:
+                self._leases.notify_all()
+            try:
+                wait_for_leases = self._wait_for_all_leases()
+                if drain_timeout is None:
+                    await wait_for_leases
+                else:
+                    await asyncio.wait_for(wait_for_leases, timeout=drain_timeout)
+            except TimeoutError:
+                self._state = (
+                    PoolState.RUNNING
+                    if previous_state is PoolState.RUNNING
+                    else previous_state
+                )
+                raise
+
+            failures = await self._stop_materialized()
+            self._state = PoolState.STOPPED
+            return failures
+
+    @asynccontextmanager
+    async def lease(
+        self,
+        *,
+        premium: bool = False,
+        premium_required: bool | None = None,
+        prefer_premium: bool = False,
+        client_name: str | None = None,
+        media: bool = False,
+        allow_users: bool = False,
+        download: bool = False,
+        respect_cooldown: bool = False,
+        priority: MediaPriority | MediaPriorityScope = "demand",
+        request_id: str | None = None,
+    ) -> AsyncIterator[TelegramClientLifecycle]:
+        """Lease a healthy client and always release its count.
+
+        premium requires a user account, as for larger uploads.
+        prefer_premium first considers healthy users and otherwise bots,
+        so reads continue when no usable optional user is present.
+        allow_users admits both account kinds for bot-compatible media parts;
+        with prefer_premium, ready user slots are selected before bot slots.
+        premium-required documents remain restricted to user accounts.
+        """
+
+        if effective_priority(priority) not in ("demand", "preload"):
+            raise ValueError("Unknown media priority")
+        if premium_required is not None:
+            premium = premium_required
+        kind: ClientKind = "user" if premium else "bot"
+
+        async with self._leases:
+            ticket = object()
+            unsubscribe = None
+            if media or download:
+                if len(self._origin_waiters) >= self._max_media_queue:
+                    mean = (
+                        sum(self._origin_durations) / len(self._origin_durations)
+                        if self._origin_durations
+                        else 1.0
+                    )
+                    raise MediaQueueFull(retry_after=int(mean) + 1)
+                self._origin_sequence += 1
+                self._origin_waiters.append(
+                    dict(
+                        ticket=ticket,
+                        kind=None if allow_users and not premium else kind,
+                        name=client_name,
+                        priority=effective_priority(priority),
+                        download=download,
+                        queued_at=time.monotonic(),
+                        request_id=request_id or f"media-{self._origin_sequence}",
+                    )
+                )
+                if isinstance(priority, MediaPriorityScope):
+                    own = self._origin_waiters[-1]
+
+                    def promote_waiter():
+                        # Its demand arrival is now, not when background work
+                        # originally queued. Keep existing demand ahead of it.
+                        own["priority"] = "demand"
+                        self._origin_waiters.remove(own)
+                        self._origin_waiters.append(own)
+
+                    unsubscribe = priority.subscribe(
+                        self._leases,
+                        promote_waiter,
+                    )
+            try:
+                while True:
+                    if self._state is not PoolState.RUNNING:
+                        raise ClientPoolNotRunning(
+                            f"client pool is {self._state.value}; not accepting leases"
+                        )
+
+                    def available(candidate_kind: ClientKind) -> list[_ClientSlot]:
+                        return [
+                            slot
+                            for slot in self._slots
+                            if slot.kind == candidate_kind
+                            and slot.client is not None
+                            and slot.started
+                            and self._slot_is_healthy(slot)
+                            and (client_name is None or slot.name == client_name)
+                        ]
+
+                    candidates = available(kind)
+                    if allow_users and not premium:
+                        candidates += available("user")
+                    elif prefer_premium and not premium:
+                        preferred = available("user")
+                        if download or respect_cooldown:
+                            # A cooling Premium account must not strand idle bots.
+                            now = time.time()
+                            ready_users = [
+                                slot for slot in preferred if slot.cooldown_until <= now
+                            ]
+                            ready_bots = [
+                                slot
+                                for slot in candidates
+                                if slot.cooldown_until <= now
+                            ]
+                            candidates = (
+                                ready_users or ready_bots or (preferred + candidates)
+                            )
+                        else:
+                            candidates = preferred or candidates
+                    if not candidates:
+                        matching = [
+                            slot
+                            for slot in self._slots
+                            if (client_name is None or slot.name == client_name)
+                            and (slot.kind == kind or (allow_users and not premium))
+                        ]
+                        if client_name is not None and not matching:
+                            raise removed_sender(client_name)
+                        for unavailable in matching:
+                            problem = connection_problem(
+                                unavailable.error,
+                                unavailable.kind,
+                                client_name=unavailable.name,
+                            )
+                            if problem is not None:
+                                raise problem
+                        if premium and not any(
+                            slot.kind == kind for slot in self._slots
+                        ):
+                            raise NoPremiumClientAvailable(
+                                "no premium user clients are configured"
+                            )
+                        raise NoClientAvailable(
+                            "no healthy matching Telegram clients are available"
+                        )
+                    now = time.time()
+
+                    def earlier_origin_for(candidate: _ClientSlot, now=now) -> bool:
+                        own_rank = effective_priority(priority) == "preload"
+                        for queued in sorted(
+                            self._origin_waiters,
+                            key=lambda waiter: waiter["priority"] == "preload",
+                        ):
+                            if queued["ticket"] is ticket:
+                                return False
+                            if (queued["priority"] == "preload") > own_rank:
+                                continue
+                            if queued["kind"] not in (None, candidate.kind) or (
+                                queued["name"] is not None
+                                and queued["name"] != candidate.name
+                            ):
+                                continue
+                            # A full upload lane must not strand a free read lane.
+                            if queued["download"]:
+                                if (
+                                    candidate.download_active < self._media_per_bot
+                                    and candidate.cooldown_until <= now
+                                ):
+                                    return True
+                            elif (
+                                candidate.media_active
+                                < (
+                                    self._uploads_per_bot
+                                    if candidate.kind == "bot"
+                                    else 1
+                                )
+                                and max(
+                                    candidate.cooldown_until,
+                                    self._channel_cooldown_until,
+                                )
+                                <= now
+                            ):
+                                return True
+                        return False
+
+                    eligible = [
+                        slot
+                        for slot in candidates
+                        if (not download or slot.download_active < self._media_per_bot)
+                        and (
+                            not (download or media)
+                            or (
+                                slot.media_active + slot.download_active
+                                < self._media_per_bot
+                                and not earlier_origin_for(slot)
+                            )
+                        )
+                        and (
+                            not (download or respect_cooldown)
+                            or slot.cooldown_until <= now
+                        )
+                        and (
+                            not media
+                            or (
+                                slot.media_active
+                                < (self._uploads_per_bot if slot.kind == "bot" else 1)
+                                and max(
+                                    slot.cooldown_until, self._channel_cooldown_until
+                                )
+                                <= now
+                            )
+                        )
+                    ]
+                    if eligible:
+                        slot = min(
+                            eligible,
+                            key=lambda item: (
+                                prefer_premium and item.kind != "user",
+                                item.download_active
+                                if download
+                                else item.media_active
+                                if media
+                                else item.active,
+                                item.selected_at,
+                                item.index,
+                            ),
+                        )
+                        self._selection_counter += 1
+                        slot.selected_at = self._selection_counter
+                        slot.active += 1
+                        if download:
+                            slot.download_active += 1
+                        if media:
+                            slot.media_active += 1
+                        client = slot.client
+                        if media or download:
+                            own = next(
+                                row
+                                for row in self._origin_waiters
+                                if row["ticket"] is ticket
+                            )
+                            self._origin_active[ticket] = dict(
+                                request_id=own["request_id"],
+                                name=slot.name,
+                                priority=effective_priority(priority),
+                                operation="download" if download else "upload",
+                                started_at=time.monotonic(),
+                            )
+                            if download:
+                                # Rotate read-ahead behind other waiting requests.
+                                self._origin_waiters.sort(
+                                    key=lambda row: (
+                                        row["download"]
+                                        and row["request_id"] == own["request_id"]
+                                        and row["priority"] == own["priority"]
+                                    )
+                                )
+                        break
+                    deadlines = [
+                        max(
+                            slot.cooldown_until,
+                            self._channel_cooldown_until if media else 0,
+                        )
+                        for slot in candidates
+                        if max(
+                            slot.cooldown_until,
+                            self._channel_cooldown_until if media else 0,
+                        )
+                        > now
+                    ]
+                    timeout = max(0.001, min(deadlines) - now) if deadlines else None
+                    try:
+                        if timeout is None:
+                            await self._leases.wait()
+                        else:
+                            await asyncio.wait_for(self._leases.wait(), timeout)
+                    except TimeoutError:
+                        pass
+            finally:
+                if unsubscribe is not None:
+                    unsubscribe()
+                if media or download:
+                    self._origin_waiters = [
+                        row
+                        for row in self._origin_waiters
+                        if row["ticket"] is not ticket
+                    ]
+                    self._leases.notify_all()
+
+        started = time.monotonic()
+        try:
+            yield client
+        except Exception as error:
+            problem = await self.report_failure(client, error)
+            if problem is not None:
+                raise problem from None
+            raise
+        finally:
+            async with self._leases:
+                if slot.active <= 0:
+                    raise RuntimeError("client lease accounting underflow")
+                slot.active -= 1
+                if download:
+                    slot.download_active -= 1
+                if media:
+                    slot.media_active -= 1
+                if media or download:
+                    self._origin_active.pop(ticket, None)
+                    self._origin_durations.append(time.monotonic() - started)
+                self._leases.notify_all()
+
+    async def download_capacity(self) -> int:
+        """Potential read windows; upload/read admission shares the media ceiling."""
+        async with self._leases:
+            return sum(
+                self._media_per_bot
+                for slot in self._slots
+                if slot.started and self._slot_is_healthy(slot)
+            )
+
+    def performance_snapshot(self) -> dict[str, Any]:
+        """Event-loop-local, bounded observations; queue ETAs are estimates."""
+        now = time.monotonic()
+        mean = (
+            sum(self._origin_durations) / len(self._origin_durations)
+            if self._origin_durations
+            else None
+        )
+        queue = sorted(
+            self._origin_waiters, key=lambda row: row["priority"] == "preload"
+        )
+        accounts = []
+        for slot in self._slots:
+            scheduler = getattr(slot.client, "_media_scheduler", None)
+            accounts.append(
+                dict(
+                    name=slot.name,
+                    kind=slot.kind,
+                    uploads=slot.media_active,
+                    downloads=slot.download_active,
+                    combined_limit=self._media_per_bot,
+                    cooldown_seconds=max(0.0, slot.cooldown_until - time.time()),
+                    requests=scheduler.snapshot() if scheduler is not None else None,
+                )
+            )
+        sample = dict(
+            at=time.time(),
+            queued=len(queue),
+            active=sum(
+                slot.media_active + slot.download_active for slot in self._slots
+            ),
+        )
+        wall_now = sample["at"]
+        if (
+            self._load_history
+            and not 0 <= wall_now - self._load_history[-1]["at"] <= 30
+        ):
+            self._load_history.clear()
+            self._last_load_sample = 0
+        while self._load_history and self._load_history[0]["at"] < wall_now - 300:
+            self._load_history.popleft()
+        if now - self._last_load_sample >= 1:
+            self._load_history.append(sample)
+            self._last_load_sample = now
+        return dict(
+            **sample,
+            max_queue=self._max_media_queue,
+            estimates=True,
+            mean_activity_seconds=mean,
+            queue=[
+                dict(
+                    position=index + 1,
+                    priority=row["priority"],
+                    request_id=row["request_id"],
+                    operation="download" if row["download"] else "upload",
+                    client_name=row["name"],
+                    waiting_seconds=round(now - row["queued_at"], 3),
+                    estimated_wait_seconds=self._estimate_origin_wait(row, index, mean),
+                )
+                for index, row in enumerate(queue[:128])
+            ],
+            accounts=accounts,
+            active_requests=[
+                dict(
+                    request_id=row["request_id"],
+                    client_name=row["name"],
+                    priority=row["priority"],
+                    operation=row["operation"],
+                    elapsed_seconds=round(now - row["started_at"], 3),
+                )
+                for row in list(self._origin_active.values())[:128]
+            ],
+            history=list(self._load_history),
+            history_window_seconds=300,
+        )
+
+    def _estimate_origin_wait(self, row, index, mean):
+        candidates = [
+            slot
+            for slot in self._slots
+            if slot.started
+            and self._slot_is_healthy(slot)
+            and row["kind"] in (None, slot.kind)
+            and row["name"] in (None, slot.name)
+        ]
+        capacity = max(1, len(candidates) * self._media_per_bot)
+        occupancy = sum(slot.media_active + slot.download_active for slot in candidates)
+        channel_deadline = 0 if row["download"] else self._channel_cooldown_until
+        cooldown = min(
+            (
+                max(
+                    0, slot.cooldown_until - time.time(), channel_deadline - time.time()
+                )
+                for slot in candidates
+            ),
+            default=0.0,
+        )
+        return (
+            cooldown + ((occupancy + index) // capacity) * mean
+            if mean is not None
+            else None
+        )
+
+    def queue_estimate(self, request_id: str) -> dict[str, Any] | None:
+        """Find a request without exposing other visitors' queue identifiers."""
+        now = time.monotonic()
+        active = sum(
+            row["request_id"] == request_id for row in self._origin_active.values()
+        )
+        queue = sorted(
+            self._origin_waiters, key=lambda row: row["priority"] == "preload"
+        )
+        matches = [
+            (index, row)
+            for index, row in enumerate(queue)
+            if row["request_id"] == request_id
+        ]
+        if not matches:
+            return (
+                dict(
+                    request_id=request_id,
+                    position=0,
+                    estimated_wait_seconds=0.0,
+                    active_operations=active,
+                    queued_operations=0,
+                    estimates=True,
+                )
+                if active
+                else None
+            )
+        index, row = matches[0]
+        mean = (
+            sum(self._origin_durations) / len(self._origin_durations)
+            if self._origin_durations
+            else None
+        )
+        estimate = self._estimate_origin_wait(row, index, mean)
+        return dict(
+            request_id=request_id,
+            position=index + 1,
+            priority=row["priority"],
+            estimated_wait_seconds=estimate,
+            waiting_seconds=round(now - row["queued_at"], 3),
+            active_operations=active,
+            queued_operations=len(matches),
+            estimates=True,
+        )
+
+    async def media_capacity(self, *, premium=False, allow_users=False) -> int:
+        """Potential media slots; leases enforce occupancy, fairness and cooldowns.
+
+        Include occupied/cooling slots so a coordinator does not permanently
+        shrink when another transfer temporarily owns them.
+        """
+        async with self._leases:
+            if self._state is not PoolState.RUNNING:
+                return 0
+            return sum(
+                self._uploads_per_bot if slot.kind == "bot" else 1
+                for slot in self._slots
+                if slot.started
+                and self._slot_is_healthy(slot)
+                and (
+                    slot.kind == "user"
+                    if premium
+                    else allow_users or slot.kind == "bot"
+                )
+            )
+
+    async def defer_client(self, client_name: str, deadline: float) -> None:
+        """Apply a persisted account FloodWait to every new media lease."""
+        async with self._leases:
+            self._account_cooldowns[client_name] = max(
+                self._account_cooldowns.get(client_name, 0),
+                deadline,
+            )
+            for slot in self._slots:
+                if slot.name == client_name:
+                    slot.cooldown_until = max(slot.cooldown_until, deadline)
+            self._leases.notify_all()
+
+    async def account_retry_at(self, client_name: str) -> float:
+        """Share account waits with isolated owner-initiated connection checks."""
+        async with self._leases:
+            return max(
+                self._account_cooldowns.get(client_name, 0),
+                *(
+                    slot.cooldown_until
+                    for slot in self._slots
+                    if slot.name == client_name
+                ),
+                0,
+            )
+
+    async def defer_channel(self, deadline: float) -> None:
+        """Message-publishing FloodWait is shared across channel writers."""
+        async with self._leases:
+            self._channel_cooldown_until = max(self._channel_cooldown_until, deadline)
+            self._leases.notify_all()
+
+    async def pace_send(self, channel: int) -> None:
+        """Conservative shared pacing; server FloodWait always takes precedence."""
+        async with self._send_lock:
+            while True:
+                remaining = (
+                    max(self._next_send, self._channel_cooldown_until) - time.time()
+                )
+                if remaining <= 0:
+                    self._next_send = time.time() + self._send_interval
+                    return
+                await asyncio.sleep(remaining)
+
+    def kind_of(self, client: TelegramClientLifecycle) -> ClientKind:
+        """Return the configured account kind without exposing credentials."""
+
+        return self._find_slot(client).kind
+
+    async def mark_unhealthy(
+        self,
+        client: TelegramClientLifecycle,
+        error: BaseException | None = None,
+    ) -> None:
+        """Exclude ``client`` from future leases until marked healthy again."""
+
+        async with self._leases:
+            slot = self._find_slot(client)
+            slot.healthy = False
+            slot.error = error
+            self._leases.notify_all()
+
+    async def report_failure(
+        self, client: TelegramClientLifecycle, error: BaseException
+    ) -> TelegramConnectionError | None:
+        """Quarantine revoked credentials or channel access, leaving waits alone."""
+        slot = self._find_slot(client)
+        if (
+            isinstance(error, TelegramConnectionError)
+            and error.client_name is not None
+            and error.client_name != slot.name
+        ):
+            return None  # A nested lease failed on another account.
+        problem = connection_problem(error, slot.kind, client_name=slot.name)
+        if problem is not None:
+            await self.mark_unhealthy(client, problem)
+        return problem
+
+    async def restore_channel_access(self, name: str) -> None:
+        """Re-enable a live account only after Connections verified its access."""
+        async with self._leases:
+            for slot in self._slots:
+                if (
+                    slot.name == name
+                    and slot.started
+                    and self._connected_state(slot.client) is not False
+                    and isinstance(slot.error, TelegramConnectionError)
+                    and slot.error.code == "TELEGRAM_CHANNEL_ACCESS"
+                ):
+                    slot.healthy = True
+                    slot.error = None
+            self._leases.notify_all()
+
+    async def mark_healthy(self, client: TelegramClientLifecycle) -> None:
+        async with self._leases:
+            slot = self._find_slot(client)
+            if not slot.started:
+                raise ClientPoolError("cannot mark a stopped client healthy")
+            slot.healthy = True
+            slot.error = None
+            self._leases.notify_all()
+
+    async def status(self) -> tuple[ClientStatus, ...]:
+        """Return a stable snapshot without exposing credential values."""
+
+        async with self._leases:
+            return tuple(
+                ClientStatus(
+                    name=slot.name,
+                    kind=slot.kind,
+                    started=slot.started,
+                    healthy=self._slot_is_healthy(slot),
+                    connected=self._connected_state(slot.client),
+                    active_leases=slot.active,
+                    last_error_type=(
+                        type(slot.error).__name__ if slot.error is not None else None
+                    ),
+                    display_name=getattr(slot.client, "display_name", None),
+                    username=getattr(slot.client, "username", None),
+                    identity_refreshing=bool(
+                        getattr(slot.client, "identity_refreshing", False)
+                    ),
+                    identity_retry_at=getattr(slot.client, "identity_retry_at", None),
+                    error=str(problem)
+                    if (
+                        problem := connection_problem(
+                            slot.error, slot.kind, client_name=slot.name
+                        )
+                    )
+                    else None,
+                    error_code=problem.code if problem else None,
+                )
+                for slot in self._slots
+            )
+
+    def refresh_identities(self) -> None:
+        """Schedule optional lookups without delaying requests or replacing clients."""
+        for slot in self._slots:
+            refresh = getattr(slot.client, "refresh_identity", None)
+            if slot.started and callable(refresh):
+                refresh()
+
+    async def health(self) -> PoolHealth:
+        statuses = await self.status()
+        started = sum(item.started for item in statuses)
+        healthy = sum(item.healthy for item in statuses)
+        total = len(statuses)
+        return PoolHealth(
+            state=self._state,
+            ready=(
+                self._state is PoolState.RUNNING
+                and (
+                    any(item.kind == "bot" and item.healthy for item in statuses)
+                    if self._allow_partial_start
+                    else total > 0 and started == total and healthy == total
+                )
+            ),
+            total_clients=total,
+            started_clients=started,
+            healthy_clients=healthy,
+            active_leases=sum(item.active_leases for item in statuses),
+            bot_clients=sum(item.kind == "bot" for item in statuses),
+            premium_clients=sum(item.kind == "user" for item in statuses),
+        )
+
+    async def _start_slot(self, slot: _ClientSlot) -> None:
+        try:
+            if slot.is_factory:
+                slot.client = await _maybe_await(slot.source())  # type: ignore[operator]
+            if slot.client is None:
+                raise TypeError(f"{slot.fallback_name} factory returned None")
+            slot.needs_stop = True
+
+            starter = getattr(slot.client, "start", None)
+            stopper = getattr(slot.client, "stop", None)
+            if not callable(starter) or not callable(stopper):
+                raise TypeError(
+                    f"{slot.fallback_name} must provide callable start() and stop()"
+                )
+
+            binder = getattr(slot.client, "bind_send_gate", None)
+            if callable(binder):
+                binder(self.pace_send, self.defer_channel)
+            identity_binder = getattr(slot.client, "bind_identity_pool", None)
+            if callable(identity_binder):
+                identity_binder(self)
+            await _maybe_await(starter())
+            slot.started = True
+            slot.healthy = True
+            slot.cooldown_until = max(
+                slot.cooldown_until,
+                self._account_cooldowns.get(slot.name, 0),
+            )
+            slot.error = None
+        except BaseException as error:
+            slot.error = error
+            slot.healthy = False
+            raise
+
+    async def _stop_materialized(
+        self,
+    ) -> tuple[tuple[str, BaseException], ...]:
+        slots = [
+            slot for slot in self._slots if slot.client is not None and slot.needs_stop
+        ]
+        results = await asyncio.gather(
+            *(self._stop_slot(slot) for slot in slots),
+            return_exceptions=True,
+        )
+        return tuple(
+            (slot.name, result)
+            for slot, result in zip(slots, results, strict=True)
+            if isinstance(result, BaseException)
+        )
+
+    async def _stop_slot(self, slot: _ClientSlot) -> None:
+        client = slot.client
+        stopped = False
+        try:
+            if client is not None:
+                stopper = getattr(client, "stop", None)
+                if callable(stopper):
+                    await _maybe_await(stopper())
+            stopped = True
+        except BaseException as error:
+            slot.error = error
+            raise
+        finally:
+            slot.started = False
+            slot.healthy = False
+            slot.active = 0
+            slot.media_active = 0
+            if stopped:
+                slot.needs_stop = False
+            if slot.is_factory and stopped:
+                slot.client = None
+
+    async def _wait_for_all_leases(self) -> None:
+        async with self._leases:
+            await self._leases.wait_for(
+                lambda: all(slot.active == 0 for slot in self._slots)
+            )
+
+    def _find_slot(self, client: TelegramClientLifecycle) -> _ClientSlot:
+        for slot in self._slots:
+            if slot.client is client:
+                return slot
+        raise ValueError("client does not belong to this pool")
+
+    @staticmethod
+    def _connected_state(client: TelegramClientLifecycle | None) -> bool | None:
+        if client is None:
+            return None
+        connected = getattr(client, "is_connected", None)
+        return connected if isinstance(connected, bool) else None
+
+    def _slot_is_healthy(self, slot: _ClientSlot) -> bool:
+        connected = self._connected_state(slot.client)
+        return slot.healthy and connected is not False
+
+
+async def current_upload_limit(settings: Settings, pool: Any) -> int:
+    """Admit logical files independently of optional Premium availability."""
+
+    return settings.upload_limit
diff --git a/tgdrive/telegram/clients.py b/tgdrive/telegram/clients.py
new file mode 100644
index 00000000..5362a980
--- /dev/null
+++ b/tgdrive/telegram/clients.py
@@ -0,0 +1,1366 @@
+"""Telethon client adapters with bounded uploads, reads, and account requests."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import hashlib
+import inspect
+import io
+import logging
+import math
+import mimetypes
+import secrets
+import time
+import weakref
+from collections import OrderedDict, deque
+from collections.abc import AsyncIterator, Awaitable, Callable
+from contextlib import suppress
+from dataclasses import dataclass, field
+from functools import partial
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+from telethon import TelegramClient, events, functions, types, utils
+from telethon.errors import (
+    FileReferenceExpiredError,
+    FileReferenceInvalidError,
+    FilerefUpgradeNeededError,
+    FloodPremiumWaitError,
+    FloodWaitError,
+    RPCError,
+)
+from telethon.sessions import StringSession
+
+from tgdrive.core.config import Settings
+from tgdrive.media.media_scheduler import MediaScheduler
+from tgdrive.telegram.client_identity import IdentityCache, account_identity
+from tgdrive.telegram.client_pool import ClientPool
+from tgdrive.telegram.connection_errors import TelegramConnectionError
+from tgdrive.transfers.file_window import FileWindow
+
+log = logging.getLogger(__name__)
+
+_DOWNLOAD_BLOCK = 1024**2
+_DOWNLOAD_REQUEST = 512 * 1024
+_DOWNLOAD_PREFETCH = 4
+
+_BLOCK_CACHE_BYTES = 24 * 1024**2
+_BLOCK_CACHE_ENTRIES = 128
+_BLOCK_CACHE_TTL = 30.0
+_BLOCK_CACHE_READS = 8
+
+
+@dataclass(slots=True)
+class _BlockFlight:
+    task: asyncio.Task[bytes] | None = None
+    waiters: int = 0
+    abandoned: bool = False
+    done: asyncio.Event = field(default_factory=asyncio.Event)
+
+
+class _BlockCache:
+    """Bounded payload LRU and shared reads; never an authorization cache."""
+
+    def __init__(
+        self,
+        *,
+        max_bytes: int = _BLOCK_CACHE_BYTES,
+        max_entries: int = _BLOCK_CACHE_ENTRIES,
+        ttl: float = _BLOCK_CACHE_TTL,
+        read_slots: int = _BLOCK_CACHE_READS,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if min(max_bytes, max_entries, ttl, read_slots) <= 0:
+            raise ValueError("Block-cache bounds must be positive")
+        self.max_bytes = max_bytes
+        self.max_entries = max_entries
+        self.ttl = ttl
+        self.clock = clock
+        self.bytes_used = 0
+        self.entries: OrderedDict[tuple[Any, ...], tuple[float, bytes]] = OrderedDict()
+        self.flights: dict[tuple[Any, ...], _BlockFlight] = {}
+        self._slots = asyncio.Semaphore(read_slots)
+
+    def _hit(self, key: tuple[Any, ...]) -> bytes | None:
+        now = self.clock()
+        for identity, (expires, data) in list(self.entries.items()):
+            if expires <= now:
+                del self.entries[identity]
+                self.bytes_used -= len(data)
+        item = self.entries.get(key)
+        if item is None:
+            return None
+        self.entries.move_to_end(key)
+        return item[1]
+
+    def _put(self, key: tuple[Any, ...], data: bytes) -> None:
+        if not data or len(data) > self.max_bytes:
+            return
+        self._hit(key)
+        old = self.entries.pop(key, None)
+        if old is not None:
+            self.bytes_used -= len(old[1])
+        while self.entries and (
+            self.bytes_used + len(data) > self.max_bytes
+            or len(self.entries) >= self.max_entries
+        ):
+            _, (_, evicted) = self.entries.popitem(last=False)
+            self.bytes_used -= len(evicted)
+        self.entries[key] = (self.clock() + self.ttl, data)
+        self.bytes_used += len(data)
+
+    async def get(
+        self,
+        key: tuple[Any, ...],
+        expected: int,
+        load: Callable[[], Awaitable[bytes]],
+    ) -> bytes:
+        while True:
+            hit = self._hit(key)
+            if hit is not None:
+                return hit
+            flight = self.flights.get(key)
+            if flight is not None and flight.abandoned:
+                # Do not join another request's cancelled read or hedge it.
+                await flight.done.wait()
+                continue
+            if flight is None:
+                await self._slots.acquire()
+                hit = self._hit(key)
+                if hit is not None:
+                    self._slots.release()
+                    return hit
+                flight = self.flights.get(key)
+                if flight is not None:
+                    self._slots.release()
+                    if flight.abandoned:
+                        await flight.done.wait()
+                        continue
+                else:
+                    flight = _BlockFlight()
+                    self.flights[key] = flight
+                    try:
+                        task = asyncio.create_task(load())
+                    except BaseException:
+                        del self.flights[key]
+                        self._slots.release()
+                        flight.done.set()
+                        raise
+                    flight.task = task
+
+                    def complete(
+                        done: asyncio.Task[bytes],
+                        owner: _BlockFlight = flight,
+                    ) -> None:
+                        try:
+                            data = done.result()
+                        except BaseException:
+                            # The awaiting consumers receive the original error.
+                            return
+                        else:
+                            if not owner.abandoned and len(data) == expected:
+                                self._put(key, data)
+                        finally:
+                            if self.flights.get(key) is owner:
+                                del self.flights[key]
+                            self._slots.release()
+                            owner.done.set()
+
+                    task.add_done_callback(complete)
+            assert flight.task is not None
+            task = flight.task
+            flight.waiters += 1
+            try:
+                return await asyncio.shield(task)
+            finally:
+                flight.waiters -= 1
+                if flight.waiters == 0 and not task.done():
+                    flight.abandoned = True
+                    task.cancel()
+                    # Keep iterator cleanup owned by the last consumer even if
+                    # its surrounding cancellation scope issues repeated cancels.
+                    while not task.done():
+                        try:
+                            await asyncio.shield(task)
+                        except asyncio.CancelledError:
+                            continue
+                        except Exception:
+                            break
+
+
+# Both keys and values are weak: a semaphore can retain its owning loop after
+# contention, so a strong cache value here would keep a closed loop alive.
+_LOOP_BLOCK_CACHES: weakref.WeakKeyDictionary[
+    asyncio.AbstractEventLoop, weakref.ReferenceType[_BlockCache]
+] = weakref.WeakKeyDictionary()
+
+
+def _client_block_cache(client: Any) -> _BlockCache:
+    loop = asyncio.get_running_loop()
+    reference = _LOOP_BLOCK_CACHES.get(loop)
+    cache = reference() if reference is not None else None
+    if cache is None:
+        cache = _BlockCache()
+        _LOOP_BLOCK_CACHES[loop] = weakref.ref(cache)
+    # Live transport clients retain their loop's cache. Finished payloads hold
+    # no clients, sessions, tokens or authorization decisions.
+    client._download_block_cache = cache
+    return cache
+
+
+def _block_identity(message: Any, index: int) -> tuple[tuple[Any, ...], int] | None:
+    native = getattr(message, "native", message)
+    target = (
+        message.download_media
+        if isinstance(message, TelegramMediaSelection)
+        else native
+    )
+    document = (
+        target
+        if isinstance(target, types.Document)
+        else getattr(target, "document", None)
+    )
+    if isinstance(document, types.Document):
+        identity = ("document", document.id, document.size)
+        size = document.size
+    else:
+        photo = (
+            target
+            if isinstance(target, types.Photo)
+            else getattr(target, "photo", None)
+        )
+        if not isinstance(photo, types.Photo) or not photo.sizes:
+            return None
+        rendition = photo.sizes[-1]
+        size = _photo_size(rendition)
+        if size is None:
+            return None
+        identity = ("photo", photo.id, rendition.type, size)
+    expected = min(_DOWNLOAD_BLOCK, max(0, size - index * _DOWNLOAD_BLOCK))
+    if not expected:
+        return None
+    return ((getattr(native, "chat_id", None), native.id, *identity, index), expected)
+
+
+def _variant_id(message: Any, identity: str) -> str:
+    native = getattr(message, "native", message)
+    value = f"{getattr(native, 'chat_id', None)}:{native.id}:{identity}".encode()
+    return "v-" + hashlib.sha256(value).hexdigest()[:24]
+
+
+def _document_info(document: Any, *, original: bool, identity: str) -> dict[str, Any]:
+    video = next(
+        (
+            item
+            for item in document.attributes
+            if isinstance(item, types.DocumentAttributeVideo)
+        ),
+        None,
+    )
+    width = video.w if video else None
+    height = video.h if video else None
+    return dict(
+        id=identity,
+        label="Original" if original else f"{height}p" if height else "Video variant",
+        width=width,
+        height=height,
+        duration=video.duration if video else None,
+        size=document.size,
+        mime_type=document.mime_type,
+        is_original=original,
+    )
+
+
+def _photo_size(size: Any) -> int | None:
+    if isinstance(size, types.PhotoSize):
+        return size.size
+    if isinstance(size, types.PhotoSizeProgressive):
+        return max(size.sizes, default=0)
+    if isinstance(size, types.PhotoCachedSize):
+        return len(size.bytes)
+    return None
+
+
+def _media_options(message: Any) -> list[tuple[dict[str, Any], Any]]:
+    native = getattr(message, "native", message)
+    document = getattr(native, "document", None)
+    if isinstance(document, types.Document):
+        options = [
+            (_document_info(document, original=True, identity="original"), native)
+        ]
+        for alternate in (
+            getattr(getattr(native, "media", None), "alt_documents", None) or []
+        ):
+            if not isinstance(alternate, types.Document) or alternate.id == document.id:
+                continue
+            identity = _variant_id(message, f"document:{alternate.id}")
+            options.append(
+                (
+                    _document_info(alternate, original=False, identity=identity),
+                    alternate,
+                )
+            )
+        return options
+    photo = getattr(native, "photo", None)
+    if not isinstance(photo, types.Photo):
+        return []
+    sizes = [size for size in photo.sizes if _photo_size(size)]
+    if not sizes:
+        return []
+    options = []
+    for index, size in enumerate(reversed(sizes)):
+        original = index == 0
+        identity = (
+            "original"
+            if original
+            else _variant_id(message, f"photo:{photo.id}:{size.type}")
+        )
+        selected = copy.copy(photo)
+        selected.sizes = [size]
+        info = dict(
+            id=identity,
+            label="Original" if original else f"{size.w}x{size.h}",
+            width=size.w,
+            height=size.h,
+            duration=None,
+            size=_photo_size(size),
+            mime_type="image/jpeg",
+            is_original=original,
+        )
+        options.append((info, selected))
+    return options
+
+
+class TelegramMediaSelection:
+    """A selected rendition tied to its source message, without changing storage."""
+
+    def __init__(self, message: Any, descriptor: dict[str, Any], media: Any) -> None:
+        self.source_message = getattr(message, "source_message", message)
+        self.native = getattr(message, "native", message)
+        self.variant_id = descriptor["id"]
+        self.download_media = media
+        self.id = self.native.id
+        metadata = SimpleNamespace(
+            file_size=descriptor["size"],
+            file_name=None,
+            mime_type=descriptor["mime_type"],
+        )
+        self.photo = metadata if isinstance(media, types.Photo) else None
+        self.document = metadata if self.photo is None else None
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.native, name)
+
+
+class TelegramMessage:
+    def __init__(self, client: Client, message: Any) -> None:
+        self._client = client
+        self.native = message
+        self.id = message.id
+        self.empty = False
+        self.from_user = SimpleNamespace(id=message.sender_id)
+        self.text = message.raw_text or ""
+        self.command = self.text.split()
+        self.photo = None
+        self.document = None
+        self.media = SimpleNamespace(value="photo" if message.photo else "document")
+        if message.file:
+            media = SimpleNamespace(
+                file_size=message.file.size, file_name=message.file.name
+            )
+            if message.photo:
+                self.photo = media
+            else:
+                self.document = media
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.native, name)
+
+    async def reply_text(self, text: str, reply_markup: Any = None) -> Any:
+        sent = await self.native.reply(text, buttons=reply_markup, parse_mode=None)
+        return TelegramMessage(self._client, sent)
+
+    async def edit_text(self, text: str, reply_markup: Any = None) -> Any:
+        return await self.native.edit(text, buttons=reply_markup, parse_mode=None)
+
+    async def copy(self, channel: int, **_kwargs: Any) -> Any:
+        identity = f"{channel}:{self.native.chat_id}:{self.id}".encode()
+        random_id = int.from_bytes(
+            hashlib.blake2b(identity, digest_size=8).digest(), "big", signed=True
+        )
+        return await self._client.copy_media(channel, self.native, random_id=random_id)
+
+
+class Client:
+    """Adapt one Telegram account to the pool's transfer and media operations."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        settings: Settings,
+        bot_token: str | None = None,
+        session_string: str | None = None,
+        updates: bool = False,
+    ) -> None:
+        self._thumbnail_directory = settings.resolved_cache_dir / "thumbnails"
+        self._token = bot_token
+        self._upload_pipeline = getattr(settings, "telegram_upload_pipeline", 4)
+        self._media_scheduler = MediaScheduler(
+            limit=getattr(settings, "telegram_request_limit", 8),
+            rate=getattr(settings, "telegram_parts_per_second", 48),
+        )
+        self._premium = bool(session_string)
+        self.display_name: str | None = None
+        self.username: str | None = None
+        self._identity_cache = IdentityCache(settings.resolved_data_dir)
+        self._identity_task: asyncio.Task | None = None
+        self._identity_pool = None
+        self._identity_next_refresh = 0.0
+        self.identity_retry_at: float | None = None
+        if bot_token:
+            identity = bot_token.split(":", 1)[0]
+            prefix = "bot-mode" if updates else "storage-bot"
+            self.name = f"{prefix}-{identity}"
+        elif session_string:
+            identity = hashlib.sha256(session_string.encode()).hexdigest()[:24]
+            self.name = f"premium-session-{identity}"
+        else:
+            self.name = name
+        directory = settings.resolved_data_dir / "sessions"
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        session = (
+            StringSession(session_string)
+            if session_string
+            else str(directory / self.name)
+        )
+        self.native = TelegramClient(
+            session,
+            settings.api_id,
+            settings.api_hash.get_secret_value(),
+            receive_updates=updates,
+            flood_sleep_threshold=0,
+            request_retries=2,
+            connection_retries=3,
+            timeout=20,
+            auto_reconnect=True,
+        )
+        self.native.parse_mode = None
+
+    @property
+    def is_connected(self) -> bool:
+        return self.native.is_connected()
+
+    async def start(self) -> None:
+        await self.native.connect()
+        try:
+            if not await self.native.is_user_authorized():
+                if not self._token:
+                    raise TelegramConnectionError(
+                        "This Premium session is no longer authorized. Open "
+                        "Connections and sign in to the same account again, then "
+                        "restart TGDrive and retry.",
+                        "TELEGRAM_CREDENTIALS_REVOKED",
+                        client_name=self.name,
+                    )
+                await self.native.sign_in(bot_token=self._token)
+            me = await self.native.get_me()
+            if me is None:
+                raise RuntimeError("Telegram did not confirm the authenticated account")
+            if self._token:
+                expected_id = int(self._token.split(":", 1)[0])
+                if not me.bot or me.id != expected_id:
+                    raise RuntimeError("Telegram bot session identity mismatch")
+            elif self._premium:
+                if me.bot or not me.premium:
+                    raise RuntimeError(
+                        "Configured Premium session is not a Premium user account"
+                    )
+                self.name = f"premium-user-{me.id}"
+            session_name = getattr(self.native.session, "filename", None)
+            if session_name:
+                await asyncio.to_thread(Path(session_name).chmod, 0o600)
+            if isinstance(self.native, TelegramClient):
+                await self._refresh_main_endpoint()
+            self._start_identity_refresh(seed=me)
+        except BaseException:
+            await self.native.disconnect()
+            raise
+
+    async def _refresh_main_endpoint(self) -> None:
+        """Refresh a stale same-DC address only during startup, with rollback.
+
+        Never choose media-only endpoints for the main RPC connection. Telethon
+        continues to own exported senders and migration for file downloads.
+        """
+        session = self.native.session
+        if not all(
+            hasattr(session, name) for name in ("dc_id", "server_address", "port")
+        ):
+            return
+        previous = (session.dc_id, session.server_address, session.port)
+        try:
+            async with asyncio.timeout(8):
+                config = await self.native(functions.help.GetConfigRequest())
+            options = [
+                option
+                for option in config.dc_options
+                if option.id == previous[0]
+                and not option.media_only
+                and not option.cdn
+                and bool(option.ipv6) == (":" in previous[1])
+                and not getattr(option, "tcpo_only", False)
+            ]
+        except OSError, RPCError, TimeoutError:
+            return  # A failed optional refresh cannot prevent startup.
+        if not options:
+            return
+        selected = options[0]
+        replacement = (previous[0], selected.ip_address, selected.port)
+        if replacement == previous:
+            return
+        await self.native.disconnect()
+        try:
+            session.set_dc(*replacement)
+            session.save()
+            async with asyncio.timeout(15):
+                await self.native.connect()
+                if not await self.native.is_user_authorized():
+                    raise RuntimeError("Refreshed Telegram endpoint lost authorization")
+        except BaseException as error:
+            await self.native.disconnect()
+            session.set_dc(*previous)
+            session.save()
+            await self.native.connect()
+            if isinstance(error, asyncio.CancelledError):
+                raise
+            log.warning("Telegram endpoint refresh failed; restored previous address")
+
+    def configure_transport(
+        self, *, upload_pipeline: int, request_limit: int, parts_per_second: float
+    ) -> None:
+        if type(upload_pipeline) is not int or not 1 <= upload_pipeline <= 16:
+            raise ValueError("Upload pipeline must be between 1 and 16")
+        self._media_scheduler.configure(limit=request_limit, rate=parts_per_second)
+        self._upload_pipeline = upload_pipeline
+
+    @property
+    def identity_refreshing(self) -> bool:
+        return self._identity_task is not None and not self._identity_task.done()
+
+    def bind_identity_pool(self, pool: Any) -> None:
+        self._identity_pool = pool
+
+    def refresh_identity(self) -> None:
+        if self.identity_refreshing or time.monotonic() < self._identity_next_refresh:
+            return
+        self._identity_next_refresh = time.monotonic() + 5
+        self._start_identity_refresh()
+
+    def _start_identity_refresh(self, *, seed: Any = None) -> None:
+        if not self.identity_refreshing:
+            self._identity_task = asyncio.create_task(self._refresh_identity(seed))
+
+    async def _refresh_identity(self, seed: Any) -> None:
+        delay = 5.0
+        try:
+            deadline = await asyncio.to_thread(self._identity_cache.retry_at, self.name)
+        except Exception:
+            deadline = 0.0
+        if seed is not None:
+            try:
+                saved = await asyncio.to_thread(self._identity_cache.read, self.name)
+                if saved and any(saved.values()):
+                    self.display_name, self.username = (
+                        saved["display_name"],
+                        saved["username"],
+                    )
+                    if deadline <= time.time():
+                        return
+            except Exception:
+                saved = None  # The optional cache cannot prevent client startup.
+        if deadline > time.time():
+            self.identity_retry_at = deadline
+            if self._identity_pool is not None:
+                await self._identity_pool.defer_client(self.name, deadline)
+            await self._wait_identity_retry(deadline - time.time())
+            seed = None
+        while True:
+            self.identity_retry_at = None
+            try:
+                if seed is None:
+                    if self._identity_pool is None:
+                        async with asyncio.timeout(8):
+                            account = await self.native.get_me()
+                    else:
+                        async with (
+                            self._identity_pool.lease(
+                                client_name=self.name, premium=self._premium
+                            ),
+                            asyncio.timeout(8),
+                        ):
+                            account = await self.native.get_me()
+                else:
+                    account = seed
+                expected_id = int(self.name.rsplit("-", 1)[1])
+                if (
+                    account is None
+                    or account.id != expected_id
+                    or bool(account.bot) != bool(self._token)
+                ):
+                    raise ValueError("Telegram identity does not match this client")
+                identity = account_identity(account)
+                if not any(identity.values()):
+                    raise ValueError("Telegram name is unavailable")
+                self.display_name, self.username = (
+                    identity["display_name"],
+                    identity["username"],
+                )
+                # A failed optional cache write retries without repeating Telegram RPCs.
+                seed = account
+                await asyncio.to_thread(self._identity_cache.write, self.name, identity)
+                return
+            except asyncio.CancelledError:
+                raise
+            except FloodWaitError as error:
+                wait = max(delay, float(error.seconds) + 0.25)
+                deadline = time.time() + wait
+                with suppress(Exception):
+                    await asyncio.to_thread(
+                        self._identity_cache.defer, self.name, deadline
+                    )
+                if self._identity_pool is not None:
+                    await self._identity_pool.defer_client(self.name, deadline)
+                seed = None
+            except Exception:
+                wait = delay
+                if seed is not None and not (self.display_name or self.username):
+                    seed = None
+            self.identity_retry_at = time.time() + wait
+            await self._wait_identity_retry(wait)
+            delay = min(delay * 2, 300)
+
+    async def _wait_identity_retry(self, delay: float) -> None:
+        await asyncio.sleep(delay)
+
+    async def stop(self) -> None:
+        if self._identity_task is not None:
+            self._identity_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await self._identity_task
+            self._identity_task = None
+        self.identity_retry_at = None
+        await self.native.disconnect()
+
+    async def _defer_read(self, error: FloodWaitError | FloodPremiumWaitError) -> None:
+        deadline = time.time() + max(1, error.seconds) + 0.25
+        pool = getattr(self, "_identity_pool", None)
+        if pool is not None:
+            await pool.defer_client(self.name, deadline)
+        cache = getattr(self, "_identity_cache", None)
+        if cache is not None:
+            with suppress(Exception):
+                await asyncio.to_thread(cache.defer, self.name, deadline)
+
+    async def get_messages(self, channel: int, *, message_ids: Any) -> Any:
+        scheduler = getattr(self, "_media_scheduler", None)
+        try:
+            if scheduler is None:
+                result = await self.native.get_messages(channel, ids=message_ids)
+            else:
+                async with scheduler.request():
+                    result = await self.native.get_messages(channel, ids=message_ids)
+        except FloodWaitError as error:
+            if scheduler is not None:
+                await scheduler.flood(max(1, error.seconds) + 0.25)
+            await self._defer_read(error)
+            raise
+        if isinstance(result, list):
+            return [TelegramMessage(self, item) if item else None for item in result]
+        return TelegramMessage(self, result) if result else None
+
+    async def _sent(self, channel: int, result: Any) -> TelegramMessage:
+        if any(
+            isinstance(item, types.UpdateNewScheduledMessage)
+            or getattr(
+                getattr(item, "message", None), "video_processing_pending", False
+            )
+            for item in result.updates
+        ):
+            raise RuntimeError(
+                "Telegram is processing scheduled media; no delivered storage "
+                "message has been confirmed. Preserve the source for recovery."
+            )
+        message_id = next(
+            (
+                item.id
+                for item in result.updates
+                if isinstance(item, types.UpdateMessageID)
+            ),
+            None,
+        )
+        if message_id is None:
+            message_id = next(
+                (
+                    item.message.id
+                    for item in result.updates
+                    if hasattr(item, "message")
+                ),
+                None,
+            )
+        if message_id is None:
+            raise RuntimeError(
+                "Telegram has not confirmed the storage message; "
+                "retry the same operation"
+            )
+        message = await self.get_messages(channel, message_ids=message_id)
+        if message is None:
+            raise RuntimeError(
+                "Telegram confirmed a message that cannot yet be fetched"
+            )
+        return message
+
+    supports_generated_thumbnails = True
+
+    def bind_send_gate(
+        self,
+        gate: Callable[[int], Awaitable[None]],
+        defer_channel: Callable[[float], Awaitable[None]] | None = None,
+    ) -> None:
+        self._send_gate = gate
+        self._defer_channel = defer_channel
+
+    async def _publish(self, channel: int, request: Any) -> Any:
+        gate = getattr(self, "_send_gate", None)
+        if gate is not None:
+            await gate(channel)
+        try:
+            return await self.native(request)
+        except FloodWaitError as exc:
+            # Save*Part FloodWait happens before this boundary and is account-scoped.
+            # SendMedia may be channel-scoped: every writer observes this cooldown.
+            exc.tgdrive_channel_flood = True
+            defer = getattr(self, "_defer_channel", None)
+            if defer is not None:
+                await defer(time.time() + exc.seconds + 0.25)
+            raise
+
+    async def send_staged(
+        self,
+        channel: int,
+        path: Path,
+        *,
+        file_name: str,
+        random_id: int,
+        progress: Any = None,
+        caption: str = "",
+        offset: int = 0,
+        size: int | None = None,
+        expected_sha256: str | None = None,
+        before_dispatch: Callable[[], Awaitable[None]] | None = None,
+        preview_name: str | None = None,
+    ) -> TelegramMessage:
+        length = (
+            (await asyncio.to_thread(path.stat)).st_size - offset
+            if size is None
+            else size
+        )
+        from tgdrive.media.generated_thumbnails import generate, save
+
+        cover = await generate(path, preview_name or file_name) if offset == 0 else None
+        with FileWindow(path, offset, length, name=file_name) as source:
+            uploaded = await self._upload_parts(
+                source, length=length, file_name=file_name, progress=progress
+            )
+            if expected_sha256 is not None:
+                source.verify(expected_sha256)
+        thumbnail = None
+        if cover:
+            try:
+                async with asyncio.timeout(4):
+
+                    class CoverSource(io.BytesIO):
+                        def verify(self, _expected):
+                            pass
+
+                    thumbnail = await self._upload_parts(
+                        CoverSource(cover),
+                        length=len(cover),
+                        file_name="thumbnail.jpg",
+                        progress=None,
+                    )
+            except OSError, TimeoutError, RPCError:
+                pass  # A failed optional thumbnail must not fail the original.
+        media = types.InputMediaUploadedDocument(
+            file=uploaded,
+            thumb=thumbnail,
+            mime_type=mimetypes.guess_type(file_name)[0] or "application/octet-stream",
+            attributes=[types.DocumentAttributeFilename(file_name)],
+            force_file=True,
+        )
+        peer = await self.native.get_input_entity(channel)
+        gate = getattr(self, "_send_gate", None)
+        if gate is not None:
+            await gate(channel)
+        if before_dispatch is not None:
+            await before_dispatch()
+        # Gate was consumed above so the durable boundary is immediately before RPC.
+        try:
+            result = await self.native(
+                functions.messages.SendMediaRequest(
+                    peer=peer,
+                    media=media,
+                    message=caption,
+                    random_id=random_id,
+                    silent=True,
+                )
+            )
+        except FloodWaitError as exc:
+            exc.tgdrive_channel_flood = True
+            defer = getattr(self, "_defer_channel", None)
+            if defer is not None:
+                await defer(time.time() + exc.seconds + 0.25)
+            raise
+        except RPCError as exc:
+            if thumbnail is None or "THUMB" not in str(exc).upper():
+                raise
+            media.thumb = None
+            result = await self._publish(
+                channel,
+                functions.messages.SendMediaRequest(
+                    peer=peer,
+                    media=media,
+                    message=caption,
+                    random_id=random_id,
+                    silent=True,
+                ),
+            )
+        message = await self._sent(channel, result)
+        directory = getattr(self, "_thumbnail_directory", None)
+        if cover and directory is not None:
+            with suppress(OSError):
+                await asyncio.to_thread(save, directory, channel, message.id, cover)
+        return message
+
+    async def _upload_parts(
+        self, source: FileWindow, *, length: int, file_name: str, progress: Any
+    ) -> Any:
+        """Pipeline bounded idempotent protocol parts; publish only after all ACKs."""
+        part_size = 512 * 1024
+        part_count = math.ceil(length / part_size)
+        file_id = secrets.randbits(63)
+        big = length > 10 * 1024 * 1024
+        digest = hashlib.md5(usedforsecurity=False) if not big else None
+        pending: set[asyncio.Task[int]] = set()
+        acknowledged = 0
+
+        async def send(request: Any, count: int) -> int:
+            attempt = 0
+            while True:
+                try:
+                    async with self._media_scheduler.request():
+                        accepted = await self.native(request)
+                        if not accepted:
+                            raise OSError(
+                                "Telegram did not acknowledge the upload part"
+                            )
+                    self._media_scheduler.record_bytes(count, upload=True)
+                    return count
+                except (FloodWaitError, FloodPremiumWaitError) as error:
+                    await self._media_scheduler.flood(max(1, error.seconds) + 0.25)
+                    await self._defer_read(error)
+                    # The shared scheduler, not each worker, observes the wait.
+                    # Flood waits do not consume the transient network retry
+                    # budget or discard successfully acknowledged sibling parts.
+                except (OSError, TimeoutError, RPCError) as error:
+                    if isinstance(error, RPCError) and getattr(error, "code", 0) < 500:
+                        raise
+                    attempt += 1
+                    if attempt >= 3:
+                        raise
+                    await asyncio.sleep(0.25 * (2 ** (attempt - 1)))
+
+        async def collect() -> None:
+            nonlocal pending, acknowledged
+            done, pending = await asyncio.wait(
+                pending, return_when=asyncio.FIRST_COMPLETED
+            )
+            # Retrieve every outcome even if another completed part failed.
+            results = await asyncio.gather(*done, return_exceptions=True)
+            for result in results:
+                if isinstance(result, BaseException):
+                    raise result
+                acknowledged += result
+            if progress is not None:
+                value = progress(acknowledged, length)
+                if inspect.isawaitable(value):
+                    await value
+
+        try:
+            for index in range(part_count):
+                if len(pending) >= self._upload_pipeline:
+                    await collect()
+                read = asyncio.create_task(asyncio.to_thread(source.read, part_size))
+                try:
+                    payload = await asyncio.shield(read)
+                except asyncio.CancelledError:
+                    # FileWindow must outlive an already running filesystem read.
+                    await read
+                    raise
+                expected = min(part_size, length - index * part_size)
+                if len(payload) != expected:
+                    raise OSError("Staged file ended before the declared upload length")
+                if digest is not None:
+                    digest.update(payload)
+                request = (
+                    functions.upload.SaveBigFilePartRequest(
+                        file_id=file_id,
+                        file_part=index,
+                        file_total_parts=part_count,
+                        bytes=payload,
+                    )
+                    if big
+                    else functions.upload.SaveFilePartRequest(
+                        file_id=file_id,
+                        file_part=index,
+                        bytes=payload,
+                    )
+                )
+                pending.add(asyncio.create_task(send(request, len(payload))))
+            while pending:
+                await collect()
+            source.verify(None)
+        finally:
+            for task in pending:
+                task.cancel()
+            if pending:
+                await asyncio.gather(*pending, return_exceptions=True)
+        if big:
+            return types.InputFileBig(id=file_id, parts=part_count, name=file_name)
+        return types.InputFile(
+            id=file_id,
+            parts=part_count,
+            name=file_name,
+            md5_checksum=digest.hexdigest(),
+        )
+
+    async def send_document(
+        self, channel: int, document: Any, **options: Any
+    ) -> TelegramMessage:
+        path = Path(document if isinstance(document, (str, Path)) else document.name)
+        return await self.send_staged(
+            channel,
+            path,
+            file_name=options.get("file_name", path.name),
+            random_id=options.get("random_id", secrets.randbits(63)),
+            progress=options.get("progress"),
+            **(
+                {"caption": options.get("caption") or ""}
+                if "caption" in options
+                else {}
+            ),
+        )
+
+    async def copy_media(
+        self, channel: int, message: Any, *, random_id: int
+    ) -> TelegramMessage:
+        result = await self._publish(
+            channel,
+            functions.messages.SendMediaRequest(
+                peer=await self.native.get_input_entity(channel),
+                media=utils.get_input_media(message.media),
+                message=message.raw_text or "",
+                random_id=random_id,
+                silent=True,
+            ),
+        )
+        return await self._sent(channel, result)
+
+    async def get_pinned_message_id(self, channel: int) -> int | None:
+        """Discover the channel's latest pin without bot-prohibited history/search."""
+        peer = await self.native.get_input_entity(channel)
+        result = await self.native(
+            functions.channels.GetFullChannelRequest(utils.get_input_channel(peer))
+        )
+        identity = getattr(result.full_chat, "pinned_msg_id", None)
+        if identity is not None and (type(identity) is not int or identity <= 0):
+            raise RuntimeError("Telegram returned an invalid pinned message identity")
+        return identity
+
+    async def storage_channel_problem(
+        self, channel: int, *, require_pin: bool
+    ) -> tuple[str, str] | None:
+        """Read current retention, privacy and bot rights without changing messages."""
+        from tgdrive.telegram.channel_state import (
+            storage_bot_rights_problem,
+            storage_channel_problem,
+        )
+
+        peer = await self.native.get_input_entity(channel)
+        result = await self.native(
+            functions.channels.GetFullChannelRequest(utils.get_input_channel(peer))
+        )
+        chat = next(
+            (item for item in result.chats if utils.get_peer_id(item) == channel),
+            None,
+        )
+        return storage_channel_problem(
+            chat, result.full_chat
+        ) or storage_bot_rights_problem(chat, require_pin=require_pin)
+
+    async def pin_message(
+        self, channel: int, message_id: int, *, silent: bool = True
+    ) -> Any:
+        """Pin a known message; channel administrators require edit_messages."""
+        if type(message_id) is not int or message_id <= 0:
+            raise ValueError("Pinned message identity must be a positive integer")
+        return await self.native(
+            functions.messages.UpdatePinnedMessageRequest(
+                peer=await self.native.get_input_entity(channel),
+                id=message_id,
+                silent=silent,
+            )
+        )
+
+    async def delete_messages(self, channel: int, message_ids: Any) -> Any:
+        return await self.native.delete_messages(channel, message_ids, revoke=True)
+
+    async def download_media(self, message: Any, *, file_name: str) -> Any:
+        return await self.native.download_media(
+            getattr(message, "native", message), file=file_name
+        )
+
+    async def download_thumbnail(
+        self,
+        message: Any,
+        *,
+        max_bytes: int = 128 * 1024,
+        target_size: int = 320,
+        max_dimension: int = 640,
+    ) -> bytes | None:
+        """Read one advertised image thumbnail; never download the document.
+
+        Telegram's regular download_media defaults to the entire original when
+        no thumbnail is supplied. Build an explicit thumbnail location instead,
+        reject oversized advertised sizes, and bound even a malformed response.
+        Animated/video thumbnails and SVG sticker outlines are not requested.
+        """
+        native = getattr(message, "native", message)
+        document = getattr(native, "document", None)
+        photo = getattr(native, "photo", None)
+        if isinstance(document, types.Document):
+            media, sizes = document, document.thumbs or []
+            location_type = types.InputDocumentFileLocation
+        elif isinstance(photo, types.Photo):
+            media, sizes = photo, photo.sizes
+            location_type = types.InputPhotoFileLocation
+        else:
+            return None
+        max_bytes = min(max_bytes, 128 * 1024)
+        max_dimension = min(max_dimension, 640)
+        choices = []
+        stripped = []
+        for size in sizes:
+            if isinstance(size, types.PhotoStrippedSize):
+                if 0 < len(size.bytes) <= max_bytes:
+                    stripped.append(size)
+                continue
+            if not isinstance(
+                size,
+                (types.PhotoSize, types.PhotoSizeProgressive, types.PhotoCachedSize),
+            ):
+                continue
+            amount = _photo_size(size)
+            dimension = max(size.w, size.h)
+            if (
+                amount is not None
+                # An empty document thumb selector requests the original.
+                and isinstance(size.type, str)
+                and bool(size.type)
+                and 0 < amount <= max_bytes
+                and min(size.w, size.h) > 0
+                and dimension <= max_dimension
+            ):
+                choices.append((size, dimension, amount))
+        if not choices:
+            if stripped:
+                result = utils.stripped_photo_to_jpg(stripped[0].bytes)
+                return result if 0 < len(result) <= max_bytes else None
+            return None
+        # Prefer the smallest rendition which fills a 320px tile. If none
+        # reaches that size, use the largest smaller rendition, never original.
+        selected, _dimension, _amount = min(
+            choices,
+            key=lambda choice: (
+                choice[1] < target_size,
+                abs(choice[1] - target_size),
+                choice[2],
+            ),
+        )
+        if isinstance(selected, types.PhotoCachedSize):
+            return selected.bytes
+        location = location_type(
+            id=media.id,
+            access_hash=media.access_hash,
+            file_reference=media.file_reference,
+            thumb_size=selected.type,
+        )
+        request_size = 32 * 1024
+        iterator = self.native.iter_download(
+            location,
+            request_size=request_size,
+            chunk_size=request_size,
+            limit=(max_bytes + request_size - 1) // request_size + 1,
+            dc_id=media.dc_id,
+        )
+        data = bytearray()
+        scheduler = getattr(self, "_media_scheduler", None)
+        try:
+            while True:
+                if scheduler is None:
+                    part = await anext(iterator, None)
+                else:
+                    async with scheduler.request():
+                        part = await anext(iterator, None)
+                    if part is not None:
+                        scheduler.record_bytes(len(part))
+                if part is None:
+                    break
+                if len(data) + len(part) > max_bytes:
+                    return None
+                data.extend(part)
+            return bytes(data) or None
+        except (FloodWaitError, FloodPremiumWaitError) as error:
+            if scheduler is not None:
+                await scheduler.flood(max(1, error.seconds) + 0.25)
+            await self._defer_read(error)
+            raise
+        finally:
+            await iterator.close()
+
+    @staticmethod
+    def describe_media(message: Any) -> dict[str, Any]:
+        options = _media_options(message)
+        return {
+            "original": options[0][0] if options else None,
+            "variants": [descriptor for descriptor, _ in options[1:]],
+        }
+
+    @staticmethod
+    def select_media_variant(message: Any, quality_id: str | None) -> Any:
+        if quality_id in {None, "original"}:
+            return getattr(message, "source_message", message)
+        for descriptor, media in _media_options(message):
+            if descriptor["id"] == quality_id:
+                return TelegramMediaSelection(message, descriptor, media)
+        raise ValueError("The requested media quality is unavailable for this file")
+
+    supports_uncached_media = True
+
+    async def stream_media(
+        self, message: Any, *, limit: int, offset: int, use_cache: bool = True
+    ) -> AsyncIterator[bytes]:
+        """Yield ordered MiB blocks with at most four windows of read-ahead."""
+        if limit <= 0:
+            return
+        if offset < 0:
+            raise ValueError("Download offset cannot be negative")
+        refreshed = 0
+        generation = 0
+        refresh_lock = asyncio.Lock()
+        selection_id = getattr(message, "variant_id", None)
+
+        def media_identity(value: Any) -> tuple[str, int] | None:
+            native = getattr(value, "native", value)
+            for kind in ("document", "photo"):
+                media = getattr(native, kind, None)
+                if media is not None:
+                    return kind, media.id
+            return None
+
+        original_identity = media_identity(message)
+
+        async def read_remote_block(index: int) -> bytes:
+            nonlocal message, refreshed, generation
+            data = bytearray()
+            while len(data) < _DOWNLOAD_BLOCK:
+                version = generation
+                # Real Telethon messages also have a download_media method.
+                # Only our explicit selection wrapper owns a rendition target.
+                target = (
+                    message.download_media
+                    if isinstance(message, TelegramMediaSelection)
+                    else getattr(message, "native", message)
+                )
+                iterator = self.native.iter_download(
+                    target,
+                    offset=index * _DOWNLOAD_BLOCK + len(data),
+                    request_size=_DOWNLOAD_REQUEST,
+                    limit=(_DOWNLOAD_BLOCK - len(data) + _DOWNLOAD_REQUEST - 1)
+                    // _DOWNLOAD_REQUEST,
+                )
+                try:
+                    while len(data) < _DOWNLOAD_BLOCK:
+                        scheduler = getattr(self, "_media_scheduler", None)
+                        if scheduler is None:
+                            try:
+                                part = await anext(iterator)
+                            except StopAsyncIteration:
+                                break
+                        else:
+                            async with scheduler.request():
+                                try:
+                                    part = await anext(iterator)
+                                except StopAsyncIteration:
+                                    part = None
+                            if part is None:
+                                break
+                            scheduler.record_bytes(len(part))
+                        data.extend(part[: _DOWNLOAD_BLOCK - len(data)])
+                        if len(data) == _DOWNLOAD_BLOCK:
+                            break
+                    return bytes(data)
+                except (FloodWaitError, FloodPremiumWaitError) as error:
+                    scheduler = getattr(self, "_media_scheduler", None)
+                    if scheduler is not None:
+                        await scheduler.flood(max(1, error.seconds) + 0.25)
+                    await self._defer_read(error)
+                    raise
+                except (
+                    FileReferenceExpiredError,
+                    FileReferenceInvalidError,
+                    FilerefUpgradeNeededError,
+                ):
+                    async with refresh_lock:
+                        if version == generation:
+                            if refreshed >= 2:
+                                raise
+                            refreshed += 1
+                            native = getattr(message, "native", message)
+                            fresh = await self.get_messages(
+                                native.chat_id, message_ids=native.id
+                            )
+                            if fresh is None:
+                                raise FileNotFoundError(
+                                    "Stored Telegram message was removed"
+                                ) from None
+                            if (
+                                original_identity is not None
+                                and media_identity(fresh) != original_identity
+                            ):
+                                raise FileNotFoundError(
+                                    "Stored Telegram media was replaced"
+                                ) from None
+                            message = self.select_media_variant(fresh, selection_id)
+                            generation += 1
+                finally:
+                    await iterator.close()
+            return bytes(data)
+
+        async def read_block(index: int) -> bytes:
+            if not use_cache:
+                return await read_remote_block(index)
+            identity = _block_identity(message, index)
+            if identity is None:
+                return await read_remote_block(index)
+            media_key, expected = identity
+            cache = _client_block_cache(self)
+            key = (id(self), getattr(self, "name", None), *media_key)
+            return await cache.get(key, expected, lambda: read_remote_block(index))
+
+        pending: deque[asyncio.Task[bytes]] = deque()
+        tasks: set[asyncio.Task[bytes]] = set()
+        next_index = offset
+        end = offset + limit
+
+        def schedule() -> None:
+            nonlocal next_index
+            task = asyncio.create_task(read_block(next_index))
+            pending.append(task)
+            tasks.add(task)
+            next_index += 1
+
+        for _ in range(min(_DOWNLOAD_PREFETCH, limit)):
+            schedule()
+        try:
+            while pending:
+                task = pending.popleft()
+                data = await task
+                tasks.discard(task)
+                if not data:
+                    return
+                yield data
+                if len(data) < _DOWNLOAD_BLOCK:
+                    return
+                if next_index < end:
+                    schedule()
+        finally:
+            for task in tasks:
+                task.cancel()
+            if tasks:
+                await asyncio.gather(*tasks, return_exceptions=True)
+
+    def register_bot(self, mode: Any) -> None:
+        async def dispatch(event: Any) -> None:
+            if (
+                not event.is_private
+                or event.sender_id not in mode.settings.telegram_admin_ids
+            ):
+                return
+            message = TelegramMessage(self, event.message)
+            words = message.text.split()
+            command = words[0].split("@")[0].lower() if words else ""
+            label = message.text.strip().casefold()
+            if message.document or message.photo:
+                await mode._file(self, message)
+            elif command in {"/start", "/help"} or label == "help":
+                await mode._help(self, message)
+            elif command in {"/set_folder", "/folders"} or label == "choose folder":
+                await mode._set_folder(self, message)
+            elif command == "/current_folder" or label == "current folder":
+                await mode._current_folder(self, message)
+            elif command == "/cancel":
+                await mode._cancel(self, message)
+            else:
+                await mode._folder_query(self, message)
+
+        self.native.add_event_handler(dispatch, events.NewMessage(incoming=True))
+
+
+def build_client_pool(settings: Settings) -> ClientPool:
+    """Create lazy client factories with the configured account admission limits."""
+    return ClientPool(
+        bot_clients=[
+            partial(
+                Client, name=f"storage-bot-{index}", settings=settings, bot_token=token
+            )
+            for index, token in enumerate(settings.bot_tokens, 1)
+        ],
+        user_clients=[
+            partial(
+                Client,
+                name=f"premium-user-{index}",
+                settings=settings,
+                session_string=session,
+            )
+            for index, session in enumerate(settings.string_sessions, 1)
+        ],
+        allow_partial_start=True,
+        media_send_interval=1.0,
+        uploads_per_bot=settings.telegram_uploads_per_bot,
+        media_cache_dir=settings.resolved_data_dir / "media-cache",
+        media_per_bot=getattr(settings, "telegram_media_per_bot", 3),
+        max_media_queue=getattr(settings, "telegram_max_queue", 256),
+    )
+
+
+def build_bot_mode_client(settings: Settings) -> Client | None:
+    """Create the separate update-receiving bot only when bot mode is configured."""
+    token = settings.main_bot_token_value
+    if not token:
+        return None
+    return Client(
+        name="tgdrive-main-bot", settings=settings, bot_token=token, updates=True
+    )
diff --git a/tgdrive/telegram/connection_errors.py b/tgdrive/telegram/connection_errors.py
new file mode 100644
index 00000000..06c2a974
--- /dev/null
+++ b/tgdrive/telegram/connection_errors.py
@@ -0,0 +1,79 @@
+"""Safe, actionable errors for Telegram accounts that need owner attention."""
+
+from __future__ import annotations
+
+
+class TelegramConnectionError(RuntimeError):
+    def __init__(self, detail: str, code: str, *, client_name: str | None = None):
+        super().__init__(detail)
+        self.code = code
+        self.client_name = client_name
+
+
+_CREDENTIAL_ERRORS = {
+    "AccessTokenExpiredError",
+    "AccessTokenInvalidError",
+    "AuthKeyUnregisteredError",
+    "AuthKeyInvalidError",
+    "AuthKeyDuplicatedError",
+    "SessionRevokedError",
+    "SessionExpiredError",
+    "UserDeactivatedError",
+    "UserDeactivatedBanError",
+    "TokenExpiredError",
+    "TokenInvalidError",
+    "UnauthorizedError",
+}
+_CHANNEL_ERRORS = {
+    "ChannelPrivateError",
+    "ChannelInvalidError",
+    "ChatAdminRequiredError",
+    "UserNotParticipantError",
+    "ChatWriteForbiddenError",
+    "ChatForbiddenError",
+    "UserBannedInChannelError",
+}
+
+
+def connection_problem(
+    error: BaseException | None, kind: str, *, client_name: str | None = None
+) -> TelegramConnectionError | None:
+    """Classify provider failures without returning raw RPC text or credentials."""
+    if isinstance(error, TelegramConnectionError):
+        return error
+    name = type(error).__name__
+    account = "storage bot" if kind == "bot" else "Premium account"
+    if name in _CREDENTIAL_ERRORS or getattr(error, "code", None) == 401:
+        repair = (
+            "replace its revoked or invalid bot token"
+            if kind == "bot"
+            else "sign in to the same Telegram account again"
+        )
+        return TelegramConnectionError(
+            f"This {account} can no longer sign in. Open Connections and {repair}, "
+            "then restart TGDrive and retry. Existing files and saved upload "
+            "progress are preserved.",
+            "TELEGRAM_CREDENTIALS_REVOKED",
+            client_name=client_name,
+        )
+    if name in _CHANNEL_ERRORS:
+        return TelegramConnectionError(
+            f"This {account} lost access or required permissions to the storage "
+            "channel. Restore its channel membership and administrator permissions, "
+            "then open Connections, Refresh and retry. Existing files and saved "
+            "upload progress are preserved.",
+            "TELEGRAM_CHANNEL_ACCESS",
+            client_name=client_name,
+        )
+    return None
+
+
+def removed_sender(client_name: str) -> TelegramConnectionError:
+    return TelegramConnectionError(
+        "The Telegram account that started this upload is no longer configured. "
+        "Reconnect the same account in Connections, restart TGDrive and retry. "
+        "The saved upload is preserved; switching an already dispatched part to "
+        "another account could create a duplicate.",
+        "TELEGRAM_ACCOUNT_REMOVED",
+        client_name=client_name,
+    )
diff --git a/tgdrive/transfers/__init__.py b/tgdrive/transfers/__init__.py
new file mode 100644
index 00000000..a30850ae
--- /dev/null
+++ b/tgdrive/transfers/__init__.py
@@ -0,0 +1 @@
+"""Durable transfer jobs, upload receipts, staging, and URL imports."""
diff --git a/tgdrive/transfers/file_window.py b/tgdrive/transfers/file_window.py
new file mode 100644
index 00000000..f70e539d
--- /dev/null
+++ b/tgdrive/transfers/file_window.py
@@ -0,0 +1,82 @@
+"""Bounded seekable staged-file views; never materialize multipart pieces."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+from pathlib import Path
+
+
+class FileWindow(io.RawIOBase):
+    def __init__(self, path: Path, offset: int, size: int, *, name: str | None = None):
+        super().__init__()
+        if type(offset) is not int or type(size) is not int or offset < 0 or size <= 0:
+            raise ValueError("Invalid staged file window")
+        self._source = path.open("rb")
+        self._offset = offset
+        self._size = size
+        self._position = 0
+        self._hashed = 0
+        self._digest = hashlib.sha256()
+        self._sequential = True
+        self.name = name or path.name
+        self._source.seek(offset)
+
+    def readable(self):
+        return True
+
+    def seekable(self):
+        return True
+
+    def tell(self):
+        return self._position
+
+    def seek(self, offset, whence=io.SEEK_SET):
+        position = (
+            offset
+            if whence == io.SEEK_SET
+            else (
+                self._position + offset
+                if whence == io.SEEK_CUR
+                else self._size + offset
+            )
+        )
+        if (
+            whence not in (io.SEEK_SET, io.SEEK_CUR, io.SEEK_END)
+            or not 0 <= position <= self._size
+        ):
+            raise ValueError("Seek outside staged file window")
+        if position != self._position:
+            if position == 0:
+                self._digest = hashlib.sha256()
+                self._hashed = 0
+                self._sequential = True
+            else:
+                self._sequential = False
+        self._position = position
+        self._source.seek(self._offset + position)
+        return position
+
+    def read(self, size=-1):
+        if self.closed:
+            raise ValueError("I/O operation on closed file")
+        remaining = self._size - self._position
+        amount = remaining if size is None or size < 0 else min(size, remaining)
+        data = self._source.read(amount)
+        if self._position != self._hashed:
+            self._sequential = False
+        self._position += len(data)
+        self._hashed += len(data)
+        self._digest.update(data)
+        return data
+
+    def verify(self, expected_sha256):
+        if not self._sequential or self._hashed != self._size:
+            raise ValueError("Staged file window was not uploaded completely")
+        if expected_sha256 is not None and self._digest.hexdigest() != expected_sha256:
+            raise ValueError("Staged file changed before Telegram publication")
+
+    def close(self):
+        if not self.closed:
+            self._source.close()
+        super().close()
diff --git a/tgdrive/transfers/manager.py b/tgdrive/transfers/manager.py
new file mode 100644
index 00000000..5f26f71e
--- /dev/null
+++ b/tgdrive/transfers/manager.py
@@ -0,0 +1,963 @@
+"""Supervised browser, URL, and Telegram transfer pipelines."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import math
+import secrets
+import shutil
+import time
+from collections.abc import Awaitable, Callable, Iterable
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+import aiofiles
+from fastapi import UploadFile
+
+from tgdrive.core.config import Settings
+from tgdrive.core.errors import (
+    DriveError,
+    NotDirectoryError,
+    NotFoundError,
+    TrashedItemError,
+    ValidationError,
+)
+from tgdrive.core.security import safe_name
+from tgdrive.recovery.backup import BackupError
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import ClientPool, current_upload_limit
+from tgdrive.transfers.remote import (
+    REMOTE_MAX_ATTEMPTS,
+    RemoteCancelled,
+    RemoteClient,
+    RemoteFileInfo,
+    RemoteTooLarge,
+)
+from tgdrive.transfers.staging import StorageUnavailable, check_staging
+from tgdrive.transfers.tasks import (
+    TransferRecord,
+    TransferRegistry,
+    TransferStatus,
+    _journalled,
+)
+
+logger = logging.getLogger(__name__)
+_CHUNK_SIZE = 1024 * 1024
+_UPLOAD_CLEANUP_TIMEOUT = 1.0
+_MEDIA_ATTRIBUTES = (
+    "document",
+    "video",
+    "audio",
+    "photo",
+    "sticker",
+    "animation",
+    "voice",
+    "video_note",
+)
+
+
+class TransferError(RuntimeError):
+    pass
+
+
+class TransferTooLarge(TransferError):
+    pass
+
+
+class TransferEmptyFile(TransferError):
+    pass
+
+
+class TransferCancelled(TransferError):
+    pass
+
+
+class BackupPending(ValueError):
+    """A catalogued upload must finish protection instead of deleting its media."""
+
+    code = "BACKUP_PENDING"
+
+
+def _media_from_message(message: Any) -> Any | None:
+    for attribute in _MEDIA_ATTRIBUTES:
+        media = getattr(message, attribute, None)
+        if media is not None:
+            return media
+    return None
+
+
+async def restore_telegram_cooldowns(
+    pool: ClientPool, records: Iterable[TransferRecord]
+) -> None:
+    """Load every future provider wait before startup checkpoint publication."""
+    now = time.time()
+    account_deadlines: dict[str, float] = {}
+    channel_deadline = 0.0
+
+    def future(value: Any) -> bool:
+        return type(value) in (int, float) and math.isfinite(value) and value > now
+
+    for record in records:
+        context = record.context
+        deadline = context.get("channel_retry_at")
+        if future(deadline):
+            channel_deadline = max(channel_deadline, deadline)
+        plan = context.get("multipart_plan")
+        candidates = plan.get("parts", []) if isinstance(plan, dict) else [context]
+        if not isinstance(candidates, list):
+            continue
+        for part in candidates:
+            if not isinstance(part, dict):
+                continue
+            sender, deadline = part.get("sender"), part.get("retry_at")
+            if isinstance(sender, str) and sender and future(deadline):
+                account_deadlines[sender] = max(
+                    account_deadlines.get(sender, 0),
+                    deadline,
+                )
+    if channel_deadline:
+        await pool.defer_channel(channel_deadline)
+    for sender, deadline in account_deadlines.items():
+        await pool.defer_client(sender, deadline)
+
+
+class TransferManager:
+    """Coordinate staging, Telegram work, and protection of catalogued uploads.
+
+    The registry owns durable job state and supervised tasks. This manager keeps
+    those records aligned with staged bytes, destination identities, and backups.
+    """
+
+    def __init__(
+        self,
+        *,
+        settings: Settings,
+        pool: ClientPool,
+        store: DriveStore,
+        remote: RemoteClient,
+        registry: TransferRegistry,
+        ensure_backup: Callable[[int], Awaitable[int]] | None = None,
+        ensure_lineage: Callable[[], Awaitable[None]] | None = None,
+        ensure_channel: Callable[[], Awaitable[None]] | None = None,
+        check_upload_allowed: Callable[[], None] | None = None,
+    ) -> None:
+        self.settings = settings
+        self.pool = pool
+        self.store = store
+        self.remote = remote
+        self.registry = registry
+        self.registry.demo_mode = bool(getattr(settings, "demo_mode", False))
+        self._ensure_backup = ensure_backup
+        self._ensure_lineage = ensure_lineage
+        self._ensure_channel = ensure_channel
+        self._check_upload_allowed = check_upload_allowed
+        self.cache_dir = settings.resolved_cache_dir
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self._semaphore = asyncio.Semaphore(settings.max_concurrent_transfers)
+        self._pending_staging: dict[str, int] = {}
+
+    async def _resolve_upload_destination(
+        self, record: TransferRecord, path: str
+    ) -> str:
+        binding = self.store.upload_destination(
+            path,
+            directory_id=record.context.get("destination_id"),
+        )
+        if (
+            record.context.get("destination_id") != binding["id"]
+            or record.context.get("destination") != binding["path"]
+        ):
+            record.context.update(
+                destination_id=binding["id"], destination=binding["path"]
+            )
+            await self.registry.persist(record)
+        return binding["path"]
+
+    async def _check_destination_or_cancel(
+        self, record: TransferRecord, path: str
+    ) -> str:
+        try:
+            return await self._resolve_upload_destination(record, path)
+        except NotFoundError, NotDirectoryError, TrashedItemError, ValidationError:
+            record.context["cancel_requested"] = True
+            record.cancel_event.set()
+            await self.registry.persist(record)
+            return path
+
+    def _destination_path(self, record: TransferRecord) -> str:
+        path = record.context.get("destination", "")
+        identity = record.context.get("destination_id")
+        if identity is not None:
+            try:
+                return self.store.resolve_id(identity)
+            except DriveError:
+                pass
+        return path
+
+    async def receive_browser_upload(
+        self,
+        upload: UploadFile,
+        destination: str,
+        *,
+        is_disconnected: Callable[[], Awaitable[bool]] | None = None,
+        on_created: Callable[[TransferRecord], Awaitable[None] | None] | None = None,
+    ) -> TransferRecord:
+        """Save an incoming multipart stream, then supervise Telegram upload."""
+
+        binding = self.store.upload_destination(destination)
+        destination = binding["path"]
+        declared_size = getattr(upload, "size", None)
+        admission_limit = await current_upload_limit(self.settings, self.pool)
+        try:
+            if self._check_upload_allowed is not None:
+                self._check_upload_allowed()
+            binding = self.store.upload_destination(
+                destination, directory_id=binding["id"]
+            )
+            destination = binding["path"]
+        except BaseException:
+            await upload.close()
+            raise
+        if isinstance(declared_size, int) and declared_size > admission_limit:
+            await upload.close()
+            raise TransferTooLarge(
+                f"file exceeds the {admission_limit}-byte upload limit"
+            )
+        if declared_size == 0:
+            await upload.close()
+            raise TransferEmptyFile("Empty files cannot be uploaded to Telegram")
+        try:
+            check_staging(self.settings, self, declared_size or admission_limit)
+        except BaseException:
+            await upload.close()
+            raise
+        transfer_id = secrets.token_urlsafe(18)
+        upload_dir = self.cache_dir / "uploads"
+        local_path = upload_dir / f"{transfer_id}.upload"
+        context = dict(
+            kind="receiving",
+            staging_size=declared_size or admission_limit,
+            staging_written=0,
+            local_path=str(local_path),
+            destination=destination,
+            destination_id=binding["id"],
+        )
+        self._pending_staging[transfer_id] = declared_size or admission_limit
+        try:
+            record = await self.registry.create(
+                "saving",
+                total=declared_size if isinstance(declared_size, int) else 0,
+                transfer_id=transfer_id,
+                context=context,
+            )
+        except BaseException:
+            try:
+                record = self.registry.get(transfer_id)
+            except KeyError:
+                pass
+            else:
+                await self.registry.cancel(record.id)
+            await upload.close()
+            raise
+        finally:
+            self._pending_staging.pop(transfer_id, None)
+        written = 0
+        try:
+            await self.registry.update(record.id, status=TransferStatus.RUNNING)
+            if on_created is not None:
+                created = on_created(record)
+                if inspect.isawaitable(created):
+                    await created
+            if record.cancel_event.is_set():
+                raise TransferCancelled("Transfer cancelled")
+            file_name = safe_name(upload.filename)
+            upload_dir.mkdir(parents=True, exist_ok=True)
+            async with self._semaphore, aiofiles.open(local_path, "xb") as output:
+                while True:
+                    if record.cancel_event.is_set():
+                        raise TransferCancelled("Transfer cancelled")
+                    chunk = await upload.read(_CHUNK_SIZE)
+                    if not chunk:
+                        break
+                    written += len(chunk)
+                    if written > admission_limit:
+                        raise TransferTooLarge(
+                            f"file exceeds the {admission_limit}-byte upload limit"
+                        )
+                    check_staging(
+                        self.settings,
+                        self,
+                        record.context["staging_size"],
+                        exclude=record.id,
+                        written=written - len(chunk),
+                    )
+                    await output.write(chunk)
+                    record.context["staging_written"] = written
+                    await self.registry.update(
+                        record.id,
+                        current=written,
+                        total=max(record.total, written),
+                    )
+            if isinstance(declared_size, int) and written != declared_size:
+                raise TransferError(
+                    f"multipart stream ended at {written} of {declared_size} bytes"
+                )
+            if written == 0:
+                raise TransferEmptyFile("Empty files cannot be uploaded to Telegram")
+            # The browser can abort in the narrow window after its multipart
+            # body was accepted but before it receives the transfer id.  Do
+            # not start a Telegram job the UI can no longer identify.
+            if is_disconnected is not None and await is_disconnected():
+                raise TransferCancelled("Transfer cancelled")
+            record.context.update(
+                kind="upload",
+                local_path=str(local_path),
+                destination=destination,
+                name=file_name,
+                size=written,
+            )
+            await self.registry.persist(record)
+            self.registry.spawn(
+                record.id,
+                lambda transfer: self._upload_path(
+                    transfer,
+                    local_path,
+                    destination,
+                    file_name,
+                    written,
+                ),
+            )
+            return record
+        except asyncio.CancelledError:
+            # Client disconnects and server shutdown cancel the request task
+            # with a BaseException, so the generic handler below cannot clean
+            # this up.  Keep the registry and cache consistent before
+            # preserving cancellation semantics for Starlette.
+            await self.registry.cancel(record.id)
+            with suppress(FileNotFoundError, NotADirectoryError):
+                local_path.unlink()
+            raise
+        except TransferCancelled:
+            await self.registry.cancel(record.id)
+            with suppress(FileNotFoundError, NotADirectoryError):
+                local_path.unlink()
+            raise
+        except Exception as exc:
+            await self.registry.update(
+                record.id,
+                status=TransferStatus.ERROR,
+                error=str(exc) or type(exc).__name__,
+            )
+            with suppress(FileNotFoundError, NotADirectoryError):
+                local_path.unlink()
+            raise
+        finally:
+            await upload.close()
+
+    async def inspect_remote(self, url: str) -> RemoteFileInfo:
+        info = await self.remote.inspect(url)
+        limit = await current_upload_limit(self.settings, self.pool)
+        if info.size is not None and info.size > limit:
+            raise RemoteTooLarge(limit, info.size)
+        return info
+
+    @_journalled
+    async def start_remote(
+        self,
+        *,
+        url: str,
+        destination: str,
+        filename: str | None,
+        single_threaded: bool = False,
+    ) -> TransferRecord:
+        if self._check_upload_allowed is not None:
+            self._check_upload_allowed()
+        binding = self.store.upload_destination(destination)
+        destination = binding["path"]
+        record = await self.registry.create(
+            "checking_source",
+            context=dict(
+                kind="remote",
+                source_kind="remote",
+                url=url,
+                destination=destination,
+                destination_id=binding["id"],
+                name=filename,
+                single_threaded=single_threaded,
+            ),
+        )
+        self.registry.spawn(
+            record.id,
+            lambda transfer: self._remote_pipeline(
+                transfer,
+                url=url,
+                destination=destination,
+                filename=safe_name(filename) if filename else None,
+            ),
+        )
+        return record
+
+    async def _remote_pipeline(
+        self,
+        record: TransferRecord,
+        *,
+        url: str,
+        destination: str,
+        filename: str | None,
+    ) -> None:
+        download_dir = self.cache_dir / "remote" / record.id
+        try:
+            destination = await self._check_destination_or_cancel(record, destination)
+            if record.cancel_event.is_set():
+                raise TransferCancelled("Transfer destination is unavailable")
+            from tgdrive.transfers.remote_scheduler import WARM_STAGING_WINDOW
+
+            admission_limit = await current_upload_limit(self.settings, self.pool)
+            if self._check_upload_allowed is not None:
+                self._check_upload_allowed()
+            retry_not_before = record.context.get("source_retry_at", 0)
+            record.context["source_attempt"] = 1
+            await self.registry.update(
+                record.id,
+                status=TransferStatus.RUNNING,
+                phase="source_retry_wait"
+                if retry_not_before > time.time()
+                else "checking_source",
+            )
+            admitted = False
+            source_size = None
+            mode = "full"
+
+            async def mode_changed(value):
+                nonlocal mode
+                mode = value
+                record.context["download_mode"] = value
+                if value == "queued" and record.phase == "source_retry_wait":
+                    record.context.pop("source_retry_at", None)
+                    await self.registry.update(
+                        record.id, phase="checking_source", error=None
+                    )
+
+            async def retry_scheduled(attempt: int, delay: float, error: Exception):
+                nonlocal admitted, source_size
+                admitted, source_size = False, None
+                # The remote client has drained writers and removed its partial
+                # file. Release the old claim before other jobs seek admission.
+                record.context.update(
+                    staging_size=0,
+                    staging_written=0,
+                    source_attempt=attempt,
+                    source_retry_at=time.time() + delay,
+                )
+                record.context.pop("download_mode", None)
+                await self.registry.update(
+                    record.id,
+                    phase="source_retry_wait",
+                    current=0,
+                    total=0,
+                    error=None,
+                )
+                scheduler = getattr(self.remote, "scheduler", None)
+                if scheduler is not None:
+                    await scheduler.refresh()
+                logger.info(
+                    "Source retry scheduled id=%s attempt=%s/%s "
+                    "error_type=%s retry_after_seconds=%.3f",
+                    record.id,
+                    attempt,
+                    REMOTE_MAX_ATTEMPTS,
+                    type(error).__name__,
+                    delay,
+                )
+
+            def can_promote():
+                if source_size is None:
+                    return False
+                if record.context.get("staging_size", 0) >= source_size:
+                    return True
+                try:
+                    check_staging(
+                        self.settings,
+                        self,
+                        source_size,
+                        exclude=record.id,
+                        written=record.context.get("staging_written", 0),
+                    )
+                except StorageUnavailable:
+                    return False
+                # Claim atomically on this event loop before another candidate
+                # is promoted. Its next progress/lifecycle update journals it.
+                record.context["staging_size"] = source_size
+                return True
+
+            async def progress(current: int, total: int | None) -> None:
+                nonlocal admitted, source_size
+                observed = max(current, total or 0)
+                if observed > admission_limit:
+                    raise RemoteTooLarge(admission_limit, observed)
+                source_size = total if total is not None else admission_limit
+                record.context["staging_written"] = current
+                if mode == "full":
+                    size = source_size
+                else:
+                    # Waiting sources reserve bounded windows, rather than
+                    # taking the full staging budget away from active imports.
+                    headroom = current + getattr(self.remote, "chunk_size", _CHUNK_SIZE)
+                    windows = (
+                        headroom + WARM_STAGING_WINDOW - 1
+                    ) // WARM_STAGING_WINDOW
+                    size = min(source_size, max(1, windows) * WARM_STAGING_WINDOW)
+                size = max(size, record.context.get("staging_size", 0))
+                reservation_changed = record.context.get("staging_size") != size
+                refresh_needed = not admitted or reservation_changed
+                if not admitted or reservation_changed:
+                    while True:
+                        try:
+                            check_staging(
+                                self.settings,
+                                self,
+                                size,
+                                exclude=record.id,
+                                written=current,
+                            )
+                            break
+                        except StorageUnavailable:
+                            record.context["download_mode"] = "waiting_storage"
+                            await self.remote._cancelable(
+                                asyncio.sleep(1), record.cancel_event
+                            )
+                    admitted = True
+                record.context.update(staging_size=size, download_mode=mode)
+                scheduler = getattr(self.remote, "scheduler", None)
+                if scheduler is not None and refresh_needed:
+                    await scheduler.refresh()
+                await self.registry.update(
+                    record.id,
+                    current=current,
+                    phase="downloading",
+                    total=total or 0,
+                    checkpoint_progress=False,
+                )
+
+            result = await self.remote.download(
+                url,
+                download_dir,
+                filename=filename,
+                # This UUID directory belongs only to this unpublished URL job.
+                overwrite=True,
+                cancel_event=record.cancel_event,
+                progress=progress,
+                max_bytes=admission_limit,
+                single_threaded=bool(record.context.get("single_threaded", False)),
+                can_promote=can_promote,
+                mode_changed=mode_changed,
+                retry=retry_scheduled,
+                retry_not_before=retry_not_before,
+            )
+            record.context.pop("source_retry_at", None)
+            await self._upload_path(
+                record,
+                result.path,
+                destination,
+                result.filename,
+                result.size,
+            )
+        except RemoteCancelled, TransferCancelled:
+            await self.registry.update(
+                record.id,
+                status=TransferStatus.CANCELLED,
+                error="Transfer cancelled",
+            )
+        finally:
+            if record.status in {TransferStatus.COMPLETED, TransferStatus.CANCELLED}:
+                shutil.rmtree(download_dir, ignore_errors=True)
+
+    @_journalled
+    async def enqueue_upload(
+        self,
+        local_path: Path,
+        destination: str,
+        file_name: str,
+        size: int,
+        *,
+        transfer_id: str | None = None,
+        folder_upload: dict[str, Any] | None = None,
+    ) -> TransferRecord:
+        if self._check_upload_allowed is not None:
+            self._check_upload_allowed()
+        binding = self.store.upload_destination(destination)
+        destination = binding["path"]
+        context = dict(
+            kind="upload",
+            local_path=str(local_path),
+            destination=destination,
+            destination_id=binding["id"],
+            name=file_name,
+            size=size,
+        )
+        if folder_upload is not None:
+            context["folder_upload"] = dict(folder_upload)
+        record = await self.registry.create(
+            "queued", total=size, transfer_id=transfer_id, context=context
+        )
+        if record.task is not None or record.terminal:
+            return record
+        self.registry.spawn(
+            record.id,
+            lambda item: self._upload_path(
+                item, local_path, destination, file_name, size
+            ),
+        )
+        return record
+
+    async def _verify_lineage(self, record: TransferRecord | None = None) -> None:
+        if self._ensure_lineage is None:
+            return
+        while True:
+            if record is not None:
+                context = record.context
+                remaining = context.get("lineage_retry_at", 0) - time.time()
+                if remaining > 0:
+                    await self.registry.update(record.id, phase="retry_wait")
+                    if not context.get("send_started"):
+                        try:
+                            await asyncio.wait_for(
+                                record.cancel_event.wait(), remaining
+                            )
+                        except TimeoutError:
+                            pass
+                        else:
+                            raise TransferCancelled("Transfer cancelled")
+                    else:
+                        await asyncio.sleep(remaining)
+            try:
+                await self._ensure_lineage()
+            except BackupError as exc:
+                delay = exc.retry_after
+                if (
+                    record is None
+                    or getattr(exc, "code", None) == "RECOVERY_REQUIRED"
+                    or type(delay) not in (int, float)
+                    or not math.isfinite(delay)
+                    or delay <= 0
+                    or not math.isfinite(time.time() + delay)
+                ):
+                    raise
+                record.context["lineage_retry_at"] = time.time() + delay
+                await self.registry.update(record.id, phase="retry_wait")
+                continue
+            if record is not None and record.context.pop("lineage_retry_at", None):
+                await self.registry.persist(record)
+            return
+
+    async def recover(self) -> None:
+        # Failed rows do not spawn automatically, but their provider cooldowns
+        # still constrain every new upload after a process restart.
+        await restore_telegram_cooldowns(self.pool, self.registry.list())
+        intents = self.store.pending_deletions()
+        restart_jobs = [
+            row
+            for row in self.registry.list()
+            if row.status is TransferStatus.ERROR
+            and row.context.get("restart_retryable") is True
+            and row.context.get("kind") in {"upload", "remote", "delete"}
+            and not row.context.get("cancel_requested")
+        ]
+        if (
+            intents
+            or restart_jobs
+            or any(not row.terminal for row in self.registry.list())
+        ):
+            await self._verify_lineage()
+        for record in restart_jobs:
+            await self.registry.retry(record.id)
+        for intent in intents:
+            try:
+                self.registry.get(intent["id"])
+            except KeyError:
+                await self.start_deletion(intent["path"])
+        for record in self.registry.list():
+            if not record.terminal and (record.task is None or record.task.done()):
+                await self._resume(record)
+
+    @_journalled
+    async def cancel_job(self, job_id: str) -> TransferRecord:
+        record = self.registry.get(job_id)
+        if record.status not in {
+            TransferStatus.COMPLETED,
+            TransferStatus.CANCELLED,
+        } and self._metadata_committed(record):
+            raise BackupPending(
+                "This file is already catalogued. Allow finalization to finish, "
+                "or retry this transfer instead of cancelling it."
+            )
+        record = await self.registry.cancel(job_id)
+        if (
+            record.context.get("send_started")
+            and (record.task is None or record.task.done())
+            and not record.terminal
+        ):
+            await self._resume(record)
+        if record.status is TransferStatus.CANCELLED and not record.context.get(
+            "send_started"
+        ):
+            staged = record.context.get("local_path")
+            if staged:
+
+                def discard():
+                    target = Path(staged).resolve()
+                    if target.is_relative_to(self.cache_dir):
+                        target.unlink(missing_ok=True)
+
+                await asyncio.to_thread(discard)
+            if hasattr(self, "uploads"):
+                await asyncio.to_thread(self.uploads.release, record.id)
+        return record
+
+    @_journalled
+    async def retry_job(self, job_id: str) -> TransferRecord:
+        record = self.registry.get(job_id)
+        if not record.terminal and record.task is not None and not record.task.done():
+            return record
+        record = await self.registry.retry(job_id)
+        if record.context.get("cancel_requested"):
+            record.cancel_event.set()
+        await self._resume(record)
+        return record
+
+    async def _resume(self, record: TransferRecord) -> None:
+        context = record.context
+        if self._metadata_committed(record):
+            self.registry.spawn(
+                record.id,
+                lambda item: self._upload_path(
+                    item,
+                    Path(context.get("local_path", self.cache_dir / record.id)),
+                    context.get("destination", "/"),
+                    context.get("name", "upload"),
+                    context.get("size", record.total),
+                ),
+            )
+        elif context.get("kind") == "delete":
+            self.registry.spawn(record.id, lambda item: self._delete_intent(item))
+        elif context.get("kind") == "upload" or (
+            context.get("source_kind") == "remote"
+            and context.get("local_path")
+            and context.get("size")
+        ):
+            self.registry.spawn(
+                record.id,
+                lambda item: self._upload_path(
+                    item,
+                    Path(context["local_path"]),
+                    context["destination"],
+                    context["name"],
+                    context["size"],
+                ),
+            )
+        elif context.get("kind") == "remote":
+            self.registry.spawn(
+                record.id,
+                lambda item: self._remote_pipeline(
+                    item,
+                    url=context["url"],
+                    destination=context["destination"],
+                    filename=context.get("name"),
+                ),
+            )
+        else:
+            await self.registry.update(
+                record.id,
+                status=TransferStatus.ERROR,
+                error="Interrupted browser receipt. Reselect the file to resume.",
+            )
+
+    def _metadata_committed(self, record: TransferRecord) -> bool:
+        return bool(
+            record.context.get("metadata_committed")
+            or self.store.has_file_operation(record.id)
+        )
+
+    async def _protect_committed_upload(
+        self, record: TransferRecord, size: int
+    ) -> None:
+        """Finish only the durable catalog checkpoint, never another media send."""
+        context = record.context
+        context["metadata_committed"] = True
+        context.setdefault("catalog_revision", self.store.revision)
+        required = context["catalog_revision"]
+        if type(required) is not int or required < 0:
+            raise TransferError("The committed catalog revision is invalid")
+        # Cancellation cannot delete a message that already belongs to the catalog.
+        context.pop("cancel_requested", None)
+        record.cancel_event.clear()
+        if record.cancel_handle is not None:
+            record.cancel_handle.cancel()
+            record.cancel_handle = None
+        await self.registry.persist(record)
+        await self.registry.update(
+            record.id,
+            status=TransferStatus.RUNNING,
+            phase=(
+                "finalizing"
+                if getattr(self.store, "backend_name", None) == "mongodb"
+                else "backup_pending"
+            ),
+            current=size,
+            total=size,
+        )
+        while self._ensure_backup is not None:
+            retry_at = context.get("backup_retry_at", 0)
+            if retry_at > time.time():
+                await asyncio.sleep(retry_at - time.time())
+            try:
+                protected = await self._ensure_backup(required)
+            except BackupError as exc:
+                delay = getattr(exc, "retry_after", None)
+                if (
+                    type(delay) not in (int, float)
+                    or not math.isfinite(delay)
+                    or delay <= 0
+                    or not math.isfinite(time.time() + delay)
+                ):
+                    raise
+                context["backup_retry_at"] = time.time() + delay
+                await self.registry.persist(record)
+                continue
+            if type(protected) is not int or protected < required:
+                raise TransferError(
+                    "The recovery checkpoint did not confirm this catalog revision"
+                )
+            context["protected_revision"] = protected
+            context.pop("backup_retry_at", None)
+            await self.registry.persist(record)
+            break
+        await self.registry.update(
+            record.id,
+            status=TransferStatus.COMPLETED,
+            phase="completed",
+            current=size,
+            total=size,
+        )
+
+    async def _upload_path(
+        self,
+        record: TransferRecord,
+        local_path: Path,
+        destination: str,
+        file_name: str,
+        size: int,
+    ) -> None:
+        if self._metadata_committed(record):
+            await self._protect_committed_upload(record, size)
+            await asyncio.to_thread(local_path.unlink, missing_ok=True)
+            uploads = getattr(self, "uploads", None)
+            if uploads is not None:
+                await asyncio.to_thread(uploads.release, record.id)
+            return
+        context = record.context
+        if "multipart_plan" not in context and (
+            context.get("send_started") or context.get("remote_message_id")
+        ):
+            raise TransferError(
+                "A dispatched upload is missing its part journal. "
+                "Preserve the staged file and inspect the transfer before retrying."
+            )
+        from tgdrive.transfers.multipart_transfer import upload_multipart
+
+        await upload_multipart(self, record, local_path, destination, file_name, size)
+
+    @_journalled
+    async def start_deletion(self, path: str) -> TransferRecord:
+        intent = await asyncio.to_thread(
+            self.store.begin_deletion, path, channel_id=self.settings.storage_channel
+        )
+        record = await self.registry.create(
+            "deleting",
+            total=len(intent["message_ids"]),
+            transfer_id=intent["id"],
+            context=dict(
+                kind="delete", deletion_id=intent["id"], name=path.rsplit("/", 1)[-1]
+            ),
+        )
+        if not record.terminal and (record.task is None or record.task.done()):
+            self.registry.spawn(record.id, lambda item: self._delete_intent(item))
+        return record
+
+    async def _delete_intent(self, record: TransferRecord) -> None:
+        intent = next(
+            (
+                item
+                for item in self.store.pending_deletions()
+                if item["id"] == record.context["deletion_id"]
+            ),
+            None,
+        )
+        if intent is None:
+            await self.registry.update(
+                record.id, status=TransferStatus.COMPLETED, phase="completed"
+            )
+            return
+        try:
+            await self._verify_lineage(record)
+            protect = getattr(self, "_ensure_replica", None)
+            if protect is not None:
+                await self.registry.update(record.id, phase="checking_backup")
+                await protect()
+            await self.registry.update(
+                record.id, status=TransferStatus.RUNNING, phase="deleting"
+            )
+            prefix = intent["path"].rstrip("/")
+            for other in self.registry.list():
+                destination = self._destination_path(other)
+                if other.id == record.id or not (
+                    destination == prefix or destination.startswith(prefix + "/")
+                ):
+                    continue
+                if (
+                    other.status is TransferStatus.COMPLETED
+                    or other.status is TransferStatus.CANCELLED
+                ):
+                    continue
+                await self.cancel_job(other.id)
+                if other.task is not None:
+                    await self.registry.update(record.id, phase="waiting_for_uploads")
+                    await asyncio.wait_for(asyncio.shield(other.task), timeout=60)
+                if other.status is not TransferStatus.CANCELLED:
+                    raise TransferError(
+                        "An upload into this folder still needs Telegram cleanup"
+                    )
+            # Permanent deletion forgets the catalog subtree, not its Telegram
+            # documents. This policy applies consistently to every file age.
+            await self._verify_lineage(record)
+            await self.registry.update(record.id, phase="deleting")
+            await asyncio.to_thread(self.store.finish_deletion, intent["id"])
+            await self.registry.update(
+                record.id,
+                status=TransferStatus.COMPLETED,
+                phase="completed",
+                current=record.total,
+            )
+        except Exception as exc:
+            await asyncio.to_thread(
+                self.store.fail_deletion, intent["id"], type(exc).__name__
+            )
+            raise
+
+    async def delete_telegram_messages(self, message_ids: list[int]) -> None:
+        if not message_ids:
+            return
+        async with self.pool.lease() as client:
+            for start in range(0, len(message_ids), 100):
+                await self._verify_lineage()
+                await client.delete_messages(
+                    self.settings.storage_channel,
+                    message_ids[start : start + 100],
+                )
+
+    async def close(self) -> None:
+        await self.registry.shutdown()
+        await self.remote.close()
diff --git a/tgdrive/transfers/multipart_transfer.py b/tgdrive/transfers/multipart_transfer.py
new file mode 100644
index 00000000..06dc07d2
--- /dev/null
+++ b/tgdrive/transfers/multipart_transfer.py
@@ -0,0 +1,649 @@
+"""Durable multipart upload coordinator; one catalog file, bounded Telegram pieces."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import secrets
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from telethon.errors import FloodPremiumWaitError, FloodWaitError
+
+from tgdrive.storage.file_parts import MAX_FILE_PARTS, validate_parts, validate_sha256
+from tgdrive.telegram.client_pool import ClientPoolNotRunning, NoClientAvailable
+from tgdrive.telegram.connection_errors import TelegramConnectionError
+from tgdrive.transfers.manager import (
+    TransferCancelled,
+    TransferEmptyFile,
+    TransferError,
+    _media_from_message,
+)
+from tgdrive.transfers.tasks import TransferStatus
+
+
+def fingerprint(
+    path: Path,
+    size: int,
+    part_size: int,
+    *,
+    cancel_event=None,
+    stop_event=None,
+) -> tuple[str, list[dict[str, Any]]]:
+    """One bounded sequential pass computes whole-file and per-part checksums."""
+    if path.stat().st_size != size:
+        raise TransferError("Staged file changed. Reselect the source.")
+    whole = hashlib.sha256()
+    parts = []
+    with path.open("rb") as source:
+        offset = 0
+        while offset < size:
+            length = min(part_size, size - offset)
+            digest = hashlib.sha256()
+            remaining = length
+            while remaining:
+                if (cancel_event is not None and cancel_event.is_set()) or (
+                    stop_event is not None and stop_event.is_set()
+                ):
+                    raise TransferCancelled("Transfer cancelled")
+                chunk = source.read(min(1024 * 1024, remaining))
+                if not chunk:
+                    raise TransferError("Staged file changed. Reselect the source.")
+                whole.update(chunk)
+                digest.update(chunk)
+                remaining -= len(chunk)
+            parts.append(
+                dict(
+                    index=len(parts),
+                    offset=offset,
+                    size=length,
+                    sha256=digest.hexdigest(),
+                    random_id=secrets.randbits(63),
+                    sender=None,
+                    send_started=False,
+                    message_id=None,
+                    confirmed=False,
+                )
+            )
+            offset += length
+        if source.read(1):
+            raise TransferError("Staged file changed. Reselect the source.")
+    return whole.hexdigest(), parts
+
+
+async def _fingerprint_owned(path, size, part_size, cancel_event):
+    """Drain cooperative hashing before releasing its concurrency/staging ownership."""
+    stop = threading.Event()
+    work = asyncio.create_task(
+        asyncio.to_thread(
+            fingerprint,
+            path,
+            size,
+            part_size,
+            cancel_event=cancel_event,
+            stop_event=stop,
+        )
+    )
+    interrupted = False
+    while True:
+        try:
+            result = await asyncio.shield(work)
+        except asyncio.CancelledError:
+            interrupted = True
+            stop.set()
+            if work.done():
+                if not work.cancelled():
+                    work.exception()
+                raise
+            continue
+        except BaseException:
+            if interrupted:
+                raise asyncio.CancelledError from None
+            raise
+        if interrupted:
+            raise asyncio.CancelledError
+        return result
+
+
+def _validate_plan(plan: Any, size: int, checksum: Any) -> None:
+    if not isinstance(plan, dict) or plan.get("version") != 1:
+        raise TransferError("The multipart journal is invalid")
+    parts = plan.get("parts")
+    if plan.get("kind") != "bot" or not isinstance(parts, list) or not parts:
+        raise TransferError("The multipart journal is invalid")
+    try:
+        # This validates immutable ordering/offsets/sizes/checksums before any effect.
+        validate_parts(
+            [
+                dict(
+                    index=p["index"],
+                    offset=p["offset"],
+                    size=p["size"],
+                    message_id=p["index"] + 1,
+                    sha256=p["sha256"],
+                )
+                for p in parts
+            ],
+            size=size,
+            message_id=1,
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        raise TransferError("The multipart journal is invalid") from exc
+    try:
+        validate_sha256(checksum, optional=False)
+    except ValueError as exc:
+        raise TransferError("The multipart checksum is missing") from exc
+    random_ids = set()
+    for part in parts:
+        if (
+            type(part.get("random_id")) is not int
+            or not -(2**63) <= part["random_id"] < 2**63
+        ):
+            raise TransferError("The multipart request identity is invalid")
+        if part["random_id"] in random_ids:
+            raise TransferError("Multipart parts cannot reuse a request identity")
+        random_ids.add(part["random_id"])
+        if "document_id" in part and (
+            type(part["document_id"]) is not int
+            or part["document_id"] == 0
+            or not -(2**63) <= part["document_id"] < 2**63
+        ):
+            raise TransferError("The multipart document identity is invalid")
+        if part.get("message_id") is not None and (
+            type(part["message_id"]) is not int or part["message_id"] <= 0
+        ):
+            raise TransferError("The multipart message identity is invalid")
+        if (
+            type(part.get("send_started")) is not bool
+            or type(part.get("confirmed")) is not bool
+        ):
+            raise TransferError("The multipart effect journal is invalid")
+        if part.get("send_started") and not isinstance(part.get("sender"), str):
+            raise TransferError("The multipart sender identity is missing")
+        if part.get("confirmed") and not part.get("message_id"):
+            raise TransferError("The multipart confirmation is missing")
+
+
+async def upload_multipart(manager, record, local_path, destination, file_name, size):
+    context = record.context
+    context.update(
+        kind="upload",
+        local_path=str(local_path),
+        destination=destination,
+        name=file_name,
+        size=size,
+    )
+    await manager.registry.persist(record)
+
+    async def persist():
+        if record.context is not context:
+            raise TransferError("The upload journal changed; retry the transfer")
+        await manager.registry.persist(record)
+        if record.context is not context:
+            raise TransferError("The upload journal changed; retry the transfer")
+
+    cleanup = False
+    try:
+        if size <= 0:
+            raise TransferEmptyFile("Empty files cannot be uploaded to Telegram")
+        if manager._ensure_channel is not None:
+            await manager._ensure_channel()
+        if manager._check_upload_allowed is not None and not context.get(
+            "multipart_plan"
+        ):
+            manager._check_upload_allowed()
+        else:
+            await manager._verify_lineage(record)
+        destination = await manager._check_destination_or_cancel(record, destination)
+        if "multipart_plan" not in context:
+            if record.cancel_event.is_set():
+                raise TransferCancelled("Transfer cancelled")
+            bot_limit = manager.settings.bot_upload_limit
+            configured = getattr(manager.settings, "upload_split_mib", 2000)
+            # Premium affects account selection, never new document boundaries.
+            # A zero setting selects the standard document cap.
+            requested = configured * 1024**2 if configured else bot_limit
+            maximum = bot_limit
+            part_size = min(maximum, requested)
+            # Preserve bounded manifest size even for a deliberately tiny preference.
+            part_size = max(part_size, (size + MAX_FILE_PARTS - 1) // MAX_FILE_PARTS)
+            part_size = min(maximum, part_size)
+            if (size + part_size - 1) // part_size > MAX_FILE_PARTS:
+                raise TransferError("File exceeds the maximum number of Telegram parts")
+            await manager.registry.update(
+                record.id, phase="verifying", status=TransferStatus.RUNNING
+            )
+            async with manager._semaphore:
+                checksum, parts = await _fingerprint_owned(
+                    local_path,
+                    size,
+                    part_size,
+                    record.cancel_event,
+                )
+            if context.get("sha256") and context["sha256"] != checksum:
+                raise TransferError("Staged file changed. Reselect the source.")
+            context["sha256"] = checksum
+            context["multipart_plan"] = dict(
+                version=1,
+                kind="bot",
+                parts=parts,
+            )
+            await persist()
+        plan = context["multipart_plan"]
+        _validate_plan(plan, size, context.get("sha256"))
+        parts = plan["parts"]
+        # Restore persisted provider cooldowns before scheduling any new media effect.
+        for part in parts:
+            if part.get("sender") and part.get("retry_at", 0) > time.time():
+                await manager.pool.defer_client(part["sender"], part["retry_at"])
+        if context.get("channel_retry_at", 0) > time.time():
+            await manager.pool.defer_channel(context["channel_retry_at"])
+        in_flight = {}
+        active_parts = set()
+        await manager.registry.update(
+            record.id,
+            phase="queued",
+            status=TransferStatus.QUEUED,
+            current=sum(p["size"] for p in parts if p.get("confirmed")),
+            total=size,
+        )
+
+        async def report(waiting_phase=None):
+            if record.context is not context:
+                raise TransferError("The upload journal changed; retry the transfer")
+            current = sum(p["size"] for p in parts if p.get("confirmed"))
+            current += sum(in_flight.values())
+            phase = "finalizing" if current >= size else "uploading"
+            if not active_parts and waiting_phase:
+                phase = waiting_phase
+            if phase == "retry_wait":
+                future = [
+                    p.get("retry_at", 0)
+                    for p in parts
+                    if not p.get("confirmed") and p.get("retry_at", 0) > time.time()
+                ]
+                deadline = max(
+                    min(future, default=0),
+                    context.get("channel_retry_at", 0),
+                )
+                if deadline > time.time():
+                    context["retry_at"] = deadline
+            else:
+                context.pop("retry_at", None)
+            await manager.registry.update(
+                record.id,
+                phase=phase,
+                status=(
+                    TransferStatus.RUNNING
+                    if active_parts or current >= size
+                    else TransferStatus.QUEUED
+                ),
+                current=min(size, current),
+                total=size,
+            )
+            if record.context is not context:
+                raise TransferError("The upload journal changed; retry the transfer")
+
+        async def upload_part(part):
+            cancelling = record.cancel_event.is_set() or context.get("cancel_requested")
+            if part.get("confirmed") or (cancelling and part.get("deleted")):
+                return
+            while True:
+                if record.cancel_event.is_set() and not part.get("send_started"):
+                    return
+                remaining = part.get("retry_at", 0) - time.time()
+                if remaining > 0:
+                    await report(waiting_phase="retry_wait")
+                    await asyncio.sleep(remaining)
+                try:
+                    async with (
+                        manager.pool.lease(
+                            allow_users=True,
+                            prefer_premium=True,
+                            client_name=part.get("sender"),
+                            media=True,
+                            request_id=record.id,
+                        ) as client,
+                    ):
+                        await manager.registry.update(record.id, error=None)
+                        if part.get("sender") is None:
+                            part["sender"] = client.name
+                            if part["index"] == 0:
+                                context["sender"] = client.name
+                                context["random_id"] = part["random_id"]
+                            await persist()
+                        if record.cancel_event.is_set() and not part.get(
+                            "send_started"
+                        ):
+                            return
+                        active_parts.add(part["index"])
+                        await report()
+                        if part.get("message_id"):
+                            message = await client.get_messages(
+                                manager.settings.storage_channel,
+                                message_ids=part["message_id"],
+                            )
+                            if (
+                                message is None or getattr(message, "empty", False)
+                            ) and (
+                                record.cancel_event.is_set()
+                                or context.get("cancel_requested")
+                            ):
+                                # A delete can succeed before its local acknowledgement.
+                                # Absence completes cleanup, never a catalog upload.
+                                part["deleted"] = True
+                                active_parts.discard(part["index"])
+                                in_flight.pop(part["index"], None)
+                                await persist()
+                                return
+                        else:
+
+                            async def before_dispatch():
+                                await manager._check_destination_or_cancel(
+                                    record, destination
+                                )
+                                if record.cancel_event.is_set() and not part.get(
+                                    "send_started"
+                                ):
+                                    raise TransferCancelled("Transfer cancelled")
+                                part["send_started"] = True
+                                context["send_started"] = True
+                                await persist()
+
+                            async def progress(current, total):
+                                if record.cancel_event.is_set() and not part.get(
+                                    "send_started"
+                                ):
+                                    raise TransferCancelled("Transfer cancelled")
+                                in_flight[part["index"]] = min(current, part["size"])
+                                await report()
+
+                            name = (
+                                file_name
+                                if len(parts) == 1
+                                else (
+                                    file_name[:180]
+                                    + f".tgdrive-part-{part['index'] + 1:04d}"
+                                    + f"-of-{len(parts):04d}"
+                                )
+                            )
+                            message = await client.send_staged(
+                                manager.settings.storage_channel,
+                                local_path,
+                                file_name=name,
+                                random_id=part["random_id"],
+                                progress=progress,
+                                offset=part["offset"],
+                                size=part["size"],
+                                expected_sha256=part["sha256"],
+                                before_dispatch=before_dispatch,
+                                **(
+                                    {"preview_name": file_name}
+                                    if getattr(
+                                        client,
+                                        "supports_generated_thumbnails",
+                                        False,
+                                    )
+                                    and part["index"] == 0
+                                    else {}
+                                ),
+                            )
+                        if (
+                            message is None
+                            or type(getattr(message, "id", None)) is not int
+                        ):
+                            raise TransferError(
+                                "Telegram did not confirm the storage message"
+                            )
+                        if part.get("message_id") and part["message_id"] != message.id:
+                            raise TransferError(
+                                "Telegram returned a different part message"
+                            )
+                        document = getattr(
+                            getattr(message, "native", message), "document", None
+                        )
+                        document_id = getattr(document, "id", None)
+                        if (
+                            part.get("document_id") is not None
+                            and document_id != part["document_id"]
+                        ):
+                            raise TransferError(
+                                "Telegram part document identity changed"
+                            )
+                        if type(document_id) is int and document_id != 0:
+                            part["document_id"] = document_id
+                        part["message_id"] = message.id
+                        if part["index"] == 0:
+                            context["remote_message_id"] = message.id
+                        await persist()
+                        if record.cancel_event.is_set() or context.get(
+                            "cancel_requested"
+                        ):
+                            return
+                        media = _media_from_message(message)
+                        if (
+                            media is None
+                            or getattr(media, "file_size", part["size"]) != part["size"]
+                        ):
+                            raise TransferError(
+                                "Telegram returned an unexpected part size"
+                            )
+                        part["confirmed"] = True
+                        part.pop("retry_at", None)
+                        in_flight.pop(part["index"], None)
+                        active_parts.discard(part["index"])
+                        await persist()
+                        await report()
+                        return
+                except TransferCancelled:
+                    active_parts.discard(part["index"])
+                    in_flight.pop(part["index"], None)
+                    if part.get("send_started"):
+                        raise
+                    return
+                except (FloodWaitError, FloodPremiumWaitError) as exc:
+                    active_parts.discard(part["index"])
+                    in_flight.pop(part["index"], None)
+                    deadline = time.time() + exc.seconds + 0.25
+                    part["retry_at"] = deadline
+                    if getattr(exc, "tgdrive_channel_flood", False):
+                        context["channel_retry_at"] = deadline
+                    await persist()
+                    if getattr(exc, "tgdrive_channel_flood", False):
+                        await manager.pool.defer_channel(deadline)
+                    await manager.pool.defer_client(part["sender"], deadline)
+                    await report(waiting_phase="retry_wait")
+                except TelegramConnectionError:
+                    active_parts.discard(part["index"])
+                    in_flight.pop(part["index"], None)
+                    if not part.get("send_started") and not part.get("message_id"):
+                        # No message dispatch occurred: another account can safely
+                        # upload these same bytes without creating a duplicate.
+                        part["sender"] = None
+                        part.pop("retry_at", None)
+                        if part["index"] == 0:
+                            context.pop("sender", None)
+                        await persist()
+                        capacity = await manager.pool.media_capacity(allow_users=True)
+                        if capacity:
+                            continue
+                    raise
+                except ClientPoolNotRunning, NoClientAvailable:
+                    active_parts.discard(part["index"])
+                    in_flight.pop(part["index"], None)
+                    if record.cancel_event.is_set() and not part.get("send_started"):
+                        return
+                    await report(waiting_phase="waiting_for_telegram")
+                    await manager.registry.update(
+                        record.id,
+                        error="Waiting for Telegram; retrying automatically. "
+                        "Open Connections and Refresh to check the account and "
+                        "storage-channel access.",
+                    )
+                    await asyncio.sleep(1)
+
+        cursor = 0
+
+        async def worker():
+            nonlocal cursor
+            while cursor < len(parts):
+                part = parts[cursor]
+                cursor += 1
+                await upload_part(part)
+
+        workers = set()
+        all_workers = set()
+        try:
+            while workers or cursor < len(parts):
+                capacity = max(
+                    1,
+                    await manager.pool.media_capacity(allow_users=True),
+                )
+                target = min(capacity, len(workers) + len(parts) - cursor)
+                for _ in range(max(0, target - len(workers))):
+                    task = asyncio.create_task(worker())
+                    workers.add(task)
+                    all_workers.add(task)
+                if not workers:
+                    break
+                done, workers = await asyncio.wait(
+                    workers, timeout=1, return_when=asyncio.FIRST_COMPLETED
+                )
+                for task in done:
+                    task.result()
+        except BaseException:
+            for task in all_workers:
+                task.cancel()
+            await asyncio.gather(*all_workers, return_exceptions=True)
+            raise
+        destination = await manager._check_destination_or_cancel(record, destination)
+        if record.cancel_event.is_set() or context.get("cancel_requested"):
+            await _cleanup_parts(manager, record, parts)
+            cleanup = True
+            raise TransferCancelled("Transfer cancelled")
+        if not all(p.get("confirmed") for p in parts):
+            raise TransferError("Telegram has not confirmed every file part")
+        manifest = [
+            {
+                key: p[key]
+                for key in (
+                    "index",
+                    "offset",
+                    "size",
+                    "message_id",
+                    "sha256",
+                    "document_id",
+                )
+                if key in p
+            }
+            for p in parts
+        ]
+        # No await between catalog commit and its durable recovery marker.
+        await asyncio.to_thread(
+            manager.store.add_file,
+            destination,
+            file_name,
+            manifest[0]["message_id"],
+            size,
+            operation_id=record.id,
+            keep_both=True,
+            parts=manifest,
+            sha256=context["sha256"],
+        )
+        context["remote_message_id"] = manifest[0]["message_id"]
+        context["metadata_committed"] = True
+        context["catalog_revision"] = manager.store.revision
+        await persist()
+        await manager._protect_committed_upload(record, size)
+        cleanup = True
+    except asyncio.CancelledError:
+        # User cancellation before any message effect may safely release local bytes.
+        # Server shutdown keeps them for the durable QUEUED restart path.
+        if (
+            record.cancel_event.is_set() or context.get("cancel_requested")
+        ) and not context.get("send_started"):
+            cleanup = True
+        raise
+    except TransferCancelled:
+        # This path is reached only when there is no unpublished ambiguous effect.
+        if context.get("send_started") and not cleanup:
+            raise
+        record.status = TransferStatus.CANCELLED
+        record.phase = "cancelled"
+        record.error = "Transfer cancelled"
+        await persist()
+        cleanup = True
+    finally:
+        if cleanup:
+            await asyncio.to_thread(local_path.unlink, missing_ok=True)
+            uploads = getattr(manager, "uploads", None)
+            if uploads is not None:
+                await asyncio.to_thread(uploads.release, record.id)
+
+
+async def _cleanup_parts(manager, record, parts):
+    """Delete only journalled own messages and retain staging until confirmation."""
+    await manager._verify_lineage(record)
+    for part in parts:
+        if not part.get("message_id") or part.get("deleted"):
+            continue
+        while not part.get("deleted"):
+            remaining = (
+                max(
+                    part.get("retry_at", 0),
+                    record.context.get("channel_retry_at", 0),
+                )
+                - time.time()
+            )
+            if remaining > 0:
+                await manager.registry.update(record.id, phase="retry_wait")
+                await asyncio.sleep(remaining)
+            try:
+                async with manager.pool.lease(
+                    client_name=part["sender"],
+                    allow_users=True,
+                    media=True,
+                ) as client:
+                    await manager._verify_lineage(record)
+                    if part.get("document_id") is not None:
+                        before = await client.get_messages(
+                            manager.settings.storage_channel,
+                            message_ids=part["message_id"],
+                        )
+                        document = getattr(
+                            getattr(before, "native", before), "document", None
+                        )
+                        observed = getattr(document, "id", None)
+                        if before is not None and observed != part["document_id"]:
+                            raise TransferError(
+                                "Telegram part document identity changed"
+                            )
+                    await client.delete_messages(
+                        manager.settings.storage_channel,
+                        part["message_id"],
+                    )
+                    if callable(getattr(client, "get_messages", None)):
+                        message = await client.get_messages(
+                            manager.settings.storage_channel,
+                            message_ids=part["message_id"],
+                        )
+                        if message is not None and not getattr(message, "empty", False):
+                            raise TransferError(
+                                "Telegram part deletion confirmation is incomplete"
+                            )
+                    part["deleted"] = True
+                    part.pop("retry_at", None)
+                    await manager.registry.persist(record)
+            except FloodWaitError as exc:
+                # Deletion FloodWait conservatively pauses channel writes.
+                deadline = time.time() + exc.seconds + 0.25
+                part["retry_at"] = deadline
+                record.context["channel_retry_at"] = deadline
+                await manager.registry.persist(record)
+                await manager.pool.defer_channel(deadline)
+                await manager.pool.defer_client(part["sender"], deadline)
+            except ClientPoolNotRunning, NoClientAvailable:
+                await manager.registry.update(record.id, phase="waiting_for_telegram")
+                await asyncio.sleep(1)
diff --git a/tgdrive/transfers/remote.py b/tgdrive/transfers/remote.py
new file mode 100644
index 00000000..6276e716
--- /dev/null
+++ b/tgdrive/transfers/remote.py
@@ -0,0 +1,964 @@
+"""Bounded, SSRF-resistant remote file inspection and downloading."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import ipaddress
+import logging
+import mimetypes
+import os
+import re
+import shutil
+import socket
+import tempfile
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from contextvars import ContextVar
+from dataclasses import dataclass
+from email.message import Message
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Protocol
+from urllib.parse import unquote, urljoin, urlsplit, urlunsplit
+
+import aiohttp
+from aiohttp.abc import AbstractResolver
+from aiohttp.resolver import DefaultResolver
+
+if TYPE_CHECKING:
+    from tgdrive.transfers.remote_ranges import RangePolicy
+
+DEFAULT_MAX_BYTES = 4 * 1024 * 1024 * 1024
+DEFAULT_CHUNK_SIZE = 1024 * 1024
+REMOTE_MAX_ATTEMPTS = 4
+logger = logging.getLogger(__name__)
+_REDIRECT_STATUSES = frozenset({301, 302, 303, 307, 308})
+_CONTENT_RANGE_RE = re.compile(r"^bytes\s+\d+-\d+/(\d+|\*)$", re.IGNORECASE)
+_UNSAFE_FILENAME_CHARS = re.compile(r'[<>:"/\\|?*\x00-\x1f\x7f]')
+_WINDOWS_RESERVED_NAMES = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{number}" for number in range(1, 10)),
+    *(f"LPT{number}" for number in range(1, 10)),
+}
+
+
+class RemoteError(RuntimeError):
+    """Base class for safe remote-transfer failures."""
+
+
+class UnsafeRemoteURL(RemoteError):
+    """A URL or resolved address violates the outbound network policy."""
+
+
+class RemoteResolutionError(RemoteError):
+    """DNS resolution failed or returned unusable answers."""
+
+
+class TooManyRedirects(RemoteError):
+    """The configured manual redirect limit was exceeded."""
+
+
+class RemoteHTTPError(RemoteError):
+    def __init__(
+        self, status: int, url: str, *, retry_after: str | None = None
+    ) -> None:
+        self.status = status
+        self.url = url
+        self.retry_after = retry_after
+        super().__init__(f"remote server returned HTTP {status}")
+
+
+class RemoteProtocolError(RemoteError):
+    """The response cannot safely represent the requested file."""
+
+
+class RemoteIncompleteResponse(RemoteProtocolError):
+    """A known-length response ended before all promised bytes arrived."""
+
+
+class RemoteRetriesExhausted(RemoteError):
+    """A bounded source-retrieval retry cycle has failed."""
+
+
+class RemoteTooLarge(RemoteError):
+    def __init__(self, limit: int, observed: int | None = None) -> None:
+        self.limit = limit
+        self.observed = observed
+        detail = f" ({observed} bytes observed)" if observed is not None else ""
+        super().__init__(f"remote file exceeds the {limit}-byte limit{detail}")
+
+
+class RemoteCancelled(RemoteError):
+    """The supplied cancellation event was set."""
+
+
+class RemoteTimeout(RemoteError):
+    """The connect/read/total timeout budget expired."""
+
+
+class RemoteDestinationExists(RemoteError):
+    """The safe destination name already exists and overwrite is disabled."""
+
+
+type ProgressCallback = Callable[[int, int | None], Awaitable[None] | None]
+type RetryCallback = Callable[[int, float, Exception], Awaitable[None] | None]
+
+
+def source_retryable(error: Exception) -> bool:
+    # Invalid URLs, unsafe redirects, certificate failures, size/storage errors
+    # and permanent HTTP responses must not become automatic request loops.
+    if isinstance(error, aiohttp.ClientSSLError):
+        return False
+    if isinstance(error, RemoteHTTPError):
+        return error.status in {408, 429, 500, 502, 503, 504}
+    return isinstance(
+        error,
+        (
+            aiohttp.ClientConnectionError,
+            aiohttp.ClientPayloadError,
+            ConnectionError,
+            TimeoutError,
+            RemoteResolutionError,
+            RemoteTimeout,
+            RemoteIncompleteResponse,
+        ),
+    )
+
+
+class HTTPSessionLike(Protocol):
+    def request(self, method: str, url: str, **kwargs: Any) -> Awaitable[Any]: ...
+
+    def close(self) -> Awaitable[None] | None: ...
+
+
+type SessionFactory = Callable[
+    [AbstractResolver, aiohttp.ClientTimeout],
+    HTTPSessionLike | Awaitable[HTTPSessionLike],
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteTimeouts:
+    connect: float = 10.0
+    read: float = 30.0
+    total: float = 60.0 * 60.0
+
+    def __post_init__(self) -> None:
+        if self.connect <= 0 or self.read <= 0 or self.total <= 0:
+            raise ValueError("remote timeouts must be positive")
+
+    def to_aiohttp(self) -> aiohttp.ClientTimeout:
+        return aiohttp.ClientTimeout(
+            total=self.total,
+            sock_connect=self.connect,
+            sock_read=self.read,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class RemoteFileInfo:
+    url: str
+    filename: str
+    size: int | None
+    content_type: str | None
+    etag: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class DownloadResult:
+    path: Path
+    url: str
+    filename: str
+    size: int
+    content_type: str | None
+
+
+def address_is_forbidden(address: str) -> bool:
+    """Return whether an IP belongs to a non-public address category."""
+
+    try:
+        parsed = ipaddress.ip_address(address.split("%", 1)[0])
+    except ValueError as error:
+        raise RemoteResolutionError("DNS returned a non-IP address") from error
+
+    addresses = [parsed]
+    if isinstance(parsed, ipaddress.IPv6Address) and parsed.ipv4_mapped is not None:
+        addresses.append(parsed.ipv4_mapped)
+
+    return any(
+        # Shared address space (100.64.0.0/10) is neither private nor reserved
+        # in ipaddress, but can reach internal services and cloud metadata.
+        not ip.is_global
+        or ip.is_loopback
+        or ip.is_private
+        or ip.is_link_local
+        or ip.is_multicast
+        or ip.is_reserved
+        or ip.is_unspecified
+        or (isinstance(ip, ipaddress.IPv6Address) and ip.is_site_local)
+        for ip in addresses
+    )
+
+
+class ValidatingResolver(AbstractResolver):
+    """Validate every DNS answer before aiohttp may connect to it.
+
+    Installing this resolver in the connector is important: a separate DNS
+    preflight alone would remain vulnerable to DNS rebinding between the check
+    and the connection.
+    """
+
+    def __init__(
+        self,
+        resolver: AbstractResolver,
+        *,
+        allow_private: bool = False,
+    ) -> None:
+        self._resolver = resolver
+        self.allow_private = allow_private
+        self._closed = False
+
+    async def resolve(
+        self,
+        host: str,
+        port: int = 0,
+        family: int = socket.AF_INET,
+    ) -> list[dict[str, Any]]:
+        try:
+            answers = await self._resolver.resolve(host, port, family)
+        except UnsafeRemoteURL:
+            raise
+        except Exception as error:
+            raise RemoteResolutionError(f"could not resolve host {host!r}") from error
+
+        if not answers:
+            raise RemoteResolutionError(f"host {host!r} returned no DNS answers")
+        if not self.allow_private:
+            for answer in answers:
+                address = answer.get("host")
+                if not isinstance(address, str) or address_is_forbidden(address):
+                    raise UnsafeRemoteURL(
+                        f"host {host!r} resolves to a non-public address"
+                    )
+        return answers
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        result = self._resolver.close()
+        if inspect.isawaitable(result):
+            await result
+
+
+def safe_filename(
+    content_disposition: str | None,
+    url: str,
+    content_type: str | None = None,
+    *,
+    fallback: str = "download.bin",
+    max_length: int = 200,
+) -> str:
+    """Derive a cross-platform basename without trusting remote path data."""
+
+    candidate: str | None = None
+    if content_disposition:
+        message = Message()
+        message["content-disposition"] = content_disposition
+        candidate = message.get_filename()
+
+    if not candidate:
+        candidate = unquote(urlsplit(url).path.rsplit("/", 1)[-1])
+    candidate = unquote(candidate or "").replace("\\", "/").rsplit("/", 1)[-1]
+    candidate = _UNSAFE_FILENAME_CHARS.sub("_", candidate).strip().rstrip(". ")
+
+    if candidate in ("", ".", ".."):
+        extension = mimetypes.guess_extension((content_type or "").split(";", 1)[0])
+        candidate = f"download{extension}" if extension else fallback
+
+    stem = candidate.split(".", 1)[0].upper()
+    if stem in _WINDOWS_RESERVED_NAMES:
+        candidate = f"_{candidate}"
+
+    if max_length <= 0:
+        raise ValueError("max_length must be positive")
+    candidate = candidate[:max_length].rstrip(". ")
+    return candidate or fallback
+
+
+class RemoteClient:
+    """Inspect and adaptively retrieve remote files with strict network limits."""
+
+    def __init__(
+        self,
+        *,
+        max_bytes: int = DEFAULT_MAX_BYTES,
+        max_redirects: int = 5,
+        min_free_bytes: int = 0,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        timeouts: RemoteTimeouts | None = None,
+        allow_private: bool = False,
+        resolver: AbstractResolver | None = None,
+        session: HTTPSessionLike | None = None,
+        session_factory: SessionFactory | None = None,
+        range_policy: RangePolicy | None = None,
+        download_concurrency: int = 2,
+    ) -> None:
+        if max_bytes <= 0:
+            raise ValueError("max_bytes must be positive")
+        if max_redirects < 0:
+            raise ValueError("max_redirects cannot be negative")
+        if chunk_size <= 0:
+            raise ValueError("chunk_size must be positive")
+        if session is not None and session_factory is not None:
+            raise ValueError("provide either session or session_factory, not both")
+
+        self._resolver = (
+            None
+            if resolver is None
+            else (
+                resolver
+                if isinstance(resolver, ValidatingResolver)
+                else ValidatingResolver(resolver, allow_private=allow_private)
+            )
+        )
+        self.allow_private = allow_private
+        self.max_bytes = max_bytes
+        self.min_free_bytes = min_free_bytes
+        self.max_redirects = max_redirects
+        self.chunk_size = chunk_size
+        self.timeouts = timeouts or RemoteTimeouts()
+        self._session = session
+        self._session_factory = session_factory
+        self._owns_session = session is None
+        self._owns_resolver = resolver is None
+        self._closed = False
+        self._session_lock = asyncio.Lock()
+        from tgdrive.transfers.remote_ranges import RangePolicy
+
+        self.range_policy = range_policy or RangePolicy()
+        self._range_slots = asyncio.Semaphore(16)
+        from tgdrive.transfers.remote_scheduler import URLDownloadScheduler
+
+        self.scheduler = URLDownloadScheduler(download_concurrency)
+        self._download_ticket: ContextVar[Any] = ContextVar(
+            "url_download", default=None
+        )
+
+    async def __aenter__(self) -> RemoteClient:
+        await self._get_session()
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        async with self._session_lock:
+            if self._closed:
+                return
+            self._closed = True
+            session = self._session if self._owns_session else None
+            resolver = self._resolver if self._owns_resolver else None
+        try:
+            if session is not None:
+                result = session.close()
+                if inspect.isawaitable(result):
+                    await result
+        finally:
+            if resolver is not None:
+                await resolver.close()
+
+    async def inspect(
+        self,
+        url: str,
+        *,
+        cancel_event: asyncio.Event | None = None,
+    ) -> RemoteFileInfo:
+        """Inspect headers without downloading a response body."""
+
+        try:
+            async with asyncio.timeout(self.timeouts.total):
+                return await self._inspect(url, cancel_event=cancel_event)
+        except TimeoutError as error:
+            raise RemoteTimeout("remote inspection timed out") from error
+
+    async def download(
+        self,
+        url: str,
+        output_dir: str | Path,
+        *,
+        filename: str | None = None,
+        overwrite: bool = False,
+        cancel_event: asyncio.Event | None = None,
+        progress: ProgressCallback | None = None,
+        max_bytes: int | None = None,
+        single_threaded: bool = False,
+        can_promote: Callable[[], bool] | None = None,
+        mode_changed: Callable[[str], Awaitable[None] | None] | None = None,
+        retry: RetryCallback | None = None,
+        retry_not_before: float = 0,
+    ) -> DownloadResult:
+        """Retry temporary source failures within one shared operation budget."""
+        from tgdrive.transfers.remote_ranges import RangeFallback, _retry_after
+
+        parallel = not single_threaded
+        try:
+            async with asyncio.timeout(self.timeouts.total):
+                if retry_not_before:
+                    await self._wait_for_retry(
+                        max(0, retry_not_before - time.time()), cancel_event
+                    )
+                for attempt in range(1, REMOTE_MAX_ATTEMPTS + 1):
+                    self._raise_if_cancelled(cancel_event)
+                    failure = None
+                    try:
+                        async with self.scheduler.admit(
+                            lambda wait: self._cancelable(wait, cancel_event),
+                            can_promote,
+                            mode_changed,
+                        ) as ticket:
+                            token = self._download_ticket.set(ticket)
+                            try:
+                                return await self._download(
+                                    url,
+                                    Path(output_dir),
+                                    filename=filename,
+                                    overwrite=overwrite,
+                                    cancel_event=cancel_event,
+                                    progress=progress,
+                                    max_bytes=self.max_bytes
+                                    if max_bytes is None
+                                    else max_bytes,
+                                    parallel=parallel,
+                                )
+                            finally:
+                                self._download_ticket.reset(token)
+                    except RangeFallback as error:
+                        # The initial full response can also break while ranges
+                        # are running. All remaining attempts stay single-stream.
+                        parallel = False
+                        failure = error
+                        delay = error.retry_after
+                        if delay or (
+                            error.__cause__ is not None
+                            and source_retryable(error.__cause__)
+                        ):
+                            delay = max(2.0**attempt, delay)
+                    except Exception as error:
+                        if not source_retryable(error):
+                            raise
+                        parallel = False
+                        failure = error
+                        delay = 2.0**attempt
+                        if (
+                            isinstance(error, RemoteHTTPError)
+                            and error.retry_after is not None
+                        ):
+                            delay = max(delay, _retry_after(error.retry_after))
+                    if attempt == REMOTE_MAX_ATTEMPTS:
+                        raise RemoteRetriesExhausted(
+                            "Source download failed after 4 attempts. "
+                            "Try again later or use another source link."
+                        ) from failure
+                    self._raise_if_cancelled(cancel_event)
+                    # The failed response/file and scheduler slot are released
+                    # before callbacks or backoff can block another download.
+                    if retry is not None:
+                        result = retry(attempt + 1, delay, failure)
+                        if inspect.isawaitable(result):
+                            await result
+                    else:
+                        logger.info(
+                            "Source retry scheduled attempt=%s/%s error_type=%s "
+                            "retry_after_seconds=%.3f",
+                            attempt + 1,
+                            REMOTE_MAX_ATTEMPTS,
+                            type(failure).__name__,
+                            delay,
+                        )
+                    await self._wait_for_retry(delay, cancel_event)
+        except TimeoutError as error:
+            raise RemoteTimeout("remote download timed out") from error
+        raise AssertionError("remote retry loop exhausted unexpectedly")
+
+    async def _wait_for_retry(self, delay: float, cancel_event) -> None:
+        await self._cancelable(asyncio.sleep(delay), cancel_event)
+
+    async def _inspect(
+        self,
+        url: str,
+        *,
+        cancel_event: asyncio.Event | None,
+    ) -> RemoteFileInfo:
+        response = None
+        final_url = url
+        try:
+            response, final_url = await self._request_following_redirects(
+                url,
+                headers={"Accept-Encoding": "identity", "Range": "bytes=0-0"},
+                cancel_event=cancel_event,
+            )
+            if response.status not in (200, 206):
+                raise RemoteHTTPError(
+                    response.status,
+                    final_url,
+                    retry_after=self._header(response.headers, "Retry-After"),
+                )
+            self._require_identity_encoding(response.headers)
+            size = self._declared_size(response.status, response.headers)
+            self._enforce_size(size)
+            content_type = self._header(response.headers, "Content-Type")
+            return RemoteFileInfo(
+                url=final_url,
+                filename=safe_filename(
+                    self._header(response.headers, "Content-Disposition"),
+                    final_url,
+                    content_type,
+                ),
+                size=size,
+                content_type=(content_type.split(";", 1)[0] if content_type else None),
+                etag=self._header(response.headers, "ETag"),
+            )
+        finally:
+            await self._release_response(response)
+
+    async def _download(
+        self,
+        url: str,
+        output_dir: Path,
+        *,
+        filename: str | None,
+        overwrite: bool,
+        cancel_event: asyncio.Event | None,
+        progress: ProgressCallback | None,
+        max_bytes: int,
+        parallel: bool,
+    ) -> DownloadResult:
+        response = None
+        temp_path: Path | None = None
+        temp_file: Any = None
+        final_url = url
+        try:
+            response, final_url = await self._request_following_redirects(
+                url,
+                headers={"Accept-Encoding": "identity"},
+                cancel_event=cancel_event,
+            )
+            if response.status != 200:
+                raise RemoteHTTPError(
+                    response.status,
+                    final_url,
+                    retry_after=self._header(response.headers, "Retry-After"),
+                )
+            self._require_identity_encoding(response.headers)
+            declared_size = self._declared_size(response.status, response.headers)
+            self._enforce_size(declared_size, max_bytes)
+
+            content_type = self._header(response.headers, "Content-Type")
+            chosen_name = safe_filename(
+                None
+                if filename is not None
+                else self._header(response.headers, "Content-Disposition"),
+                final_url if filename is None else filename,
+                content_type,
+            )
+            output_dir = await asyncio.to_thread(
+                self._prepare_output_dir,
+                output_dir,
+            )
+            final_path = output_dir / chosen_name
+            if final_path.exists() and not overwrite:
+                raise RemoteDestinationExists(
+                    f"destination {chosen_name!r} already exists"
+                )
+
+            temp_file = tempfile.NamedTemporaryFile(  # noqa: SIM115
+                mode="wb",
+                prefix=f".{chosen_name}.",
+                suffix=".part",
+                dir=output_dir,
+                delete=False,
+            )
+            temp_path = Path(temp_file.name)
+            downloaded = 0
+            await self._report_progress(progress, downloaded, declared_size)
+
+            from tgdrive.transfers.remote_ranges import download_ranges, range_validator
+
+            validator = range_validator(response.headers)
+            ticket = self._download_ticket.get()
+            while True:
+                if (
+                    parallel
+                    and self.range_policy.max_connections > 1
+                    and declared_size is not None
+                    and declared_size - downloaded >= self.range_policy.minimum_size
+                    and validator is not None
+                    and (ticket is None or ticket.full_speed)
+                ):
+                    # A waiting source can switch to parallel ranges in-place
+                    # after promotion, keeping its already received prefix.
+                    await download_ranges(
+                        self,
+                        response,
+                        final_url,
+                        temp_file,
+                        output_dir,
+                        declared_size,
+                        validator,
+                        cancel_event,
+                        progress,
+                        initial_offset=downloaded,
+                    )
+                    downloaded = declared_size
+                    break
+                chunk = await self._read_chunk(response.content, cancel_event)
+                if not chunk:
+                    break
+                downloaded += len(chunk)
+                self._enforce_size(downloaded, max_bytes)
+                await self._disk_io(self._write_chunk, temp_file, chunk, output_dir)
+                await self._report_progress(progress, downloaded, declared_size)
+
+            if declared_size is not None and downloaded != declared_size:
+                error_type = (
+                    RemoteIncompleteResponse
+                    if downloaded < declared_size
+                    else RemoteProtocolError
+                )
+                raise error_type(
+                    f"remote stream ended at {downloaded} of {declared_size} bytes"
+                )
+
+            await self._disk_io(temp_file.flush)
+            await self._disk_io(os.fsync, temp_file.fileno())
+            temp_file.close()
+            temp_file = None
+            await self._disk_io(
+                self._publish_temp, temp_path, final_path, overwrite=overwrite
+            )
+            temp_path = None
+            return DownloadResult(
+                path=final_path,
+                url=final_url,
+                filename=chosen_name,
+                size=downloaded,
+                content_type=(content_type.split(";", 1)[0] if content_type else None),
+            )
+        except BaseException:
+            if temp_file is not None:
+                temp_file.close()
+            if temp_path is not None:
+                temp_path.unlink(missing_ok=True)
+            raise
+        finally:
+            await self._release_response(response)
+
+    async def _request_following_redirects(
+        self,
+        url: str,
+        *,
+        headers: Mapping[str, str],
+        cancel_event: asyncio.Event | None,
+    ) -> tuple[Any, str]:
+        current = url
+        session = await self._get_session()
+
+        for redirect_count in range(self.max_redirects + 1):
+            self._raise_if_cancelled(cancel_event)
+            current = await self._cancelable(self._validate_url(current), cancel_event)
+            response = await self._cancelable(
+                session.request(
+                    "GET",
+                    current,
+                    headers=dict(headers),
+                    allow_redirects=False,
+                    timeout=self.timeouts.to_aiohttp(),
+                ),
+                cancel_event,
+                cleanup=self._release_response,
+            )
+            if response.status not in _REDIRECT_STATUSES:
+                return response, current
+
+            location = self._header(response.headers, "Location")
+            await self._release_response(response)
+            if not location:
+                raise RemoteProtocolError("redirect response omitted Location")
+            if redirect_count >= self.max_redirects:
+                raise TooManyRedirects(
+                    f"remote exceeded {self.max_redirects} redirect(s)"
+                )
+            current = urljoin(current, location)
+
+        raise AssertionError("redirect loop exhausted unexpectedly")
+
+    async def _validate_url(self, url: str) -> str:
+        if not isinstance(url, str) or not url:
+            raise UnsafeRemoteURL("remote URL must be a non-empty string")
+        if any(ord(character) < 0x20 for character in url):
+            raise UnsafeRemoteURL("remote URL contains control characters")
+
+        parsed = urlsplit(url)
+        if parsed.scheme.lower() not in ("http", "https"):
+            raise UnsafeRemoteURL("only http and https URLs are allowed")
+        if parsed.username is not None or parsed.password is not None:
+            raise UnsafeRemoteURL("userinfo is not allowed in remote URLs")
+        if not parsed.hostname:
+            raise UnsafeRemoteURL("remote URL must include a hostname")
+        try:
+            port = parsed.port or (443 if parsed.scheme.lower() == "https" else 80)
+        except ValueError as error:
+            raise UnsafeRemoteURL("remote URL has an invalid port") from error
+
+        host = parsed.hostname
+        try:
+            literal = ipaddress.ip_address(host.split("%", 1)[0])
+        except ValueError:
+            try:
+                host.encode("idna")
+            except UnicodeError as error:
+                raise UnsafeRemoteURL("remote hostname is invalid") from error
+            resolver = self._resolver
+            if resolver is None:
+                raise RuntimeError("remote resolver was not initialized") from None
+            await resolver.resolve(host, port, socket.AF_UNSPEC)
+        else:
+            if not self.allow_private and address_is_forbidden(str(literal)):
+                raise UnsafeRemoteURL("remote URL uses a non-public IP address")
+
+        return urlunsplit(
+            (
+                parsed.scheme.lower(),
+                parsed.netloc,
+                parsed.path or "/",
+                parsed.query,
+                "",
+            )
+        )
+
+    async def _get_session(self) -> HTTPSessionLike:
+        async with self._session_lock:
+            if self._closed:
+                raise RemoteError("remote client is closed")
+            if self._resolver is None:
+                self._resolver = ValidatingResolver(
+                    DefaultResolver(),
+                    allow_private=self.allow_private,
+                )
+            resolver = self._resolver
+            if self._session is not None:
+                return self._session
+
+            timeout = self.timeouts.to_aiohttp()
+            if self._session_factory is not None:
+                value = self._session_factory(resolver, timeout)
+                self._session = await value if inspect.isawaitable(value) else value
+            else:
+                connector = aiohttp.TCPConnector(
+                    resolver=resolver,
+                    use_dns_cache=False,
+                )
+                self._session = aiohttp.ClientSession(
+                    connector=connector,
+                    timeout=timeout,
+                    auto_decompress=False,
+                    trust_env=False,
+                    read_bufsize=self.chunk_size,
+                )
+            return self._session
+
+    def _write_chunk(
+        self, output: Any, chunk: bytes, directory: Path, offset: int | None = None
+    ) -> None:
+        if self.min_free_bytes and shutil.disk_usage(directory).free < (
+            self.min_free_bytes + len(chunk)
+        ):
+            raise RemoteError("Temporary storage is full. Free disk space and retry.")
+        if offset is None:
+            output.write(chunk)
+        else:
+            remaining = memoryview(chunk)
+            while remaining:
+                written = os.pwrite(output.fileno(), remaining, offset)
+                if written <= 0:
+                    raise OSError("remote staging write made no progress")
+                remaining = remaining[written:]
+                offset += written
+
+    @staticmethod
+    async def _disk_io(operation: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+        # Cancelling an await does not stop its thread. Drain the write before
+        # any worker/file cleanup can close or reuse its descriptor.
+        worker = asyncio.create_task(asyncio.to_thread(operation, *args, **kwargs))
+        try:
+            return await asyncio.shield(worker)
+        except asyncio.CancelledError:
+            while not worker.done():
+                try:
+                    await asyncio.shield(worker)
+                except asyncio.CancelledError:
+                    continue
+                except Exception:
+                    break
+            if not worker.cancelled():
+                worker.exception()
+            raise
+
+    async def _read_chunk(
+        self,
+        content: Any,
+        cancel_event: asyncio.Event | None,
+        limit: int | None = None,
+    ) -> bytes:
+        from tgdrive.transfers.remote_scheduler import WARM_READ_SIZE
+
+        ticket = self._download_ticket.get()
+        if ticket is not None:
+            await self._cancelable(ticket.pace(), cancel_event)
+        size = self.chunk_size if limit is None else limit
+        if ticket is not None and not ticket.full_speed:
+            size = min(size, WARM_READ_SIZE)
+        result = await self._cancelable(content.read(size), cancel_event)
+        if ticket is not None:
+            ticket.received(len(result))
+        return result
+
+    async def _cancelable(
+        self,
+        operation: Awaitable[Any],
+        cancel_event: asyncio.Event | None,
+        *,
+        cleanup: Callable[[Any], Awaitable[None]] | None = None,
+    ) -> Any:
+        if cancel_event is None:
+            return await operation
+        read_task = asyncio.ensure_future(operation)
+        cancel_task = asyncio.create_task(cancel_event.wait())
+        delivered = False
+        try:
+            await asyncio.wait(
+                (read_task, cancel_task),
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            if cancel_event.is_set():
+                read_task.cancel()
+                raise RemoteCancelled("remote download was cancelled")
+            result = await read_task
+            delivered = True
+            return result
+        finally:
+            cancel_task.cancel()
+            if not read_task.done():
+                read_task.cancel()
+            await asyncio.gather(read_task, cancel_task, return_exceptions=True)
+            if (
+                cleanup is not None
+                and not delivered
+                and not read_task.cancelled()
+                and read_task.exception() is None
+            ):
+                await cleanup(read_task.result())
+
+    @staticmethod
+    async def _report_progress(
+        callback: ProgressCallback | None,
+        current: int,
+        total: int | None,
+    ) -> None:
+        if callback is None:
+            return
+        value = callback(current, total)
+        if inspect.isawaitable(value):
+            await value
+
+    @staticmethod
+    def _raise_if_cancelled(cancel_event: asyncio.Event | None) -> None:
+        if cancel_event is not None and cancel_event.is_set():
+            raise RemoteCancelled("remote operation was cancelled")
+
+    def _enforce_size(self, size: int | None, limit: int | None = None) -> None:
+        maximum = self.max_bytes if limit is None else limit
+        if size is not None and size > maximum:
+            raise RemoteTooLarge(maximum, size)
+
+    @classmethod
+    def _declared_size(cls, status: int, headers: Mapping[str, str]) -> int | None:
+        content_range = cls._header(headers, "Content-Range")
+        if content_range:
+            match = _CONTENT_RANGE_RE.fullmatch(content_range.strip())
+            if match and match.group(1) != "*":
+                return int(match.group(1))
+        if status == 200:
+            content_length = cls._header(headers, "Content-Length")
+            if content_length is not None:
+                try:
+                    value = int(content_length)
+                except ValueError as error:
+                    raise RemoteProtocolError(
+                        "invalid Content-Length header"
+                    ) from error
+                if value < 0:
+                    raise RemoteProtocolError("negative Content-Length header")
+                return value
+        return None
+
+    @classmethod
+    def _require_identity_encoding(cls, headers: Mapping[str, str]) -> None:
+        encoding = cls._header(headers, "Content-Encoding")
+        if encoding and encoding.strip().lower() != "identity":
+            raise RemoteProtocolError("remote ignored identity content encoding")
+
+    @staticmethod
+    def _header(headers: Mapping[str, str], name: str) -> str | None:
+        direct = headers.get(name)
+        if direct is not None:
+            return str(direct)
+        lowered = name.lower()
+        for key, value in headers.items():
+            if str(key).lower() == lowered:
+                return str(value)
+        return None
+
+    @staticmethod
+    async def _release_response(response: Any | None) -> None:
+        if response is None:
+            return
+        release = getattr(response, "release", None)
+        if callable(release):
+            result = release()
+            if inspect.isawaitable(result):
+                await result
+            return
+        close = getattr(response, "close", None)
+        if callable(close):
+            result = close()
+            if inspect.isawaitable(result):
+                await result
+
+    @staticmethod
+    def _prepare_output_dir(output_dir: Path) -> Path:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        return output_dir.resolve()
+
+    @staticmethod
+    def _publish_temp(temp_path: Path, final_path: Path, *, overwrite: bool) -> None:
+        if overwrite:
+            os.replace(temp_path, final_path)
+        else:
+            try:
+                os.link(temp_path, final_path)
+            except FileExistsError as error:
+                raise RemoteDestinationExists(
+                    f"destination {final_path.name!r} already exists"
+                ) from error
+            else:
+                temp_path.unlink()
+        descriptor = os.open(final_path.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
diff --git a/tgdrive/transfers/remote_ranges.py b/tgdrive/transfers/remote_ranges.py
new file mode 100644
index 00000000..fadddb58
--- /dev/null
+++ b/tgdrive/transfers/remote_ranges.py
@@ -0,0 +1,287 @@
+"""Adaptive, validator-bound HTTP ranges written into one unpublished file."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import TYPE_CHECKING, Any
+
+from aiohttp import ClientConnectionError, ClientPayloadError, ClientSSLError
+
+from tgdrive.transfers.remote import RemoteCancelled, RemoteError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from tgdrive.transfers.remote import ProgressCallback, RemoteClient
+
+MIB = 1024 * 1024
+_RANGE = re.compile(r"bytes\s+(\d+)-(\d+)/(\d+)", re.IGNORECASE)
+_STRONG_ETAG = re.compile(r'"[\x21\x23-\x7e\x80-\xff]*"')
+
+
+@dataclass(frozen=True, slots=True)
+class RangePolicy:
+    minimum_size: int = 16 * MIB
+    block_size: int = 8 * MIB
+    max_connections: int = 8
+    sample_seconds: float = 1.0
+
+    def __post_init__(self) -> None:
+        if self.block_size <= 0 or self.minimum_size < 2 * self.block_size:
+            raise ValueError(
+                "parallel threshold must cover at least two positive blocks"
+            )
+        if not 1 <= self.max_connections <= 8 or self.sample_seconds <= 0:
+            raise ValueError("invalid remote range concurrency or sample interval")
+
+
+class RangeFallback(RemoteError):
+    """Drain all writers and restart once using an ordinary full response."""
+
+    def __init__(self, size: int, *, retry_after: float = 0) -> None:
+        super().__init__("source cannot safely continue parallel retrieval")
+        self.size = size
+        self.retry_after = retry_after
+
+
+def range_validator(headers: Any) -> str | None:
+    """An advertised range capability alone cannot identify immutable bytes."""
+    from tgdrive.transfers.remote import RemoteClient
+
+    if (RemoteClient._header(headers, "Accept-Ranges") or "").lower() == "none":
+        return None
+    etag = (RemoteClient._header(headers, "ETag") or "").strip()
+    return etag if _STRONG_ETAG.fullmatch(etag) else None
+
+
+class RangeConcurrency:
+    """Probe 2 → 4 → 8, keeping a lower width when added streams do not help."""
+
+    def __init__(self, maximum: int) -> None:
+        self.maximum = maximum
+        self.target = min(2, maximum)
+        self.accepted = self.target
+        self.rate = 0.0
+        self.probing = False
+        self.settled = False
+        self.slow_samples = 0
+
+    def observe(self, rate: float) -> int:
+        if rate <= 0:
+            return self.target
+        if self.probing:
+            if rate < self.rate * 1.10:
+                self.target = self.accepted
+                self.settled = True
+            else:
+                self.accepted, self.rate = self.target, rate
+            self.probing = False
+        elif not self.rate:
+            self.rate = rate
+        elif self.settled or self.target == self.maximum:
+            self.slow_samples = self.slow_samples + 1 if rate < self.rate * 0.7 else 0
+            if self.slow_samples >= 2 and self.target > 2:
+                self.target = self.accepted = max(2, self.target // 2)
+                self.rate, self.slow_samples = rate, 0
+            return self.target
+        if not self.settled and self.target < self.maximum:
+            self.target = min(self.maximum, self.target * 2)
+            self.probing = True
+        return self.target
+
+
+def _retry_after(value: str | None) -> float:
+    if value is not None:
+        try:
+            return max(0.0, float(int(value)))
+        except ValueError, OverflowError:
+            try:
+                return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+            except ValueError, TypeError, OverflowError:
+                pass
+    return 1.0
+
+
+async def download_ranges(
+    client: RemoteClient,
+    initial: Any,
+    url: str,
+    output: Any,
+    directory: Path,
+    size: int,
+    validator: str,
+    cancel_event: asyncio.Event | None,
+    progress: ProgressCallback | None,
+    *,
+    initial_offset: int = 0,
+) -> None:
+    policy = client.range_policy
+    controller = RangeConcurrency(policy.max_connections)
+    prefix_end = initial_offset + policy.block_size
+    next_offset = prefix_end
+    block_size = policy.block_size
+    written = initial_offset
+    live_workers = 0
+    progress_lock = asyncio.Lock()
+    workers: set[asyncio.Task[None]] = set()
+    all_workers: set[asyncio.Task[None]] = set()
+    cancelled = asyncio.create_task(cancel_event.wait()) if cancel_event else None
+
+    async def consume(response: Any, start: int, end: int, *, exact: bool) -> int:
+        nonlocal written
+        cursor = start
+        while cursor < end:
+            chunk = await client._read_chunk(
+                response.content, cancel_event, min(client.chunk_size, end - cursor)
+            )
+            if not chunk or len(chunk) > end - cursor:
+                raise RangeFallback(size)
+            await client._disk_io(client._write_chunk, output, chunk, directory, cursor)
+            cursor += len(chunk)
+            async with progress_lock:
+                written += len(chunk)
+                await client._report_progress(progress, written, size)
+        if exact and await client._read_chunk(response.content, cancel_event, 1):
+            raise RangeFallback(size)
+        return cursor
+
+    async def fetch(start: int, end: int) -> None:
+        # Failed ranges are discarded before a single-stream fallback. Never
+        # retry a partial interval while counting the same bytes a second time.
+        response = None
+        try:
+            async with client._range_slots:
+                response, final_url = await client._request_following_redirects(
+                    url,
+                    headers={
+                        "Accept-Encoding": "identity",
+                        "Range": f"bytes={start}-{end - 1}",
+                        "If-Range": validator,
+                    },
+                    cancel_event=cancel_event,
+                )
+                if response.status in {429, 503}:
+                    raise RangeFallback(
+                        size,
+                        retry_after=_retry_after(
+                            client._header(response.headers, "Retry-After")
+                        ),
+                    )
+                if response.status != 206 or final_url != url:
+                    raise RangeFallback(size)
+                content_range = _RANGE.fullmatch(
+                    (client._header(response.headers, "Content-Range") or "").strip()
+                )
+                if (
+                    content_range is None
+                    or tuple(map(int, content_range.groups())) != (start, end - 1, size)
+                    or range_validator(response.headers) != validator
+                    or (
+                        client._header(response.headers, "Content-Encoding")
+                        or "identity"
+                    )
+                    .strip()
+                    .lower()
+                    != "identity"
+                ):
+                    raise RangeFallback(size)
+                length = client._header(response.headers, "Content-Length")
+                if length is not None and length.strip() != str(end - start):
+                    raise RangeFallback(size)
+                await consume(response, start, end, exact=True)
+        except ClientSSLError:
+            raise
+        except (ClientConnectionError, ClientPayloadError, TimeoutError) as error:
+            raise RangeFallback(size) from error
+        finally:
+            await client._release_response(response)
+
+    async def worker(*, prefix: bool = False) -> None:
+        nonlocal next_offset, block_size, live_workers
+        try:
+            if prefix:
+                try:
+                    await consume(initial, initial_offset, prefix_end, exact=False)
+                except ClientSSLError:
+                    raise
+                except (
+                    ClientConnectionError,
+                    ClientPayloadError,
+                    TimeoutError,
+                ) as error:
+                    raise RangeFallback(size) from error
+                finally:
+                    await client._release_response(initial)
+                return
+            while next_offset < size and live_workers <= controller.target:
+                client._raise_if_cancelled(cancel_event)
+                start = next_offset
+                fair_block = max(policy.block_size, (size - start) // controller.target)
+                end = min(size, start + min(block_size, fair_block))
+                next_offset = end
+                began = time.monotonic()
+                await fetch(start, end)
+                elapsed = time.monotonic() - began
+                if elapsed > 0:
+                    # Aim for two seconds per request, avoiding both a swarm of
+                    # tiny ranges and huge final intervals that strand peers.
+                    block_size = min(
+                        64 * MIB,
+                        max(policy.block_size, int((end - start) / elapsed * 2)),
+                    )
+        finally:
+            live_workers -= 1
+
+    def spawn(*, prefix: bool = False) -> None:
+        nonlocal live_workers
+        live_workers += 1
+        task = asyncio.create_task(worker(prefix=prefix))
+        workers.add(task)
+        all_workers.add(task)
+
+    try:
+        spawn(prefix=True)
+        spawn()
+        sampled_at, sampled_bytes = time.monotonic(), initial_offset
+        while workers:
+            waiting = workers | ({cancelled} if cancelled is not None else set())
+            done, _ = await asyncio.wait(
+                waiting,
+                timeout=policy.sample_seconds,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+            client._raise_if_cancelled(cancel_event)
+            for task in done & workers:
+                workers.remove(task)
+                all_workers.discard(task)
+                task.result()
+            now = time.monotonic()
+            if now - sampled_at >= policy.sample_seconds:
+                controller.observe((written - sampled_bytes) / (now - sampled_at))
+                sampled_at, sampled_bytes = now, written
+            while live_workers < controller.target and next_offset < size:
+                spawn()
+        if written != size:
+            raise RangeFallback(size)
+    except RemoteCancelled:
+        raise
+    finally:
+        pending = all_workers | ({cancelled} if cancelled is not None else set())
+        for task in pending:
+            if not task.done():
+                task.cancel()
+        # All positioned writes must finish before the caller can close/truncate
+        # the file. A second shutdown cancellation cannot skip that drain.
+        drain = asyncio.gather(*pending, return_exceptions=True)
+        interrupted = False
+        while not drain.done():
+            try:
+                await asyncio.shield(drain)
+            except asyncio.CancelledError:
+                interrupted = True
+        if interrupted:
+            raise asyncio.CancelledError
diff --git a/tgdrive/transfers/remote_scheduler.py b/tgdrive/transfers/remote_scheduler.py
new file mode 100644
index 00000000..368c79a5
--- /dev/null
+++ b/tgdrive/transfers/remote_scheduler.py
@@ -0,0 +1,121 @@
+"""Bounded URL connections, FIFO full-speed slots and paced waiting sources."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from collections.abc import Awaitable, Callable
+from contextlib import asynccontextmanager, suppress
+from dataclasses import dataclass, field
+
+WARM_BYTES_PER_SECOND = 64 * 1024
+WARM_READ_SIZE = 16 * 1024
+WARM_STAGING_WINDOW = 32 * 1024 * 1024
+EXTRA_SOURCE_CONNECTIONS = 8
+
+
+@dataclass(eq=False, slots=True)
+class DownloadTicket:
+    can_promote: Callable[[], bool]
+    changed: Callable[[str], Awaitable[None] | None]
+    full_speed: bool = False
+    next_read: float = 0
+    promoted: asyncio.Event = field(default_factory=asyncio.Event)
+    error: Exception | None = None
+
+    async def notify(self, mode: str) -> None:
+        result = self.changed(mode)
+        if inspect.isawaitable(result):
+            await result
+
+    async def pace(self) -> None:
+        if self.error is not None:
+            raise self.error
+        delay = self.next_read - time.monotonic()
+        if not self.full_speed and delay > 0:
+            with suppress(TimeoutError):
+                await asyncio.wait_for(self.promoted.wait(), delay)
+
+    def received(self, size: int) -> None:
+        if not self.full_speed:
+            self.next_read = time.monotonic() + size / WARM_BYTES_PER_SECOND
+
+
+class URLDownloadScheduler:
+    def __init__(self, full_speed_limit: int = 2) -> None:
+        self._tickets: list[DownloadTicket] = []
+        self._changed = asyncio.Event()
+        self._monitor: asyncio.Task[None] | None = None
+        self._refresh_lock = asyncio.Lock()
+        if type(full_speed_limit) is not int or not 1 <= full_speed_limit <= 8:
+            raise ValueError("URL download concurrency must be between 1 and 8")
+        self.full_speed_limit = full_speed_limit
+
+    async def configure(self, limit: int) -> None:
+        if type(limit) is not int or not 1 <= limit <= 8:
+            raise ValueError("URL download concurrency must be between 1 and 8")
+        self.full_speed_limit = limit
+        await self.refresh()
+        self._notify()
+
+    async def refresh(self) -> None:
+        async with self._refresh_lock:
+            running = sum(ticket.full_speed for ticket in self._tickets)
+            for ticket in self._tickets:
+                if running >= self.full_speed_limit:
+                    break
+                if ticket.full_speed or ticket.error is not None:
+                    continue
+                try:
+                    ready = ticket.can_promote()
+                except Exception as error:
+                    ticket.error = error
+                    ticket.promoted.set()
+                    continue
+                if ready:
+                    ticket.full_speed = True
+                    ticket.promoted.set()
+                    await ticket.notify("full")
+                    running += 1
+
+    def _notify(self) -> None:
+        previous, self._changed = self._changed, asyncio.Event()
+        previous.set()
+
+    async def wait(self) -> None:
+        await self._changed.wait()
+
+    async def _watch(self) -> None:
+        try:
+            while self._tickets:
+                await asyncio.sleep(1)
+                await self.refresh()
+        finally:
+            if self._monitor is asyncio.current_task():
+                self._monitor = None
+
+    @asynccontextmanager
+    async def admit(self, wait, can_promote=None, changed=None):
+        changed = changed or (lambda _mode: None)
+        ticket = DownloadTicket(can_promote or (lambda: True), changed)
+        await ticket.notify("queued")
+        while len(self._tickets) >= self.full_speed_limit + EXTRA_SOURCE_CONNECTIONS:
+            await wait(self.wait())
+        self._tickets.append(ticket)
+        try:
+            await ticket.notify("warm")
+            await self.refresh()
+            if self._monitor is None:
+                self._monitor = asyncio.create_task(self._watch())
+            yield ticket
+        finally:
+            self._tickets.remove(ticket)
+            try:
+                await self.refresh()
+            finally:
+                self._notify()
+                if not self._tickets and self._monitor is not None:
+                    monitor, self._monitor = self._monitor, None
+                    monitor.cancel()
+                    await asyncio.gather(monitor, return_exceptions=True)
diff --git a/tgdrive/transfers/staging.py b/tgdrive/transfers/staging.py
new file mode 100644
index 00000000..72b1f25b
--- /dev/null
+++ b/tgdrive/transfers/staging.py
@@ -0,0 +1,79 @@
+"""Shared admission accounting for receipt, multipart and URL upload staging.
+
+Admissions run synchronously on the server event loop. Reservations live in the
+existing receipt/job journals so restart and retries retain their storage claim.
+Physical free space already excludes written bytes; subtract only future writes.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import shutil
+from pathlib import Path
+
+
+class StorageUnavailable(ValueError):
+    def __init__(self, message: str, status: int = 507):
+        super().__init__(message)
+        self.status = status
+
+
+def staging_usage(manager, *, receipts=None, exclude=None):
+    reserved = remaining = 0
+    seen = set()
+    receipts = receipts or getattr(manager, "uploads", None)
+    if receipts is not None:
+        for item in receipts._all():
+            if item["state"] not in {"receiving", "queued", "cancelling"}:
+                continue
+            seen.add(item["id"])
+            if item["id"] == exclude:
+                continue
+            reserved += item["total_size"]
+            if item["state"] == "receiving":
+                remaining += max(0, item["total_size"] - item["offset"])
+    registry = getattr(manager, "registry", None)
+    for job in registry.staging_records() if registry is not None else ():
+        if job.id in seen or job.id == exclude:
+            continue
+        seen.add(job.id)
+        context = job.context
+        raw_path = context.get("local_path")
+        written = 0
+        if raw_path:
+            with contextlib.suppress(FileNotFoundError):
+                written = Path(raw_path).stat().st_size
+        active = not job.terminal or (job.task is not None and not job.task.done())
+        size = max(written, context.get("staging_size", 0)) if active else written
+        reserved += size
+        if active:
+            received = max(written, context.get("staging_written", 0))
+            remaining += max(0, size - received)
+    for identity, size in getattr(manager, "_pending_staging", {}).items():
+        if identity not in seen and identity != exclude:
+            reserved += size
+            remaining += size
+    return reserved, remaining
+
+
+def check_staging(settings, manager, size, *, receipts=None, exclude=None, written=0):
+    reserved, remaining = staging_usage(manager, receipts=receipts, exclude=exclude)
+    if reserved + size > settings.staging_budget_bytes:
+        raise StorageUnavailable(
+            "Temporary upload storage is reserved by other transfers. "
+            "Finish or cancel a transfer, or increase the upload budget."
+        )
+    try:
+        free = shutil.disk_usage(settings.resolved_cache_dir).free
+    except OSError:
+        raise StorageUnavailable(
+            "Cannot check free space on the upload drive. "
+            "Check server storage and retry.",
+            status=503,
+        ) from None
+    required = remaining + max(0, size - written)
+    if free - required < settings.min_free_bytes:
+        raise StorageUnavailable(
+            "Not enough free disk space for this upload after existing reservations "
+            "and the free-space reserve. Free space or finish another transfer first."
+        )
diff --git a/tgdrive/transfers/tasks.py b/tgdrive/transfers/tasks.py
new file mode 100644
index 00000000..d16fbfc0
--- /dev/null
+++ b/tgdrive/transfers/tasks.py
@@ -0,0 +1,1370 @@
+"""Bounded transfer state and background-task supervision."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import errno
+import logging
+import math
+import re
+import secrets
+import time
+import unicodedata
+from collections import deque
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field, replace
+from enum import StrEnum
+from functools import wraps
+from pathlib import Path
+from typing import Any
+
+from aiohttp import ClientConnectionError, ClientPayloadError
+from pymongo.errors import PyMongoError
+from telethon.errors import RpcCallFailError, ServerError, TimedOutError
+
+from tgdrive.storage.mongo import DatabaseUnavailable
+
+logger = logging.getLogger(__name__)
+_DEFAULT_CANCEL_GRACE_SECONDS = 10.0
+_SHUTDOWN_DRAIN_SECONDS = 5.0
+_PROGRESS_JOURNAL_SECONDS = 0.5
+_PROGRESS_STALE_SECONDS = 15.0
+_BYTE_PHASES = frozenset({"saving", "downloading", "uploading"})
+
+
+def _journalled(operation):
+    """A disconnected caller must drain its commit before releasing the journal."""
+
+    @wraps(operation)
+    async def owned(*args, **kwargs):
+        task = asyncio.create_task(operation(*args, **kwargs))
+        cancelled = False
+        while True:
+            try:
+                result = await asyncio.shield(task)
+                break
+            except asyncio.CancelledError:
+                if task.cancelled():
+                    raise
+                cancelled = True
+        if cancelled:
+            raise asyncio.CancelledError
+        return result
+
+    return owned
+
+
+def _retry_after_restart(error: Exception) -> bool:
+    """Only known temporary transport failures may restart without owner input."""
+    from tgdrive.recovery.backup import BackupError, RecoveryConflict
+    from tgdrive.transfers.remote import (
+        RemoteHTTPError,
+        RemoteResolutionError,
+        RemoteTimeout,
+    )
+
+    if isinstance(error, RecoveryConflict):
+        return False
+    if isinstance(error, BackupError) and isinstance(error.__cause__, Exception):
+        # Checkpoint publication wraps provider errors in a safe domain exception.
+        error = error.__cause__
+    if isinstance(
+        error,
+        (
+            ConnectionError,
+            TimeoutError,
+            ClientConnectionError,
+            ClientPayloadError,
+            ServerError,
+            RpcCallFailError,
+            TimedOutError,
+            RemoteResolutionError,
+            RemoteTimeout,
+        ),
+    ):
+        return True
+    if isinstance(error, RemoteHTTPError):
+        return error.status in {408, 429} or 500 <= error.status <= 599
+    return isinstance(error, OSError) and error.errno in {
+        errno.ENETDOWN,
+        errno.ENETUNREACH,
+        errno.ENETRESET,
+        errno.ECONNABORTED,
+        errno.ECONNRESET,
+        errno.ETIMEDOUT,
+        errno.EHOSTUNREACH,
+    }
+
+
+def _failure_diagnostic(error: Exception) -> tuple[str, str]:
+    """Stable categories/actions without formatting private exception messages."""
+    from tgdrive.recovery.backup import BackupError, RecoveryConflict
+    from tgdrive.telegram.connection_errors import connection_problem
+    from tgdrive.transfers.remote import (
+        RemoteHTTPError,
+        RemoteRetriesExhausted,
+        RemoteTooLarge,
+        UnsafeRemoteURL,
+    )
+
+    if isinstance(error, RecoveryConflict):
+        return (
+            "RECOVERY_REQUIRED",
+            "check Storage & Backups and follow recovery guidance",
+        )
+    if isinstance(error, (DatabaseUnavailable, PyMongoError)):
+        return "DATABASE_UNAVAILABLE", "restore MongoDB access and retry the transfer"
+    if isinstance(error, OSError) and error.errno in {errno.ENOSPC, errno.EDQUOT}:
+        return "STAGING_FULL", "free unrelated disk space; preserve unfinished uploads"
+    problem = connection_problem(error, "bot")
+    if problem is not None and problem.code in {
+        "TELEGRAM_CREDENTIALS_REVOKED",
+        "TELEGRAM_CHANNEL_ACCESS",
+        "TELEGRAM_ACCOUNT_REMOVED",
+    }:
+        return problem.code, "repair the account or channel in Connections and retry"
+    if isinstance(error, RemoteHTTPError):
+        code = (
+            f"REMOTE_HTTP_{error.status}"
+            if type(error.status) is int and 100 <= error.status <= 599
+            else "REMOTE_HTTP_ERROR"
+        )
+        return code, "check source availability and access before retrying"
+    if isinstance(error, RemoteRetriesExhausted):
+        return (
+            "REMOTE_RETRIES_EXHAUSTED",
+            "check source availability or use another link",
+        )
+    if isinstance(error, UnsafeRemoteURL):
+        return "REMOTE_URL_BLOCKED", "check the source URL and outbound network policy"
+    if isinstance(error, RemoteTooLarge):
+        return "REMOTE_FILE_TOO_LARGE", "check the configured upload limit"
+    if isinstance(error, BackupError):
+        return "CHECKPOINT_FAILED", "check Storage & Backups before retrying"
+    if _retry_after_restart(error):
+        return "TRANSPORT_INTERRUPTED", "restore the connection and retry the transfer"
+    return "TRANSFER_FAILED", "inspect the transfer error in Transfers"
+
+
+class TransferStatus(StrEnum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    CANCELLING = "cancelling"
+    COMPLETED = "completed"
+    ERROR = "error"
+    CANCELLED = "cancelled"
+
+
+_TERMINAL = {
+    TransferStatus.COMPLETED,
+    TransferStatus.ERROR,
+    TransferStatus.CANCELLED,
+}
+
+
+@dataclass(slots=True)
+class TransferRecord:
+    id: str
+    phase: str
+    status: TransferStatus = TransferStatus.QUEUED
+    current: int = 0
+    total: int = 0
+    error: str | None = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    started_at: float | None = None
+    finished_at: float | None = None
+    progress_updated_at: float | None = None
+    _progress_samples: deque[tuple[float, int]] = field(
+        default_factory=lambda: deque(maxlen=64), repr=False
+    )
+    cancel_event: asyncio.Event = field(default_factory=asyncio.Event, repr=False)
+    task: asyncio.Task[None] | None = field(default=None, repr=False)
+    cancel_handle: asyncio.TimerHandle | None = field(default=None, repr=False)
+
+    context: dict[str, Any] = field(default_factory=dict)
+    _accepted: bool = field(default=True, repr=False)
+    _committed: TransferRecord | None = field(default=None, repr=False)
+
+    @property
+    def committed(self) -> TransferRecord:
+        return self._committed or self
+
+    @property
+    def terminal(self) -> bool:
+        return self.committed.status in _TERMINAL
+
+    @property
+    def history_hidden(self) -> bool:
+        return self.terminal and bool(self.committed.context.get("history_cleared"))
+
+    def as_dict(self) -> dict[str, Any]:
+        if self._committed is not None:
+            return self._committed.as_dict()
+        now = time.time()
+        elapsed = (
+            max(0.0, (self.finished_at or now) - self.started_at)
+            if self.started_at is not None
+            else 0.0
+        )
+        speed = None
+        eta = None
+        if (
+            self.status is TransferStatus.RUNNING
+            and self.phase in _BYTE_PHASES
+            and self.context.get("kind") != "delete"
+            and self.progress_updated_at is not None
+            and len(self._progress_samples) >= 2
+            and time.monotonic() - self._progress_samples[-1][0]
+            <= _PROGRESS_STALE_SECONDS
+        ):
+            first_at, first_bytes = self._progress_samples[0]
+            last_at, last_bytes = self._progress_samples[-1]
+            duration = last_at - first_at
+            if duration > 0 and last_bytes > first_bytes:
+                speed = (last_bytes - first_bytes) / duration
+                if self.total > self.current:
+                    eta = (self.total - self.current) / speed
+        download_mode = (
+            self.context.get("download_mode")
+            if self.phase in {"checking_source", "downloading"}
+            else None
+        )
+        if download_mode in {"warm", "queued", "waiting_storage"}:
+            eta = None
+        deadline_keys = ["retry_at", "backup_retry_at", "lineage_retry_at"]
+        if self.phase == "source_retry_wait":
+            deadline_keys.append("source_retry_at")
+        deadlines = [
+            value
+            for key in deadline_keys
+            if type(value := self.context.get(key)) in (int, float)
+            and math.isfinite(value)
+        ]
+        result = {
+            "retry_at": max(deadlines, default=None),
+            "id": self.id,
+            "status": self.status.value,
+            "phase": self.phase,
+            "current": self.current,
+            "total": self.total,
+            "error": self.error,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
+            "progress_updated_at": self.progress_updated_at,
+            "elapsed_seconds": elapsed,
+            "speed_bytes_per_second": speed,
+            "eta_seconds": eta,
+        }
+        if self.phase in {"checking_source", "source_retry_wait", "downloading"}:
+            from tgdrive.transfers.remote import REMOTE_MAX_ATTEMPTS
+
+            result["source_attempt"] = self.context.get("source_attempt", 1)
+            result["source_max_attempts"] = REMOTE_MAX_ATTEMPTS
+        plan = self.context.get("multipart_plan")
+        if download_mode in {"full", "warm", "queued", "waiting_storage"}:
+            result["download_mode"] = download_mode
+        parts = plan.get("parts") if isinstance(plan, dict) else None
+        if isinstance(parts, list) and len(parts) > 1:
+            result["telegram_parts"] = {
+                "total": len(parts),
+                "stored": sum(bool(part.get("confirmed")) for part in parts),
+            }
+        folder_upload = self.context.get("folder_upload")
+        folder_fields = ("id", "name", "root_path", "created_at")
+        if isinstance(folder_upload, dict) and all(
+            key in folder_upload for key in folder_fields
+        ):
+            result["folder_upload"] = {
+                key: copy.deepcopy(folder_upload[key]) for key in folder_fields
+            }
+        return result
+
+
+class TransferNotFound(KeyError):
+    pass
+
+
+class TransferRegistry:
+    """Own transfer records and ensure spawned tasks are observed and drained."""
+
+    def __init__(
+        self,
+        *,
+        ttl_seconds: int = 3600,
+        max_entries: int = 1000,
+        cancel_grace_seconds: float = _DEFAULT_CANCEL_GRACE_SECONDS,
+        database_path: Path | None = None,
+        mongo=None,
+        mongo_backend=None,
+        demo_mode: bool = False,
+    ) -> None:
+        if cancel_grace_seconds < 0:
+            raise ValueError("cancel_grace_seconds cannot be negative")
+        self._ttl = ttl_seconds
+        self._max_entries = max_entries
+        self._cancel_grace = cancel_grace_seconds
+        self.demo_mode = demo_mode
+        self._records: dict[str, TransferRecord] = {}
+        self._tasks: set[asyncio.Task[None]] = set()
+        self._finalizers: set[asyncio.Task[None]] = set()
+        self._journal_lock = asyncio.Lock()
+        self._shutting_down = False
+        self._mongo = mongo
+        self._mongo_backend = mongo_backend
+        self._durable: dict[str, dict[str, Any]] = {}
+        self._last_progress_commit: dict[str, float] = {}
+        self._logged: dict[str, tuple[TransferStatus, str, bool, float]] = {}
+        self._history: dict[str, dict[str, Any]] = {}
+        if database_path is not None:
+            raise ValueError(
+                "Transfer persistence requires MongoDB, not a local database path"
+            )
+        if mongo is not None:
+            for row in mongo.find({"archived": {"$ne": True}}):
+                self._load_record(row["_id"], row["data"])
+            if mongo_backend is not None:
+                mongo.create_index([("archived", 1), ("created_at", -1), ("_id", -1)])
+                mongo.create_index(
+                    [("archived", 1), ("status", 1), ("created_at", -1), ("_id", -1)]
+                )
+
+    def _load_record(self, identity, item):
+        if not isinstance(item, dict) or item.get("id") != identity:
+            raise ValueError("job identity does not match its row")
+        for field_name in ("current", "total"):
+            if type(item.get(field_name)) is not int or item[field_name] < 0:
+                raise ValueError("invalid byte count")
+        for field_name in ("created_at", "updated_at"):
+            if type(item.get(field_name)) not in (
+                int,
+                float,
+            ) or not math.isfinite(item[field_name]):
+                raise ValueError("invalid job timestamp")
+        for field_name in (
+            "started_at",
+            "finished_at",
+            "progress_updated_at",
+        ):
+            timestamp = item.get(field_name)
+            if timestamp is not None and (
+                type(timestamp) not in (int, float) or not math.isfinite(timestamp)
+            ):
+                raise ValueError("invalid optional job timestamp")
+        if not isinstance(item.get("context"), dict) or not isinstance(
+            item.get("phase"), str
+        ):
+            raise ValueError("invalid job context")
+        item["status"] = TransferStatus(item["status"])
+        item.setdefault("started_at", None)
+        item.setdefault(
+            "finished_at",
+            item["updated_at"] if item["status"] in _TERMINAL else None,
+        )
+        item.setdefault("progress_updated_at", None)
+        record = TransferRecord(**item)
+        if record.context.get("cancel_requested"):
+            record.cancel_event.set()
+        self._records[item["id"]] = record
+        self._durable[item["id"]] = copy.deepcopy(item)
+        self._logged[record.id] = self._log_snapshot(record)
+
+    async def _write(self, operation, *args, **kwargs):
+        if self._mongo_backend is not None:
+            return await asyncio.to_thread(
+                self._mongo_backend.write, self._mongo, operation, *args, **kwargs
+            )
+        return await asyncio.to_thread(getattr(self._mongo, operation), *args, **kwargs)
+
+    @_journalled
+    async def persist(self, record: TransferRecord) -> None:
+        context = record.context
+        async with self._journal_lock:
+            if record.context is not context:
+                raise DatabaseUnavailable(
+                    "Transfer state changed after a failed commit"
+                )
+            await self._persist(record)
+
+    @_journalled
+    async def prune(self, *, now: float | None = None) -> None:
+        async with self._journal_lock:
+            await self._prune(now=now)
+
+    async def _persist(self, record: TransferRecord) -> None:
+        # Lifecycle/context commits are immediate; byte counters are advisory.
+        if record.status is TransferStatus.RUNNING and record.started_at is None:
+            record.started_at = time.time()
+        if record.terminal:
+            if record.finished_at is None:
+                record.finished_at = time.time()
+            record._progress_samples.clear()
+        else:
+            record.finished_at = None
+            record.context.pop("history_cleared", None)
+        self._last_progress_commit[record.id] = time.monotonic()
+        if self._mongo is None:
+            record._accepted = True
+            self._log_record(record)
+            return
+        item = {
+            key: getattr(record, key)
+            for key in (
+                "id",
+                "phase",
+                "status",
+                "current",
+                "total",
+                "error",
+                "created_at",
+                "updated_at",
+                "started_at",
+                "finished_at",
+                "progress_updated_at",
+            )
+        } | {"context": copy.deepcopy(record.context)}
+        previous = self._durable.get(record.id)
+        if previous is not None:
+            record._committed = TransferRecord(
+                **copy.deepcopy(previous),
+                task=record.task,
+                cancel_event=record.cancel_event,
+            )
+        try:
+            await self._write(
+                "replace_one",
+                {"_id": record.id},
+                {"_id": record.id, "data": item},
+                upsert=True,
+            )
+        except (
+            PyMongoError,
+            DatabaseUnavailable,
+            ValueError,
+            TypeError,
+        ):
+            if previous is not None:
+                for key, value in previous.items():
+                    if key == "context":
+                        record.context = copy.deepcopy(value)
+                    else:
+                        setattr(
+                            record,
+                            key,
+                            TransferStatus(value) if key == "status" else value,
+                        )
+                if record.context.get("cancel_requested"):
+                    record.cancel_event.set()
+                else:
+                    record.cancel_event.clear()
+            raise DatabaseUnavailable(
+                "Transfer state could not be saved to MongoDB"
+            ) from None
+        finally:
+            record._committed = None
+        self._durable[record.id] = copy.deepcopy(item)
+        record._accepted = True
+        self._log_record(record)
+
+    @staticmethod
+    def _log_snapshot(
+        record: TransferRecord,
+    ) -> tuple[TransferStatus, str, bool, float]:
+        deadlines = [
+            record.context.get(key)
+            for key in (
+                "retry_at",
+                "channel_retry_at",
+                "backup_retry_at",
+                "lineage_retry_at",
+            )
+        ]
+        plan = record.context.get("multipart_plan")
+        if isinstance(plan, dict) and isinstance(plan.get("parts"), list):
+            deadlines.extend(
+                part.get("retry_at") for part in plan["parts"] if isinstance(part, dict)
+            )
+        retry_at = max(
+            (
+                value
+                for value in deadlines
+                if type(value) in (int, float) and math.isfinite(value)
+            ),
+            default=0.0,
+        )
+        return record.status, record.phase, record.started_at is not None, retry_at
+
+    def _log_record(self, record: TransferRecord) -> None:
+        """Log committed lifecycle changes, never byte callbacks or poll snapshots."""
+        current = self._log_snapshot(record)
+        previous = self._logged.get(record.id)
+        self._logged[record.id] = current
+        if previous is None:
+            logger.debug("Transfer queued id=%s bytes=%s", record.id, record.total)
+            return
+        kind = record.context.get("kind")
+        kind = (
+            kind if kind in {"upload", "remote", "delete", "receiving"} else "transfer"
+        )
+        now = time.time()
+        if current[2] and not previous[2]:
+            logger.info(
+                "Transfer started id=%s kind=%s phase=%s bytes=%s queue_seconds=%.3f",
+                record.id,
+                kind,
+                record.phase,
+                record.total,
+                max(0.0, (record.started_at or now) - record.created_at),
+            )
+        if record.status != previous[0] and record.status in {
+            TransferStatus.COMPLETED,
+            TransferStatus.CANCELLED,
+        }:
+            logger.info(
+                "Transfer finished id=%s kind=%s status=%s bytes=%s/%s "
+                "elapsed_seconds=%.3f",
+                record.id,
+                kind,
+                record.status.value,
+                record.current,
+                record.total,
+                max(0.0, (record.finished_at or now) - record.created_at),
+            )
+        if current[3] > max(now, previous[3]):
+            reason = (
+                "recovery_checkpoint"
+                if record.context.get("backup_retry_at") == current[3]
+                else "catalog_verification"
+                if record.context.get("lineage_retry_at") == current[3]
+                else "telegram_cooldown"
+            )
+            logger.warning(
+                "Transfer retry scheduled id=%s reason=%s retry_after_seconds=%s; "
+                "retry is automatic",
+                record.id,
+                reason,
+                math.ceil(current[3] - now),
+            )
+        if record.phase == "waiting_for_telegram" and previous[1] != record.phase:
+            logger.warning(
+                "Transfer waiting id=%s reason=no_telegram_client; "
+                "check Connections; retry is automatic",
+                record.id,
+            )
+        if current[:2] != previous[:2]:
+            logger.debug(
+                "Transfer state id=%s status=%s phase=%s bytes=%s/%s",
+                record.id,
+                record.status.value,
+                record.phase,
+                record.current,
+                record.total,
+            )
+
+    @staticmethod
+    def _retained(record: TransferRecord) -> bool:
+        record = record.committed
+        context = record.context
+        deadlines = [context.get("retry_at"), context.get("channel_retry_at")]
+        plan = context.get("multipart_plan")
+        if isinstance(plan, dict) and isinstance(plan.get("parts"), list):
+            deadlines.extend(
+                part.get("retry_at") for part in plan["parts"] if isinstance(part, dict)
+            )
+        if any(
+            type(deadline) in (int, float)
+            and math.isfinite(deadline)
+            and deadline > time.time()
+            for deadline in deadlines
+        ):
+            return True
+        if record.context.get("kind") in {
+            "upload",
+            "remote",
+            "delete",
+        } and record.status not in {TransferStatus.COMPLETED, TransferStatus.CANCELLED}:
+            return True
+        source = record.context.get("local_path")
+        return bool(source and Path(source).exists())
+
+    @staticmethod
+    def history_snapshot(
+        record: TransferRecord, *, retained: bool = True
+    ) -> dict[str, Any]:
+        """Public summary without source URLs, credentials or payload context."""
+        record = record.committed
+        summary = record.as_dict() | {
+            "name": record.context.get("name", "Transfer"),
+            "kind": record.context.get(
+                "source_kind", record.context.get("kind", "upload")
+            ),
+            "destination": record.context.get("destination", "/"),
+            "retained": retained,
+        }
+        if not retained:
+            summary["error"] = (
+                "Transfer failed" if record.status is TransferStatus.ERROR else None
+            )
+        return summary
+
+    async def _remove(self, transfer_id: str) -> None:
+        record = self._records[transfer_id]
+        summary = (
+            self.history_snapshot(record, retained=False)
+            if record.terminal
+            and not record.history_hidden
+            and record.context.get("kind") != "delete"
+            else None
+        )
+        if self._mongo is not None:
+            if summary is not None:
+                args = (
+                    {"_id": transfer_id},
+                    {
+                        "_id": transfer_id,
+                        "archived": True,
+                        "created_at": record.created_at,
+                        "status": record.status.value,
+                        "search_name": unicodedata.normalize(
+                            "NFC", summary["name"]
+                        ).casefold(),
+                        "summary": summary,
+                    },
+                )
+                await self._write("replace_one", *args)
+            else:
+                await self._write("delete_one", {"_id": transfer_id})
+        if self._mongo is None and summary is not None:
+            self._history[transfer_id] = summary
+            # Nonpersistent test runtimes stay bounded; MongoDB archives are paged.
+            if len(self._history) > self._max_entries:
+                oldest = min(
+                    self._history, key=lambda key: self._history[key]["created_at"]
+                )
+                del self._history[oldest]
+        self._records.pop(transfer_id, None)
+        self._durable.pop(transfer_id, None)
+        self._last_progress_commit.pop(transfer_id, None)
+        self._logged.pop(transfer_id, None)
+
+    @staticmethod
+    def _history_matches(row, statuses, before, query=""):
+        return (
+            row.get("kind") != "delete"
+            and (not statuses or row["status"] in statuses)
+            and (before is None or (row["created_at"], row["id"]) < before)
+            and query
+            in unicodedata.normalize("NFC", str(row.get("name", ""))).casefold()
+        )
+
+    def _archived_history(self, statuses, before, limit, term=""):
+        if self._mongo is not None:
+            query: dict[str, Any] = {"archived": True}
+            if statuses:
+                query["status"] = {"$in": list(statuses)}
+            if term:
+                query["search_name"] = {"$regex": re.escape(term)}
+            if before is not None:
+                at, identity = before
+                query["$or"] = [
+                    {"created_at": {"$lt": at}},
+                    {"created_at": at, "_id": {"$lt": identity}},
+                ]
+            cursor = self._mongo.find(query).sort([("created_at", -1), ("_id", -1)])
+            return [row["summary"] for row in cursor.limit(limit)]
+        return sorted(
+            (
+                row
+                for row in list(self._history.values())
+                if self._history_matches(row, statuses, before, term)
+            ),
+            key=lambda row: (row["created_at"], row["id"]),
+            reverse=True,
+        )[:limit]
+
+    async def history(self, *, status="all", before=None, limit=50, query=""):
+        statuses = {
+            "all": (),
+            "finished": ("completed", "error", "cancelled"),
+            "queued": ("queued",),
+            "running": ("running", "cancelling"),
+            "completed": ("completed",),
+            "error": ("error",),
+            "cancelled": ("cancelled",),
+        }
+        if (
+            status not in statuses
+            or not 1 <= limit <= 200
+            or not isinstance(query, str)
+            or len(query) > 255
+        ):
+            raise ValueError("Invalid transfer history page")
+        query = unicodedata.normalize("NFC", query.strip()).casefold()
+        selected = statuses[status]
+        # Snapshot live progress on the event loop; only the DB lookup runs in a thread.
+        live = [
+            row
+            for record in self.list()
+            if not record.history_hidden
+            and self._history_matches(
+                row := self.history_snapshot(record), selected, before, query
+            )
+        ]
+        archived = await asyncio.to_thread(
+            self._archived_history, selected, before, limit + 1, query
+        )
+        merged = {row["id"]: row for row in archived}
+        merged.update({row["id"]: row for row in live})
+        ordered = sorted(
+            merged.values(),
+            key=lambda row: (row["created_at"], row["id"]),
+            reverse=True,
+        )
+        has_more = len(ordered) > limit
+        page = ordered[:limit]
+        return {
+            "jobs": page,
+            "has_more": has_more,
+            "next_before": page[-1]["created_at"] if has_more else None,
+            "next_before_id": page[-1]["id"] if has_more else None,
+        }
+
+    @staticmethod
+    def _history_task_id(row):
+        folder = row.get("folder_upload")
+        if (
+            row.get("kind") in {"upload", "receiving"}
+            and isinstance(folder, dict)
+            and isinstance(folder.get("id"), str)
+            and folder["id"]
+        ):
+            return "folder:" + folder["id"]
+        return "job:" + row["id"]
+
+    def _task_archive_rows(self, selected=None):
+        """Stream summaries; numbered pages never materialize the whole archive."""
+        if self._mongo is not None:
+            query: dict[str, Any] = {"archived": True}
+            if selected is not None:
+                query["$or"] = [
+                    {
+                        "summary.folder_upload.id": {
+                            "$in": [
+                                key[7:] for key in selected if key.startswith("folder:")
+                            ]
+                        }
+                    },
+                    {
+                        "_id": {
+                            "$in": [
+                                key[4:] for key in selected if key.startswith("job:")
+                            ]
+                        }
+                    },
+                ]
+            cursor = self._mongo.find(query)
+            for document in cursor.batch_size(200):
+                yield document["summary"]
+            return
+        for row in list(self._history.values()):
+            if selected is None or self._history_task_id(row) in selected:
+                yield copy.deepcopy(row)
+
+    @staticmethod
+    def _task_status(statuses):
+        if statuses & {"running", "cancelling"}:
+            return "running"
+        if "queued" in statuses:
+            return "queued"
+        if "error" in statuses:
+            return "error"
+        return "completed" if statuses == {"completed"} else "cancelled"
+
+    def _numbered_history(
+        self, live, *, status, page, limit, query, offset, exclude_folders
+    ):
+        live_ids = {row["id"] for row in live}
+        tasks = {}
+        excluded = {"folder:" + identity for identity in exclude_folders}
+
+        def observe(row):
+            if row.get("kind") == "delete":
+                return
+            identity = self._history_task_id(row)
+            if identity in excluded:
+                return
+            folder = row.get("folder_upload")
+            created_at = (
+                folder.get("created_at", row["created_at"])
+                if identity.startswith("folder:")
+                else row["created_at"]
+            )
+            entry = tasks.setdefault(
+                identity,
+                {"created_at": created_at, "statuses": set(), "matches": False},
+            )
+            entry["created_at"] = min(entry["created_at"], created_at)
+            entry["statuses"].add(row["status"])
+            names = [row.get("name", "")]
+            if identity.startswith("folder:"):
+                names.append(folder.get("name", ""))
+            entry["matches"] |= any(
+                query in unicodedata.normalize("NFC", str(name)).casefold()
+                for name in names
+            )
+
+        for row in self._task_archive_rows():
+            if row["id"] not in live_ids:
+                observe(row)
+        for row in live:
+            observe(row)
+        matching = [
+            identity
+            for identity, entry in tasks.items()
+            if entry["matches"]
+            and (
+                status == "all"
+                or (
+                    status == "finished"
+                    and self._task_status(entry["statuses"])
+                    in {"completed", "cancelled", "error"}
+                )
+                or status == self._task_status(entry["statuses"])
+            )
+        ]
+        matching.sort(
+            key=lambda identity: (tasks[identity]["created_at"], identity), reverse=True
+        )
+        total = len(matching)
+        pages = max(1, (total + limit - 1) // limit)
+        if offset is None:
+            page = min(page, pages)
+            offset = (page - 1) * limit
+        selected = matching[offset : offset + limit]
+        selected_ids = set(selected)
+        members = {}
+        if selected:
+            for row in self._task_archive_rows(selected_ids):
+                if (
+                    row["id"] not in live_ids
+                    and self._history_task_id(row) in selected_ids
+                ):
+                    members[row["id"]] = row
+            for row in live:
+                if self._history_task_id(row) in selected_ids:
+                    members[row["id"]] = row
+        order = {identity: index for index, identity in enumerate(selected)}
+        jobs = sorted(
+            members.values(),
+            key=lambda row: (
+                order[self._history_task_id(row)],
+                row["created_at"],
+                row["id"],
+            ),
+        )
+        return {
+            "jobs": jobs,
+            "page": page,
+            "page_size": limit,
+            "total_tasks": total,
+            "total_pages": pages,
+            "has_more": offset + limit < total,
+            "offset": offset,
+            "next_offset": min(total, offset + limit),
+        }
+
+    async def task_history(
+        self,
+        *,
+        status="all",
+        page=1,
+        limit=20,
+        query="",
+        offset=None,
+        exclude_folders=(),
+    ):
+        if (
+            status
+            not in {
+                "all",
+                "finished",
+                "queued",
+                "running",
+                "completed",
+                "error",
+                "cancelled",
+            }
+            or type(page) is not int
+            or page < 1
+            or type(limit) is not int
+            or not 1 <= limit <= 200
+            or not isinstance(query, str)
+            or len(query) > 255
+            or (offset is not None and (type(offset) is not int or offset < 0))
+        ):
+            raise ValueError("Invalid transfer task page")
+        # Progress and recovery contexts belong to the event loop. The worker
+        # sees copied public snapshots and streams archived summaries in batches.
+        live = [
+            self.history_snapshot(record)
+            for record in self.list()
+            if not record.history_hidden
+        ]
+        return await asyncio.to_thread(
+            self._numbered_history,
+            live,
+            status=status,
+            page=page,
+            limit=limit,
+            query=unicodedata.normalize("NFC", query.strip()).casefold(),
+            offset=offset,
+            exclude_folders=tuple(exclude_folders),
+        )
+
+    @_journalled
+    async def clear_history(self, *, exclude_folders=()) -> int:
+        """Forget finished display history without discarding recovery contexts."""
+        async with self._journal_lock:
+            active_folders = set(exclude_folders)
+            for record in self._records.values():
+                folder = record.context.get("folder_upload")
+                if not record.terminal and isinstance(folder, dict):
+                    active_folders.add(folder["id"])
+
+            if self._mongo is not None:
+                query: dict[str, Any] = {
+                    "archived": True,
+                    "status": {"$in": [status.value for status in _TERMINAL]},
+                    "summary.folder_upload.id": {"$nin": sorted(active_folders)},
+                }
+                result = await self._write("delete_many", query)
+                cleared = result.deleted_count
+            else:
+                removed = [
+                    identity
+                    for identity, row in self._history.items()
+                    if row.get("folder_upload", {}).get("id") not in active_folders
+                ]
+                for identity in removed:
+                    del self._history[identity]
+                cleared = len(removed)
+
+            for record in self._records.values():
+                folder = record.context.get("folder_upload", {})
+                if (
+                    record.terminal
+                    and not record.history_hidden
+                    and record.context.get("kind") != "delete"
+                    and folder.get("id") not in active_folders
+                ):
+                    # Retained errors may still own staged bytes, send identities or
+                    # backup barriers. Hide their history, keeping recovery intact.
+                    record.context["history_cleared"] = True
+                    await self._persist(record)
+                    cleared += 1
+            return cleared
+
+    def close(self) -> None:
+        if self._tasks or self._finalizers:
+            raise RuntimeError("Drain transfer tasks before closing the journal")
+
+    def list(self) -> list[TransferRecord]:
+        return sorted(
+            (record for record in self._records.values() if record._accepted),
+            key=lambda item: item.created_at,
+            reverse=True,
+        )
+
+    def staging_records(self) -> list[TransferRecord]:
+        """Include unacknowledged reservations when admitting another upload."""
+        return list(self._records.values())
+
+    @_journalled
+    async def retry(self, transfer_id: str) -> TransferRecord:
+        async with self._journal_lock:
+            record = self.get(transfer_id)
+            if record.status not in {TransferStatus.ERROR, TransferStatus.QUEUED}:
+                raise ValueError("Only failed or interrupted transfers can be retried")
+            record.status = TransferStatus.QUEUED
+            record.error = None
+            record.context.pop("restart_retryable", None)
+            record._progress_samples.clear()
+            record.cancel_event.clear()
+            await self._persist(record)
+            logger.info("Transfer retry requested id=%s", record.id)
+            return record
+
+    @_journalled
+    async def create(
+        self,
+        phase: str,
+        *,
+        total: int = 0,
+        transfer_id: str | None = None,
+        context: dict[str, Any] | None = None,
+    ) -> TransferRecord:
+        async with self._journal_lock:
+            await self._prune()
+            if transfer_id is not None and transfer_id in self._records:
+                return self._records[transfer_id]
+            if self._shutting_down:
+                raise RuntimeError("Transfer registry is shutting down")
+            if len(self._records) >= self._max_entries:
+                terminal = sorted(
+                    (
+                        r
+                        for r in self._records.values()
+                        if r.terminal
+                        and not self._retained(r)
+                        and (r.task is None or r.task.done())
+                    ),
+                    key=lambda record: record.updated_at,
+                )
+                if terminal:
+                    await self._remove(terminal[0].id)
+                else:
+                    raise RuntimeError("too many active transfers")
+            transfer_id = transfer_id or secrets.token_urlsafe(18)
+            if transfer_id in self._records:
+                return self._records[transfer_id]
+            record = TransferRecord(
+                id=transfer_id,
+                phase=phase,
+                total=max(0, total),
+                context=copy.deepcopy(context) if context is not None else {},
+                _accepted=False,
+            )
+            from tgdrive.storage.demo_files import restricted_writes
+
+            if self.demo_mode and restricted_writes.get():
+                record.context["demo_read_only"] = True
+            self._records[transfer_id] = record
+            try:
+                await self._persist(record)
+            except BaseException:
+                self._records.pop(transfer_id, None)
+                raise
+            return record
+
+    def get(self, transfer_id: str) -> TransferRecord:
+        try:
+            record = self._records[transfer_id]
+        except KeyError as exc:
+            raise TransferNotFound(transfer_id) from exc
+        if not record._accepted:
+            raise TransferNotFound(transfer_id)
+        return record
+
+    @_journalled
+    async def update(
+        self,
+        transfer_id: str,
+        *,
+        status: TransferStatus | None = None,
+        phase: str | None = None,
+        current: int | None = None,
+        total: int | None = None,
+        error: str | None = None,
+        checkpoint_progress: bool = True,
+    ) -> TransferRecord:
+        async with self._journal_lock:
+            record = self.get(transfer_id)
+            # Terminal snapshots are immutable.  In particular, a late progress
+            # callback from a transport that is winding down after cancellation
+            # must not change the phase/bytes the API has already reported.
+            if record.terminal:
+                return record
+            previous_phase = record.phase
+            previous_status = record.status
+            previous_current = record.current
+            previous_total = record.total
+            if status is not None:
+                record.status = status
+            if phase is not None:
+                record.phase = phase
+            if current is not None:
+                record.current = max(0, current)
+            if total is not None:
+                record.total = max(0, total)
+            if error is not None:
+                record.error = error[:500]
+            now = time.time()
+            monotonic = time.monotonic()
+            record.updated_at = now
+            transition = (
+                record.phase != previous_phase or record.status != previous_status
+            )
+            if (
+                transition
+                or record.current < previous_current
+                or record.total != previous_total
+                or record.phase not in _BYTE_PHASES
+                or record.status is not TransferStatus.RUNNING
+            ):
+                record._progress_samples.clear()
+            if (
+                record.phase in _BYTE_PHASES
+                and record.status is TransferStatus.RUNNING
+                and current is not None
+            ):
+                record.progress_updated_at = now
+                record._progress_samples.append((monotonic, record.current))
+                while (
+                    len(record._progress_samples) > 2
+                    and record._progress_samples[1][0] < monotonic - 5
+                ):
+                    record._progress_samples.popleft()
+            # Never throttle phase/status/error or recovery-context changes. Staging
+            # write counts are advisory, like current; they are not resumable receipt
+            # offsets or Telegram send identities. URL retrieval restarts from zero.
+            durable = self._durable.get(record.id)
+            context_changed = durable is not None and {
+                key: value
+                for key, value in durable["context"].items()
+                if key != "staging_written"
+            } != {
+                key: value
+                for key, value in record.context.items()
+                if key != "staging_written"
+            }
+            if (
+                transition
+                or error is not None
+                or context_changed
+                or (
+                    checkpoint_progress
+                    and self._mongo is None
+                    and monotonic - self._last_progress_commit.get(record.id, 0)
+                    >= _PROGRESS_JOURNAL_SECONDS
+                )
+            ):
+                await self._persist(record)
+            return record
+
+    @_journalled
+    async def cancel(self, transfer_id: str) -> TransferRecord:
+        async with self._journal_lock:
+            record = self.get(transfer_id)
+            if record.context.get("kind") == "delete" and not record.terminal:
+                raise ValueError(
+                    "Permanent deletion cannot be cancelled after it starts"
+                )
+            if not record.terminal or (
+                record.status == TransferStatus.ERROR and self._retained(record)
+            ):
+                candidate = replace(
+                    record,
+                    context=dict(record.context, cancel_requested=True),
+                    cancel_event=asyncio.Event(),
+                    _progress_samples=record._progress_samples.copy(),
+                )
+                running = record.task is not None and not record.task.done()
+                ambiguous = bool(record.context.get("send_started"))
+                if ambiguous:
+                    candidate.status = (
+                        TransferStatus.CANCELLING if running else TransferStatus.QUEUED
+                    )
+                    candidate.phase = "cleanup_pending"
+                    candidate.error = (
+                        "Cancellation requested; Telegram cleanup is pending"
+                    )
+                else:
+                    candidate.status = (
+                        TransferStatus.CANCELLING
+                        if running
+                        else TransferStatus.CANCELLED
+                    )
+                    candidate.phase = "cancelling"
+                    candidate.error = "Transfer cancelled"
+                candidate.updated_at = time.time()
+                await self._persist(candidate)
+                for key in ("status", "phase", "error", "updated_at", "finished_at"):
+                    setattr(record, key, getattr(candidate, key))
+                record.context["cancel_requested"] = True
+                record.cancel_event.set()
+                if record.terminal:
+                    record._progress_samples.clear()
+                if running:
+                    record.cancel_handle = asyncio.get_running_loop().call_later(
+                        self._cancel_grace, self._force_cancel, record
+                    )
+            return record
+
+    def spawn(
+        self,
+        transfer_id: str,
+        work: Callable[[TransferRecord], Awaitable[None]],
+    ) -> asyncio.Task[None]:
+        record = self.get(transfer_id)
+        if record.task is not None and not record.task.done():
+            return record.task
+        if record.terminal:
+            raise ValueError("Terminal transfers cannot be started again without retry")
+
+        started = False
+
+        async def runner() -> None:
+            nonlocal started
+            started = True
+            try:
+                from tgdrive.storage.demo_files import write_policy
+
+                with write_policy(
+                    self.demo_mode and record.context.get("demo_read_only") is True
+                ):
+                    await work(record)
+            except asyncio.CancelledError:
+                if (
+                    self._mongo is not None
+                    and self._shutting_down
+                    and not record.cancel_event.is_set()
+                ):
+                    record.status = TransferStatus.QUEUED
+                    record.phase = "interrupted"
+                    await self.persist(record)
+                elif record.context.get("send_started"):
+                    record.status = TransferStatus.QUEUED
+                    record.phase = (
+                        "cleanup_pending"
+                        if record.cancel_event.is_set()
+                        else "interrupted"
+                    )
+                    await self.persist(record)
+                elif not record.terminal:
+                    await self.update(
+                        record.id,
+                        status=TransferStatus.CANCELLED,
+                        error="Transfer cancelled",
+                    )
+                raise
+            except Exception as exc:
+                retryable = _retry_after_restart(exc)
+                code, action = _failure_diagnostic(exc)
+                logger.error(
+                    "Transfer failed id=%s phase=%s error_type=%s retryable=%s "
+                    "code=%s; %s",
+                    record.id,
+                    record.phase,
+                    type(exc).__name__,
+                    retryable,
+                    code,
+                    action,
+                )
+                logger.debug("Transfer failure detail id=%s", record.id, exc_info=True)
+                if record.cancel_event.is_set() and record.context.get("send_started"):
+                    record.status = TransferStatus.QUEUED
+                    record.phase = "cleanup_pending"
+                    record.error = str(exc)[:500] or type(exc).__name__
+                    await self.persist(record)
+                else:
+                    if retryable:
+                        record.context["restart_retryable"] = True
+                    else:
+                        record.context.pop("restart_retryable", None)
+                    await self.update(
+                        record.id,
+                        status=TransferStatus.ERROR,
+                        error=(
+                            "The connection was interrupted. Retry this transfer, "
+                            "or restart TGDrive after restoring the connection."
+                            if retryable
+                            else str(exc) or type(exc).__name__
+                        ),
+                    )
+            finally:
+                await self._settle_cancelled(record)
+
+        task = asyncio.create_task(runner(), name=f"transfer:{transfer_id}")
+        record.task = task
+        self._tasks.add(task)
+        task.add_done_callback(
+            lambda done: self._task_done(record, done, started=started)
+        )
+        return task
+
+    def _force_cancel(self, record: TransferRecord) -> None:
+        task = record.task
+        if task is not None and not task.done() and record.cancel_event.is_set():
+            logger.warning(
+                "Transfer %s did not stop cooperatively; forcing task cancellation",
+                record.id,
+            )
+            task.cancel()
+
+    def _task_done(
+        self,
+        record: TransferRecord,
+        task: asyncio.Task[None],
+        *,
+        started: bool,
+    ) -> None:
+        self._tasks.discard(task)
+        if record.cancel_handle is not None:
+            record.cancel_handle.cancel()
+            record.cancel_handle = None
+        if not started and record.cancel_event.is_set() and not record.terminal:
+            finalizer = asyncio.create_task(self._settle_cancelled(record))
+            self._finalizers.add(finalizer)
+            finalizer.add_done_callback(self._finalizer_done)
+        if not task.cancelled():
+            error = task.exception()
+            if error is not None:
+                logger.error(
+                    "Transfer task %s failed during supervision",
+                    record.id,
+                    exc_info=(type(error), error, error.__traceback__),
+                )
+
+    @_journalled
+    async def _settle_cancelled(self, record: TransferRecord) -> None:
+        async with self._journal_lock:
+            if record.cancel_event.is_set() and not record.terminal:
+                if record.context.get("send_started"):
+                    record.status = TransferStatus.QUEUED
+                    record.phase = "cleanup_pending"
+                else:
+                    record.status = TransferStatus.CANCELLED
+                    record.phase = "cancelled"
+                await self._persist(record)
+
+    def _finalizer_done(self, task: asyncio.Task[None]) -> None:
+        self._finalizers.discard(task)
+        if not task.cancelled() and (error := task.exception()) is not None:
+            logger.error(
+                "Transfer cancellation journal failed",
+                exc_info=(type(error), error, error.__traceback__),
+            )
+
+    async def _prune(self, *, now: float | None = None) -> None:
+        current = time.time() if now is None else now
+        expired = [
+            transfer_id
+            for transfer_id, record in self._records.items()
+            if record.terminal
+            and not self._retained(record)
+            and (record.task is None or record.task.done())
+            and record.updated_at <= current - self._ttl
+        ]
+        for transfer_id in expired:
+            await self._remove(transfer_id)
+
+    async def shutdown(self) -> None:
+        self._shutting_down = True
+        if self._mongo is None:
+            for record in list(self._records.values()):
+                if not record.terminal:
+                    await self.cancel(record.id)
+        pending = set(self._tasks)
+        for _ in range(2):
+            for task in pending:
+                task.cancel()
+            if not pending:
+                break
+            _, pending = await asyncio.wait(pending, timeout=_SHUTDOWN_DRAIN_SECONDS)
+        if pending:
+            logger.error("Shutdown left %s stalled transfer task(s)", len(pending))
+        while self._finalizers:
+            await asyncio.gather(*tuple(self._finalizers), return_exceptions=True)
diff --git a/tgdrive/transfers/transfer_locations.py b/tgdrive/transfers/transfer_locations.py
new file mode 100644
index 00000000..63e09fae
--- /dev/null
+++ b/tgdrive/transfers/transfer_locations.py
@@ -0,0 +1,37 @@
+"""Owner-only transfer destinations resolved from stable catalog identities."""
+
+from tgdrive.core.errors import DriveError, TrashedItemError
+
+
+def location_record(node, path, chain, *, stored):
+    is_item = stored and node["id"] != "root"
+    folders = chain[:-1] if is_item else chain
+    folder_path = (path.rsplit("/", 1)[0] or "/") if is_item else path
+    folder_label = " / ".join(["My Files", *(row["name"] for row in folders[1:])])
+    return {
+        "available": True,
+        "folder_path": folder_path,
+        "folder_label": folder_label,
+        "item_id": node["id"] if is_item else None,
+        "item_name": node["name"] if is_item else None,
+        "display_path": folder_label + (" / " + node["name"] if is_item else ""),
+    }
+
+
+def locate_transfer(store, job):
+    try:
+        return store.transfer_location(
+            job.get("id"),
+            job.get("destination", "/"),
+            completed=job.get("status") == "completed",
+        )
+    except TrashedItemError:
+        return {"available": False, "reason": "Item is in Trash"}
+    except DriveError:
+        return {"available": False, "reason": "Location is no longer available"}
+
+
+def enrich_locations(store, jobs):
+    for job in jobs:
+        job["location"] = locate_transfer(store, job)
+    return jobs
diff --git a/tgdrive/transfers/uploads.py b/tgdrive/transfers/uploads.py
new file mode 100644
index 00000000..c516f300
--- /dev/null
+++ b/tgdrive/transfers/uploads.py
@@ -0,0 +1,607 @@
+"""Durable browser receipts with bounded staging and verified resumable chunks."""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import errno
+import hashlib
+import logging
+import os
+import re
+import secrets
+import shutil
+import time
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+from weakref import WeakValueDictionary
+
+from tgdrive.core.errors import DriveError
+from tgdrive.core.security import safe_name
+from tgdrive.storage.store import ROOT_ID, _normalize_path
+from tgdrive.transfers.staging import StorageUnavailable, check_staging
+from tgdrive.transfers.tasks import _journalled
+from tgdrive.web.schemas import FolderUploadMetadata
+
+logger = logging.getLogger(__name__)
+
+CHUNK_SIZE = 8 * 1024 * 1024
+_ACTIVE = {"receiving", "queued", "cancelling"}
+_ID = re.compile(r"[0-9a-f]{32}")
+
+
+class UploadError(ValueError):
+    def __init__(
+        self, message: str, status: int = 409, *, code: str = "UPLOAD_ERROR"
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class ResumableUploads:
+    def __init__(self, settings: Any, manager: Any) -> None:
+        self.settings = settings
+        self.manager = manager
+        self.root = settings.resolved_cache_dir / "receipts"
+        self.root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        settings.resolved_data_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
+        from tgdrive.storage.mongo import for_settings
+
+        backend = for_settings(settings)
+        self._mongo_backend = backend
+        self._mongo = backend.db.receipts
+        self._items: dict[str, dict[str, Any]] = {}
+        self._terminal_expiry: dict[str, float] = {}
+        for row in self._mongo.find({}):
+            self._items[row["_id"]] = row["data"]
+            if "purge_at" in row:
+                self._terminal_expiry[row["_id"]] = row["purge_at"].timestamp()
+        # Held contexts and waiting tasks own locks; idle entries retain no lock.
+        self.locks: WeakValueDictionary[str, asyncio.Lock] = WeakValueDictionary()
+        self.slots = asyncio.Semaphore(settings.max_concurrent_transfers)
+        self._creation_lock = asyncio.Lock()
+        self._pending: dict[str, dict[str, Any]] = {}
+        self._reconcile_finished()
+
+    def close(self) -> None:
+        """The shared MongoDB backend owns its connection lifecycle."""
+
+    def _all(self):
+        self._prune_terminal()
+        # Pending receipts reserve space before their first worker await,
+        # including for URL/multipart admissions sharing the same budget.
+        items = dict(self._pending)
+        items.update(self._items)
+        return copy.deepcopy(list(items.values()))
+
+    def _prune_terminal(self, upload_id: str | None = None) -> None:
+        """Expire only settled cached receipts, using their durable TTL deadline."""
+        now = time.time()
+        if upload_id is None:
+            candidates = tuple(self._terminal_expiry.items())
+        else:
+            deadline = self._terminal_expiry.get(upload_id)
+            candidates = () if deadline is None else ((upload_id, deadline),)
+        for upload_id, deadline in candidates:
+            if (
+                deadline > now
+                or upload_id in self._pending
+                or self.locks.get(upload_id) is not None
+                or self._items[upload_id]["state"] not in {"finished", "cancelled"}
+            ):
+                continue
+            record = self._existing_job(upload_id)
+            if record is not None and (
+                str(record.status) not in {"completed", "cancelled"}
+                or (record.task is not None and not record.task.done())
+            ):
+                continue
+            del self._items[upload_id]
+            del self._terminal_expiry[upload_id]
+
+    def _save(self, item: dict[str, Any]) -> None:
+        from datetime import UTC, datetime
+
+        document = {"_id": item["id"], "data": item}
+        if item["state"] in {"finished", "cancelled"}:
+            document["purge_at"] = datetime.fromtimestamp(
+                max(item["expires_at"], time.time() + 86400), UTC
+            )
+        self._mongo_backend.write(
+            self._mongo, "replace_one", {"_id": item["id"]}, document, upsert=True
+        )
+        if "purge_at" in document:
+            self._terminal_expiry[item["id"]] = document["purge_at"].timestamp()
+        else:
+            self._terminal_expiry.pop(item["id"], None)
+        self._items[item["id"]] = copy.deepcopy(item)
+
+    def _existing_job(self, upload_id: str) -> Any | None:
+        try:
+            return self.manager.registry.get(upload_id).committed
+        except KeyError:
+            return None
+
+    def _reconcile_finished(self) -> None:
+        for item in self._all():
+            if item["state"] not in _ACTIVE:
+                continue
+            record = self._existing_job(item["id"])
+            if record is not None and item["state"] == "receiving":
+                # A crash can occur after enqueue committed but before the
+                # receipt's queued state committed. The job owns its bytes now.
+                item["state"] = "queued"
+                self._save(item)
+            if record is not None and str(record.status) in {"completed", "cancelled"}:
+                path = self.root / (item["id"] + ".part")
+                path.unlink(missing_ok=True)
+                item["state"] = (
+                    "cancelled" if str(record.status) == "cancelled" else "finished"
+                )
+                self._save(item)
+
+    def get_unchecked(self, upload_id: str) -> dict[str, Any]:
+        if not isinstance(upload_id, str) or not _ID.fullmatch(upload_id):
+            raise UploadError("Upload session not found", 404)
+        self._prune_terminal(upload_id)
+        item = copy.deepcopy(self._items.get(upload_id))
+        if item is None:
+            raise UploadError("Upload session not found", 404)
+        if item.get("id") != upload_id or item.get("state") not in _ACTIVE | {
+            "finished",
+            "cancelled",
+        }:
+            raise UploadError("Stored upload session is invalid", 500)
+        return item
+
+    def _destination(self, item: dict[str, Any]) -> str:
+        try:
+            binding = self.manager.store.upload_destination(
+                item["parent_id"],
+                directory_id=item.get("parent_node_id"),
+            )
+        except DriveError as exc:
+            raise UploadError(
+                "The destination folder is unavailable. "
+                "Restore it or cancel this upload."
+            ) from exc
+        if (
+            item.get("parent_node_id") != binding["id"]
+            or item["parent_id"] != binding["path"]
+        ):
+            item.update(parent_node_id=binding["id"], parent_id=binding["path"])
+            self._save(item)
+        return binding["path"]
+
+    def get(self, upload_id: str) -> dict[str, Any]:
+        item = self.get_unchecked(upload_id)
+        # Inspection remains available when a folder is trashed/deleted, so owners
+        # can cancel the receipt; active chunks/complete enforce the binding below.
+        with suppress(UploadError):
+            self._destination(item)
+        if item["state"] == "receiving" and item["expires_at"] <= time.time():
+            lock = self.locks.get(upload_id)
+            if lock is None or not lock.locked():
+                self._cancel_receiving(item)
+            raise UploadError("Upload session expired. Select the file again.", 410)
+        return item
+
+    def path(self, upload_id: str) -> Path:
+        self.get_unchecked(upload_id)
+        return self.root / (upload_id + ".part")
+
+    def create(
+        self,
+        name: str,
+        parent_id: str,
+        total_size: int,
+        *,
+        folder_upload: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        self._reconcile_finished()
+        for item in self._all():
+            lock = self.locks.get(item["id"])
+            if (
+                item["id"] not in self._pending
+                and item["state"] == "receiving"
+                and item["expires_at"] <= time.time()
+                and (lock is None or not lock.locked())
+            ):
+                self._cancel_receiving(item)
+        item = self._admit(name, parent_id, total_size, folder_upload)
+        self._open_receipt(item)
+        return item
+
+    def _admit(
+        self,
+        name: str,
+        parent_id: str,
+        total_size: int,
+        folder_upload: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        if type(total_size) is not int or total_size <= 0:
+            raise UploadError("File size must be a positive integer", 422)
+        if total_size > self.settings.upload_limit:
+            raise UploadError("File exceeds the configured upload limit", 413)
+        if folder_upload is not None:
+            try:
+                folder_upload = FolderUploadMetadata.model_validate(
+                    folder_upload
+                ).model_dump()
+            except ValueError:
+                raise UploadError("Invalid folder upload metadata", 422) from None
+            root_parts, original_root = _normalize_path(folder_upload["root_path"])
+            if not root_parts or root_parts[-1] == ROOT_ID:
+                raise UploadError("A folder upload requires a non-root folder", 422)
+            # Browser queue entries retain their original paths. Bind both
+            # opaque identities again so moving the folder or an ancestor does
+            # not strand files that have not created a receipt yet.
+            root = self.manager.store.upload_destination(
+                original_root, directory_id=root_parts[-1]
+            )
+            parent_parts, original_parent = _normalize_path(parent_id)
+            binding = self.manager.store.upload_destination(
+                original_parent,
+                directory_id=parent_parts[-1] if parent_parts else ROOT_ID,
+            )
+            parent_id = binding["path"]
+            root_path = root["path"]
+            if parent_id != root_path and not parent_id.startswith(root_path + "/"):
+                raise UploadError("The file is outside its folder upload", 422)
+            folder_upload["root_path"] = root_path
+        else:
+            binding = self.manager.store.upload_destination(parent_id)
+            parent_id = binding["path"]
+        active = self._all()
+        active = [item for item in active if item["state"] in _ACTIVE]
+        if len(active) >= 1000:
+            raise UploadError("Too many unfinished upload sessions", 429)
+        try:
+            check_staging(self.settings, self.manager, total_size, receipts=self)
+        except StorageUnavailable as exc:
+            raise UploadError(str(exc), exc.status) from None
+        upload_id = secrets.token_hex(16)
+        item = {
+            "id": upload_id,
+            "name": safe_name(name),
+            "parent_id": parent_id,
+            "parent_node_id": binding["id"],
+            "total_size": total_size,
+            "offset": 0,
+            "checksums": [],
+            "chunk_size": CHUNK_SIZE,
+            "state": "receiving",
+            "created_at": time.time(),
+            "expires_at": time.time() + self.settings.upload_session_ttl_seconds,
+        }
+        if folder_upload is not None:
+            item["folder_upload"] = folder_upload
+        return item
+
+    def _open_receipt(self, item: dict[str, Any]) -> None:
+        upload_id = item["id"]
+        path = self.root / (upload_id + ".part")
+        descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+        try:
+            try:
+                os.fsync(descriptor)
+            finally:
+                os.close(descriptor)
+            directory = os.open(self.root, os.O_RDONLY | os.O_DIRECTORY)
+            try:
+                os.fsync(directory)
+            finally:
+                os.close(directory)
+        except BaseException:
+            path.unlink(missing_ok=True)
+            raise
+        try:
+            self._save(item)
+        except BaseException:
+            # A lost acknowledgement is not evidence of rollback. Keep the
+            # file and reservation until expiry/reconciliation; a committed
+            # cloud receipt must never point at a file we just deleted.
+            self._items[upload_id] = copy.deepcopy(item)
+            raise
+        logger.debug(
+            "Device receipt opened id=%s bytes=%s", upload_id, item["total_size"]
+        )
+
+    @staticmethod
+    async def _owned_worker(callback: Any, *args: Any) -> Any:
+        work = asyncio.get_running_loop().run_in_executor(None, callback, *args)
+        cancelled = False
+        while True:
+            try:
+                result = await asyncio.shield(work)
+                break
+            except asyncio.CancelledError:
+                # A disconnected request still owns its worker through fsync
+                # and the MongoDB commit, including repeated cancellation.
+                cancelled = True
+        if cancelled:
+            raise asyncio.CancelledError
+        return result
+
+    async def _reconcile_for_creation(self) -> None:
+        for snapshot in self._all():
+            upload_id = snapshot["id"]
+            if upload_id in self._pending or snapshot["state"] not in _ACTIVE:
+                continue
+            lock = self.locks.setdefault(upload_id, asyncio.Lock())
+            if lock.locked():
+                # An active append/complete/cancel owns this receipt's state.
+                continue
+            async with lock:
+                item = self.get_unchecked(upload_id)
+                record = self._existing_job(upload_id)
+                state = item["state"]
+                if record is not None and str(record.status) in {
+                    "completed",
+                    "cancelled",
+                }:
+                    item["state"] = (
+                        "cancelled" if str(record.status) == "cancelled" else "finished"
+                    )
+                elif (
+                    record is None
+                    and item["state"] == "receiving"
+                    and item["expires_at"] <= time.time()
+                ):
+                    item["state"] = "cancelled"
+                if item["state"] == state:
+                    # Active jobs release their own receipt. Saving a queued
+                    # snapshot here could race that synchronous terminal save.
+                    continue
+
+                def reconcile(
+                    item: dict[str, Any] = item, upload_id: str = upload_id
+                ) -> None:
+                    if item["state"] in {"finished", "cancelled"}:
+                        (self.root / (upload_id + ".part")).unlink(missing_ok=True)
+                    self._save(item)
+
+                # Job inspection and receipt locking stay on the event loop;
+                # only immutable receipt work reaches the cloud worker.
+                await self._owned_worker(reconcile)
+
+    async def create_async(
+        self,
+        name: str,
+        parent_id: str,
+        total_size: int,
+        *,
+        folder_upload: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        async with self._creation_lock:
+            await self._reconcile_for_creation()
+            item = self._admit(name, parent_id, total_size, folder_upload)
+            self._pending[item["id"]] = item
+            try:
+                await self._owned_worker(self._open_receipt, item)
+            finally:
+                self._pending.pop(item["id"], None)
+            return item
+
+    async def append(
+        self, upload_id: str, offset: int, body: bytes | bytearray
+    ) -> dict[str, Any]:
+        async with self.slots, self.locks.setdefault(upload_id, asyncio.Lock()):
+            item = await self._owned_worker(self.get, upload_id)
+            if item["state"] != "receiving":
+                raise UploadError("This upload no longer accepts chunks")
+            await self._owned_worker(self._destination, item)
+            if type(offset) is not int or offset != item["offset"]:
+                raise UploadError(
+                    "Upload offset changed. Read the current offset and resume.",
+                    code="UPLOAD_OFFSET_CHANGED",
+                )
+            if (
+                not body
+                or len(body) > CHUNK_SIZE
+                or offset + len(body) > item["total_size"]
+            ):
+                raise UploadError("Invalid upload chunk length", 413)
+            if len(body) != CHUNK_SIZE and offset + len(body) != item["total_size"]:
+                raise UploadError(
+                    "Only the last chunk may be smaller than chunk_size", 422
+                )
+            path = self.path(upload_id)
+            if not path.exists() or path.stat().st_size < offset:
+                raise UploadError(
+                    "Staged bytes are missing. Cancel and select the file again."
+                )
+            if (
+                shutil.disk_usage(self.root).free - len(body)
+                < self.settings.min_free_bytes
+            ):
+                raise UploadError("Temporary storage is full", 507)
+
+            def commit(checksum: str) -> None:
+                item["checksums"].append(
+                    {"offset": offset, "size": len(body), "sha256": checksum}
+                )
+                item["offset"] += len(body)
+                item["expires_at"] = (
+                    time.time() + self.settings.upload_session_ttl_seconds
+                )
+                self._save(item)
+
+            def write() -> str:
+                with path.open("r+b") as handle:
+                    handle.truncate(offset)
+                    handle.seek(offset)
+                    handle.write(body)
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                checksum = hashlib.sha256(body).hexdigest()
+                # A majority transaction can take several network round
+                # trips. Keep it off the HTTP event loop, but in the same
+                # owned worker as the fsync so disconnects still drain it.
+                commit(checksum)
+                return checksum
+
+            work = asyncio.get_running_loop().run_in_executor(None, write)
+            cancelled = False
+            while True:
+                try:
+                    await asyncio.shield(work)
+                    break
+                except OSError as exc:
+                    if exc.errno in {errno.ENOSPC, errno.EDQUOT}:
+                        raise UploadError(
+                            "Upload storage filled while receiving data. "
+                            "Free disk space, then resume this upload.",
+                            507,
+                        ) from None
+                    raise
+                except asyncio.CancelledError:
+                    # Repeated disconnect/shutdown cancellation still cannot
+                    # release this lock while an OS write or its durable cloud
+                    # receipt commit is in progress.
+                    cancelled = True
+            if cancelled:
+                raise asyncio.CancelledError
+            return item
+
+    @staticmethod
+    def _verify(item: dict[str, Any], path: Path) -> None:
+        if not path.is_file() or path.stat().st_size != item["total_size"]:
+            raise UploadError(
+                "Staged bytes are missing or incomplete. Select the file again."
+            )
+        expected_offset = 0
+        with path.open("rb") as handle:
+            for chunk in item["checksums"]:
+                if (
+                    chunk["offset"] != expected_offset
+                    or not 0 < chunk["size"] <= CHUNK_SIZE
+                ):
+                    raise UploadError("Upload checksum journal is inconsistent")
+                content = handle.read(chunk["size"])
+                if (
+                    len(content) != chunk["size"]
+                    or hashlib.sha256(content).hexdigest() != chunk["sha256"]
+                ):
+                    raise UploadError(
+                        "Staged file checksum failed. Select the file again."
+                    )
+                expected_offset += len(content)
+        if expected_offset != item["total_size"]:
+            raise UploadError("Upload checksum journal is incomplete")
+
+    @_journalled
+    async def complete(self, upload_id: str) -> Any:
+        started = time.monotonic()
+        async with self.locks.setdefault(upload_id, asyncio.Lock()):
+            item = await self._owned_worker(self.get, upload_id)
+            if item["state"] in {"cancelled", "cancelling"}:
+                raise UploadError("Upload was cancelled")
+            existing = self._existing_job(upload_id)
+            if existing is not None:
+                if item["state"] == "receiving":
+                    item["state"] = "queued"
+                    await self._owned_worker(self._save, item)
+                return existing
+            if item["state"] == "finished":
+                raise UploadError("Completed upload history expired", 410)
+            if item["offset"] != item["total_size"]:
+                raise UploadError("Upload is incomplete")
+            await self._owned_worker(self._destination, item)
+            verification_started = time.monotonic()
+            verification = asyncio.get_running_loop().run_in_executor(
+                None, self._verify, item, self.path(upload_id)
+            )
+            cancelled = False
+            while True:
+                try:
+                    await asyncio.shield(verification)
+                    break
+                except asyncio.CancelledError:
+                    # All bytes already belong to the server. A browser leaving
+                    # during verification must not strand a complete receipt, or
+                    # release its lock while its disk worker is still reading.
+                    cancelled = True
+                except UploadError:
+                    logger.warning(
+                        "Device upload verification failed id=%s bytes=%s; "
+                        "cancel this receipt and upload the original file again",
+                        upload_id,
+                        item["total_size"],
+                    )
+                    raise
+            verification_seconds = time.monotonic() - verification_started
+            # A folder may move while disk verification yields. Resolve its UUID
+            # immediately before enqueue, rather than reusing the old ancestry.
+            destination = await self._owned_worker(self._destination, item)
+            record = await self.manager.enqueue_upload(
+                self.path(upload_id),
+                destination,
+                item["name"],
+                item["total_size"],
+                transfer_id=upload_id,
+                **(
+                    {"folder_upload": copy.deepcopy(item["folder_upload"])}
+                    if item.get("folder_upload") is not None
+                    else {}
+                ),
+            )
+            item["state"] = "queued"
+            await self._owned_worker(self._save, item)
+            logger.info(
+                "Device upload accepted id=%s job_id=%s bytes=%s "
+                "receipt_age_seconds=%s "
+                "verify_seconds=%.3f handoff_seconds=%.3f",
+                upload_id,
+                record.id,
+                item["total_size"],
+                (
+                    f"{max(0.0, time.time() - item['created_at']):.3f}"
+                    if type(item.get("created_at")) in (int, float)
+                    else "unknown"
+                ),
+                verification_seconds,
+                time.monotonic() - started,
+            )
+            if cancelled:
+                raise asyncio.CancelledError
+            return record
+
+    def _cancel_receiving(self, item: dict[str, Any]) -> None:
+        (self.root / (item["id"] + ".part")).unlink(missing_ok=True)
+        item["state"] = "cancelled"
+        self._save(item)
+
+    async def cancel(self, upload_id: str) -> dict[str, Any]:
+        async with self.locks.setdefault(upload_id, asyncio.Lock()):
+            item = self.get_unchecked(upload_id)
+            if item["state"] in {"finished", "cancelled"}:
+                return item
+            if item["state"] == "receiving" and self._existing_job(upload_id) is None:
+                await self._owned_worker(self._cancel_receiving, item)
+            else:
+                cancel = getattr(
+                    self.manager, "cancel_job", self.manager.registry.cancel
+                )
+                # The manager checks committed metadata before mutating the
+                # receipt or job; a protected file must never enter cleanup.
+                record = await cancel(upload_id)
+                item["state"] = (
+                    "cancelled" if str(record.status) == "cancelled" else "cancelling"
+                )
+                await self._owned_worker(self._save, item)
+            return item
+
+    def release(self, upload_id: str) -> None:
+        try:
+            item = self.get_unchecked(upload_id)
+        except UploadError as exc:
+            if exc.status == 404:
+                return
+            raise
+        item["state"] = (
+            "cancelled" if item["state"] in {"cancelled", "cancelling"} else "finished"
+        )
+        self._save(item)
diff --git a/tgdrive/web/__init__.py b/tgdrive/web/__init__.py
new file mode 100644
index 00000000..7aa5ee5c
--- /dev/null
+++ b/tgdrive/web/__init__.py
@@ -0,0 +1 @@
+"""HTTP application, request contracts, and access handling."""
diff --git a/tgdrive/web/api_v1.py b/tgdrive/web/api_v1.py
new file mode 100644
index 00000000..e659f107
--- /dev/null
+++ b/tgdrive/web/api_v1.py
@@ -0,0 +1,832 @@
+"""Typed owner API for durable uploads, jobs and drive actions."""
+
+from __future__ import annotations
+
+import asyncio
+import unicodedata
+from dataclasses import asdict
+from datetime import UTC, datetime, timedelta
+from typing import Any, Literal
+
+from fastapi import Depends, HTTPException, Query, Request, Response
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, StrictBool
+
+from tgdrive.core.errors import ValidationError as DriveValidationError
+from tgdrive.recovery.backup import RecoveryConflict
+from tgdrive.settings.management_api import register_management_routes
+from tgdrive.storage.demo_files import (
+    annotate,
+    check_path,
+    check_receipt,
+    check_transfer,
+    restricted_writes,
+    write_policy,
+)
+from tgdrive.storage.store import (
+    MAX_NAME_LENGTH,
+    MAX_SEARCH_OFFSET,
+    FolderTreeConflictError,
+)
+from tgdrive.telegram.client_pool import current_upload_limit
+from tgdrive.transfers.transfer_locations import enrich_locations, locate_transfer
+from tgdrive.transfers.uploads import CHUNK_SIZE, ResumableUploads, UploadError
+from tgdrive.web.demo_access import session_access
+from tgdrive.web.schemas import (
+    FolderTreeRequest,
+    FolderUploadMetadata,
+    TransferTaskHistoryRequest,
+)
+from tgdrive.web.share_links import token_factory
+
+
+class TransferLocationRequest(BaseModel):
+    transfer_id: str | None = Field(
+        default=None, min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+    )
+    destination: str = Field(default="/", max_length=4096)
+    completed: bool = False
+
+
+class ClearTransferHistoryRequest(BaseModel):
+    exclude_folders: list[str] = Field(default_factory=list, max_length=2000)
+
+
+class UploadCreate(BaseModel):
+    name: str = Field(min_length=1, max_length=1024)
+    parent_id: str = Field(default="/", max_length=4096)
+    total_size: int = Field(gt=0)
+    folder_upload: FolderUploadMetadata | None = None
+
+
+class StarItem(BaseModel):
+    path: str = Field(min_length=1, max_length=4096)
+    starred: StrictBool
+
+
+class ShareCreate(BaseModel):
+    path: str = Field(min_length=1, max_length=4096)
+    expires_in_days: int | None = Field(default=7, ge=1, le=3650)
+    expires_at: datetime | None = None
+    label: str = Field(default="", max_length=80)
+
+
+class MoveItems(BaseModel):
+    paths: list[str] = Field(min_length=1, max_length=1000)
+    destination: str = Field(min_length=1, max_length=4096)
+    conflict: Literal["keep_both", "skip"] = "keep_both"
+    allow_public_exposure: bool = False
+
+
+class BulkItems(BaseModel):
+    paths: list[str] = Field(min_length=1, max_length=1000)
+    action: Literal["trash", "restore", "delete"]
+    allow_public_exposure: bool = False
+
+
+class RevokeShare(BaseModel):
+    path: str | None = Field(default=None, min_length=1, max_length=4096)
+    share_id: str | None = Field(
+        default=None, min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+    )
+
+
+class ShareUpdate(BaseModel):
+    share_id: str = Field(min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_-]+$")
+    label: str = Field(default="", max_length=80)
+    expires_at: datetime | None = None
+
+
+def register_routes(
+    app: Any,
+    settings: Any,
+    *,
+    require_admin: Any,
+    is_admin: Any,
+    get_store: Any,
+    get_manager: Any,
+    get_runtime: Any,
+) -> None:
+    register_management_routes(
+        app, settings, require_admin=require_admin, get_runtime=get_runtime
+    )
+    from tgdrive.recovery.restore_api import register_restore_routes
+
+    register_restore_routes(
+        app, settings, require_admin=require_admin, get_runtime=get_runtime
+    )
+    from tgdrive.observability.performance_api import register_performance_routes
+
+    register_performance_routes(
+        app,
+        settings,
+        require_admin=require_admin,
+        get_runtime=get_runtime,
+        get_store=get_store,
+    )
+    admin = [Depends(require_admin)]
+    chunk_receivers = asyncio.Semaphore(settings.max_concurrent_transfers)
+
+    def describe(value):
+        return annotate(value) if settings.demo_mode else value
+
+    def uploads(request: Request) -> ResumableUploads:
+        manager = get_manager(request)
+        if not hasattr(manager, "uploads"):
+            manager.uploads = ResumableUploads(settings, manager)
+        return manager.uploads
+
+    @app.exception_handler(UploadError)
+    async def upload_error(_request: Request, exc: UploadError) -> JSONResponse:
+        return JSONResponse(
+            {"detail": str(exc), "code": exc.code}, status_code=exc.status
+        )
+
+    @app.get("/api/v1/session")
+    async def session(request: Request, response: Response) -> dict[str, bool]:
+        response.headers["Cache-Control"] = "no-store"
+        if settings.demo_mode:
+            return session_access(request)
+        return {"authenticated": is_admin(request)}
+
+    @app.get("/api/v1/status", dependencies=admin)
+    async def status(request: Request) -> dict[str, Any]:
+        runtime = get_runtime(request)
+        if getattr(runtime, "recovery_only", False):
+            return {
+                "recovery_only": True,
+                "telegram_ready": False,
+                "restart_required": bool(
+                    getattr(runtime, "archive_restore_restart_required", False)
+                ),
+                "admission_paused": True,
+                "metadata_revision": 0,
+                "backup": [],
+                "recovery": None,
+                "clients": None,
+            }
+        pool = getattr(runtime, "pool", None)
+        health = await pool.health() if pool else None
+        statuses = (
+            await pool.status() if callable(getattr(pool, "status", None)) else ()
+        )
+        telegram_issues = [
+            {
+                "code": getattr(item, "error_code", None) or "TELEGRAM_DISCONNECTED",
+                "detail": getattr(item, "error", None)
+                or "A Telegram account is disconnected. Open Connections and "
+                "Refresh to check credentials, channel permissions and network access.",
+            }
+            for item in statuses
+            if not item.healthy
+        ]
+        backup = getattr(runtime, "backup", None)
+        history = []
+        if backup and hasattr(backup, "history"):
+            try:
+                history = await asyncio.to_thread(backup.history, limit=1)
+            except TypeError:
+                history = (await asyncio.to_thread(backup.history))[:1]
+        connections = getattr(runtime, "connection_manager", None)
+        restart_required = bool(connections and connections.restart_required)
+        return {
+            "restart_required": restart_required,
+            "admission_paused": restart_required,
+            "telegram_ready": bool(health and health.ready),
+            "telegram_issues": telegram_issues,
+            "demo": bool(getattr(runtime, "synthetic", False)),
+            "max_file_size": await current_upload_limit(settings, pool),
+            "staging_budget_bytes": settings.staging_budget_bytes,
+            "metadata_revision": get_store(request).revision,
+            "backup": history,
+            "recovery": backup.protection_status(get_store(request))
+            if backup and hasattr(backup, "protection_status")
+            else None,
+            "clients": asdict(health) if health else None,
+        }
+
+    @app.post("/api/v1/backup", dependencies=admin)
+    async def back_up_now(request: Request) -> dict[str, Any]:
+        runtime = get_runtime(request)
+        service = getattr(runtime, "backup", None)
+        if service is None or not hasattr(service, "ensure_revision"):
+            raise HTTPException(503, "Drive backup is not available yet")
+        store = get_store(request)
+        try:
+            await service.snapshot_now(store)
+        except RecoveryConflict:
+            raise
+        except Exception:
+            # A lost confirmation does not prove that Telegram received nothing.
+            # The durable checkpoint journal owns retries and reconciliation.
+            raise HTTPException(
+                503,
+                "Backup is not confirmed yet. Check the backup status and try again.",
+            ) from None
+        return {"recovery": service.protection_status(store)}
+
+    @app.get("/api/v1/backup/recovery-key", dependencies=admin)
+    async def recovery_key(request: Request):
+        runtime = get_runtime(request)
+        if getattr(runtime, "mongo", None) is None or not settings.mongodb_backup_key:
+            raise HTTPException(404, "MongoDB backup recovery key is unavailable")
+        return Response(
+            "MONGODB_BACKUP_KEY="
+            + settings.mongodb_backup_key.get_secret_value()
+            + "\n",
+            media_type="text/plain",
+            headers={
+                "Content-Disposition": (
+                    'attachment; filename="tgdrive-recovery-key.env"'
+                ),
+                "Cache-Control": "no-store",
+                "X-Content-Type-Options": "nosniff",
+            },
+        )
+
+    @app.get("/api/v1/search", dependencies=admin)
+    async def search(
+        request: Request,
+        q: str = Query(min_length=1, max_length=MAX_NAME_LENGTH),
+        offset: int = Query(default=0, ge=0, le=MAX_SEARCH_OFFSET),
+        limit: int = Query(default=100, ge=1, le=200),
+        sort: Literal["name", "date", "size"] = "name",
+        order: Literal["asc", "desc"] | None = None,
+    ) -> dict[str, Any]:
+        try:
+            return describe(
+                get_store(request).search_page(
+                    q, offset=offset, limit=limit, sort=sort, order=order
+                )
+            )
+        except DriveValidationError as error:
+            raise HTTPException(422, str(error)) from None
+
+    @app.get("/api/v1/starred", dependencies=admin)
+    async def starred_items(
+        request: Request,
+        response: Response,
+        q: str = Query(default="", max_length=MAX_NAME_LENGTH),
+    ):
+        response.headers["Cache-Control"] = "no-store"
+        items = await asyncio.to_thread(get_store(request).list_starred, q)
+        return describe({"data": {"contents": items}})
+
+    @app.patch("/api/v1/starred", dependencies=admin)
+    async def star_item(body: StarItem, request: Request, response: Response):
+        response.headers["Cache-Control"] = "no-store"
+        check_path(get_store(request), body.path)
+        result = await asyncio.to_thread(
+            get_store(request).set_starred, body.path, body.starred
+        )
+        return {"item": result}
+
+    @app.get("/api/v1/trash", dependencies=admin)
+    async def search_trash(
+        request: Request,
+        response: Response,
+        q: str = Query(default="", max_length=MAX_NAME_LENGTH),
+    ):
+        response.headers["Cache-Control"] = "no-store"
+        contents = await asyncio.to_thread(
+            get_store(request).list_trash, unicodedata.normalize("NFC", q.strip())
+        )
+        return describe({"data": {"contents": contents}})
+
+    @app.get("/api/v1/nodes", dependencies=admin)
+    async def nodes(
+        request: Request,
+        parent_id: str = "/",
+        offset: int = 0,
+        limit: int = 100,
+        sort: str = "name",
+    ) -> dict[str, Any]:
+        if (
+            offset < 0
+            or not 1 <= limit <= 500
+            or sort not in {"name", "size", "type", "date"}
+        ):
+            raise HTTPException(422, "Invalid pagination or sort")
+        data = get_store(request).get_directory(parent_id)
+        items = list(data["contents"].values())
+        items.sort(
+            key=lambda item: (
+                item["type"] != "folder",
+                str(item.get("upload_date" if sort == "date" else sort, "")).casefold()
+                if sort != "size"
+                else item.get("size", 0),
+                item["id"],
+            )
+        )
+        return describe(
+            {
+                "items": items[offset : offset + limit],
+                "total": len(items),
+                "offset": offset,
+            }
+        )
+
+    @app.post("/api/v1/folders/tree", dependencies=admin, status_code=201)
+    async def prepare_folder_tree(payload: FolderTreeRequest, request: Request) -> Any:
+        check_path(get_store(request), payload.destination)
+        try:
+            return await asyncio.to_thread(
+                get_store(request).prepare_folder_tree,
+                payload.destination,
+                payload.root_name,
+                payload.folders,
+                payload.client_request_id,
+            )
+        except FolderTreeConflictError as exc:
+            return JSONResponse(
+                {"detail": str(exc), "code": "FOLDER_TREE_CONFLICT"}, status_code=409
+            )
+
+    @app.post("/api/v1/uploads", dependencies=admin, status_code=201)
+    async def create_upload(payload: UploadCreate, request: Request) -> dict[str, Any]:
+        check_path(get_store(request), payload.parent_id)
+        limit = await current_upload_limit(
+            settings, getattr(get_runtime(request), "pool", None)
+        )
+        await require_admin(request)  # Recheck after awaiting live account health.
+        check_path(get_store(request), payload.parent_id)
+        if payload.total_size > limit:
+            raise UploadError(
+                f"File exceeds the currently available {limit}-byte upload limit", 413
+            )
+        return await uploads(request).create_async(
+            payload.name,
+            payload.parent_id,
+            payload.total_size,
+            folder_upload=(
+                payload.folder_upload.model_dump() if payload.folder_upload else None
+            ),
+        )
+
+    @app.get("/api/v1/uploads/{upload_id}", dependencies=admin)
+    async def inspect_upload(upload_id: str, request: Request) -> dict[str, Any]:
+        with write_policy(False):
+            return await ResumableUploads._owned_worker(uploads(request).get, upload_id)
+
+    @app.head("/api/v1/uploads/{upload_id}", dependencies=admin)
+    async def upload_offset(upload_id: str, request: Request) -> Response:
+        with write_policy(False):
+            item = await ResumableUploads._owned_worker(uploads(request).get, upload_id)
+        return Response(
+            headers={
+                "Upload-Offset": str(item["offset"]),
+                "Upload-Length": str(item["total_size"]),
+                "Cache-Control": "no-store",
+            }
+        )
+
+    @app.patch("/api/v1/uploads/{upload_id}", dependencies=admin)
+    async def append_upload(upload_id: str, request: Request) -> Response:
+        try:
+            offset = int(request.headers["upload-offset"])
+        except (KeyError, ValueError) as exc:
+            raise HTTPException(422, "Upload-Offset is required") from exc
+        if (
+            request.headers.get("content-type", "").split(";")[0]
+            != "application/octet-stream"
+        ):
+            raise HTTPException(415, "Use application/octet-stream")
+        if restricted_writes.get():
+            check_receipt(get_store(request), uploads(request).get_unchecked(upload_id))
+        async with chunk_receivers:
+            body = bytearray()
+            async for part in request.stream():
+                if len(body) + len(part) > CHUNK_SIZE:
+                    raise UploadError("Upload chunk is too large", 413)
+                body.extend(part)
+            await require_admin(request)
+            check_receipt(get_store(request), uploads(request).get_unchecked(upload_id))
+            item = await uploads(request).append(upload_id, offset, body)
+        return Response(status_code=204, headers={"Upload-Offset": str(item["offset"])})
+
+    @app.post(
+        "/api/v1/uploads/{upload_id}/complete", dependencies=admin, status_code=202
+    )
+    async def complete_upload(upload_id: str, request: Request) -> dict[str, Any]:
+        await require_admin(request)
+        check_receipt(get_store(request), uploads(request).get_unchecked(upload_id))
+        record = await uploads(request).complete(upload_id)
+        return {"id": record.id, "job": record.as_dict()}
+
+    @app.post("/api/v1/uploads/{upload_id}/cancel", dependencies=admin)
+    async def cancel_upload(upload_id: str, request: Request) -> dict[str, Any]:
+        check_receipt(get_store(request), uploads(request).get_unchecked(upload_id))
+        return await uploads(request).cancel(upload_id)
+
+    def job_snapshot(record: Any, request: Request) -> dict[str, Any]:
+        record = record.committed
+        return record.as_dict() | {
+            "name": record.context.get("name", "Transfer"),
+            "kind": record.context.get(
+                "source_kind", record.context.get("kind", "upload")
+            ),
+            "queue": (
+                get_runtime(request).pool.queue_estimate(record.id)
+                if callable(getattr(get_runtime(request).pool, "queue_estimate", None))
+                else None
+            ),
+            "destination": record.context.get("destination", "/"),
+            "history_cleared": record.history_hidden,
+        }
+
+    @app.get("/api/v1/jobs", dependencies=admin)
+    async def jobs(request: Request, response: Response) -> dict[str, Any]:
+        response.headers["Cache-Control"] = "no-store"
+        return {
+            "jobs": [
+                job_snapshot(record, request)
+                for record in get_manager(request).registry.list()
+            ]
+        }
+
+    @app.get("/api/v1/transfers/history", dependencies=admin)
+    async def transfer_history(
+        request: Request,
+        response: Response,
+        status: Literal[
+            "all", "finished", "queued", "running", "completed", "error", "cancelled"
+        ] = "all",
+        limit: int = Query(default=50, ge=1, le=200),
+        before: float | None = Query(default=None, ge=0, allow_inf_nan=False),
+        before_id: str | None = Query(
+            default=None, min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+        ),
+        q: str = Query(default="", max_length=MAX_NAME_LENGTH),
+        page: int | None = Query(default=None, ge=1),
+    ) -> dict[str, Any]:
+        if (before is None) != (before_id is None):
+            raise HTTPException(400, "Both history cursor fields are required")
+        if page is not None and before is not None:
+            raise HTTPException(400, "Use either a numbered page or a history cursor")
+        response.headers["Cache-Control"] = "no-store"
+        registry = get_manager(request).registry
+        if page is not None:
+            result = await registry.task_history(
+                status=status, limit=limit, page=page, query=q
+            )
+        else:
+            result = await registry.history(
+                status=status,
+                limit=limit,
+                before=(before, before_id) if before is not None else None,
+                query=q,
+            )
+        estimate = getattr(get_runtime(request).pool, "queue_estimate", None)
+        if callable(estimate):
+            for row in result["jobs"]:
+                row["queue"] = estimate(row["id"])
+        await asyncio.to_thread(enrich_locations, get_store(request), result["jobs"])
+        return result
+
+    @app.delete("/api/v1/transfers/history", dependencies=admin)
+    async def clear_transfer_history(
+        payload: ClearTransferHistoryRequest, request: Request, response: Response
+    ) -> dict[str, Any]:
+        response.headers["Cache-Control"] = "no-store"
+        cleared = await get_manager(request).registry.clear_history(
+            exclude_folders=payload.exclude_folders
+        )
+        return {"cleared": cleared}
+
+    @app.post("/api/v1/transfers/history/tasks", dependencies=admin)
+    async def transfer_task_history(
+        payload: TransferTaskHistoryRequest, request: Request, response: Response
+    ) -> dict[str, Any]:
+        response.headers["Cache-Control"] = "no-store"
+        result = await get_manager(request).registry.task_history(
+            status=payload.status,
+            page=payload.page,
+            limit=payload.limit,
+            query=payload.q,
+            offset=payload.offset,
+            exclude_folders=payload.exclude_folders,
+        )
+        estimate = getattr(get_runtime(request).pool, "queue_estimate", None)
+        if callable(estimate):
+            for row in result["jobs"]:
+                row["queue"] = estimate(row["id"])
+        await asyncio.to_thread(enrich_locations, get_store(request), result["jobs"])
+        return result
+
+    @app.post("/api/v1/transfers/location", dependencies=admin)
+    async def transfer_location(
+        payload: TransferLocationRequest, request: Request, response: Response
+    ):
+        response.headers["Cache-Control"] = "no-store"
+        return await asyncio.to_thread(
+            locate_transfer,
+            get_store(request),
+            {
+                "id": payload.transfer_id,
+                "destination": payload.destination,
+                "status": "completed" if payload.completed else "queued",
+            },
+        )
+
+    @app.get("/api/v1/jobs/{job_id}", dependencies=admin)
+    async def job(job_id: str, request: Request, response: Response) -> dict[str, Any]:
+        response.headers["Cache-Control"] = "no-store"
+        return job_snapshot(get_manager(request).registry.get(job_id), request)
+
+    @app.post("/api/v1/jobs/{job_id}/cancel", dependencies=admin)
+    async def cancel_job(job_id: str, request: Request) -> dict[str, Any]:
+        check_transfer(get_store(request), get_manager(request).registry.get(job_id))
+        try:
+            return job_snapshot(await get_manager(request).cancel_job(job_id), request)
+        except ValueError as exc:
+            if getattr(exc, "code", None) == "BACKUP_PENDING":
+                raise
+            raise HTTPException(409, str(exc)) from exc
+
+    @app.post("/api/v1/jobs/{job_id}/retry", dependencies=admin)
+    async def retry_job(job_id: str, request: Request) -> dict[str, Any]:
+        manager = get_manager(request)
+        record = manager.registry.get(job_id)
+        check_transfer(get_store(request), record)
+        record.context["demo_read_only"] = restricted_writes.get()
+        await manager.registry.persist(record)
+        try:
+            return job_snapshot(await get_manager(request).retry_job(job_id), request)
+        except ValueError as exc:
+            raise HTTPException(409, str(exc)) from exc
+
+    @app.get("/api/v1/shares", dependencies=admin)
+    async def shares(request: Request) -> Response:
+        records = await asyncio.to_thread(
+            get_store(request).list_shares,
+            include_expired=True,
+            token_factory=token_factory(settings),
+        )
+        return JSONResponse({"shares": records}, headers={"Cache-Control": "no-store"})
+
+    def selected_share(store, payload):
+        rows = store.list_shares(token_factory=token_factory(settings))
+        if payload.share_id:
+            rows = [row for row in rows if row["id"] == payload.share_id]
+        elif payload.path:
+            path = store.resolve_id(payload.path.rstrip("/").rsplit("/", 1)[-1])
+            rows = [row for row in rows if row["path"] == path]
+            if len(rows) > 1:
+                raise HTTPException(409, "Choose the individual link in Shared Links.")
+        else:
+            raise HTTPException(422, "A link ID or item path is required.")
+        if not rows:
+            raise HTTPException(410, "This link has expired or been revoked.")
+        return rows[0]
+
+    @app.post("/api/v1/shares/link", dependencies=admin)
+    async def copy_share(payload: RevokeShare, request: Request) -> Response:
+        def lookup():
+            row = selected_share(get_store(request), payload)
+            if not row["copyable"]:
+                raise HTTPException(
+                    409,
+                    "The original link URL is unavailable. Existing copies still "
+                    "work until this link expires or is revoked.",
+                )
+            return {
+                "auth": token_factory(settings)(row["id"]),
+                "id": row["id"],
+                "path": row["path"],
+                "type": row["type"],
+                "node_id": row["node_id"],
+            }
+
+        return JSONResponse(
+            await asyncio.to_thread(lookup), headers={"Cache-Control": "no-store"}
+        )
+
+    @app.post("/api/v1/shares", dependencies=admin, status_code=201)
+    async def create_share(payload: ShareCreate, request: Request) -> Response:
+        check_path(get_store(request), payload.path, descendants=True)
+        expires = (
+            payload.expires_at.isoformat()
+            if payload.expires_at
+            else (
+                datetime.now(UTC) + timedelta(days=payload.expires_in_days)
+            ).isoformat()
+            if payload.expires_in_days
+            else None
+        )
+
+        def create():
+            store = get_store(request)
+            with store.metadata_batch():
+                factory = token_factory(settings)
+                token = store.create_share(
+                    payload.path,
+                    expires_at=expires,
+                    label=payload.label,
+                    token_factory=factory,
+                )
+                row = next(
+                    row
+                    for row in store.list_shares(payload.path, token_factory=factory)
+                    if factory(row["id"]) == token
+                )
+                return {
+                    "auth": token,
+                    "id": row["id"],
+                    "path": row["path"],
+                    "expires_at": row["expires_at"],
+                    "label": row["label"],
+                }
+
+        return JSONResponse(
+            await asyncio.to_thread(create),
+            status_code=201,
+            headers={"Cache-Control": "no-store"},
+        )
+
+    @app.patch("/api/v1/shares", dependencies=admin)
+    async def update_share(payload: ShareUpdate, request: Request) -> dict[str, str]:
+        changes = {}
+        if "label" in payload.model_fields_set:
+            changes["label"] = payload.label
+        if "expires_at" in payload.model_fields_set:
+            changes["expires_at"] = (
+                payload.expires_at.isoformat() if payload.expires_at else None
+            )
+        await asyncio.to_thread(
+            get_store(request).update_share, payload.share_id, **changes
+        )
+        return {"status": "ok"}
+
+    @app.post("/api/v1/download-links", dependencies=admin)
+    async def download_link(payload: RevokeShare, request: Request) -> Response:
+        def create_or_reuse():
+            store = get_store(request)
+            with store.metadata_batch():
+                if not payload.path:
+                    raise HTTPException(422, "An item path is required.")
+                path = store.resolve_id(payload.path.rstrip("/").rsplit("/", 1)[-1])
+                store.get_file(path)
+                rows = [
+                    row
+                    for row in store.list_shares(
+                        path, token_factory=token_factory(settings)
+                    )
+                    if row.get("label") == "Download link" and row["copyable"]
+                ]
+                if rows:
+                    row = rows[0]
+                    if not row["copyable"]:
+                        raise HTTPException(
+                            409,
+                            "Create a replacement in Shared Links "
+                            "before copying this older link.",
+                        )
+                    token, expires = (
+                        token_factory(settings)(row["id"]),
+                        row["expires_at"],
+                    )
+                else:
+                    expires = (datetime.now(UTC) + timedelta(days=1)).isoformat()
+                    token = store.create_share(
+                        path,
+                        expires_at=expires,
+                        token_factory=token_factory(settings),
+                        label="Download link",
+                    )
+            from urllib.parse import urlencode
+
+            url = (
+                str(request.base_url).rstrip("/")
+                + "/file?"
+                + urlencode({"path": path, "auth": token, "download": "1"})
+            )
+            return {"url": url, "expires_at": expires, "path": path}
+
+        return JSONResponse(
+            await asyncio.to_thread(create_or_reuse),
+            headers={"Cache-Control": "no-store"},
+        )
+
+    @app.delete("/api/v1/shares", dependencies=admin)
+    async def revoke_share(payload: RevokeShare, request: Request) -> dict[str, Any]:
+        def revoke():
+            store = get_store(request)
+            if payload.share_id:
+                store.revoke_share(payload.share_id)
+            elif payload.path:
+                path = store.resolve_id(payload.path.rstrip("/").rsplit("/", 1)[-1])
+                store.revoke_share(path)
+            else:
+                raise HTTPException(422, "A link ID or item path is required.")
+
+        await asyncio.to_thread(revoke)
+        return {"status": "ok"}
+
+    def public_destination(store: Any, path: str) -> bool:
+        destination = path.rstrip("/") or "/"
+        return any(
+            destination == share["path"].rstrip("/")
+            or destination.startswith(share["path"].rstrip("/") + "/")
+            for share in store.list_shares()
+        )
+
+    def selection(paths: list[str]) -> list[str]:
+        selected = sorted(
+            dict.fromkeys("/" + path.strip("/") for path in paths), key=len
+        )
+        return [
+            path
+            for path in selected
+            if not any(
+                path.startswith(parent.rstrip("/") + "/")
+                for parent in selected
+                if parent != path
+            )
+        ]
+
+    @app.post("/api/v1/nodes/move", dependencies=admin)
+    def move_items(payload: MoveItems, request: Request) -> Any:
+        store = get_store(request)
+        check_path(store, payload.destination)
+        for path in payload.paths:
+            check_path(store, path, descendants=True)
+        with store.metadata_batch():
+            if (
+                public_destination(store, payload.destination)
+                and not payload.allow_public_exposure
+            ):
+                return JSONResponse(
+                    {
+                        "detail": "This destination is publicly shared. "
+                        "Confirm to expose these items.",
+                        "code": "PUBLIC_EXPOSURE_CONFIRMATION_REQUIRED",
+                    },
+                    status_code=409,
+                )
+            selected = selection(payload.paths)
+            moved = store.move_many(
+                selected, payload.destination, conflict=payload.conflict
+            )
+            results = [
+                {
+                    "path": path,
+                    "status": "moved" if result else "skipped",
+                    "item": result,
+                }
+                for path, result in zip(selected, moved, strict=True)
+            ]
+        return {"results": results}
+
+    @app.post("/api/v1/nodes/bulk", dependencies=admin)
+    async def bulk_items(payload: BulkItems, request: Request) -> Any:
+        store = get_store(request)
+        selected = selection(payload.paths)
+        for path in selected:
+            check_path(store, path, descendants=True)
+        results = []
+        if payload.action == "delete":
+            for path in selected:
+                store.validate_deletion(path)
+            for path in selected:
+                record = await get_manager(request).start_deletion(path)
+                results.append({"path": path, "id": record.id, "status": "deleting"})
+        else:
+
+            def apply_metadata():
+                with store.metadata_batch():
+                    if (
+                        payload.action == "restore"
+                        and not payload.allow_public_exposure
+                    ):
+                        for path in selected:
+                            if public_destination(store, path.rsplit("/", 1)[0] or "/"):
+                                return JSONResponse(
+                                    {
+                                        "detail": (
+                                            "Restoring here makes content "
+                                            "publicly accessible."
+                                        ),
+                                        "code": "PUBLIC_EXPOSURE_CONFIRMATION_REQUIRED",
+                                    },
+                                    status_code=409,
+                                )
+                    store.set_trashed_many(selected, payload.action == "trash")
+                    results.extend(
+                        [
+                            {
+                                "path": path,
+                                "status": "trashed"
+                                if payload.action == "trash"
+                                else "restored",
+                            }
+                            for path in selected
+                        ]
+                    )
+                return None
+
+            response = await asyncio.to_thread(apply_metadata)
+            if response is not None:
+                return response
+        return JSONResponse(
+            {"results": results}, status_code=202 if payload.action == "delete" else 200
+        )
diff --git a/tgdrive/web/app.py b/tgdrive/web/app.py
new file mode 100644
index 00000000..358be39b
--- /dev/null
+++ b/tgdrive/web/app.py
@@ -0,0 +1,1459 @@
+"""FastAPI application factory and owner/share HTTP routes."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import math
+import time
+from contextlib import asynccontextmanager, suppress
+from pathlib import Path
+from typing import Annotated, Any, cast
+
+from argon2 import PasswordHasher
+from fastapi import (
+    Depends,
+    FastAPI,
+    File,
+    Form,
+    HTTPException,
+    Query,
+    Request,
+    Response,
+    UploadFile,
+)
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import ValidationError as SettingsValidationError
+
+from tgdrive import __version__
+from tgdrive.core.config import Settings, get_settings
+from tgdrive.core.errors import (
+    DriveError,
+    DuplicateNameError,
+    InvalidPathError,
+    NotDirectoryError,
+    NotFileError,
+    NotFoundError,
+    RootMutationError,
+    TrashedItemError,
+)
+from tgdrive.core.errors import (
+    ValidationError as DriveValidationError,
+)
+from tgdrive.core.logging import configure_logging
+from tgdrive.core.runtime import Runtime
+from tgdrive.core.security import (
+    SESSION_COOKIE,
+    InvalidSession,
+    LoginLimiter,
+    SessionManager,
+    credential_session_key,
+    demo_admin_session_key,
+    verify_password,
+)
+from tgdrive.media.previews import describe_media, describe_preview
+from tgdrive.media.streaming import (
+    TelegramFileNotFound,
+    TelegramVariantNotFound,
+    _record_request_error,
+    stream_telegram_file,
+)
+from tgdrive.media.thumbnails import ThumbnailBusy, ThumbnailCache, load_thumbnail
+from tgdrive.recovery.backup import RecoveryConflict
+from tgdrive.storage.demo_files import (
+    annotate,
+    check_path,
+    check_transfer,
+    request_policy,
+)
+from tgdrive.storage.mongo import DatabaseUnavailable
+from tgdrive.storage.store import DriveStore
+from tgdrive.telegram.client_pool import (
+    ClientPoolNotRunning,
+    NoClientAvailable,
+    current_upload_limit,
+)
+from tgdrive.telegram.connection_errors import TelegramConnectionError
+from tgdrive.transfers.manager import (
+    BackupPending,
+    TransferCancelled,
+    TransferEmptyFile,
+    TransferManager,
+    TransferTooLarge,
+)
+from tgdrive.transfers.remote import RemoteError, RemoteTooLarge, UnsafeRemoteURL
+from tgdrive.transfers.tasks import TransferNotFound, TransferRecord
+from tgdrive.web.api_v1 import register_routes
+from tgdrive.web.demo_access import is_demo_restricted, session_access
+from tgdrive.web.http_guard import (
+    ApiBodyGuardMiddleware,
+    SameOriginMiddleware,
+    SecurityHeadersMiddleware,
+    UploadGuardMiddleware,
+)
+from tgdrive.web.request_ids import (
+    RequestCapacityError,
+    RequestIdCancelled,
+    RequestIdConflict,
+    RequestIdNotFound,
+    TransferStart,
+    TransferStarts,
+)
+from tgdrive.web.schemas import (
+    DirectoryRequest,
+    FolderCreateRequest,
+    ItemPathRequest,
+    LoginRequest,
+    RemoteInspectRequest,
+    RemoteStartRequest,
+    RenameRequest,
+    TransferCancelRequest,
+    TransferLookupRequest,
+    TransferRequest,
+    TrashRequest,
+)
+
+logger = logging.getLogger(__name__)
+PROJECT_DIR = Path(__file__).resolve().parents[2]
+WEBSITE_DIR = PROJECT_DIR / "website"
+STATIC_DIR = (
+    WEBSITE_DIR / "dist" / "static"
+    if (WEBSITE_DIR / "dist" / "static").exists()
+    else WEBSITE_DIR / "public" / "static"
+)
+
+
+def _json_error(detail: str, status_code: int) -> JSONResponse:
+    return JSONResponse(
+        status_code=status_code,
+        content={"status": detail, "detail": detail},
+    )
+
+
+def _runtime(request: Request) -> Any:
+    return request.app.state.runtime
+
+
+def _store(request: Request) -> DriveStore:
+    store = getattr(_runtime(request), "store", None)
+    if store is None:
+        raise HTTPException(status_code=503, detail="TGDrive is not ready")
+    return cast(DriveStore, store)
+
+
+def _transfers(request: Request) -> TransferManager:
+    manager = getattr(_runtime(request), "transfers", None)
+    if manager is None:
+        raise HTTPException(status_code=503, detail="TGDrive is not ready")
+    return cast(TransferManager, manager)
+
+
+def _is_admin(request: Request) -> bool:
+    token = request.cookies.get(SESSION_COOKIE)
+    if not token:
+        return False
+    try:
+        request.app.state.sessions.verify(token)
+        return True
+    except InvalidSession:
+        return False
+
+
+async def require_admin(request: Request) -> None:
+    if not _is_admin(request):
+        raise HTTPException(status_code=401, detail="Not authenticated")
+    request_policy(request)
+    # Use the matched route so proxy root paths cannot bypass demo restrictions.
+    path = request.scope["route"].path
+    if is_demo_restricted(request):
+        management_path = any(
+            path == root or path.startswith(root + "/")
+            for root in ("/api/v1/settings", "/api/v1/replica", "/api/v1/backup")
+        )
+        secret_export = path in {
+            "/api/v1/replica/key",
+            "/api/v1/backup/recovery-key",
+        }
+        if secret_export or (
+            management_path and request.method not in {"GET", "HEAD", "OPTIONS"}
+        ):
+            from tgdrive.settings.managed_settings import SettingsProblem
+
+            raise SettingsProblem(
+                "Configuration and management are read-only in the public demo.",
+                code="DEMO_MODE_READ_ONLY",
+                status=403,
+            )
+    runtime = _runtime(request)
+    if (
+        getattr(runtime, "archive_restore_restart_required", False)
+        and request.method not in {"GET", "HEAD", "OPTIONS"}
+        and request.url.path != "/api/logout"
+    ):
+        from tgdrive.settings.managed_settings import SettingsProblem
+
+        raise SettingsProblem(
+            "Database restore has paused this installation. Restart TGDrive "
+            "through Docker or Coolify before making further changes.",
+            code="DATABASE_RESTORE_RESTART_REQUIRED",
+            status=409,
+        )
+    replica = getattr(runtime, "replica", None)
+    if (
+        getattr(runtime, "recovery_only", False)
+        or (replica is not None and replica.blocked)
+    ) and (
+        request.method not in {"GET", "HEAD", "OPTIONS"}
+        and not request.url.path.startswith("/api/v1/replica")
+        and request.url.path
+        not in {
+            "/api/checkPassword",
+            "/api/logout",
+            "/api/v1/backup/restore",
+        }
+        and not request.url.path.endswith("/cancel")
+    ):
+        raise HTTPException(
+            409, "Channel recovery has paused file changes. Open Storage & Backups."
+        )
+    connections = getattr(runtime, "connection_manager", None)
+    if connections is not None and connections.restart_required:
+        allowed = (
+            request.method in {"GET", "HEAD", "OPTIONS"}
+            or request.url.path
+            in {
+                "/api/checkPassword",
+                "/api/logout",
+                "/api/getDirectory",
+                "/api/v1/backup/restore",
+            }
+            or request.url.path == "/api/v1/settings"
+            or request.url.path.startswith("/api/v1/settings/premium-login/")
+            or request.url.path.endswith("/cancel")
+        )
+        if not allowed:
+            from tgdrive.settings.managed_settings import SettingsProblem
+
+            raise SettingsProblem(
+                "Restart TGDrive to apply the saved connection settings "
+                "before making changes.",
+                code="SETTINGS_RESTART_REQUIRED",
+                status=409,
+            )
+    service = getattr(runtime, "backup", None)
+    if not getattr(service, "recovery_required", False):
+        return
+    path = request.url.path
+    read_posts = {
+        "/api/getDirectory",
+        "/api/getFileInfoFromUrl",
+        "/api/getTransferByRequest",
+        "/api/getTransferProgress",
+        "/api/logout",
+    }
+    if (
+        request.method in {"GET", "HEAD", "OPTIONS"}
+        or path in read_posts
+        or path == "/api/v1/backup/restore"
+    ):
+        return
+    if path == "/api/cancelUpload" or path.endswith("/cancel"):
+        return
+    raise RecoveryConflict(
+        "This installation needs recovery before changes are allowed. "
+        "Preserve its local data and recover the latest Telegram checkpoint."
+    )
+
+
+Admin = Annotated[None, Depends(require_admin)]
+
+
+def create_app(
+    settings: Settings | None = None,
+    *,
+    runtime: Any | None = None,
+) -> FastAPI:
+    configure_logging(settings.log_level if settings is not None else "INFO")
+    try:
+        settings = settings or get_settings()
+    except SettingsValidationError as error:
+        fields = sorted({str(item["loc"][0]) for item in error.errors() if item["loc"]})
+        detail = "Invalid TGDrive configuration: " + ", ".join(fields)
+        logging.getLogger(__name__).error(
+            "%s. Correct the private environment settings and redeploy.", detail
+        )
+        raise RuntimeError(detail) from None
+    except DatabaseUnavailable as error:
+        logging.getLogger(__name__).error("TGDrive startup rejected: %s", error)
+        raise
+    from tgdrive.replication.replica_activation import (
+        ActivationError,
+        effective_settings,
+    )
+
+    activation_unavailable = False
+    try:
+        settings = effective_settings(settings)
+    except DatabaseUnavailable as error:
+        logging.getLogger(__name__).error("TGDrive startup rejected: %s", error)
+        raise
+    except ActivationError:
+        activation_unavailable = True
+        logging.getLogger(__name__).warning(
+            "Saved recovery activation needs review; opening owner recovery."
+        )
+    configure_logging(settings.log_level)
+    app_runtime = runtime or Runtime(settings)
+    if activation_unavailable:
+        app_runtime._activation_unavailable = True
+    owner_credential = (
+        settings.admin_password_hash.get_secret_value()
+        if settings.admin_password_hash
+        else settings.admin_password.get_secret_value()
+    )
+    demo_credential = (
+        settings.demo_admin_password_hash or settings.demo_admin_password
+        if settings.demo_mode
+        else None
+    )
+    sessions = SessionManager(
+        credential_session_key(settings.session_key, owner_credential),
+        settings.session_ttl_seconds,
+        mongo_backend=getattr(app_runtime, "mongo", None),
+        demo_admin_key=(
+            demo_admin_session_key(
+                settings.session_key, demo_credential.get_secret_value()
+            )
+            if demo_credential
+            else None
+        ),
+    )
+    password_hash = (
+        settings.admin_password_hash.get_secret_value()
+        if settings.admin_password_hash
+        else PasswordHasher().hash(settings.admin_password.get_secret_value())
+    )
+    demo_password_hash = (
+        settings.demo_admin_password_hash.get_secret_value()
+        if settings.demo_admin_password_hash and demo_credential
+        else PasswordHasher().hash(demo_credential.get_secret_value())
+        if demo_credential
+        else None
+    )
+    limiter = LoginLimiter()
+    # Argon2 is deliberately expensive. Bound its memory/CPU use and keep it off
+    # the HTTP event loop so a login does not stall streams and health checks.
+    login_lock = asyncio.Lock()
+
+    @asynccontextmanager
+    async def lifespan(_app: FastAPI):
+        try:
+            await _app.state.thumbnail_repair.start()
+            await app_runtime.start()
+            await _app.state.thumbnail_rebuild.restore()
+            if settings.demo_mode and getattr(app_runtime, "store", None) is not None:
+                try:
+                    await asyncio.to_thread(app_runtime.store.ensure_demo_files)
+                except BaseException:
+                    await app_runtime.stop()
+                    raise
+            from tgdrive.observability.traffic import (
+                checkpoint_history,
+                sample_performance,
+            )
+
+            sampler = asyncio.create_task(
+                sample_performance(
+                    _app.state.traffic,
+                    getattr(app_runtime, "pool", None),
+                    history=_app.state.telemetry_history,
+                ),
+                name="tgdrive-performance-sampler",
+            )
+            try:
+                yield
+            finally:
+                sampler.cancel()
+                with suppress(asyncio.CancelledError):
+                    await sampler
+                try:
+                    await checkpoint_history(
+                        _app.state.traffic,
+                        getattr(app_runtime, "pool", None),
+                        _app.state.telemetry_history,
+                        force=True,
+                    )
+                except Exception:
+                    logging.getLogger(__name__).exception(
+                        "Could not checkpoint performance history on shutdown"
+                    )
+                login_service = getattr(_app.state, "premium_login_service", None)
+                if login_service is not None:
+                    await login_service.close()
+                connection_manager = getattr(app_runtime, "connection_manager", None)
+                if connection_manager is not None:
+                    await connection_manager.close()
+                await _app.state.thumbnail_rebuild.close()
+                await _app.state.thumbnails.close()
+                await app_runtime.stop()
+        finally:
+            sessions.close()
+
+    app = FastAPI(
+        title="TGDrive",
+        version=__version__,
+        docs_url=None,
+        redoc_url=None,
+        openapi_url=None,
+        lifespan=lifespan,
+    )
+    app.state.settings = settings
+    app.state.runtime = app_runtime
+    app.state.sessions = sessions
+    app.state.login_limiter = limiter
+    app.state.thumbnails = ThumbnailCache()
+    from tgdrive.media.generated_thumbnails import CachedThumbnailRepair
+
+    app.state.thumbnail_repair = CachedThumbnailRepair(
+        settings.resolved_cache_dir / "thumbnails"
+    )
+    from tgdrive.media.thumbnail_rebuild import register_thumbnail_routes
+
+    register_thumbnail_routes(app, settings, require_admin)
+    starts = TransferStarts(ttl_seconds=settings.transfer_ttl_seconds)
+    app.state.transfer_starts = starts
+
+    @app.exception_handler(DatabaseUnavailable)
+    async def database_unavailable(_request: Request, _error: DatabaseUnavailable):
+        return JSONResponse(
+            {
+                "detail": "MongoDB is unavailable. Check its connection and retry.",
+                "code": "DATABASE_UNAVAILABLE",
+            },
+            status_code=503,
+        )
+
+    from pymongo.errors import PyMongoError
+
+    app.add_exception_handler(PyMongoError, database_unavailable)
+
+    @app.exception_handler(RecoveryConflict)
+    async def recovery_conflict(
+        _request: Request, exc: RecoveryConflict
+    ) -> JSONResponse:
+        return JSONResponse({"detail": str(exc), "code": exc.code}, status_code=409)
+
+    @app.exception_handler(BackupPending)
+    async def checkpoint_pending(_request: Request, exc: BackupPending) -> JSONResponse:
+        return JSONResponse({"detail": str(exc), "code": exc.code}, status_code=409)
+
+    @app.exception_handler(DriveError)
+    async def drive_error_handler(_request: Request, exc: DriveError) -> JSONResponse:
+        if isinstance(exc, DuplicateNameError):
+            code = 409
+        elif isinstance(
+            exc,
+            (NotFoundError, NotDirectoryError, NotFileError, TrashedItemError),
+        ):
+            code = 404
+        elif isinstance(
+            exc,
+            (DriveValidationError, InvalidPathError, RootMutationError),
+        ):
+            code = 400
+        else:
+            code = 500
+            logger.error(
+                "Unexpected drive error type: %s",
+                type(exc).__name__,
+                exc_info=(type(exc), exc, exc.__traceback__),
+            )
+        return _json_error(str(exc), code)
+
+    @app.exception_handler(TelegramConnectionError)
+    async def telegram_connection_error(
+        _request: Request, exc: TelegramConnectionError
+    ) -> JSONResponse:
+        return JSONResponse({"detail": str(exc), "code": exc.code}, status_code=503)
+
+    @app.exception_handler(ClientPoolNotRunning)
+    @app.exception_handler(NoClientAvailable)
+    async def telegram_unavailable(_request: Request, _exc: Exception) -> JSONResponse:
+        if getattr(_exc, "code", None) == "TELEGRAM_QUEUE_FULL":
+            return JSONResponse(
+                {
+                    "detail": "Telegram is busy and its waiting queue is full. "
+                    "Retry shortly.",
+                    "code": "TELEGRAM_QUEUE_FULL",
+                },
+                status_code=503,
+                headers={"Retry-After": str(getattr(_exc, "retry_after", 1))},
+            )
+        return _json_error(
+            "No usable Telegram account is connected. Open Connections and Refresh "
+            "to check bot tokens, Premium sessions and storage-channel permissions. "
+            "Restore the connection, then retry.",
+            503,
+        )
+
+    from tgdrive.transfers.staging import StorageUnavailable
+
+    @app.exception_handler(StorageUnavailable)
+    async def staging_error_handler(_request: Request, exc: StorageUnavailable):
+        return _json_error(str(exc), exc.status)
+
+    @app.exception_handler(RemoteError)
+    async def remote_error_handler(_request: Request, exc: RemoteError) -> JSONResponse:
+        if isinstance(exc, RemoteTooLarge):
+            code = 413
+        elif isinstance(exc, UnsafeRemoteURL):
+            code = 400
+        else:
+            code = 502
+        return _json_error(str(exc), code)
+
+    @app.exception_handler(TransferNotFound)
+    @app.exception_handler(RequestIdNotFound)
+    async def transfer_not_found_handler(
+        _request: Request, _exc: TransferNotFound
+    ) -> JSONResponse:
+        return _json_error("Transfer not found", 404)
+
+    @app.exception_handler(RequestIdConflict)
+    @app.exception_handler(RequestIdCancelled)
+    async def transfer_start_conflict(
+        _request: Request, exc: RequestIdConflict | RequestIdCancelled
+    ) -> JSONResponse:
+        return _json_error(str(exc), 409)
+
+    @app.exception_handler(RequestCapacityError)
+    async def transfer_capacity_error(
+        _request: Request, exc: RequestCapacityError
+    ) -> JSONResponse:
+        return _json_error(str(exc), 503)
+
+    @app.exception_handler(RequestValidationError)
+    async def request_validation_handler(
+        _request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        # SecretStr values stay hidden; avoid echoing rejected input as well.
+        message = "; ".join(error["msg"] for error in exc.errors())
+        return _json_error(message or "Invalid request", 422)
+
+    @app.get("/")
+    async def home_page() -> Response:
+        index = WEBSITE_DIR / "dist" / "index.html"
+        if index.exists():
+            return FileResponse(index, headers={"Cache-Control": "no-store"})
+        return HTMLResponse(
+            "<!doctype html><html lang='en'><meta charset='utf-8'>"
+            "<meta name='viewport' content='width=device-width,initial-scale=1'>"
+            "<title>TGDrive setup</title>"
+            "<link rel='icon' type='image/svg+xml' href='/static/brand/favicon.svg'>"
+            "<main><p><img src='/static/brand/tgdrive-logo.svg' "
+            "width='251' height='50' alt='TGDrive'></p>"
+            "<h1>Build the TGDrive interface</h1>"
+            "<p>In the website folder, run <code>npm ci</code>, then "
+            "<code>npm run build</code>, and restart TGDrive.</p></main></html>",
+            headers={"Cache-Control": "no-store"},
+        )
+
+    @app.get("/stream")
+    async def video_player(
+        path: Annotated[str, Query(min_length=1, max_length=4096)],
+        auth: Annotated[str | None, Query(max_length=512)] = None,
+    ) -> FileResponse:
+        # Authorization happens when the native player requests /file.
+        del path, auth
+        return FileResponse(
+            WEBSITE_DIR / "dist" / "VideoPlayer.html"
+            if (WEBSITE_DIR / "dist" / "VideoPlayer.html").exists()
+            else WEBSITE_DIR / "public" / "VideoPlayer.html",
+            headers={"Cache-Control": "no-store"},
+        )
+
+    @app.get("/health/live")
+    async def health_live() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/health/ready")
+    @app.get("/healthz")
+    async def health_ready(request: Request) -> JSONResponse:
+        current_runtime = _runtime(request)
+        ready = bool(getattr(current_runtime, "ready", False))
+        pool_health = getattr(getattr(current_runtime, "pool", None), "health", None)
+        if ready and callable(pool_health):
+            health = await pool_health()
+            ready = bool(health.ready)
+        return JSONResponse(
+            status_code=200 if ready else 503,
+            content={"status": "ok" if ready else "not ready"},
+        )
+
+    @app.get("/api/config")
+    async def public_config(request: Request, response: Response) -> dict[str, Any]:
+        response.headers["Cache-Control"] = "no-store"
+        access = session_access(request)
+        return {
+            "status": "ok",
+            "max_file_size": await current_upload_limit(
+                settings, getattr(_runtime(request), "pool", None)
+            ),
+            "timezone": settings.timezone,
+            "demo_mode": settings.demo_mode,
+            "demo_read_only": access["demo_read_only"],
+            "demo_admin": access["demo_admin"],
+            "recovery_only": bool(getattr(_runtime(request), "recovery_only", False)),
+        }
+
+    @app.post("/api/checkPassword")
+    async def check_password(payload: LoginRequest, request: Request) -> JSONResponse:
+        client_key = request.client.host if request.client else "unknown"
+        decision = limiter.check(client_key)
+        if not decision.allowed:
+            return JSONResponse(
+                status_code=429,
+                headers={"Retry-After": str(decision.retry_after)},
+                content={
+                    "status": "Too many login attempts",
+                    "detail": "Too many login attempts",
+                },
+            )
+        expected = password_hash
+        if login_lock.locked():
+            return JSONResponse(
+                status_code=429,
+                headers={"Retry-After": "1"},
+                content={
+                    "status": "Login busy; retry shortly",
+                    "detail": "Login busy; retry shortly",
+                    "code": "LOGIN_BUSY",
+                },
+            )
+        async with login_lock:
+            valid = await asyncio.to_thread(verify_password, payload.password, expected)
+            demo_admin = False
+            if not valid and demo_password_hash is not None:
+                demo_admin = await asyncio.to_thread(
+                    verify_password, payload.password, demo_password_hash
+                )
+                valid = demo_admin
+        if not valid:
+            limiter.failure(client_key)
+            return _json_error("Invalid password", 401)
+        limiter.success(client_key)
+        response = JSONResponse({"status": "ok"})
+        response.set_cookie(
+            SESSION_COOKIE,
+            await asyncio.to_thread(sessions.create, demo_admin=demo_admin),
+            max_age=settings.session_ttl_seconds,
+            httponly=True,
+            secure=settings.cookie_secure,
+            samesite="strict",
+            path="/",
+        )
+        return response
+
+    @app.post("/api/logout")
+    async def logout(request: Request) -> JSONResponse:
+        # Invalid cookies must not turn this public route into database work.
+        if _is_admin(request):
+            await asyncio.to_thread(sessions.revoke, request.cookies[SESSION_COOKIE])
+        response = JSONResponse({"status": "ok"})
+        response.delete_cookie(
+            SESSION_COOKIE,
+            secure=settings.cookie_secure,
+            httponly=True,
+            samesite="strict",
+            path="/",
+        )
+        return response
+
+    @app.post("/api/getDirectory")
+    async def get_directory(
+        payload: DirectoryRequest, request: Request
+    ) -> JSONResponse:
+        if _is_admin(request):
+            await require_admin(request)
+        store = _store(request)
+        requested = payload.path
+        auth_home_path: str | None = None
+        if requested == "/trash":
+            await require_admin(request)
+            data: dict[str, Any] = {"contents": store.list_trash()}
+        elif requested.startswith("/search_"):
+            await require_admin(request)
+            query = requested.removeprefix("/search_")
+            page = store.search_page(query, limit=500)
+            data = {
+                "contents": {row["id"]: row for row in page["items"]},
+                "search": {key: value for key, value in page.items() if key != "items"},
+            }
+        elif requested.startswith("/share_"):
+            if getattr(
+                getattr(_runtime(request), "backup", None), "recovery_required", False
+            ):
+                raise RecoveryConflict(
+                    "Shared access is paused until recovery completes"
+                )
+            real_path = "/" + requested.removeprefix("/share_").lstrip("/")
+            if real_path != "/":
+                real_path = store.resolve_id(real_path.rstrip("/").rsplit("/", 1)[-1])
+            auth_home_path = store.authorize_directory(real_path, payload.auth or "")
+            if auth_home_path is None:
+                raise HTTPException(status_code=403, detail="Invalid share link")
+            data = store.get_directory(real_path)
+            for item in data.get("contents", {}).values():
+                item.pop("starred", None)
+        else:
+            await require_admin(request)
+            data = store.get_directory(requested)
+        if settings.demo_mode:
+            annotate(data)
+        return JSONResponse(
+            {
+                "status": "ok",
+                "data": data,
+                "auth_home_path": auth_home_path,
+            }
+        )
+
+    @app.post("/api/createNewFolder")
+    async def create_folder(
+        payload: FolderCreateRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, str]:
+        check_path(_store(request), payload.path)
+        await asyncio.to_thread(
+            _store(request).create_folder, payload.path, payload.name
+        )
+        return {"status": "ok"}
+
+    @app.post("/api/renameFileFolder")
+    async def rename_item(
+        payload: RenameRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, str]:
+        check_path(_store(request), payload.path, descendants=True)
+        await asyncio.to_thread(_store(request).rename, payload.path, payload.name)
+        return {"status": "ok"}
+
+    @app.post("/api/trashFileFolder")
+    async def trash_item(
+        payload: TrashRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, str]:
+        check_path(_store(request), payload.path, descendants=True)
+        await asyncio.to_thread(
+            _store(request).set_trashed, payload.path, payload.trash
+        )
+        return {"status": "ok"}
+
+    @app.post("/api/deleteFileFolder")
+    async def delete_item(
+        payload: ItemPathRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, str]:
+        store = _store(request)
+        check_path(store, payload.path, descendants=True)
+        manager = _transfers(request)
+        normalized_path = "/" + payload.path.strip("/")
+        trash_paths = {
+            (
+                f"{item['path'].rstrip('/')}/{item['id']}"
+                if item["path"] != "/"
+                else f"/{item['id']}"
+            )
+            for item in store.list_trash().values()
+        }
+        if normalized_path not in trash_paths:
+            raise HTTPException(
+                status_code=409,
+                detail="Item must be in trash before permanent deletion",
+            )
+        record = await manager.start_deletion(payload.path)
+        return JSONResponse({"status": "ok", "id": record.id}, status_code=202)
+
+    async def create_share(
+        payload: ItemPathRequest,
+        request: Request,
+        expected_type: str,
+    ) -> dict[str, str]:
+        store = _store(request)
+        check_path(store, payload.path, descendants=True)
+        if expected_type == "folder":
+            store.get_directory(payload.path)
+        else:
+            store.get_file(payload.path)
+        from tgdrive.web.share_links import token_factory
+
+        token = await asyncio.to_thread(
+            store.create_share,
+            payload.path,
+            token_factory=token_factory(settings),
+        )
+        return {"status": "ok", "auth": token}
+
+    @app.post("/api/getFolderShareAuth")
+    async def folder_share(
+        payload: ItemPathRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, str]:
+        return await create_share(payload, request, "folder")
+
+    @app.post("/api/getFileShareAuth")
+    async def file_share(
+        payload: ItemPathRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, str]:
+        return await create_share(payload, request, "file")
+
+    @app.post("/api/upload")
+    async def upload_file(
+        request: Request,
+        _admin: Admin,
+        file: Annotated[UploadFile, File()],
+        path: Annotated[str, Form(min_length=1, max_length=4096)],
+        client_request_id: Annotated[
+            str | None,
+            Form(min_length=16, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"),
+        ] = None,
+    ) -> JSONResponse:
+        check_path(_store(request), path)
+        manager = _transfers(request)
+        entry: TransferStart | None = None
+        if client_request_id:
+            entry, created = starts.claim(
+                client_request_id,
+                ("local", path, file.filename or "", str(file.size)),
+            )
+            if not created:
+                await file.close()
+                snapshot = entry.snapshot()
+                return JSONResponse(
+                    {"status": "ok", "id": snapshot["id"], "data": snapshot}
+                )
+
+        async def bind_created(record: TransferRecord) -> None:
+            if entry is not None and starts.bind(entry, record):
+                await manager.registry.cancel(record.id)
+
+        try:
+            record = await manager.receive_browser_upload(
+                file,
+                path,
+                is_disconnected=request.is_disconnected,
+                on_created=bind_created,
+            )
+        except TransferTooLarge as exc:
+            if entry:
+                starts.fail(entry, str(exc))
+            return _json_error(str(exc), 413)
+        except TransferEmptyFile as exc:
+            if entry:
+                starts.fail(entry, str(exc))
+            return _json_error(str(exc), 422)
+        except TransferCancelled as exc:
+            if entry:
+                starts.cancel(entry.request_id)
+            return _json_error(str(exc), 409)
+        except Exception as exc:
+            if entry:
+                starts.fail(entry, str(exc) or type(exc).__name__)
+            raise
+        if entry and entry.record is None:
+            bind_created(record)
+        return JSONResponse({"status": "ok", "id": record.id})
+
+    @app.post("/api/getFileInfoFromUrl")
+    async def inspect_remote(
+        payload: RemoteInspectRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, Any]:
+        info = await _transfers(request).inspect_remote(str(payload.url))
+        return {
+            "status": "ok",
+            "data": {
+                "file_name": info.filename,
+                "file_size": info.size if info.size is not None else -1,
+                "content_type": info.content_type,
+            },
+        }
+
+    @app.post("/api/startFileDownloadFromUrl")
+    async def start_remote(
+        payload: RemoteStartRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, Any]:
+        check_path(_store(request), payload.path)
+        entry: TransferStart | None = None
+        if payload.client_request_id:
+            entry, created = starts.claim(
+                payload.client_request_id,
+                (
+                    "remote",
+                    payload.path,
+                    str(payload.url),
+                    payload.filename or "",
+                    str(payload.single_threaded),
+                ),
+            )
+            if not created:
+                snapshot = entry.snapshot()
+                return {"status": "ok", "id": snapshot["id"], "data": snapshot}
+        try:
+            manager = _transfers(request)
+            # Source DNS, headers and size admission belong to the cancellable
+            # server job. Return its identity without waiting on an external host.
+            record = await manager.start_remote(
+                url=str(payload.url),
+                destination=payload.path,
+                filename=payload.filename,
+                single_threaded=payload.single_threaded,
+            )
+        except Exception as exc:
+            if entry:
+                starts.fail(entry, str(exc) or type(exc).__name__)
+            raise
+        if entry:
+            starts.bind(entry, record)
+        return {"status": "ok", "id": record.id}
+
+    @app.post("/api/getTransferByRequest")
+    async def transfer_by_request(
+        payload: TransferLookupRequest, request: Request, _admin: Admin
+    ) -> dict[str, Any]:
+        del request
+        snapshot = starts.get(payload.client_request_id).snapshot()
+        return {"status": "ok", "id": snapshot["id"], "data": snapshot}
+
+    @app.post("/api/getTransferProgress")
+    async def transfer_progress(
+        payload: TransferRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, Any]:
+        record = _transfers(request).registry.get(payload.id)
+        return {"status": "ok", "data": record.as_dict()}
+
+    @app.post("/api/cancelUpload")
+    async def cancel_transfer(
+        payload: TransferCancelRequest,
+        request: Request,
+        _admin: Admin,
+    ) -> dict[str, Any]:
+        manager = _transfers(request)
+        cancel = getattr(manager, "cancel_job", manager.registry.cancel)
+        if payload.client_request_id:
+            try:
+                existing = starts.get(payload.client_request_id)
+            except RequestIdNotFound:
+                existing = None
+            # Refuse a committed upload before setting any cancellation intent.
+            if existing is not None and existing.record is not None:
+                check_transfer(_store(request), existing.record)
+                await cancel(existing.record.id)
+            entry = starts.cancel(payload.client_request_id)
+            snapshot = entry.snapshot()
+        else:
+            assert payload.id is not None
+            check_transfer(_store(request), manager.registry.get(payload.id))
+            snapshot = (await cancel(payload.id)).as_dict()
+        return {"status": "ok", "id": snapshot["id"], "data": snapshot}
+
+    def authorized_file(
+        request: Request, path: str, auth: str | None
+    ) -> tuple[str, dict[str, Any]]:
+        store = _store(request)
+        if getattr(
+            getattr(_runtime(request), "backup", None), "recovery_required", False
+        ):
+            raise RecoveryConflict(
+                "File access is paused until this installation is recovered. "
+                "Preserve local data and recover the latest Telegram checkpoint."
+            )
+        if path != "/":
+            path = store.resolve_id(path.rstrip("/").rsplit("/", 1)[-1])
+        if auth is not None or not _is_admin(request):
+            try:
+                authorized = store.authorize_file(path, auth or "")
+            except DriveError:
+                authorized = False
+            if not authorized:
+                raise HTTPException(status_code=403, detail="Invalid share link")
+        return path, store.get_file(path)
+
+    @app.get("/api/v1/preview")
+    async def file_preview(
+        request: Request,
+        path: Annotated[str, Query(min_length=1, max_length=4096)],
+        auth: Annotated[str | None, Query(max_length=512)] = None,
+    ) -> dict[str, Any]:
+        path, file_data = authorized_file(request, path, auth)
+        try:
+            result = await describe_preview(
+                pool=_runtime(request).pool,
+                channel_id=settings.storage_channel,
+                message_id=file_data["message_id"],
+                parts=file_data.get("parts"),
+                file_name=file_data["name"],
+                size=file_data["size"],
+                path=path,
+                auth=auth,
+            )
+            authorized_file(request, path, auth)
+            return result
+        except TelegramFileNotFound as exc:
+            raise HTTPException(404, exc.public_detail) from exc
+
+    @app.get("/api/v1/books")
+    async def book_preview(
+        request: Request,
+        path: Annotated[str, Query(min_length=1, max_length=4096)],
+        auth: Annotated[str | None, Query(max_length=512)] = None,
+        entry: Annotated[str | None, Query(min_length=1, max_length=1024)] = None,
+    ) -> Response:
+        from tgdrive.media.books import BookCache, parse_book, read_range
+
+        path, data = authorized_file(request, path, auth)
+        cache = getattr(app.state, "book_cache", None)
+        if cache is None:
+            cache = app.state.book_cache = BookCache()
+        key = cache.key(data, entry)
+        pending = getattr(app.state, "book_requests", 0)
+        if pending >= 16:
+            raise HTTPException(
+                503,
+                "The reader is busy. Try again shortly.",
+                headers={"Retry-After": "2"},
+            )
+        semaphore = getattr(app.state, "book_slots", None)
+        if semaphore is None:
+            semaphore = app.state.book_slots = asyncio.Semaphore(2)
+        app.state.book_requests = pending + 1
+        acquired = False
+
+        async def authorize():
+            _, current = await asyncio.to_thread(authorized_file, request, path, auth)
+            if any(
+                current.get(key) != data.get(key)
+                for key in ("message_id", "size", "parts")
+            ):
+                raise HTTPException(409, "The stored book changed. Reopen it.")
+
+        async def fetch(start, count):
+            return await read_range(
+                _runtime(request).pool,
+                settings.storage_channel,
+                data,
+                start,
+                count,
+                authorize,
+            )
+
+        def response(payload):
+            content, mime, etag = payload
+            headers = {
+                "Cache-Control": "private, no-cache",
+                "Vary": "Cookie",
+                "ETag": etag,
+                "X-Content-Type-Options": "nosniff",
+            }
+            if etag in [
+                value.strip()
+                for value in request.headers.get("if-none-match", "").split(",")
+            ]:
+                return Response(status_code=304, headers=headers)
+            return Response(content, media_type=mime, headers=headers)
+
+        try:
+            # Waiters hold only descriptors; no parser slot or page buffer.
+            async with asyncio.timeout(55), cache.hold(key):
+                await authorize()
+                cached = cache.get(key)
+                if cached is not None:
+                    return response(cached)
+                try:
+                    await asyncio.wait_for(semaphore.acquire(), timeout=10)
+                    acquired = True
+                except TimeoutError as exc:
+                    raise HTTPException(
+                        503,
+                        "The reader is busy. Try again shortly.",
+                        headers={"Retry-After": "2"},
+                    ) from exc
+                await authorize()
+                result = await parse_book(data, fetch, entry, raw_images=True)
+                await authorize()
+                return response(cache.put(key, result))
+        except TimeoutError as exc:
+            raise HTTPException(
+                503,
+                "The reader is busy. Try again shortly.",
+                headers={"Retry-After": "2"},
+            ) from exc
+        finally:
+            if acquired:
+                semaphore.release()
+            app.state.book_requests -= 1
+
+    @app.get("/api/v1/thumbnail")
+    async def file_thumbnail(
+        request: Request,
+        path: Annotated[str, Query(min_length=1, max_length=4096)],
+        auth: Annotated[str | None, Query(max_length=512)] = None,
+    ) -> Response:
+        path, file_data = authorized_file(request, path, auth)
+        # Prefer upload-generated/provider covers; missing derivatives can use
+        # a complete verified original already cached, without origin reads.
+        headers = {"Cache-Control": "private, no-cache", "Vary": "Cookie"}
+
+        def file_identity(data):
+            return (
+                data["message_id"],
+                data["size"],
+                tuple(
+                    (part["message_id"], part["offset"], part["size"], part["sha256"])
+                    for part in data.get("parts") or []
+                ),
+            )
+
+        identity = file_identity(file_data)
+        key = (settings.storage_channel, *identity)
+        pool = _runtime(request).pool
+        cache = getattr(pool, "_media_read_cache", None)
+        source = {
+            "channel_id": settings.storage_channel,
+            "message_id": file_data["message_id"],
+            "size": file_data["size"],
+            "parts": file_data.get("parts"),
+        }
+        version = cache.cached_source_version(**source) if cache is not None else None
+
+        def recheck():
+            _current_path, current = authorized_file(request, path, auth)
+            if file_identity(current) != identity:
+                raise HTTPException(409, "File changed; refresh the directory")
+
+        async def load_cover():
+            from tgdrive.media.generated_thumbnails import read
+            from tgdrive.media.thumbnails import Thumbnail
+
+            content = await asyncio.to_thread(
+                read,
+                settings.resolved_cache_dir / "thumbnails",
+                settings.storage_channel,
+                file_data["message_id"],
+            )
+            if content:
+                return Thumbnail(content, "image/jpeg")
+            provider_error = None
+            try:
+                provider = await load_thumbnail(
+                    pool=pool,
+                    channel_id=settings.storage_channel,
+                    message_id=file_data["message_id"],
+                )
+                if provider is not None:
+                    return provider
+            except ThumbnailBusy as exc:
+                provider_error = exc
+            if cache is not None:
+                content = await app.state.thumbnail_repair.get(
+                    cache,
+                    source=source,
+                    name=file_data["name"],
+                    version=version,
+                    authorize=recheck,
+                )
+                if content:
+                    return Thumbnail(content, "image/jpeg")
+            if provider_error is not None:
+                raise provider_error
+            return None
+
+        try:
+            thumbnail = await app.state.thumbnails.get(
+                key,
+                load_cover,
+                missing_revision=version.data_revision if version is not None else None,
+            )
+        except ThumbnailBusy:
+            recheck()
+            return JSONResponse(
+                {
+                    "code": "THUMBNAIL_BUSY",
+                    "detail": "Thumbnail temporarily unavailable",
+                },
+                status_code=503,
+                headers={**headers, "Retry-After": "5"},
+            )
+        # Even a cache hit or conditional 304 must pass today's share/session
+        # authorization. Nothing in the payload cache grants access to a file.
+        recheck()
+        if thumbnail is None:
+            # Optional derivative absence is a successful icon fallback, not a
+            # missing original. Keep real authorization/file failures distinct.
+            return Response(status_code=204, headers=headers)
+        headers["ETag"] = thumbnail.etag
+        if request.headers.get("if-none-match") == thumbnail.etag:
+            return Response(status_code=304, headers=headers)
+        return Response(
+            thumbnail.content, media_type=thumbnail.media_type, headers=headers
+        )
+
+    @app.get("/api/v1/media")
+    async def file_media(
+        request: Request,
+        path: Annotated[str, Query(min_length=1, max_length=4096)],
+        auth: Annotated[str | None, Query(max_length=512)] = None,
+    ) -> dict[str, Any]:
+        _path, file_data = authorized_file(request, path, auth)
+        try:
+            result = await describe_media(
+                pool=_runtime(request).pool,
+                channel_id=settings.storage_channel,
+                message_id=file_data["message_id"],
+                parts=file_data.get("parts"),
+                file_name=file_data["name"],
+                size=file_data["size"],
+            )
+            authorized_file(request, _path, auth)
+            return result
+        except TelegramFileNotFound as exc:
+            raise HTTPException(404, exc.public_detail) from exc
+
+    @app.api_route("/file", methods=["GET", "HEAD"])
+    async def download_file(
+        request: Request,
+        path: Annotated[str, Query(min_length=1, max_length=4096)],
+        auth: Annotated[str | None, Query(max_length=512)] = None,
+        download: bool = False,
+        preview: bool = False,
+        quality: Annotated[str | None, Query(max_length=128)] = None,
+        request_id: Annotated[
+            str | None, Query(max_length=128, pattern=r"^[A-Za-z0-9_-]+$")
+        ] = None,
+    ) -> Response:
+        path, file_data = authorized_file(request, path, auth)
+
+        pool = _runtime(request).pool
+        progress = None
+        if request_id and request.method == "GET":
+            requests = getattr(pool, "_request_files", None)
+            if requests is None:
+                requests = {}
+                try:
+                    pool._request_files = requests
+                except AttributeError:
+                    requests = None
+            if requests is not None:
+                progress = requests[request_id] = dict(
+                    file=(
+                        settings.storage_channel,
+                        file_data["message_id"],
+                        file_data["size"],
+                    ),
+                    phase="checking_file",
+                    code=None,
+                    retry_at=None,
+                )
+                while len(requests) > 4096:
+                    requests.pop(next(iter(requests)))
+
+        async def authorize():
+            _, current = await asyncio.to_thread(authorized_file, request, path, auth)
+            if any(
+                current.get(key) != file_data.get(key)
+                for key in ("message_id", "size", "parts")
+            ):
+                raise HTTPException(
+                    409, "The stored file changed. Restart the download."
+                )
+
+        if request.method == "HEAD" and quality is None:
+            import mimetypes
+
+            from tgdrive.media.ranges import (
+                MalformedRange,
+                RangeNotSatisfiable,
+                parse_byte_range,
+            )
+            from tgdrive.media.streaming import (
+                _content_disposition,
+                _not_modified,
+                _request_range,
+                media_etag,
+            )
+
+            total = file_data["size"]
+            tag = media_etag(
+                settings.storage_channel,
+                file_data["message_id"],
+                total,
+                parts=file_data.get("parts"),
+            )
+            mime = (
+                mimetypes.guess_type(file_data["name"])[0] or "application/octet-stream"
+            )
+            headers = {
+                "Accept-Ranges": "bytes",
+                "Content-Encoding": "identity",
+                "ETag": tag,
+                "Cache-Control": "private, no-store, no-transform",
+                "Content-Disposition": _content_disposition(
+                    file_data["name"], mime, download=download, preview=preview
+                ),
+            }
+            if _not_modified(request, tag):
+                return Response(status_code=304, headers=headers)
+            try:
+                selected = parse_byte_range(_request_range(request, tag), total)
+            except MalformedRange:
+                return Response(status_code=400, headers=headers)
+            except RangeNotSatisfiable as exc:
+                return Response(
+                    status_code=416,
+                    headers=headers | {"Content-Range": exc.content_range},
+                )
+            headers["Content-Length"] = str(selected.length)
+            if selected.content_range:
+                headers["Content-Range"] = selected.content_range
+            return Response(
+                status_code=206 if selected.is_partial else 200,
+                headers=headers,
+                media_type=mime,
+            )
+        try:
+            response = await stream_telegram_file(
+                pool=_runtime(request).pool,
+                channel_id=settings.storage_channel,
+                message_id=file_data["message_id"],
+                parts=file_data.get("parts"),
+                file_name=file_data["name"],
+                expected_size=file_data["size"],
+                request=request,
+                download=download,
+                preview=preview,
+                quality=quality,
+                authorize=authorize,
+                request_id=request_id,
+                request_status=progress,
+            )
+            if progress is not None and progress["phase"] == "checking_file":
+                progress["phase"] = None
+            return response
+        except BaseException as exc:
+            _record_request_error(progress, exc)
+            if isinstance(exc, TelegramVariantNotFound):
+                raise HTTPException(404, "This media quality is unavailable") from exc
+            if isinstance(exc, TelegramFileNotFound):
+                raise HTTPException(status_code=404, detail=exc.public_detail) from exc
+            raise
+
+    @app.get("/api/v1/file-status")
+    async def file_status(
+        request: Request,
+        path: Annotated[str, Query(min_length=1, max_length=4096)],
+        request_id: Annotated[
+            str, Query(min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_-]+$")
+        ],
+        auth: Annotated[str | None, Query(max_length=512)] = None,
+    ):
+        _, data = authorized_file(request, path, auth)
+        pool = _runtime(request).pool
+        estimate = getattr(pool, "queue_estimate", None)
+        progress = getattr(pool, "_request_files", {}).get(request_id)
+        if progress is not None and progress["file"] != (
+            settings.storage_channel,
+            data["message_id"],
+            data["size"],
+        ):
+            progress = None
+        queue = (
+            estimate(request_id)
+            if progress is not None and callable(estimate)
+            else None
+        )
+        phase = progress["phase"] if progress is not None else None
+        if (
+            queue
+            and queue.get("queued_operations")
+            and not queue.get("active_operations")
+            and phase in {"checking_file", "receiving"}
+        ):
+            phase = "waiting_for_telegram"
+        return JSONResponse(
+            {
+                "queue": queue,
+                "size": data["size"],
+                "phase": phase,
+                "code": progress["code"] if progress is not None else None,
+                "retry_after": max(
+                    0, math.ceil(progress["retry_at"] - time.monotonic())
+                )
+                if progress is not None and progress["retry_at"] is not None
+                else None,
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+
+    from tgdrive.replication.replica_api import register_replica_routes
+
+    register_replica_routes(app, settings, require_admin, _runtime)
+    register_routes(
+        app,
+        settings,
+        require_admin=require_admin,
+        is_admin=_is_admin,
+        get_store=_store,
+        get_manager=_transfers,
+        get_runtime=_runtime,
+    )
+    if (WEBSITE_DIR / "dist" / "assets").exists():
+        app.mount(
+            "/assets",
+            StaticFiles(directory=WEBSITE_DIR / "dist" / "assets"),
+            name="assets",
+        )
+    app.mount(
+        "/static",
+        StaticFiles(directory=STATIC_DIR, check_dir=True),
+        name="static",
+    )
+    notices = WEBSITE_DIR / "dist" / "third-party"
+    if not notices.is_dir():
+        notices = WEBSITE_DIR / "public" / "third-party"
+    if notices.is_dir():
+        app.mount(
+            "/third-party",
+            StaticFiles(directory=notices, check_dir=True),
+            name="third-party",
+        )
+    app.add_middleware(
+        UploadGuardMiddleware,
+        sessions=sessions,
+        upload_limit=settings.upload_limit,
+        max_concurrent=settings.max_concurrent_transfers,
+    )
+    from tgdrive.observability.traffic import TrafficCounters, TrafficMiddleware
+
+    app.state.traffic = TrafficCounters()
+    from tgdrive.observability.telemetry_history import TelemetryHistory
+
+    app.state.telemetry_history = TelemetryHistory(settings.resolved_data_dir)
+    app.add_middleware(TrafficMiddleware, counters=app.state.traffic)
+    app.add_middleware(SameOriginMiddleware)
+    app.add_middleware(ApiBodyGuardMiddleware, sessions=sessions)
+    app.add_middleware(SecurityHeadersMiddleware, secure=settings.cookie_secure)
+    return app
diff --git a/tgdrive/web/demo_access.py b/tgdrive/web/demo_access.py
new file mode 100644
index 00000000..fa9dcf77
--- /dev/null
+++ b/tgdrive/web/demo_access.py
@@ -0,0 +1,29 @@
+"""Request permissions from server-verified demo session capabilities."""
+
+from __future__ import annotations
+
+from contextlib import suppress
+
+from fastapi import Request
+
+from tgdrive.core.security import SESSION_COOKIE, InvalidSession
+
+
+def session_access(request: Request) -> dict[str, bool]:
+    demo_mode = bool(request.app.state.settings.demo_mode)
+    token = request.cookies.get(SESSION_COOKIE)
+    claims = None
+    if token:
+        with suppress(InvalidSession):
+            claims = request.app.state.sessions.verify(token)
+    demo_admin = demo_mode and claims is not None and claims.get("demo_admin") is True
+    return {
+        "authenticated": claims is not None,
+        "demo_mode": demo_mode,
+        "demo_admin": demo_admin,
+        "demo_read_only": demo_mode and not demo_admin,
+    }
+
+
+def is_demo_restricted(request: Request) -> bool:
+    return session_access(request)["demo_read_only"]
diff --git a/tgdrive/web/http_guard.py b/tgdrive/web/http_guard.py
new file mode 100644
index 00000000..32c5ef14
--- /dev/null
+++ b/tgdrive/web/http_guard.py
@@ -0,0 +1,382 @@
+"""Authenticate and bound multipart bodies before FastAPI starts parsing them."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from http.cookies import CookieError, SimpleCookie
+from urllib.parse import urlsplit
+
+from starlette.datastructures import MutableHeaders
+from starlette.exceptions import HTTPException
+from starlette.formparsers import MultiPartException
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
+
+from tgdrive.core.security import SESSION_COOKIE, InvalidSession, SessionManager
+
+logger = logging.getLogger(__name__)
+
+
+def _authenticated(scope: Scope, sessions: SessionManager) -> bool:
+    try:
+        cookies: SimpleCookie[str] = SimpleCookie()
+        for key, value in scope.get("headers", []):
+            if key.lower() == b"cookie":
+                cookies.load(value.decode("latin-1"))
+        token = cookies.get(SESSION_COOKIE)
+        if token is None:
+            return False
+        sessions.verify(token.value)
+    except InvalidSession, CookieError, ValueError:
+        return False
+    return True
+
+
+class ApiBodyGuardMiddleware:
+    """Bound JSON requests and authenticate private routes before body decoding."""
+
+    _PUBLIC_POST_PATHS = frozenset(
+        {
+            "/api/checkPassword",
+            "/api/logout",
+            "/api/getDirectory",
+        }
+    )
+
+    def __init__(
+        self, app: ASGIApp, *, sessions: SessionManager, body_limit: int = 65536
+    ) -> None:
+        self.app = app
+        self.sessions = sessions
+        self.body_limit = body_limit
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        path = scope.get("path", "")
+        if (
+            scope["type"] != "http"
+            or not path.startswith("/api/")
+            or path == "/api/upload"
+            or (path.startswith("/api/v1/uploads/") and scope.get("method") == "PATCH")
+            or scope.get("method") not in {"POST", "PUT", "PATCH", "DELETE"}
+        ):
+            await self.app(scope, receive, send)
+            return
+        if path not in self._PUBLIC_POST_PATHS and not _authenticated(
+            scope, self.sessions
+        ):
+            await UploadGuardMiddleware._reject(
+                scope, receive, send, "Not authenticated", 401
+            )
+            return
+        body_limit = self.body_limit
+        if path == "/api/v1/backup/restore" and scope.get("method") == "POST":
+            from tgdrive.recovery.mongo_backup import MAX_EXPANDED
+
+            body_limit = MAX_EXPANDED
+        elif (
+            path == "/api/v1/transfers/history/tasks" and scope.get("method") == "POST"
+        ):
+            body_limit = max(body_limit, 256 * 1024)
+        lengths = [
+            value
+            for key, value in scope.get("headers", [])
+            if key.lower() == b"content-length"
+        ]
+        if lengths:
+            try:
+                parsed = [int(value) for value in lengths]
+                if len(set(parsed)) != 1 or parsed[0] < 0:
+                    raise ValueError("Invalid Content-Length")
+            except ValueError:
+                await UploadGuardMiddleware._reject(
+                    scope, receive, send, "Invalid Content-Length", 400
+                )
+                return
+            if parsed[0] > body_limit:
+                if path == "/api/v1/backup/restore":
+                    logger.warning(
+                        "Database archive restore rejected: request exceeds "
+                        "the 1 GiB limit"
+                    )
+                await UploadGuardMiddleware._reject(
+                    scope, receive, send, "API request body is too large", 413
+                )
+                return
+        count = 0
+        too_large = False
+        rejected = False
+
+        async def limited_receive() -> Message:
+            nonlocal count, too_large
+            message = await receive()
+            if message["type"] == "http.request":
+                count += len(message.get("body", b""))
+                if count > body_limit:
+                    too_large = True
+                    if path == "/api/v1/backup/restore":
+                        logger.warning(
+                            "Database archive restore rejected: upload exceeds "
+                            "the 1 GiB limit"
+                        )
+                    raise HTTPException(413, "API request body is too large")
+            return message
+
+        async def limited_send(message: Message) -> None:
+            nonlocal rejected
+            if too_large:
+                if not rejected:
+                    rejected = True
+                    await UploadGuardMiddleware._reject(
+                        scope, receive, send, "API request body is too large", 413
+                    )
+                return
+            await send(message)
+
+        await self.app(scope, limited_receive, limited_send)
+
+
+class SameOriginMiddleware:
+    """Reject browser-originated mutations from another origin, including subdomains."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    @staticmethod
+    def _matches_origin(raw: bytes, scope: Scope, *, referrer: bool = False) -> bool:
+        headers = scope.get("headers", [])
+        hosts = [value for name, value in headers if name.lower() == b"host"]
+        if len(hosts) != 1:
+            return False
+        try:
+            origin = urlsplit(raw.decode("ascii"))
+            host = urlsplit("//" + hosts[0].decode("ascii"))
+            scheme = scope.get("scheme", "http")
+            default_port = 443 if scheme == "https" else 80
+            return (
+                origin.scheme == scheme
+                and origin.hostname == host.hostname
+                and (origin.port if origin.port is not None else default_port)
+                == (host.port if host.port is not None else default_port)
+                and (referrer or (origin.path in {"", "/"} and not origin.query))
+                and not origin.fragment
+                and origin.username is None
+                and host.username is None
+                and not host.path
+                and not host.query
+                and not host.fragment
+                and host.hostname is not None
+            )
+        except UnicodeError, ValueError:
+            return False
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] == "http"
+            and scope.get("path", "").startswith("/api/")
+            and scope.get("method") in {"POST", "PUT", "PATCH", "DELETE"}
+        ):
+            raw_headers = scope.get("headers", [])
+            headers = dict(raw_headers)
+            origins = [
+                value for name, value in raw_headers if name.lower() == b"origin"
+            ]
+            referrers = [
+                value for name, value in raw_headers if name.lower() == b"referer"
+            ]
+            if origins:
+                same = len(origins) == 1 and self._matches_origin(origins[0], scope)
+            elif headers.get(b"sec-fetch-site") in {b"cross-site", b"same-site"}:
+                # SameSite cookies include sibling subdomains. Without Origin,
+                # Fetch Metadata must not treat those siblings as trusted.
+                same = False
+            elif referrers:
+                same = len(referrers) == 1 and self._matches_origin(
+                    referrers[0], scope, referrer=True
+                )
+            else:
+                # CLI/API clients do not send browser-origin headers.
+                same = True
+            if not same:
+                await UploadGuardMiddleware._reject(
+                    scope, receive, send, "Cross-origin requests are not allowed", 403
+                )
+                return
+        await self.app(scope, receive, send)
+
+
+class UploadGuardMiddleware:
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        sessions: SessionManager,
+        upload_limit: int,
+        max_concurrent: int,
+    ) -> None:
+        self.app = app
+        self.sessions = sessions
+        self.body_limit = upload_limit + 2 * 1024**2
+        self.slots = asyncio.Semaphore(max_concurrent)
+
+    @staticmethod
+    async def _reject(
+        scope: Scope, receive: Receive, send: Send, detail: str, code: int
+    ) -> None:
+        response = JSONResponse(
+            {"status": detail, "detail": detail},
+            status_code=code,
+            headers={
+                "Cache-Control": "no-store",
+                "X-Content-Type-Options": "nosniff",
+                "X-Frame-Options": "DENY",
+            },
+        )
+        await response(scope, receive, send)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] != "http"
+            or scope.get("path") != "/api/upload"
+            or scope.get("method") != "POST"
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        headers = scope.get("headers", [])
+        if not _authenticated(scope, self.sessions):
+            await self._reject(scope, receive, send, "Not authenticated", 401)
+            return
+
+        lengths = [value for key, value in headers if key.lower() == b"content-length"]
+        if lengths:
+            try:
+                parsed = [int(value) for value in lengths]
+                if len(set(parsed)) != 1 or parsed[0] < 0:
+                    raise ValueError("Invalid Content-Length")
+            except ValueError:
+                await self._reject(scope, receive, send, "Invalid Content-Length", 400)
+                return
+            if parsed[0] > self.body_limit:
+                await self._reject(
+                    scope, receive, send, "Upload body is too large", 413
+                )
+                return
+
+        body_bytes = 0
+        too_large = False
+        response_started = False
+        rejected = False
+
+        async def bounded_receive() -> Message:
+            nonlocal body_bytes, too_large
+            message = await receive()
+            if message["type"] == "http.request":
+                body_bytes += len(message.get("body", b""))
+                if body_bytes > self.body_limit:
+                    too_large = True
+                    # Starlette's multipart parser closes all files already
+                    # opened when this exact exception type is raised.
+                    raise MultiPartException("Upload body is too large")
+            return message
+
+        async def guarded_send(message: Message) -> None:
+            nonlocal response_started, rejected
+            if too_large:
+                if not rejected:
+                    rejected = True
+                    await self._reject(
+                        scope, receive, send, "Upload body is too large", 413
+                    )
+                return
+            if message["type"] == "http.response.start":
+                response_started = True
+            await send(message)
+
+        async with self.slots:
+            try:
+                await self.app(scope, bounded_receive, guarded_send)
+            except MultiPartException:
+                if too_large and not response_started and not rejected:
+                    await self._reject(
+                        scope, receive, send, "Upload body is too large", 413
+                    )
+                else:
+                    raise
+
+
+class StreamConcurrencyMiddleware:
+    """Hold a slot until a file response finishes or its client disconnects."""
+
+    def __init__(self, app: ASGIApp, *, max_concurrent: int) -> None:
+        self.app = app
+        self.slots = asyncio.Semaphore(max_concurrent)
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] == "http"
+            and scope.get("path") in {"/file", "/api/v1/preview", "/api/v1/media"}
+            and scope.get("method") in {"GET", "HEAD"}
+        ):
+            async with self.slots:
+                await self.app(scope, receive, send)
+            return
+        await self.app(scope, receive, send)
+
+
+class SecurityHeadersMiddleware:
+    """Set headers directly in ASGI without buffering streaming response bodies."""
+
+    def __init__(self, app: ASGIApp, *, secure: bool) -> None:
+        self.app = app
+        self.secure = secure
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        async def with_headers(message: Message) -> None:
+            if message["type"] == "http.response.start":
+                message["headers"] = [
+                    (name, value)
+                    for name, value in message.get("headers", [])
+                    if name.lower() != b"alt-svc"
+                ]
+                headers = MutableHeaders(scope=message)
+                # Keep the established HTTPS route instead of advertising an
+                # alternative whose UDP path may be unavailable. The deployment
+                # edge must preserve this policy after proxy-generated headers.
+                headers["Alt-Svc"] = "clear"
+                headers.setdefault("X-Content-Type-Options", "nosniff")
+                headers.setdefault("X-Frame-Options", "DENY")
+                headers.setdefault("Referrer-Policy", "no-referrer")
+                headers.setdefault(
+                    "Permissions-Policy",
+                    "camera=(), microphone=(), geolocation=(), payment=(), usb=()",
+                )
+                headers.setdefault(
+                    "Content-Security-Policy",
+                    "default-src 'self'; base-uri 'none'; object-src 'none'; "
+                    "frame-ancestors 'none'; form-action 'self'; "
+                    "script-src 'self' 'wasm-unsafe-eval'; worker-src 'self' blob:; "
+                    "style-src 'self'; style-src-elem 'self'; "
+                    "style-src-attr 'unsafe-inline'; "
+                    "img-src 'self' data: blob:; media-src 'self' blob:; "
+                    # Player frame conversion and local subtitle files use
+                    # in-memory data/blob URLs. No remote origin is permitted.
+                    "connect-src 'self' data: blob:",
+                )
+                if self.secure:
+                    headers.setdefault(
+                        "Strict-Transport-Security",
+                        "max-age=31536000; includeSubDomains",
+                    )
+                path = scope.get("path", "")
+                if path.startswith("/api/"):
+                    headers.setdefault("Cache-Control", "no-store")
+                elif path.startswith("/static/"):
+                    headers.setdefault("Cache-Control", "public, max-age=3600")
+            await send(message)
+
+        await self.app(scope, receive, with_headers)
diff --git a/tgdrive/web/request_ids.py b/tgdrive/web/request_ids.py
new file mode 100644
index 00000000..c1a548b1
--- /dev/null
+++ b/tgdrive/web/request_ids.py
@@ -0,0 +1,117 @@
+"""Bounded idempotency keys and cancellation intents for transfer starts."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from tgdrive.transfers.tasks import TransferRecord
+
+
+class RequestIdConflict(ValueError):
+    pass
+
+
+class RequestIdNotFound(KeyError):
+    pass
+
+
+class RequestIdCancelled(ValueError):
+    pass
+
+
+class RequestCapacityError(RuntimeError):
+    pass
+
+
+@dataclass(slots=True)
+class TransferStart:
+    request_id: str
+    fingerprint: tuple[str, ...] | None = None
+    record: TransferRecord | None = None
+    cancelled: bool = False
+    error: str | None = None
+    updated_at: float = field(default_factory=time.monotonic)
+
+    @property
+    def active(self) -> bool:
+        return self.record is not None and not self.record.terminal
+
+    def snapshot(self) -> dict[str, str | int | None]:
+        if self.record is not None:
+            return self.record.as_dict()
+        status = "cancelled" if self.cancelled else "error" if self.error else "queued"
+        return {
+            "id": "",
+            "status": status,
+            "phase": status if status != "queued" else "accepting",
+            "current": 0,
+            "total": 0,
+            "error": "Transfer cancelled" if self.cancelled else self.error,
+        }
+
+
+class TransferStarts:
+    """Single-event-loop state; active records are never expired or evicted."""
+
+    def __init__(self, *, ttl_seconds: int = 3600, max_entries: int = 1000) -> None:
+        self._ttl = ttl_seconds
+        self._max_entries = max_entries
+        self._entries: dict[str, TransferStart] = {}
+
+    def _prune(self) -> None:
+        deadline = time.monotonic() - self._ttl
+        for key, entry in list(self._entries.items()):
+            updated = entry.record.updated_at if entry.record else entry.updated_at
+            if not entry.active and updated <= deadline:
+                del self._entries[key]
+
+    def _new(self, request_id: str) -> TransferStart:
+        self._prune()
+        if len(self._entries) >= self._max_entries:
+            raise RequestCapacityError("Too many transfer requests; try again later")
+        entry = TransferStart(request_id)
+        self._entries[request_id] = entry
+        return entry
+
+    def claim(
+        self, request_id: str, fingerprint: tuple[str, ...]
+    ) -> tuple[TransferStart, bool]:
+        self._prune()
+        entry = self._entries.get(request_id)
+        created = entry is None
+        if entry is None:
+            entry = self._new(request_id)
+        if entry.cancelled:
+            raise RequestIdCancelled("Transfer cancelled")
+        if entry.fingerprint is not None and entry.fingerprint != fingerprint:
+            raise RequestIdConflict(
+                "Request ID was already used for a different upload"
+            )
+        entry.fingerprint = fingerprint
+        return entry, created
+
+    def bind(self, entry: TransferStart, record: TransferRecord) -> bool:
+        entry.record = record
+        entry.updated_at = time.monotonic()
+        return entry.cancelled
+
+    def fail(self, entry: TransferStart, detail: str) -> None:
+        entry.error = detail[:500]
+        entry.updated_at = time.monotonic()
+
+    def get(self, request_id: str) -> TransferStart:
+        self._prune()
+        try:
+            return self._entries[request_id]
+        except KeyError as exc:
+            raise RequestIdNotFound(request_id) from exc
+
+    def cancel(self, request_id: str) -> TransferStart:
+        self._prune()
+        entry = self._entries.get(request_id) or self._new(request_id)
+        if entry.record is not None and entry.record.terminal:
+            return entry
+        entry.cancelled = True
+        entry.updated_at = time.monotonic()
+        return entry
diff --git a/tgdrive/web/schemas.py b/tgdrive/web/schemas.py
new file mode 100644
index 00000000..5f1797e5
--- /dev/null
+++ b/tgdrive/web/schemas.py
@@ -0,0 +1,118 @@
+"""Validated payloads for owner requests, folder uploads, and transfer history."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, HttpUrl, model_validator
+
+
+class RequestModel(BaseModel):
+    model_config = ConfigDict(extra="ignore", str_strip_whitespace=True)
+
+
+class LoginRequest(RequestModel):
+    # Passwords hashed by the owner CLI may intentionally include whitespace.
+    model_config = ConfigDict(str_strip_whitespace=False)
+    password: str = Field(alias="pass", min_length=1, max_length=512)
+
+
+class DirectoryRequest(RequestModel):
+    path: str = Field(min_length=1, max_length=4096)
+    auth: str | None = Field(default=None, max_length=512)
+
+
+class FolderCreateRequest(RequestModel):
+    path: str = Field(min_length=1, max_length=4096)
+    name: str = Field(min_length=1, max_length=255)
+
+
+class ItemPathRequest(RequestModel):
+    path: str = Field(min_length=1, max_length=4096)
+
+
+class RenameRequest(ItemPathRequest):
+    name: str = Field(min_length=1, max_length=255)
+
+
+class TrashRequest(ItemPathRequest):
+    trash: bool
+
+
+class TransferRequest(RequestModel):
+    id: str = Field(min_length=8, max_length=128)
+
+
+class TransferLookupRequest(RequestModel):
+    client_request_id: str = Field(
+        min_length=16, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+    )
+
+
+class TransferCancelRequest(RequestModel):
+    id: str | None = Field(default=None, min_length=8, max_length=128)
+    client_request_id: str | None = Field(
+        default=None, min_length=16, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+    )
+
+    @model_validator(mode="after")
+    def require_identifier(self) -> TransferCancelRequest:
+        if (self.id is None) == (self.client_request_id is None):
+            raise ValueError("Provide either id or client_request_id")
+        return self
+
+
+class RemoteInspectRequest(RequestModel):
+    url: HttpUrl
+
+
+class RemoteStartRequest(RemoteInspectRequest):
+    path: str = Field(min_length=1, max_length=4096)
+    filename: str | None = Field(default=None, max_length=255)
+    single_threaded: bool = Field(default=False, alias="singleThreaded")
+    client_request_id: str | None = Field(
+        default=None, min_length=16, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+    )
+
+
+class FolderTreeRequest(BaseModel):
+    """Folder names are validated verbatim; whitespace must not be silently stripped."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+    destination: str = Field(min_length=1, max_length=4096)
+    root_name: str = Field(min_length=1, max_length=255)
+    folders: list[Annotated[list[str], Field(min_length=1, max_length=63)]] = Field(
+        max_length=999
+    )
+    client_request_id: str = Field(
+        min_length=16, max_length=128, pattern=r"^[A-Za-z0-9_-]+$"
+    )
+
+
+class FolderUploadMetadata(BaseModel):
+    """Stable identity for one explicitly selected device folder upload."""
+
+    model_config = ConfigDict(extra="forbid", strict=True)
+    id: str = Field(min_length=16, max_length=128, pattern=r"^[A-Za-z0-9_-]+$")
+    name: str = Field(min_length=1, max_length=255)
+    root_path: str = Field(min_length=2, max_length=4096, pattern=r"^/")
+    created_at: float = Field(ge=0, allow_inf_nan=False)
+
+
+TransferIdentity = Annotated[
+    str, Field(min_length=1, max_length=128, pattern=r"^[A-Za-z0-9_-]+$")
+]
+
+
+class TransferTaskHistoryRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    status: Literal[
+        "all", "finished", "queued", "running", "completed", "error", "cancelled"
+    ] = "all"
+    page: int = Field(default=1, ge=1)
+    limit: int = Field(default=20, ge=1, le=200)
+    q: str = Field(default="", max_length=255)
+    offset: int | None = Field(default=None, ge=0)
+    exclude_folders: list[TransferIdentity] = Field(
+        default_factory=list, max_length=2000
+    )
diff --git a/tgdrive/web/share_links.py b/tgdrive/web/share_links.py
new file mode 100644
index 00000000..e826bdd4
--- /dev/null
+++ b/tgdrive/web/share_links.py
@@ -0,0 +1,21 @@
+"""Re-copyable share capabilities derived from the persistent owner secret.
+
+Only hashes enter the catalog. Domain separation keeps this capability distinct
+from login sessions. Re-copying a link requires the original persistent secret.
+"""
+
+import base64
+import hashlib
+import hmac
+
+
+def token_factory(settings):
+    key = settings.session_secret.get_secret_value().encode()
+
+    def derive(identity):
+        digest = hmac.new(
+            key, b"tgdrive/share-link/v1\0" + identity.encode(), hashlib.sha256
+        ).digest()
+        return base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+
+    return derive
diff --git a/utils/bot_mode.py b/utils/bot_mode.py
deleted file mode 100644
index ddb09479..00000000
--- a/utils/bot_mode.py
+++ /dev/null
@@ -1,197 +0,0 @@
-import asyncio
-from pyrogram import Client, filters
-from pyrogram.types import Message, InlineKeyboardMarkup, InlineKeyboardButton
-import config
-from utils.logger import Logger
-from pathlib import Path
-
-logger = Logger(__name__)
-
-START_CMD = """🚀 **Welcome To TG Drive's Bot Mode**
-
-You can use this bot to upload files to your TG Drive website directly instead of doing it from website.
-
-🗄 **Commands:**
-/set_folder - Set folder for file uploads
-/current_folder - Check current folder
-
-📤 **How To Upload Files:** Send a file to this bot and it will be uploaded to your TG Drive website. You can also set a folder for file uploads using /set_folder command.
-
-Read more about [TG Drive's Bot Mode](https://github.com/TechShreyash/TGDrive#tg-drives-bot-mode)
-"""
-
-SET_FOLDER_PATH_CACHE = {}  # Cache to store folder path for each folder id
-DRIVE_DATA = None
-BOT_MODE = None
-
-session_cache_path = Path(f"./cache")
-session_cache_path.parent.mkdir(parents=True, exist_ok=True)
-
-main_bot = Client(
-    name="main_bot",
-    api_id=config.API_ID,
-    api_hash=config.API_HASH,
-    bot_token=config.MAIN_BOT_TOKEN,
-    sleep_threshold=config.SLEEP_THRESHOLD,
-    workdir=session_cache_path,
-)
-
-
-@main_bot.on_message(
-    filters.command(["start", "help"])
-    & filters.private
-    & filters.user(config.TELEGRAM_ADMIN_IDS),
-)
-async def start_handler(client: Client, message: Message):
-    await message.reply_text(START_CMD)
-
-
-@main_bot.on_message(
-    filters.command("set_folder")
-    & filters.private
-    & filters.user(config.TELEGRAM_ADMIN_IDS),
-)
-async def set_folder_handler(client: Client, message: Message):
-    global SET_FOLDER_PATH_CACHE, DRIVE_DATA
-
-    while True:
-        try:
-            folder_name = await message.ask(
-                "Send the folder name where you want to upload files\n\n/cancel to cancel",
-                timeout=60,
-                filters=filters.text,
-            )
-        except asyncio.TimeoutError:
-            await message.reply_text("Timeout\n\nUse /set_folder to set folder again")
-            return
-
-        if folder_name.text.lower() == "/cancel":
-            await message.reply_text("Cancelled")
-            return
-
-        folder_name = folder_name.text.strip()
-        search_result = DRIVE_DATA.search_file_folder(folder_name)
-
-        # Get folders from search result
-        folders = {}
-        for item in search_result.values():
-            if item.type == "folder":
-                folders[item.id] = item
-
-        if len(folders) == 0:
-            await message.reply_text(f"No Folder found with name {folder_name}")
-        else:
-            break
-
-    buttons = []
-    folder_cache = {}
-    folder_cache_id = len(SET_FOLDER_PATH_CACHE) + 1
-
-    for folder in search_result.values():
-        path = folder.path.strip("/")
-        folder_path = "/" + ("/" + path + "/" + folder.id).strip("/")
-        folder_cache[folder.id] = (folder_path, folder.name)
-        buttons.append(
-            [
-                InlineKeyboardButton(
-                    folder.name,
-                    callback_data=f"set_folder_{folder_cache_id}_{folder.id}",
-                )
-            ]
-        )
-    SET_FOLDER_PATH_CACHE[folder_cache_id] = folder_cache
-
-    await message.reply_text(
-        "Select the folder where you want to upload files",
-        reply_markup=InlineKeyboardMarkup(buttons),
-    )
-
-
-@main_bot.on_callback_query(
-    filters.user(config.TELEGRAM_ADMIN_IDS) & filters.regex(r"set_folder_")
-)
-async def set_folder_callback(client: Client, callback_query: Message):
-    global SET_FOLDER_PATH_CACHE, BOT_MODE
-
-    folder_cache_id, folder_id = callback_query.data.split("_")[2:]
-
-    folder_path_cache = SET_FOLDER_PATH_CACHE.get(int(folder_cache_id))
-    if folder_path_cache is None:
-        await callback_query.answer("Request Expired, Send /set_folder again")
-        await callback_query.message.delete()
-        return
-
-    folder_path, name = folder_path_cache.get(folder_id)
-    del SET_FOLDER_PATH_CACHE[int(folder_cache_id)]
-    BOT_MODE.set_folder(folder_path, name)
-
-    await callback_query.answer(f"Folder Set Successfully To : {name}")
-    await callback_query.message.edit(
-        f"Folder Set Successfully To : {name}\n\nNow you can send / forward files to me and it will be uploaded to this folder."
-    )
-
-
-@main_bot.on_message(
-    filters.command("current_folder")
-    & filters.private
-    & filters.user(config.TELEGRAM_ADMIN_IDS),
-)
-async def current_folder_handler(client: Client, message: Message):
-    global BOT_MODE
-
-    await message.reply_text(f"Current Folder: {BOT_MODE.current_folder_name}")
-
-
-# Handling when any file is sent to the bot
-@main_bot.on_message(
-    filters.private
-    & filters.user(config.TELEGRAM_ADMIN_IDS)
-    & (
-        filters.document
-        | filters.video
-        | filters.audio
-        | filters.photo
-        | filters.sticker
-    )
-)
-async def file_handler(client: Client, message: Message):
-    global BOT_MODE, DRIVE_DATA
-
-    copied_message = await message.copy(config.STORAGE_CHANNEL)
-    file = (
-        copied_message.document
-        or copied_message.video
-        or copied_message.audio
-        or copied_message.photo
-        or copied_message.sticker
-    )
-
-    DRIVE_DATA.new_file(
-        BOT_MODE.current_folder,
-        file.file_name,
-        copied_message.id,
-        file.file_size,
-    )
-
-    await message.reply_text(
-        f"""✅ File Uploaded Successfully To Your TG Drive Website
-                             
-**File Name:** {file.file_name}
-**Folder:** {BOT_MODE.current_folder_name}
-"""
-    )
-
-
-async def start_bot_mode(d, b):
-    global DRIVE_DATA, BOT_MODE
-    DRIVE_DATA = d
-    BOT_MODE = b
-
-    logger.info("Starting Main Bot")
-    await main_bot.start()
-
-    await main_bot.send_message(
-        config.STORAGE_CHANNEL, "Main Bot Started -> TG Drive's Bot Mode Enabled"
-    )
-    logger.info("Main Bot Started")
-    logger.info("TG Drive's Bot Mode Enabled")
diff --git a/utils/clients.py b/utils/clients.py
deleted file mode 100644
index 618979db..00000000
--- a/utils/clients.py
+++ /dev/null
@@ -1,113 +0,0 @@
-import asyncio, config
-from pathlib import Path
-from pyrogram import Client
-from utils.directoryHandler import backup_drive_data, loadDriveData
-from utils.logger import Logger
-import os
-import signal
-
-logger = Logger(__name__)
-
-multi_clients = {}
-premium_clients = {}
-work_loads = {}
-premium_work_loads = {}
-main_bot = None
-
-
-async def initialize_clients():
-    global multi_clients, work_loads, premium_clients, premium_work_loads
-    logger.info("Initializing Clients")
-
-    session_cache_path = Path(f"./cache")
-    session_cache_path.parent.mkdir(parents=True, exist_ok=True)
-
-    all_tokens = dict((i, t) for i, t in enumerate(config.BOT_TOKENS, start=1))
-    all_sessions = dict(
-        (i, s) for i, s in enumerate(config.STRING_SESSIONS, start=len(all_tokens) + 1)
-    )
-
-    async def start_client(client_id, token, type):
-        try:
-            logger.info(f"Starting - {type.title()} Client {client_id}")
-
-            if type == "bot":
-                client = Client(
-                    name=str(client_id),
-                    api_id=config.API_ID,
-                    api_hash=config.API_HASH,
-                    bot_token=token,
-                    workdir=session_cache_path,
-                )
-                client.loop = asyncio.get_running_loop()
-                await client.start()
-                await client.send_message(
-                    config.STORAGE_CHANNEL,
-                    f"Started - {type.title()} Client {client_id}",
-                )
-                multi_clients[client_id] = client
-                work_loads[client_id] = 0
-            elif type == "user":
-                client = await Client(
-                    name=str(client_id),
-                    api_id=config.API_ID,
-                    api_hash=config.API_HASH,
-                    session_string=token,
-                    sleep_threshold=config.SLEEP_THRESHOLD,
-                    workdir=session_cache_path,
-                    no_updates=True,
-                ).start()
-                await client.send_message(
-                    config.STORAGE_CHANNEL,
-                    f"Started - {type.title()} Client {client_id}",
-                )
-                premium_clients[client_id] = client
-                premium_work_loads[client_id] = 0
-
-            logger.info(f"Started - {type.title()} Client {client_id}")
-        except Exception as e:
-            logger.error(
-                f"Failed To Start {type.title()} Client - {client_id} Error: {e}"
-            )
-
-    await asyncio.gather(
-        *(
-            [
-                start_client(client_id, client, "bot")
-                for client_id, client in all_tokens.items()
-            ]
-            + [
-                start_client(client_id, client, "user")
-                for client_id, client in all_sessions.items()
-            ]
-        )
-    )
-    if len(multi_clients) == 0:
-        logger.error("No Clients Were Initialized")
-
-        # Forcefully terminates the program immediately
-        os.kill(os.getpid(), signal.SIGKILL)
-
-    if len(premium_clients) == 0:
-        logger.info("No Premium Clients Were Initialized")
-
-    logger.info("Clients Initialized")
-
-    # Load the drive data
-    await loadDriveData()
-
-    # Start the backup drive data task
-    asyncio.create_task(backup_drive_data())
-
-
-def get_client(premium_required=False) -> Client:
-    global multi_clients, work_loads, premium_clients, premium_work_loads
-
-    if premium_required:
-        index = min(premium_work_loads, key=premium_work_loads.get)
-        premium_work_loads[index] += 1
-        return premium_clients[index]
-
-    index = min(work_loads, key=work_loads.get)
-    work_loads[index] += 1
-    return multi_clients[index]
diff --git a/utils/directoryHandler.py b/utils/directoryHandler.py
deleted file mode 100644
index ac9e9fc5..00000000
--- a/utils/directoryHandler.py
+++ /dev/null
@@ -1,387 +0,0 @@
-from pathlib import Path
-import sys
-import config, dill
-from pyrogram.types import InputMediaDocument, Message
-import os, random, string, asyncio
-from utils.logger import Logger
-from datetime import datetime, timezone
-import os
-import signal
-
-logger = Logger(__name__)
-
-cache_dir = Path("./cache")
-cache_dir.mkdir(parents=True, exist_ok=True)
-drive_cache_path = cache_dir / "drive.data"
-
-
-def getRandomID():
-    global DRIVE_DATA
-    while True:
-        id = "".join(random.choices(string.ascii_uppercase + string.digits, k=6))
-        if not DRIVE_DATA:
-            return id
-        if id not in DRIVE_DATA.used_ids:
-            DRIVE_DATA.used_ids.append(id)
-            return id
-
-
-def get_current_utc_time():
-    return datetime.now(timezone.utc).strftime("Date - %Y-%m-%d | Time - %H:%M:%S")
-
-
-class Folder:
-    def __init__(self, name: str, path: str) -> None:
-        self.name = name
-        self.contents = {}
-        if name == "/":
-            self.id = "root"
-        else:
-            self.id = getRandomID()
-        self.type = "folder"
-        self.trash = False
-        self.path = ("/" + path.strip("/") + "/").replace("//", "/")
-        self.upload_date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-        self.auth_hashes = []
-
-
-class File:
-    def __init__(
-        self,
-        name: str,
-        file_id: int,
-        size: int,
-        path: str,
-    ) -> None:
-        self.name = name
-        self.file_id = file_id
-        self.id = getRandomID()
-        self.size = size
-        self.type = "file"
-        self.trash = False
-        self.path = path[:-1] if path[-1] == "/" else path
-        self.upload_date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
-
-class NewDriveData:
-    def __init__(self, contents: dict, used_ids: list) -> None:
-        self.contents = contents
-        self.used_ids = used_ids
-        self.isUpdated = False
-
-    def save(self) -> None:
-        with open(drive_cache_path, "wb") as f:
-            dill.dump(self, f)
-        self.isUpdated = True
-        logger.info("Drive data saved successfully.")
-
-    def new_folder(self, path: str, name: str) -> None:
-        logger.info(f"Creating new folder '{name}' in path '{path}'.")
-
-        folder = Folder(name, path)
-        if path == "/":
-            directory_folder: Folder = self.contents[path]
-            directory_folder.contents[folder.id] = folder
-        else:
-            paths = path.strip("/").split("/")
-            directory_folder: Folder = self.contents["/"]
-            for path in paths:
-                directory_folder = directory_folder.contents[path]
-            directory_folder.contents[folder.id] = folder
-
-        self.save()
-        return folder.path + folder.id
-
-    def new_file(self, path: str, name: str, file_id: int, size: int) -> None:
-        logger.info(f"Creating new file '{name}' in path '{path}'.")
-
-        file = File(name, file_id, size, path)
-        if path == "/":
-            directory_folder: Folder = self.contents[path]
-            directory_folder.contents[file.id] = file
-        else:
-            paths = path.strip("/").split("/")
-            directory_folder: Folder = self.contents["/"]
-            for path in paths:
-                directory_folder = directory_folder.contents[path]
-            directory_folder.contents[file.id] = file
-
-        self.save()
-
-    def get_directory(
-        self, path: str, is_admin: bool = True, auth: str = None
-    ) -> Folder:
-        folder_data: Folder = self.contents["/"]
-        auth_success = False
-        auth_home_path = None
-
-        if path != "/":
-            path = path.strip("/")
-
-            if "/" in path:
-                path = path.split("/")
-            else:
-                path = [path]
-
-            for folder in path:
-                folder_data = folder_data.contents[folder]
-
-                if auth in folder_data.auth_hashes:
-                    auth_success = True
-                    auth_home_path = (
-                        "/" + folder_data.path.strip("/") + "/" + folder_data.id
-                    )
-
-        if not is_admin and not auth_success:
-            logger.warning(f"Unauthorized access attempt to path '{path}'.")
-            return None
-
-        if auth_success:
-            logger.info(f"Authorization successful for path '{path}'.")
-            return folder_data, auth_home_path
-
-        return folder_data
-
-    def get_folder_auth(self, path: str) -> None:
-        auth = getRandomID()
-        folder_data: Folder = self.contents["/"]
-
-        if path != "/":
-            path = path.strip("/")
-
-            if "/" in path:
-                path = path.split("/")
-            else:
-                path = [path]
-
-            for folder in path:
-                folder_data = folder_data.contents[folder]
-
-        folder_data.auth_hashes.append(auth)
-        self.save()
-        logger.info(f"Authorization hash generated for path '{path}'.")
-        return auth
-
-    def get_file(self, path) -> File:
-        if len(path.strip("/").split("/")) > 0:
-            folder_path = "/" + "/".join(path.strip("/").split("/")[:-1])
-            file_id = path.strip("/").split("/")[-1]
-        else:
-            folder_path = "/"
-            file_id = path.strip("/")
-
-        folder_data = self.get_directory(folder_path)
-        return folder_data.contents[file_id]
-
-    def rename_file_folder(self, path: str, new_name: str) -> None:
-        if len(path.strip("/").split("/")) > 0:
-            folder_path = "/" + "/".join(path.strip("/").split("/")[:-1])
-            file_id = path.strip("/").split("/")[-1]
-        else:
-            folder_path = "/"
-            file_id = path.strip("/")
-        folder_data = self.get_directory(folder_path)
-        folder_data.contents[file_id].name = new_name
-        self.save()
-        logger.info(f"Item at path '{path}' renamed to '{new_name}'.")
-
-    def trash_file_folder(self, path: str, trash: bool) -> None:
-        action = "Trashing" if trash else "Restoring"
-
-        if len(path.strip("/").split("/")) > 0:
-            folder_path = "/" + "/".join(path.strip("/").split("/")[:-1])
-            file_id = path.strip("/").split("/")[-1]
-        else:
-            folder_path = "/"
-            file_id = path.strip("/")
-        folder_data = self.get_directory(folder_path)
-        folder_data.contents[file_id].trash = trash
-        self.save()
-        logger.info(f"Item at path '{path}' {action.lower()} successfully.")
-
-    def get_trashed_files_folders(self):
-        root_dir = self.get_directory("/")
-        trash_data = {}
-
-        def traverse_directory(folder):
-            for item in folder.contents.values():
-                if item.type == "folder":
-                    if item.trash:
-                        trash_data[item.id] = item
-                    else:
-                        # Recursively traverse the subfolder
-                        traverse_directory(item)
-                elif item.type == "file":
-                    if item.trash:
-                        trash_data[item.id] = item
-
-        traverse_directory(root_dir)
-        return trash_data
-
-    def delete_file_folder(self, path: str) -> None:
-
-        if len(path.strip("/").split("/")) > 0:
-            folder_path = "/" + "/".join(path.strip("/").split("/")[:-1])
-            file_id = path.strip("/").split("/")[-1]
-        else:
-            folder_path = "/"
-            file_id = path.strip("/")
-
-        folder_data = self.get_directory(folder_path)
-        del folder_data.contents[file_id]
-        self.save()
-        logger.info(f"Item at path '{path}' deleted successfully.")
-
-    def search_file_folder(self, query: str):
-        logger.info(f"Searching for items matching query '{query}'.")
-
-        root_dir = self.get_directory("/")
-        search_results = {}
-
-        def traverse_directory(folder):
-            for item in folder.contents.values():
-                if query.lower() in item.name.lower():
-                    search_results[item.id] = item
-                if item.type == "folder":
-                    traverse_directory(item)
-
-        traverse_directory(root_dir)
-        logger.info(f"Search completed. Found {len(search_results)} matching items.")
-        return search_results
-
-
-class NewBotMode:
-    def __init__(self, drive_data: NewDriveData) -> None:
-        self.drive_data = drive_data
-
-        # Set the current folder to root directory by default
-        self.current_folder = "/"
-        self.current_folder_name = "/ (root directory)"
-
-    def set_folder(self, folder_path: str, name: str) -> None:
-        self.current_folder = folder_path
-        self.current_folder_name = name
-        self.drive_data.save()
-        logger.info(f"Current folder set to '{name}' at path '{folder_path}'.")
-
-
-DRIVE_DATA: NewDriveData = None
-BOT_MODE: NewBotMode = None
-
-
-# Function to backup the drive data to telegram
-async def backup_drive_data(loop=True):
-    global DRIVE_DATA
-    logger.info("Starting backup drive data task.")
-
-    while True:
-        try:
-            if not DRIVE_DATA.isUpdated:
-                if not loop:
-                    break
-                await asyncio.sleep(config.DATABASE_BACKUP_TIME)
-                continue
-
-            logger.info("Backing up drive data to Telegram.")
-            from utils.clients import get_client
-
-            client = get_client()
-            time_text = f"📅 **Last Updated :** {get_current_utc_time()} (UTC +00:00)"
-            caption = (
-                f"🔐 **TG Drive Data Backup File**\n\n"
-                "Do not edit or delete this message. This is a backup file for the tg drive data.\n\n"
-                f"{time_text}"
-            )
-
-            media_doc = InputMediaDocument(drive_cache_path, caption=caption)
-            msg = await client.edit_message_media(
-                config.STORAGE_CHANNEL,
-                config.DATABASE_BACKUP_MSG_ID,
-                media=media_doc,
-                file_name="drive.data",
-            )
-
-            DRIVE_DATA.isUpdated = False
-            logger.info("Drive data backed up to Telegram successfully.")
-
-            try:
-                await msg.pin()
-            except Exception as pin_e:
-                logger.error(f"Error pinning backup message: {pin_e}")
-
-            if not loop:
-                break
-
-            await asyncio.sleep(config.DATABASE_BACKUP_TIME)
-        except Exception as e:
-            logger.error(f"Backup Error: {e}")
-            await asyncio.sleep(10)
-
-
-async def init_drive_data():
-    global DRIVE_DATA
-
-    logger.info("Initializing drive data.")
-    root_dir = DRIVE_DATA.get_directory("/")
-    if not hasattr(root_dir, "auth_hashes"):
-        root_dir.auth_hashes = []
-
-    def traverse_directory(folder):
-        for item in folder.contents.values():
-            if item.type == "folder":
-                traverse_directory(item)
-
-                if not hasattr(item, "auth_hashes"):
-                    item.auth_hashes = []
-
-    traverse_directory(root_dir)
-    DRIVE_DATA.save()
-    logger.info("Drive data initialization completed.")
-
-
-async def loadDriveData():
-    global DRIVE_DATA, BOT_MODE
-
-    logger.info("Loading drive data.")
-    from utils.clients import get_client
-
-    client = get_client()
-    try:
-        try:
-            msg: Message = await client.get_messages(
-                config.STORAGE_CHANNEL, config.DATABASE_BACKUP_MSG_ID
-            )
-        except Exception as e:
-            logger.error(f"Error fetching backup message: {e}")
-
-            # Forcefully terminates the program immediately
-            os.kill(os.getpid(), signal.SIGKILL)
-
-        if not msg.document:
-            logger.error(f"Error fetching backup message: {e}")
-
-            # Forcefully terminates the program immediately
-            os.kill(os.getpid(), signal.SIGKILL)
-
-        if msg.document.file_name == "drive.data":
-            dl_path = await msg.download()
-            with open(dl_path, "rb") as f:
-                DRIVE_DATA = dill.load(f)
-
-            logger.info("Drive data loaded from Telegram backup.")
-        else:
-            raise Exception("Backup drive.data file not found on Telegram.")
-    except Exception as e:
-        logger.warning(f"Backup load failed: {e}")
-        logger.info("Creating new drive.data file.")
-        DRIVE_DATA = NewDriveData({"/": Folder("/", "/")}, [])
-        DRIVE_DATA.save()
-
-    await init_drive_data()
-
-    if config.MAIN_BOT_TOKEN:
-        from utils.bot_mode import start_bot_mode
-
-        BOT_MODE = NewBotMode(DRIVE_DATA)
-        await start_bot_mode(DRIVE_DATA, BOT_MODE)
-        logger.info("Bot mode started.")
diff --git a/utils/downloader.py b/utils/downloader.py
deleted file mode 100644
index 2b268868..00000000
--- a/utils/downloader.py
+++ /dev/null
@@ -1,85 +0,0 @@
-import os
-import aiohttp, asyncio
-from utils.extra import get_filename
-from utils.logger import Logger
-from pathlib import Path
-from utils.uploader import start_file_uploader
-from techzdl import TechZDL
-
-logger = Logger(__name__)
-
-DOWNLOAD_PROGRESS = {}
-STOP_DOWNLOAD = []
-
-cache_dir = Path("./cache")
-cache_dir.mkdir(parents=True, exist_ok=True)
-
-
-async def download_progress_callback(status, current, total, id):
-    global DOWNLOAD_PROGRESS
-
-    DOWNLOAD_PROGRESS[id] = (
-        status,
-        current,
-        total,
-    )
-
-
-async def download_file(url, id, path, filename, singleThreaded):
-    global DOWNLOAD_PROGRESS, STOP_DOWNLOAD
-
-    logger.info(f"Downloading file from {url}")
-
-    try:
-        downloader = TechZDL(
-            url,
-            output_dir=cache_dir,
-            debug=False,
-            progress_callback=download_progress_callback,
-            progress_args=(id,),
-            max_retries=5,
-            single_threaded=singleThreaded,
-        )
-        await downloader.start(in_background=True)
-
-        await asyncio.sleep(5)
-
-        while downloader.is_running:
-            if id in STOP_DOWNLOAD:
-                logger.info(f"Stopping download {id}")
-                await downloader.stop()
-                return
-            await asyncio.sleep(1)
-
-        if downloader.download_success is False:
-            raise downloader.download_error
-
-        DOWNLOAD_PROGRESS[id] = (
-            "completed",
-            downloader.total_size,
-            downloader.total_size,
-        )
-
-        logger.info(f"File downloaded to {downloader.output_path}")
-
-        asyncio.create_task(
-            start_file_uploader(
-                downloader.output_path, id, path, filename, downloader.total_size
-            )
-        )
-    except Exception as e:
-        DOWNLOAD_PROGRESS[id] = ("error", 0, 0)
-        logger.error(f"Failed to download file: {url} {e}")
-
-
-async def get_file_info_from_url(url):
-    downloader = TechZDL(
-        url,
-        output_dir=cache_dir,
-        debug=False,
-        progress_callback=download_progress_callback,
-        progress_args=(id,),
-        max_retries=5,
-    )
-    file_info = await downloader.get_file_info()
-    return {"file_size": file_info["total_size"], "file_name": file_info["filename"]}
diff --git a/utils/extra.py b/utils/extra.py
deleted file mode 100644
index b3585a7c..00000000
--- a/utils/extra.py
+++ /dev/null
@@ -1,124 +0,0 @@
-import mimetypes
-from urllib.parse import unquote_plus
-import re
-import urllib.parse
-from pathlib import Path
-from config import WEBSITE_URL
-import asyncio, aiohttp
-from utils.directoryHandler import get_current_utc_time, getRandomID
-from utils.logger import Logger
-
-logger = Logger(__name__)
-
-
-def convert_class_to_dict(data, isObject, showtrash=False):
-    if isObject == True:
-        data = data.__dict__.copy()
-    new_data = {"contents": {}}
-
-    for key in data["contents"]:
-        if data["contents"][key].trash == showtrash:
-            if data["contents"][key].type == "folder":
-                folder = data["contents"][key]
-                new_data["contents"][key] = {
-                    "name": folder.name,
-                    "type": folder.type,
-                    "id": folder.id,
-                    "path": folder.path,
-                    "upload_date": folder.upload_date,
-                }
-            else:
-                file = data["contents"][key]
-                new_data["contents"][key] = {
-                    "name": file.name,
-                    "type": file.type,
-                    "size": file.size,
-                    "id": file.id,
-                    "path": file.path,
-                    "upload_date": file.upload_date,
-                }
-    return new_data
-
-
-async def auto_ping_website():
-    if WEBSITE_URL is not None:
-        async with aiohttp.ClientSession() as session:
-            while True:
-                try:
-                    async with session.get(WEBSITE_URL) as response:
-                        if response.status == 200:
-                            logger.info(f"Pinged website at {get_current_utc_time()}")
-                        else:
-                            logger.warning(f"Failed to ping website: {response.status}")
-                except Exception as e:
-                    logger.warning(f"Failed to ping website: {e}")
-
-                await asyncio.sleep(60)  # Ping website every minute
-
-
-import shutil
-
-
-def reset_cache_dir():
-    cache_dir = Path("./cache")
-    downloads_dir = Path("./downloads")
-    shutil.rmtree(cache_dir, ignore_errors=True)
-    shutil.rmtree(downloads_dir, ignore_errors=True)
-    cache_dir.mkdir(parents=True, exist_ok=True)
-    downloads_dir.mkdir(parents=True, exist_ok=True)
-    logger.info("Cache and downloads directory reset")
-
-
-def parse_content_disposition(content_disposition):
-    # Split the content disposition into parts
-    parts = content_disposition.split(";")
-
-    # Initialize filename variable
-    filename = None
-
-    # Loop through parts to find the filename
-    for part in parts:
-        part = part.strip()
-        if part.startswith("filename="):
-            # If filename is found
-            filename = part.split("=", 1)[1]
-        elif part.startswith("filename*="):
-            # If filename* is found
-            match = re.match(r"filename\*=(\S*)''(.*)", part)
-            if match:
-                encoding, value = match.groups()
-                try:
-                    filename = urllib.parse.unquote(value, encoding=encoding)
-                except ValueError:
-                    # Handle invalid encoding
-                    pass
-
-    if filename is None:
-        raise Exception("Failed to get filename")
-    return filename
-
-
-def get_filename(headers, url):
-    try:
-        if headers.get("Content-Disposition"):
-            filename = parse_content_disposition(headers["Content-Disposition"])
-        else:
-            filename = unquote_plus(url.strip("/").split("/")[-1])
-
-        filename = filename.strip(' "')
-    except:
-        filename = unquote_plus(url.strip("/").split("/")[-1])
-
-    filename = filename.strip()
-
-    if filename == "" or "." not in filename:
-        if headers.get("Content-Type"):
-            extension = mimetypes.guess_extension(headers["Content-Type"])
-            if extension:
-                filename = f"{getRandomID()}{extension}"
-            else:
-                filename = getRandomID()
-        else:
-            filename = getRandomID()
-
-    return filename
diff --git a/utils/logger.py b/utils/logger.py
deleted file mode 100644
index 9e37ad8a..00000000
--- a/utils/logger.py
+++ /dev/null
@@ -1,48 +0,0 @@
-import logging
-from tqdm import tqdm
-
-
-class TqdmLoggingHandler(logging.Handler):
-    def emit(self, record):
-        try:
-            msg = self.format(record)
-            tqdm.write(msg)
-            self.flush()
-        except Exception:
-            self.handleError(record)
-
-
-class Logger:
-    def __init__(self, name, level=logging.DEBUG):
-        self.logger = logging.getLogger(name)
-        self.logger.setLevel(level)
-        self.formatter = logging.Formatter("%(name)s - %(levelname)s - %(message)s")
-
-        # Remove existing handlers to prevent duplicate logs
-        if self.logger.hasHandlers():
-            self.logger.handlers.clear()
-
-        # FileHandler for logging to a file
-        file_handler = logging.FileHandler("logs.txt", mode="w")
-        file_handler.setFormatter(self.formatter)
-        self.logger.addHandler(file_handler)
-
-        # Custom TqdmLoggingHandler for console output
-        stream_handler = TqdmLoggingHandler()
-        stream_handler.setFormatter(self.formatter)
-        self.logger.addHandler(stream_handler)
-
-    def debug(self, message):
-        self.logger.debug(message)
-
-    def info(self, message):
-        self.logger.info(message)
-
-    def warning(self, message):
-        self.logger.warning(message)
-
-    def error(self, message):
-        self.logger.error(message)
-
-    def critical(self, message):
-        self.logger.critical(message)
diff --git a/utils/streamer/__init__.py b/utils/streamer/__init__.py
deleted file mode 100644
index c285be40..00000000
--- a/utils/streamer/__init__.py
+++ /dev/null
@@ -1,82 +0,0 @@
-import math, mimetypes
-from fastapi.responses import StreamingResponse, Response
-from utils.logger import Logger
-from utils.streamer.custom_dl import ByteStreamer
-from utils.streamer.file_properties import get_name
-from utils.clients import (
-    get_client,
-)
-from urllib.parse import quote
-
-logger = Logger(__name__)
-
-class_cache = {}
-
-
-async def media_streamer(channel: int, message_id: int, file_name: str, request):
-    global class_cache
-
-    range_header = request.headers.get("Range", 0)
-
-    faster_client = get_client()
-
-    if faster_client in class_cache:
-        tg_connect = class_cache[faster_client]
-    else:
-        tg_connect = ByteStreamer(faster_client)
-        class_cache[faster_client] = tg_connect
-
-    file_id = await tg_connect.get_file_properties(channel, message_id)
-    file_size = file_id.file_size
-
-    if range_header:
-        from_bytes, until_bytes = range_header.replace("bytes=", "").split("-")
-        from_bytes = int(from_bytes)
-        until_bytes = int(until_bytes) if until_bytes else file_size - 1
-    else:
-        from_bytes = 0
-        until_bytes = file_size - 1
-
-    if (until_bytes > file_size) or (from_bytes < 0) or (until_bytes < from_bytes):
-        return Response(
-            status_code=416,
-            content="416: Range not satisfiable",
-            headers={"Content-Range": f"bytes */{file_size}"},
-        )
-
-    chunk_size = 1024 * 1024
-    until_bytes = min(until_bytes, file_size - 1)
-
-    offset = from_bytes - (from_bytes % chunk_size)
-    first_part_cut = from_bytes - offset
-    last_part_cut = until_bytes % chunk_size + 1
-
-    req_length = until_bytes - from_bytes + 1
-    part_count = math.ceil(until_bytes / chunk_size) - math.floor(offset / chunk_size)
-    body = tg_connect.yield_file(
-        file_id, offset, first_part_cut, last_part_cut, part_count, chunk_size
-    )
-
-    disposition = "attachment"
-    mime_type = mimetypes.guess_type(file_name.lower())[0] or "application/octet-stream"
-
-    if (
-        "video/" in mime_type
-        or "audio/" in mime_type
-        or "image/" in mime_type
-        or "/html" in mime_type
-    ):
-        disposition = "inline"
-
-    return StreamingResponse(
-        status_code=206 if range_header else 200,
-        content=body,
-        headers={
-            "Content-Type": f"{mime_type}",
-            "Content-Range": f"bytes {from_bytes}-{until_bytes}/{file_size}",
-            "Content-Length": str(req_length),
-            "Content-Disposition": f'{disposition}; filename="{quote(file_name)}"',
-            "Accept-Ranges": "bytes",
-        },
-        media_type=mime_type,
-    )
diff --git a/utils/streamer/custom_dl.py b/utils/streamer/custom_dl.py
deleted file mode 100644
index 1f1a9167..00000000
--- a/utils/streamer/custom_dl.py
+++ /dev/null
@@ -1,199 +0,0 @@
-import asyncio
-from typing import Dict, Union
-from pyrogram import Client, utils, raw
-from .file_properties import get_file_ids
-from pyrogram.session import Session, Auth
-from pyrogram.errors import AuthBytesInvalid
-from pyrogram.file_id import FileId, FileType, ThumbnailSource
-from utils.logger import Logger
-
-logger = Logger(__name__)
-
-
-class ByteStreamer:
-    def __init__(self, client: Client):
-        self.clean_timer = 30 * 60
-        self.client: Client = client
-        self.cached_file_ids: Dict[int, FileId] = {}
-        asyncio.create_task(self.clean_cache())
-
-    async def get_file_properties(self, channel, message_id: int) -> FileId:
-        if message_id not in self.cached_file_ids:
-            await self.generate_file_properties(channel, message_id)
-        return self.cached_file_ids[message_id]
-
-    async def generate_file_properties(self, channel, message_id: int) -> FileId:
-        file_id = await get_file_ids(self.client, channel, message_id)
-        if not file_id:
-            raise Exception("FileNotFound")
-        self.cached_file_ids[message_id] = file_id
-        return self.cached_file_ids[message_id]
-
-    async def generate_media_session(self, client: Client, file_id: FileId) -> Session:
-        """
-        Generates the media session for the DC that contains the media file.
-        This is required for getting the bytes from Telegram servers.
-        """
-
-        media_session = client.media_sessions.get(file_id.dc_id, None)
-
-        if media_session is None:
-            if file_id.dc_id != await client.storage.dc_id():
-                media_session = Session(
-                    client,
-                    file_id.dc_id,
-                    await Auth(
-                        client, file_id.dc_id, await client.storage.test_mode()
-                    ).create(),
-                    await client.storage.test_mode(),
-                    is_media=True,
-                )
-                await media_session.start()
-
-                for _ in range(6):
-                    exported_auth = await client.invoke(
-                        raw.functions.auth.ExportAuthorization(dc_id=file_id.dc_id)
-                    )
-
-                    try:
-                        await media_session.invoke(
-                            raw.functions.auth.ImportAuthorization(
-                                id=exported_auth.id, bytes=exported_auth.bytes
-                            )
-                        )
-                        break
-                    except AuthBytesInvalid:
-                        logger.debug(
-                            f"Invalid authorization bytes for DC {file_id.dc_id}"
-                        )
-                        continue
-                else:
-                    await media_session.stop()
-                    raise AuthBytesInvalid
-            else:
-                media_session = Session(
-                    client,
-                    file_id.dc_id,
-                    await client.storage.auth_key(),
-                    await client.storage.test_mode(),
-                    is_media=True,
-                )
-                await media_session.start()
-            logger.debug(f"Created media session for DC {file_id.dc_id}")
-            client.media_sessions[file_id.dc_id] = media_session
-        else:
-            logger.debug(f"Using cached media session for DC {file_id.dc_id}")
-        return media_session
-
-    @staticmethod
-    async def get_location(
-        file_id: FileId,
-    ) -> Union[
-        raw.types.InputPhotoFileLocation,
-        raw.types.InputDocumentFileLocation,
-        raw.types.InputPeerPhotoFileLocation,
-    ]:
-        """
-        Returns the file location for the media file.
-        """
-        file_type = file_id.file_type
-
-        if file_type == FileType.CHAT_PHOTO:
-            if file_id.chat_id > 0:
-                peer = raw.types.InputPeerUser(
-                    user_id=file_id.chat_id, access_hash=file_id.chat_access_hash
-                )
-            else:
-                if file_id.chat_access_hash == 0:
-                    peer = raw.types.InputPeerChat(chat_id=-file_id.chat_id)
-                else:
-                    peer = raw.types.InputPeerChannel(
-                        channel_id=utils.get_channel_id(file_id.chat_id),
-                        access_hash=file_id.chat_access_hash,
-                    )
-
-            location = raw.types.InputPeerPhotoFileLocation(
-                peer=peer,
-                volume_id=file_id.volume_id,
-                local_id=file_id.local_id,
-                big=file_id.thumbnail_source == ThumbnailSource.CHAT_PHOTO_BIG,
-            )
-        elif file_type == FileType.PHOTO:
-            location = raw.types.InputPhotoFileLocation(
-                id=file_id.media_id,
-                access_hash=file_id.access_hash,
-                file_reference=file_id.file_reference,
-                thumb_size=file_id.thumbnail_size,
-            )
-        else:
-            location = raw.types.InputDocumentFileLocation(
-                id=file_id.media_id,
-                access_hash=file_id.access_hash,
-                file_reference=file_id.file_reference,
-                thumb_size=file_id.thumbnail_size,
-            )
-        return location
-
-    async def yield_file(
-        self,
-        file_id: FileId,
-        offset: int,
-        first_part_cut: int,
-        last_part_cut: int,
-        part_count: int,
-        chunk_size: int,
-    ):
-        """
-        Custom generator that yields the bytes of the media file.
-        """
-        client = self.client
-        logger.debug(f"Starting to yielding file with client.")
-        media_session = await self.generate_media_session(client, file_id)
-
-        current_part = 1
-        location = await self.get_location(file_id)
-
-        try:
-            r = await media_session.invoke(
-                raw.functions.upload.GetFile(
-                    location=location, offset=offset, limit=chunk_size
-                ),
-            )
-            if isinstance(r, raw.types.upload.File):
-                while True:
-                    chunk = r.bytes
-                    if not chunk:
-                        break
-                    elif part_count == 1:
-                        yield chunk[first_part_cut:last_part_cut]
-                    elif current_part == 1:
-                        yield chunk[first_part_cut:]
-                    elif current_part == part_count:
-                        yield chunk[:last_part_cut]
-                    else:
-                        yield chunk
-
-                    current_part += 1
-                    offset += chunk_size
-
-                    if current_part > part_count:
-                        break
-
-                    r = await media_session.invoke(
-                        raw.functions.upload.GetFile(
-                            location=location, offset=offset, limit=chunk_size
-                        ),
-                    )
-        except (TimeoutError, AttributeError):
-            pass
-        finally:
-            logger.debug(f"Finished yielding file with {current_part} parts.")
-
-    async def clean_cache(self) -> None:
-        """
-        function to clean the cache to reduce memory usage
-        """
-        while True:
-            await asyncio.sleep(self.clean_timer)
-            self.cached_file_ids.clear()
-            logger.debug("Cleaned the cache")
diff --git a/utils/streamer/file_properties.py b/utils/streamer/file_properties.py
deleted file mode 100644
index 4d5c4326..00000000
--- a/utils/streamer/file_properties.py
+++ /dev/null
@@ -1,84 +0,0 @@
-from pyrogram import Client
-from pyrogram.types import Message
-from pyrogram.file_id import FileId
-from typing import Any, Optional, Union
-from pyrogram.raw.types.messages import Messages
-from datetime import datetime
-
-
-async def parse_file_id(message: "Message") -> Optional[FileId]:
-    media = get_media_from_message(message)
-    if media:
-        return FileId.decode(media.file_id)
-
-
-async def parse_file_unique_id(message: "Messages") -> Optional[str]:
-    media = get_media_from_message(message)
-    if media:
-        return media.file_unique_id
-
-
-async def get_file_ids(client: Client, chat_id, message_id) -> Optional[FileId]:
-    message = await client.get_messages(chat_id, int(message_id))
-    if message.empty:
-        raise Exception("FileNotFound")
-    media = get_media_from_message(message)
-    file_unique_id = await parse_file_unique_id(message)
-    file_id = await parse_file_id(message)
-    setattr(file_id, "file_size", getattr(media, "file_size", 0))
-    setattr(file_id, "mime_type", getattr(media, "mime_type", ""))
-    setattr(file_id, "file_name", getattr(media, "file_name", ""))
-    setattr(file_id, "unique_id", file_unique_id)
-    return file_id
-
-
-def get_media_from_message(message: "Message") -> Any:
-    media_types = (
-        "audio",
-        "document",
-        "photo",
-        "sticker",
-        "animation",
-        "video",
-        "voice",
-        "video_note",
-    )
-    for attr in media_types:
-        media = getattr(message, attr, None)
-        if media:
-            return media
-
-
-def get_name(media_msg: Union[Message, FileId]) -> str:
-    if isinstance(media_msg, Message):
-        media = get_media_from_message(media_msg)
-        file_name = getattr(media, "file_name", "")
-
-    elif isinstance(media_msg, FileId):
-        file_name = getattr(media_msg, "file_name", "")
-
-    if not file_name:
-        if isinstance(media_msg, Message) and media_msg.media:
-            media_type = media_msg.media.value
-        elif media_msg.file_type:
-            media_type = media_msg.file_type.name.lower()
-        else:
-            media_type = "file"
-
-        formats = {
-            "photo": "jpg",
-            "audio": "mp3",
-            "voice": "ogg",
-            "video": "mp4",
-            "animation": "mp4",
-            "video_note": "mp4",
-            "sticker": "webp",
-        }
-
-        ext = formats.get(media_type)
-        ext = "." + ext if ext else ""
-
-        date = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
-        file_name = f"{media_type}-{date}{ext}"
-
-    return file_name
diff --git a/utils/uploader.py b/utils/uploader.py
deleted file mode 100644
index 27a5f567..00000000
--- a/utils/uploader.py
+++ /dev/null
@@ -1,69 +0,0 @@
-from utils.clients import get_client
-from pyrogram import Client
-from pyrogram.types import Message
-from config import STORAGE_CHANNEL
-import os
-from utils.logger import Logger
-from urllib.parse import unquote_plus
-
-logger = Logger(__name__)
-PROGRESS_CACHE = {}
-STOP_TRANSMISSION = []
-
-
-async def progress_callback(current, total, id, client: Client, file_path):
-    global PROGRESS_CACHE, STOP_TRANSMISSION
-
-    PROGRESS_CACHE[id] = ("running", current, total)
-    if id in STOP_TRANSMISSION:
-        logger.info(f"Stopping transmission {id}")
-        client.stop_transmission()
-        try:
-            os.remove(file_path)
-        except:
-            pass
-
-
-async def start_file_uploader(
-    file_path, id, directory_path, filename, file_size, delete=True
-):
-    global PROGRESS_CACHE
-    from utils.directoryHandler import DRIVE_DATA
-
-    logger.info(f"Uploading file {file_path} {id}")
-
-    if file_size > 1.98 * 1024 * 1024 * 1024:
-        # Use premium client for files larger than 2 GB
-        client: Client = get_client(premium_required=True)
-    else:
-        client: Client = get_client()
-
-    PROGRESS_CACHE[id] = ("running", 0, 0)
-
-    message: Message = await client.send_document(
-        STORAGE_CHANNEL,
-        file_path,
-        progress=progress_callback,
-        progress_args=(id, client, file_path),
-        disable_notification=True,
-    )
-    size = (
-        message.photo
-        or message.document
-        or message.video
-        or message.audio
-        or message.sticker
-    ).file_size
-
-    filename = unquote_plus(filename)
-
-    DRIVE_DATA.new_file(directory_path, filename, message.id, size)
-    PROGRESS_CACHE[id] = ("completed", size, size)
-
-    logger.info(f"Uploaded file {file_path} {id}")
-
-    if delete:
-        try:
-            os.remove(file_path)
-        except Exception as e:
-            pass
diff --git a/uv.lock b/uv.lock
new file mode 100755
index 00000000..9690edce
--- /dev/null
+++ b/uv.lock
@@ -0,0 +1,1658 @@
+version = 1
+revision = 5
+requires-python = "==3.14.8"
+
+[[package]]
+name = "aiofiles"
+version = "25.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/41/c3/534eac40372d8ee36ef40df62ec129bee4fdb5ad9706e58a29be53b2c970/aiofiles-25.1.0.tar.gz", hash = "sha256:a8d728f0a29de45dc521f18f07297428d56992a742f0cd2701ba86e44d23d5b2", size = 46354, upload-time = "2025-10-09T20:51:04.358Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/bc/8a/340a1555ae33d7354dbca4faa54948d76d89a27ceef032c8c3bc661d003e/aiofiles-25.1.0-py3-none-any.whl", hash = "sha256:abe311e527c862958650f9438e859c1fa7568a141b22abcd015e120e86a85695", size = 14668, upload-time = "2025-10-09T20:51:03.174Z" },
+]
+
+[[package]]
+name = "aiohappyeyeballs"
+version = "2.7.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ce/f4/eec0465c2f67b2664688d0240b3212d5196fd89e741df67ddb81f8d35658/aiohappyeyeballs-2.7.1.tar.gz", hash = "sha256:065665c041c42a5938ed220bdcd7230f22527fbec085e1853d2402c8a3615d9d", size = 24757, upload-time = "2026-07-01T17:11:55.501Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/43/1947f06babed6b3f1d7f38b0c767f52df66bfb2bc10b468c4a7de9eceff2/aiohappyeyeballs-2.7.1-py3-none-any.whl", hash = "sha256:9243213661e29250eb41368e5daa826fc017156c3b8a11440826b2e3ed376472", size = 15038, upload-time = "2026-07-01T17:11:54.055Z" },
+]
+
+[[package]]
+name = "aiohttp"
+version = "3.14.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "aiohappyeyeballs" },
+    { name = "aiosignal" },
+    { name = "attrs" },
+    { name = "frozenlist" },
+    { name = "multidict" },
+    { name = "propcache" },
+    { name = "yarl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6c/4c/bdccd81e9ee225b69c60e7766c9a5b05364f118f4d383713b89a682d772d/aiohttp-3.14.5.tar.gz", hash = "sha256:5558a7f5a05af9ecf744af91e5baefc436f93c9333e656c27ec253f9a6bbe178", size = 8078052, upload-time = "2026-10-11T01:05:12.408Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/43/be/3184a1d34a8be665569eadb7e9e764b4629e4f3413e241cb2e4d6fecf3b3/aiohttp-3.14.5-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:939042d5cda21d41a6f512e7cc8b8e33a2aebff863352251da495fbd91b673b5", size = 540673, upload-time = "2026-10-11T01:01:41.354Z" },
+    { url = "https://files.pythonhosted.org/packages/60/2a/d35f3ba4cf157b072e3b674bf9983047ca5ea5173c995d32d877e1191d36/aiohttp-3.14.5-cp314-cp314-android_24_x86_64.whl", hash = "sha256:6da32b5ff3fd78d244e37300463434c7145162bfd2b6e9e915ab164da37f7343", size = 554087, upload-time = "2026-10-11T01:01:43.719Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/d2/61a33880ca4eaca95a9c60ca3f6beed15555af1028652dfaac601627787b/aiohttp-3.14.5-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:1b438b73c38111818d0c9d6a5c2bfed8584c8e503a49ef085d70e874ec846738", size = 522613, upload-time = "2026-10-11T01:01:46.154Z" },
+    { url = "https://files.pythonhosted.org/packages/31/1d/de579b299d2225dc2c6fd99d579d91f16c02a913fb5af9a3cf2fe9bd88ba/aiohttp-3.14.5-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:755933b107ea7a6a9ac916f635a70595a5b1a32fac10a8ff0b9f2ab88555550c", size = 529682, upload-time = "2026-10-11T01:01:48.477Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/4a/ddb923564e15e053b6e060b0036e1694dcadcb13aa476c5a87dcad20e336/aiohttp-3.14.5-cp314-cp314-ios_13_0_x86_64_iphonesimulator.whl", hash = "sha256:b3cc509327c7b27f6f4727a8830f4004f6df7766e179f2f4b8e54e65c0bec5d3", size = 540120, upload-time = "2026-10-11T01:01:50.474Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/36/a640fbecaa53727a5900b892bdbe17b5f3e8cc88903e22864fe41b654def/aiohttp-3.14.5-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:7bd8ac754ebd6733a3e2a0dd1674c4d8ab086196803fd8dcd776f07b4e2607d9", size = 818795, upload-time = "2026-10-11T01:01:52.665Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/b6/d52ca608859e271b5fa7944074802dc45f60e52c318a4ddc34edbf73586e/aiohttp-3.14.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:e724a7b6091f0b1ac064f9d1b15ff9ec52e6033a86cdae649e5f086e32a3c0db", size = 549667, upload-time = "2026-10-11T01:01:54.65Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/b5/05b8ac39a76ff4bca89f42a4c2471560c71f894ff6e4bc16158c951874e3/aiohttp-3.14.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c32e26310cc10e547f53cd13d39a369034f69dcb7d749d5cb0e5f67bc196b6ba", size = 548922, upload-time = "2026-10-11T01:01:56.547Z" },
+    { url = "https://files.pythonhosted.org/packages/19/b0/5aa186d56ce2334dabe29b70bd99dc8ae926ee44184c0de64a53d415a4f3/aiohttp-3.14.5-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1eb8167961ec4dfcc8cb9dd50bd0ee72519f7ef496be95203e49e27b01618382", size = 1882422, upload-time = "2026-10-11T01:01:59.258Z" },
+    { url = "https://files.pythonhosted.org/packages/db/f7/7d5c91bb9620db300c8ddb05337a9014301acb626223faff3abcb8ea47d7/aiohttp-3.14.5-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:c1d60eafd9c7e8e74abd03a5b00df44e7febfe6d9b89b559c0a6551eef0699d4", size = 1843621, upload-time = "2026-10-11T01:02:01.417Z" },
+    { url = "https://files.pythonhosted.org/packages/30/0a/b208953b96d8f24b75f6da704f508e6c5cf3022f52b60c61933df082e89c/aiohttp-3.14.5-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:137351bf20bbed9a65e839f4a4452ac377389bdb2f2857d2acffef38f5e9f2d1", size = 1927915, upload-time = "2026-10-11T01:02:03.697Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/79/90ebcccb55e2d1e11a1fed581d83bb966e38fb35fb4b2577fdc980f8707a/aiohttp-3.14.5-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:fba47bc2c3d7303c3d027c6cf4d07626c37b1314ac81f5820c31032e0ca1f677", size = 2036339, upload-time = "2026-10-11T01:02:06.046Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/66/55a8904b3a129fafdf94f9cc0a2e4ca09a3c914650be52355db7ad0bbdb6/aiohttp-3.14.5-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:94684b879ac1d71e4238850c99b62dc1b28d9086b156a2555f082010b85a865c", size = 1888041, upload-time = "2026-10-11T01:02:08.384Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/b8/96b25da7329a52e42c812b1e8b076386039ec4fc312afa043d173d8147fc/aiohttp-3.14.5-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:56572c42e3ecd636de8d2c3dd54cf5fc939cb5c32eb56297f176a0d366fac622", size = 1703849, upload-time = "2026-10-11T01:02:10.903Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/43/fbf976e3ae4c038d6f5c84945ab2150298c2d71201674d4e53d158063e75/aiohttp-3.14.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:a95529a92a446db351675f4aab518feaf5e99842f63f5dd17160c2b74f382db3", size = 1849703, upload-time = "2026-10-11T01:02:13.15Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/7d/218e912f4c1d89bde7ac551409be57ad2f6121638e56942d395a7cb1fa58/aiohttp-3.14.5-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:3edbece0379b8b4aaa67619b8aa2399bb66fce372cd5911098a434ea77220aa0", size = 1852695, upload-time = "2026-10-11T01:02:15.295Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/42/252a1b9287e3b6e393a1c3bd1776f36af30f5f25f071bbf2b0cb7eba9116/aiohttp-3.14.5-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:56d9828f204331a5ca8850fcfe2bcce95a149f1f223f60cc7216e5524978e480", size = 1893493, upload-time = "2026-10-11T01:02:17.93Z" },
+    { url = "https://files.pythonhosted.org/packages/78/97/71cae83d5100556fad1521684f7cd1e3e578432644f850245ed3bd969310/aiohttp-3.14.5-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:20064a177a070d789ee64a50b01a9161d3468e989baacfc6c714aa685c4b332f", size = 1693468, upload-time = "2026-10-11T01:02:20.666Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/69/73d88e97a8b5f0ca7a946d0011c0de99fb188b1687c7948ecd0553dc5bf0/aiohttp-3.14.5-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:81c2b3dfd56c62bee6108e4852d5970b4cf9086390b6983f52b666e878c1f115", size = 1915398, upload-time = "2026-10-11T01:02:23.011Z" },
+    { url = "https://files.pythonhosted.org/packages/05/f0/881644bcb15d4b258daea9b720a0af9dc4330496cc8d6ade9090cdd0cffc/aiohttp-3.14.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:09ec102b4b8c9a920275733bbc11fdbb615efe6f9231a06007c0218d336fb77a", size = 1871470, upload-time = "2026-10-11T01:02:25.278Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/de/19d9ebbcce5aedaa3242d8a99ff8816a60bdb7629fb0084bf4a45bfd1f62/aiohttp-3.14.5-cp314-cp314-win32.whl", hash = "sha256:9c428eb2bd8817588d16a0ab898aa4eb5d141f896aa2b394cc79a4cf61d9a8e2", size = 485517, upload-time = "2026-10-11T01:02:27.579Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/74/8cdaf0e58c2588371670d5a9a8215bbb971d36940b6e5d051967dd05c07d/aiohttp-3.14.5-cp314-cp314-win_amd64.whl", hash = "sha256:6f967dde489ca6a8c02d093ab245d2cbf50ccb5c36adf0188b17b0ca39d24b67", size = 511755, upload-time = "2026-10-11T01:02:29.685Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/6b/e0100e25502430a531c7cf1482a378d0b65bf728ab60c01ee270e56bc469/aiohttp-3.14.5-cp314-cp314-win_arm64.whl", hash = "sha256:1d2d981b53dd09a319e3570ef8cc3bbc3ef86f5a7abef0f6b2bff3867db3a9e7", size = 495151, upload-time = "2026-10-11T01:02:32.163Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/c2/ca2ead7b655688c53c03aeeb6e96e6851c9ff08d6be7b13802f53a6ae8fd/aiohttp-3.14.5-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:9ce66feae6ac65327379460380549bf1b8df8e17c4e25df2a2bcf168272e3bed", size = 855396, upload-time = "2026-10-11T01:02:34.443Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/70/22206fea409255a240c926ce11de48de354ae2bb90ca44f709c05497585d/aiohttp-3.14.5-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:27c2322e03f66101acb09869ce1cf1efc04994ee95e1735b69827bf8c8b9d781", size = 567734, upload-time = "2026-10-11T01:02:36.644Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/e5/79a36c118308b56f8667d67e05d2fb6dc638ab45985704cdb199631bedaa/aiohttp-3.14.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ff75a7537413a86e7cafe98e0e1d6e3dc4b15c6349896e7d5c6b881bfdb6d550", size = 567379, upload-time = "2026-10-11T01:02:38.757Z" },
+    { url = "https://files.pythonhosted.org/packages/63/a3/2ebec7dece3b1f02c30d2e484647f6f7b13952b1bb40a4cb285b849e8432/aiohttp-3.14.5-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9c061aa954daaf57d2a4b8374f9fca621ef0e1b603584431c220c22458c59b6d", size = 2050686, upload-time = "2026-10-11T01:02:41.169Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/d2/7e4d093db2f4450482652e7ef19a9e19919028f5135aa52bc4078c3beb80/aiohttp-3.14.5-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:1612fa5857b37bf32e5c1eaeefb96e3b01e9c70679eec81f0934e8a600080863", size = 1915077, upload-time = "2026-10-11T01:02:43.563Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/88/bd40d09958442a0a1df67da81de496361d6e2afc04f9db2950d835da750b/aiohttp-3.14.5-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:adbeee7d6fd4cf5fe0aece2fb3edc4243615d3180430ba8149d01a90670cac99", size = 2027204, upload-time = "2026-10-11T01:02:46.185Z" },
+    { url = "https://files.pythonhosted.org/packages/63/eb/3a601c1f8d3103c1a60ea981f20924855da9f575d2007fc38f8898b792fb/aiohttp-3.14.5-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b2966998927d7bed9db12c0a4647b0c7b179755878fc9c357fe1ffd3e3b0c1a5", size = 2149520, upload-time = "2026-10-11T01:02:48.812Z" },
+    { url = "https://files.pythonhosted.org/packages/22/d0/4e41bfe1b1ce1cb6f6d2e59fa7a88ef5cf92c402b2d07e9018778ba9edbc/aiohttp-3.14.5-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8e317e0fb6b16212c881d2205a7d87414c29acd69320b3aa6dce9d9c7b86fe4f", size = 2002039, upload-time = "2026-10-11T01:02:51.293Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/5e/72067019545c502b881b031153c437752ecef48d7d213bc0218ccebb4bfb/aiohttp-3.14.5-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:50343c1757b4b6f6708eeaf24534b32f19dfb99fb1b762c00420867a62fc81e0", size = 1786164, upload-time = "2026-10-11T01:02:53.533Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/fe/7741efd6119bfb7a00827fe6f7b84b4409de58d888ae21adc5a9a6824992/aiohttp-3.14.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:083673c7a94c3ea035caaa5ca04288bdb44887abfe1f5ba23294e6a4b03efd2d", size = 1970689, upload-time = "2026-10-11T01:02:55.888Z" },
+    { url = "https://files.pythonhosted.org/packages/43/e7/342a13bf67f34d269bf2f7e870ecd72b99c832cc6f0a271a9210c0ebfb84/aiohttp-3.14.5-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:2528cb4c6b92008c76ac9ac6298624069bb2db91ff4929905512d1d84485f658", size = 1951967, upload-time = "2026-10-11T01:02:58.467Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/d4/fdb3b27340617e5e64df18a70fa89097778652ea5c7c7e2f79def76999c3/aiohttp-3.14.5-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:b1b8ece1e71132d2afba4dbc0c3d62c766e25165990b25db1196c04969eb3d84", size = 1968511, upload-time = "2026-10-11T01:03:00.883Z" },
+    { url = "https://files.pythonhosted.org/packages/83/b2/e8f88298de78d1a951f36f9f966d38ec6ed1d4721303ba02064a545e8aa6/aiohttp-3.14.5-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:fce9523df31cea6284f3e2c479876750d7687cf671d7b25d32b19effc0e86441", size = 1778497, upload-time = "2026-10-11T01:03:03.206Z" },
+    { url = "https://files.pythonhosted.org/packages/22/68/9ccdb93d664345c546be7f34480b921774d8c0d98f47e70d7e03b115d475/aiohttp-3.14.5-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:09e0eb18c7e0c8777e2f9149de63799195b9b3ca1b5c81ba6f32f2c6b8628210", size = 1999676, upload-time = "2026-10-11T01:03:05.829Z" },
+    { url = "https://files.pythonhosted.org/packages/57/4a/a33cfa6dcb00e94194ae4fe710432ca4ed111e016356b4ba4d2f4c3a124c/aiohttp-3.14.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6774814fd5c338e72ee0da5cbb9432816df450e69c019f72b5d29bdec2a1792d", size = 1963437, upload-time = "2026-10-11T01:03:08.196Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/20/eacbecfea3b5c3dcbfc9b023e3a5460f43e5dda16d06a2877ebe7184c3f3/aiohttp-3.14.5-cp314-cp314t-win32.whl", hash = "sha256:33f706574e32c6e694f352a856e05caf18f7f2c871b3e87b41c55ea452b409ab", size = 503973, upload-time = "2026-10-11T01:03:10.481Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/78/18eec294f6c8c5dc845dcf6d730a0147d8d0f17e86138a7bdb85e43a30fa/aiohttp-3.14.5-cp314-cp314t-win_amd64.whl", hash = "sha256:5ba14a839fbe87cf7c12a6b5661c05f324a296eb8363141edb3944ba63d4c9d3", size = 531190, upload-time = "2026-10-11T01:03:12.716Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/39/e53f8169acc85271ebd12b5b32ad7f1541b35639ccbe0f49034c64785d10/aiohttp-3.14.5-cp314-cp314t-win_arm64.whl", hash = "sha256:1061b364556e8172e8d46b0b183adeeb73e8c42d30ebc745591e1bd89acad52e", size = 510360, upload-time = "2026-10-11T01:03:15.08Z" },
+    { url = "https://files.pythonhosted.org/packages/68/30/173960c42b05a6c59f7558e4b12a4b0d9ba376cf6aa9bde7f9e08a30ca8d/aiohttp-3.14.5-py3-none-any.whl", hash = "sha256:efc21a454892828368b11c2c780de0ff8bc991f73f6b99c6b66e56205470929b", size = 279517, upload-time = "2026-10-11T01:05:08.523Z" },
+]
+
+[[package]]
+name = "aiosignal"
+version = "1.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "frozenlist" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/61/62/06741b579156360248d1ec624842ad0edf697050bbaf7c3e46394e106ad1/aiosignal-1.4.0.tar.gz", hash = "sha256:f47eecd9468083c2029cc99945502cb7708b082c232f9aca65da147157b251c7", size = 25007, upload-time = "2025-07-03T22:54:43.528Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/76/641ae371508676492379f16e2fa48f4e2c11741bd63c48be4b12a6b09cba/aiosignal-1.4.0-py3-none-any.whl", hash = "sha256:053243f8b92b990551949e63930a839ff0cf0b0ebbe0597b0f3fb19e1a0fe82e", size = 7490, upload-time = "2025-07-03T22:54:42.156Z" },
+]
+
+[[package]]
+name = "annotated-doc"
+version = "0.0.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5a/8e/38aa427ed5402449e226975b649c5dc73ccadfefeb95e6aecb8f8ea4b6b6/annotated_doc-0.0.5.tar.gz", hash = "sha256:c7e58ce09192557605d8bbd92836d7e1d520ac9580096042c0bfd197efacf1bb", size = 10758, upload-time = "2026-07-28T13:50:58.129Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3e/30/e900b21425a860e195f32e37657aa1f7c7f2b1bfb26f03ca209b90933c06/annotated_doc-0.0.5-py3-none-any.whl", hash = "sha256:117bac03a25ede5df5440e855b32d556049ca169ead221505badf432fed4b101", size = 5302, upload-time = "2026-07-28T13:50:57.239Z" },
+]
+
+[[package]]
+name = "annotated-types"
+version = "0.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5f/56/a8120250d128bed162cd73c76d45f6ef9991f3e068f62a8ee060afa3104a/annotated_types-0.8.0.tar.gz", hash = "sha256:13b2beaad985e05e2d6407ee4c4f35590b11f8d693a258a561055cac8f64cab7", size = 15893, upload-time = "2026-07-23T20:16:13.995Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/99/91/8acff4f5e50511b911bbccb72b8628a49c68ce14148cd9f6431094859a90/annotated_types-0.8.0-py3-none-any.whl", hash = "sha256:f072f4d804ea359e4eaf198b1af7a8b0943881a87f31bb764f8bf219bb9419e0", size = 13427, upload-time = "2026-07-23T20:16:12.938Z" },
+]
+
+[[package]]
+name = "anyio"
+version = "4.15.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "idna" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a9/d2/f4d173e22df740bc37b1db102b386ba719b66e95b0f0d751f556b387e6d2/anyio-4.15.1.tar.gz", hash = "sha256:9f28306018cbd6d329e64a36d58256edff76dd996fe423bc957326e578b82a94", size = 276966, upload-time = "2026-09-05T10:42:39.44Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/12/b8/4bd346e22b28902df4d651910f5242c28d84e4a5c2435ca5c3f797ed7e2e/anyio-4.15.1-py3-none-any.whl", hash = "sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101", size = 132079, upload-time = "2026-09-05T10:42:37.923Z" },
+]
+
+[[package]]
+name = "argon2-cffi"
+version = "25.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "argon2-cffi-bindings" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0e/89/ce5af8a7d472a67cc819d5d998aa8c82c5d860608c4db9f46f1162d7dab9/argon2_cffi-25.1.0.tar.gz", hash = "sha256:694ae5cc8a42f4c4e2bf2ca0e64e51e23a040c6a517a85074683d3959e1346c1", size = 45706, upload-time = "2025-06-03T06:55:32.073Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4f/d3/a8b22fa575b297cd6e3e3b0155c7e25db170edf1c74783d6a31a2490b8d9/argon2_cffi-25.1.0-py3-none-any.whl", hash = "sha256:fdc8b074db390fccb6eb4a3604ae7231f219aa669a2652e0f20e16ba513d5741", size = 14657, upload-time = "2025-06-03T06:55:30.804Z" },
+]
+
+[[package]]
+name = "argon2-cffi-bindings"
+version = "26.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/0b/43/bb8b6e8708d49a5ab36781333af092d9f483b198a2710d01281204640055/argon2_cffi_bindings-26.1.0.tar.gz", hash = "sha256:63505c71542a44b68b1e38060450fb006404170da375feb31af153e7f9c6205d", size = 1790807, upload-time = "2026-08-20T07:44:22.492Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e7/d2/0ae991f1b2181e5be49007c574710a800ad36c2978683addb3e67c474e55/argon2_cffi_bindings-26.1.0-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:21ca0396fe5ec995dd54431c32698189666f9224810acfa752e50d2bd94d9df2", size = 25521, upload-time = "2026-08-20T07:32:43.019Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/e4/ad91d8297638aa2258aad4501c306aca99480dfe76ccd638173fa3702db9/argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:78de2d65e0b9ea7ce9d1b1c3e87297b2d7305a02c266ee2a2d6910daddd7ee69", size = 27177, upload-time = "2026-08-20T07:32:44.158Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/86/5363df11b86d02cf3662208e7406496327649cc90eb365bf6f4e8a54a41f/argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:27f1821903e2ceadcb88ec2b45ef190897b7682449c772f4d9b53e42c520cf29", size = 26597, upload-time = "2026-08-20T07:32:45.172Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/b5/a14dcc592652347dad23ee93b278a4da5d2a25c9ed3ebd10d68eea823a4f/argon2_cffi_bindings-26.1.0-cp310-abi3-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:d88e5f7e60f28ae0b0cc6b2f16c43e87cd642a196a86f85e0d8bb6fe016fc16d", size = 27403, upload-time = "2026-08-20T07:32:46.13Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/81/b4a20d4902af7f796390bf9245ff83c5217dfa7367efa1d14986956c482b/argon2_cffi_bindings-26.1.0-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:34b7d9c24a4165a2c61cc8ae11d44d48c9ce2830fb536cb7914e11fdd9962728", size = 27132, upload-time = "2026-08-20T07:32:47.13Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/1b/c8de358af07b1c490e0fcb863ef98e46ddb486e45567aca5a60bd68d9daa/argon2_cffi_bindings-26.1.0-cp310-abi3-musllinux_1_2_riscv64.whl", hash = "sha256:224865cbbcb7a2bd1356741dff12b0134df726b6d44bb7b500df8e303cbd9e81", size = 27588, upload-time = "2026-08-20T07:32:48.087Z" },
+    { url = "https://files.pythonhosted.org/packages/48/2f/7ee62a6e79f9309f9d9982d301b22a00010adb580c05c8109b94d7b33de0/argon2_cffi_bindings-26.1.0-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ffff613aaa9ce6236766e2fc6dc560bb5abde7a2e2416e3db1f9ae395a2b4dd4", size = 26785, upload-time = "2026-08-20T07:32:48.977Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/10/960d0ee93d4897741bcaf4799c697dae2d81499f66fd1ed042a7dd54c1f4/argon2_cffi_bindings-26.1.0-cp310-abi3-win32.whl", hash = "sha256:a86c069c91a747a2c4e5c51473590aeb48172fff9b2130d23729a42d98665ecb", size = 23898, upload-time = "2026-08-20T07:32:50.114Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/3a/0cc14a05810e6add9bce5e87693334baa2222de5f647fa31781885b6573f/argon2_cffi_bindings-26.1.0-cp310-abi3-win_amd64.whl", hash = "sha256:2c36ff87b5dfaa477d0bd51e9d7f6abdae7c8955d2983c97419085d842154b3e", size = 25730, upload-time = "2026-08-20T07:32:51.091Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/db/d83cf2af140547f0b9cdaece05b2dc2dcbf991be4667331d073eff771435/argon2_cffi_bindings-26.1.0-cp310-abi3-win_arm64.whl", hash = "sha256:f9c4420a7a864fe1b86ce35befc95b8e39fb852493b81cf798671ddc265de638", size = 24478, upload-time = "2026-08-20T07:32:52.111Z" },
+    { url = "https://files.pythonhosted.org/packages/76/38/de696045960f5b846d428c0fb6c130ed3da87aac2af209b05c193815404c/argon2_cffi_bindings-26.1.0-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:db0fcd827ca61622a01b220aadfbece01939acf53888f2cb98cd93e9b1e2c97e", size = 15449, upload-time = "2026-08-20T07:32:54.075Z" },
+    { url = "https://files.pythonhosted.org/packages/91/0a/c25af768f6b75a5a71e31207f87c540656b2808c015260444a22763221ad/argon2_cffi_bindings-26.1.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:28524438cd3e723f25412f63d4fd516ff5bae9ae5aa56acbe2a1404398a0cf31", size = 25683, upload-time = "2026-08-20T07:32:55.05Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/7e/be212c751ab0bcea7f646615f933bf262e8e50b3f7bef32f861d0a2d066b/argon2_cffi_bindings-26.1.0-cp314-cp314t-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ac82fc756a446b6ccd7139ce70efa9d8bbe541e7ad579a12dcb52764b7175c5f", size = 27311, upload-time = "2026-08-20T07:32:56.166Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/ee/f84b28e4afd13d3cac36c1d8fa8c239d2dc2c51cd978d02ee5d5ad98d9bb/argon2_cffi_bindings-26.1.0-cp314-cp314t-manylinux_2_26_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6a4e68eed961a8de6928d1c17ff3dc2a547e0e923c17f8f1cd79fb7bc9502f98", size = 26771, upload-time = "2026-08-20T07:32:57.206Z" },
+    { url = "https://files.pythonhosted.org/packages/21/c3/95c07a023691ecd529da9cb6a8f0779e13ebc1bdfaa86d145fdc1c6e7e79/argon2_cffi_bindings-26.1.0-cp314-cp314t-manylinux_2_34_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:151dfaad9de753f4af2a7854e707e4784f2acc434340ade64239c5b104b2d605", size = 27568, upload-time = "2026-08-20T07:32:58.361Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/31/3a18e31406d8694b4d6a31573c3e572fff6bed318bb744453eb653766d22/argon2_cffi_bindings-26.1.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:061a6919145bbf282ebf1f9c59d3135d4833c25313c8595c0d68cf7712ddfce2", size = 27280, upload-time = "2026-08-20T07:32:59.343Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/39/d4be4577e178b2397aa5b5575c8a309bf0da2afe05fe0c72c8f398662d63/argon2_cffi_bindings-26.1.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:62ff20cd130c956c7c9144d5fe35228f98b51c579b2439e988b27ef93e16c02a", size = 27776, upload-time = "2026-08-20T07:33:00.325Z" },
+    { url = "https://files.pythonhosted.org/packages/71/47/78f4dd96f7411339f723b96fe24039c1bd5835102b8a5ba71ac4ec712ac7/argon2_cffi_bindings-26.1.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:19423e5d7ac1cc354baab59eaabf18db2ec04ef6593b5abe5a34f323c4a8f87a", size = 26932, upload-time = "2026-08-20T07:33:01.272Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/cd/96bfd37434cc0a848a9066c291d84b28846c4c9ea289ed9866b1164d622b/argon2_cffi_bindings-26.1.0-cp314-cp314t-win32.whl", hash = "sha256:4f84cdd868978d7b7350a566c254042d44216d9e37f241f3a6d3b1dfebeede35", size = 24878, upload-time = "2026-08-20T07:33:02.189Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/42/d8b6810abd9b1bd2f47ebbccf460da59c9f32e94888bea4f7b137d998797/argon2_cffi_bindings-26.1.0-cp314-cp314t-win_amd64.whl", hash = "sha256:2b741888c93147444fdfc851abd81cc207f37f7f7da42062a00deb3888e57da8", size = 26656, upload-time = "2026-08-20T07:33:03.222Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/d1/095d95eaf2ed1d9f77268cf3291bde148c6cd56121f8db2c74c1ba618a0e/argon2_cffi_bindings-26.1.0-cp314-cp314t-win_arm64.whl", hash = "sha256:6ab674f668d5962a3a4136ae0812519b0f1586874263723a32181d60d64137e1", size = 25378, upload-time = "2026-08-20T07:33:04.332Z" },
+]
+
+[[package]]
+name = "attrs"
+version = "26.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9a/8e/82a0fe20a541c03148528be8cac2408564a6c9a0cc7e9171802bc1d26985/attrs-26.1.0.tar.gz", hash = "sha256:d03ceb89cb322a8fd706d4fb91940737b6642aa36998fe130a9bc96c985eff32", size = 952055, upload-time = "2026-03-19T14:22:25.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" },
+]
+
+[[package]]
+name = "bandit"
+version = "1.9.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "pyyaml" },
+    { name = "rich" },
+    { name = "stevedore" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/aa/c3/0cb80dfe0f3076e5da7e4c5ad8e57bac6ac357ff4a6406205501cade4965/bandit-1.9.4.tar.gz", hash = "sha256:b589e5de2afe70bd4d53fa0c1da6199f4085af666fde00e8a034f152a52cd628", size = 4242677, upload-time = "2026-02-25T06:44:15.503Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/05/a4/a26d5b25671d27e03afb5401a0be5899d94ff8fab6a698b1ac5be3ec29ef/bandit-1.9.4-py3-none-any.whl", hash = "sha256:f89ffa663767f5a0585ea075f01020207e966a9c0f2b9ef56a57c7963a3f6f8e", size = 134741, upload-time = "2026-02-25T06:44:13.694Z" },
+]
+
+[[package]]
+name = "boolean-py"
+version = "5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c4/cf/85379f13b76f3a69bca86b60237978af17d6aa0bc5998978c3b8cf05abb2/boolean_py-5.0.tar.gz", hash = "sha256:60cbc4bad079753721d32649545505362c754e121570ada4658b852a3a318d95", size = 37047, upload-time = "2025-04-03T10:39:49.734Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/ca/78d423b324b8d77900030fa59c4aa9054261ef0925631cd2501dd015b7b7/boolean_py-5.0-py3-none-any.whl", hash = "sha256:ef28a70bd43115208441b53a045d1549e2f0ec6e3d08a9d142cbc41c1938e8d9", size = 26577, upload-time = "2025-04-03T10:39:48.449Z" },
+]
+
+[[package]]
+name = "cachecontrol"
+version = "0.14.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "msgpack" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2d/f6/c972b32d80760fb79d6b9eeb0b3010a46b89c0b23cf6329417ff7886cd22/cachecontrol-0.14.4.tar.gz", hash = "sha256:e6220afafa4c22a47dd0badb319f84475d79108100d04e26e8542ef7d3ab05a1", size = 16150, upload-time = "2025-11-14T04:32:13.138Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ef/79/c45f2d53efe6ada1110cf6f9fca095e4ff47a0454444aefdde6ac4789179/cachecontrol-0.14.4-py3-none-any.whl", hash = "sha256:b7ac014ff72ee199b5f8af1de29d60239954f223e948196fa3d84adaffc71d2b", size = 22247, upload-time = "2025-11-14T04:32:11.733Z" },
+]
+
+[package.optional-dependencies]
+filecache = [
+    { name = "filelock" },
+]
+
+[[package]]
+name = "certifi"
+version = "2026.10.19"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a6/bd/1436c50cc46699de0230fbaacc1d1de7bfec413176099949e9d5112e88f2/certifi-2026.10.19.tar.gz", hash = "sha256:035c1e85572b141bf1c3a3eff0e33a8eb74917522f2559075ff8d2fea780a1ae", size = 137598, upload-time = "2026-10-20T02:24:16.604Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c4/51/29046e48f693c54e5b7412216d447a1d8362c9653148d98c02cdf65fa733/certifi-2026.10.19-py3-none-any.whl", hash = "sha256:42d35340cc5b9ba78e818ddbff0c5b1c2b779de448a340fd1b989f5fa8670e1b", size = 136464, upload-time = "2026-10-20T02:24:15.072Z" },
+]
+
+[[package]]
+name = "cffi"
+version = "2.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pycparser", marker = "implementation_name != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9e/ef/008a1939e372c06329a3fce4279c02f328488f3526744906eeec3da7ad5f/cffi-2.1.1.tar.gz", hash = "sha256:dd31f52ea1086513bb9df30f8fcee9b8918323ae067a3d5b78bc826a000712be", size = 530807, upload-time = "2026-08-03T21:21:18.939Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d3/7b/d6bbf82b8b96e7391438898c42f5bd96dd02030fd5b64937d248220003e2/cffi-2.1.1-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:7dbb61fe3a7699468030f71bbe5f8a0e326a151daa91beb11a6fc1f980c55e1c", size = 194064, upload-time = "2026-08-03T21:20:17.148Z" },
+    { url = "https://files.pythonhosted.org/packages/94/e6/bcc91b283be94735e268487a054004f0aa19947b6348fa367db53230abc8/cffi-2.1.1-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:f24fb43132a4c6b4cb4eb029492919b2db645be6808d738f244fd146c03c32cb", size = 196720, upload-time = "2026-08-03T21:20:18.268Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/99/c4b0c17cacdc9c3b8f280026286a9826d6a208c0f047591a3c3ce99b91fd/cffi-2.1.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:d28630f5854ab07ab1fd4aba756de52326c82e6be15d414b12793f1975048b54", size = 184964, upload-time = "2026-08-03T21:20:19.708Z" },
+    { url = "https://files.pythonhosted.org/packages/b3/a9/9db617d05d7367c1ad0ab00b3aa6e6f9281edd689b4ee9ea0e5a84e89c97/cffi-2.1.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:661c298b4821edebead0c91edd2b00374d67ad7c5a1f7a91d4442633b79d6a72", size = 184962, upload-time = "2026-08-03T21:20:20.833Z" },
+    { url = "https://files.pythonhosted.org/packages/67/b8/b42132ca113dc567d37684437b46ca1dafc885902b02a110a02d5b511857/cffi-2.1.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:58acb8ab8e295e6c5ea12f888cbb13cf21511ef2a3303a23f4325c29d17fe5c1", size = 222328, upload-time = "2026-08-03T21:20:22.118Z" },
+    { url = "https://files.pythonhosted.org/packages/80/10/c5c0cbf0a657aecf59ef511409734230bf556f05a0d6c9eed7aa5c0a0166/cffi-2.1.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:456a61fa52d579ebf9df2e9552ead5129855dbaff6c1e5a9b1bc408809bdc062", size = 209985, upload-time = "2026-08-03T21:20:23.401Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/6c/bfa0b87b03b9238148beca990292843c9396ba069b54496596594173de7b/cffi-2.1.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:a4f00aa42f75d6e4595e8866e748cc1705adc0cddfeb2ca86d0d03993d63ba03", size = 208530, upload-time = "2026-08-03T21:20:24.628Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/02/4e7d553a7ac4b4238b38b3c1b80d486e9d4436f8d2acbf87a0997fe3f402/cffi-2.1.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:b0431303acaea1089ad4b3e9ce4e6518193def1118d4073ca848635ee4ea2e96", size = 221525, upload-time = "2026-08-03T21:20:25.758Z" },
+    { url = "https://files.pythonhosted.org/packages/82/1d/a4aaf9babd75acb4d5f223bff71533bee748dd770a382619a798960ee9ba/cffi-2.1.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:64faea20f4e2613363a1a9b9c7dd73058f3ecd00133a511e72ad7c511658f527", size = 225053, upload-time = "2026-08-03T21:20:26.985Z" },
+    { url = "https://files.pythonhosted.org/packages/81/10/5dc0e7bdd18e22107054288283380fc97a06ae3f1656a106908d666a3c88/cffi-2.1.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5c58fe613dc5e5336357eff555824a314d8e43282600435c8d1cb6a7a2fedd13", size = 223213, upload-time = "2026-08-03T21:20:28.277Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/e9/d0061c364cde06ee43168a0d076ac1da512cbc380d44767b844ba34fe2b6/cffi-2.1.1-cp314-cp314-win32.whl", hash = "sha256:1a18a57b58cfb21fc28d72e876acf10eaed67a1ed96226f92af4df681d571c4c", size = 177682, upload-time = "2026-08-03T21:20:44.288Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/06/1c3e01e3ba14c39f6d10bfbac52753b7e22259e38088e5cfe1d704918690/cffi-2.1.1-cp314-cp314-win_amd64.whl", hash = "sha256:3222ba5d678f80a030e6afbcc33dc1ae5cb45facabb61cee2c7016b8432fde48", size = 187949, upload-time = "2026-08-03T21:20:45.623Z" },
+    { url = "https://files.pythonhosted.org/packages/87/5b/da4e39efe18eeb89cf580ea9cfc66b6a7c3eadb808fc0cc1d3a295cb5a5d/cffi-2.1.1-cp314-cp314-win_arm64.whl", hash = "sha256:ab36d55f9ed2d067327667c2fea18dda018eb628dd6347aa01dda6cf1f5d3836", size = 182947, upload-time = "2026-08-03T21:20:46.955Z" },
+    { url = "https://files.pythonhosted.org/packages/23/59/40338bf421c5accea1d45158170c87006ef1cd371b05c077e76476949728/cffi-2.1.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:7750c6449dff7864bb9bb27ddfb0267756189201a3afc911d82b3caacd70dfc3", size = 188504, upload-time = "2026-08-03T21:20:29.495Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/47/5ecf1023850036e674c77ec4de86182d309ae344e39e7cba984b7df5d647/cffi-2.1.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0beceaabe56af686895136a2de78db54ecd8e4046b236b8fd6d6cb61389e9bf2", size = 188259, upload-time = "2026-08-03T21:20:31.291Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/9c/92934c3bea9f785b23eba304538c0b4d37a2a96d2431eb3a1bc87a11aa19/cffi-2.1.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:49cbc70e6542d4ccccb936558d1064a8012541e78f821f955cff24e357776c94", size = 223864, upload-time = "2026-08-03T21:20:32.571Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/45/ba4c93527bc38616a8bd36488acb69a2212d60486794f0c1f318949bbb76/cffi-2.1.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:e2d65b31f36619cda3999b78b2aa9632e76b78448e7a56fc4240824200e7c4fc", size = 211538, upload-time = "2026-08-03T21:20:33.808Z" },
+    { url = "https://files.pythonhosted.org/packages/80/e9/b6ef565e452acb932fb0cb5443f44a78efbd1233e566f02b5a83855e9115/cffi-2.1.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:28907ab9bfb6aa13184cfc17c6b8e1023c5ab6fd7076d8c20a35e59fe04f8f29", size = 210688, upload-time = "2026-08-03T21:20:34.974Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/95/eff5f0cee78d2eabc7eebffec40d3fc1876b5f3c95582e018bb4b99601f2/cffi-2.1.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:51b31d1c98274844cfd7838ce00bfc27c7423a4dc00fc0772fc3331c2cc90676", size = 223803, upload-time = "2026-08-03T21:20:36.564Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/01/579d39fb8bef00a335a23d83757b44feb24cd6345a2c451b64cb67b9c362/cffi-2.1.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:5e7cecbaadb83884793e05828cee59b210b24583b9c7425d0ba6a754fe22eb4e", size = 226763, upload-time = "2026-08-03T21:20:37.816Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/b0/0b44f47c60b01b57b6e2bbd92343f13a85a1d93bc46ccf6e47e244acd99c/cffi-2.1.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:25792eac27877609e7bb06d42ff88278a6624fff2ba9bbb523c09616b117e80f", size = 225688, upload-time = "2026-08-03T21:20:38.959Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/d2/3b7176cb570a1d3e27faf67b72f591af508036e0d8b2be2ef9af9e8c84bb/cffi-2.1.1-cp314-cp314t-win32.whl", hash = "sha256:8ef53b2de9bcb9197d31854256575d59dbac0cba72ac627bb291ef5eceb74be4", size = 182868, upload-time = "2026-08-03T21:20:40.388Z" },
+    { url = "https://files.pythonhosted.org/packages/56/78/31f00c1bcd97c9bbf55f1bfdf5bc809a5de8887473e90bb9960dca825e80/cffi-2.1.1-cp314-cp314t-win_amd64.whl", hash = "sha256:616f097f2fe415bc92a247f02e11f634e1f9e9a83d327e3c915c15089c87869e", size = 194104, upload-time = "2026-08-03T21:20:41.725Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/1b/58496f2ed0a35de575250c02a43ab3cc2c04d494a88fed31c1cabc0fd176/cffi-2.1.1-cp314-cp314t-win_arm64.whl", hash = "sha256:ad2c86c495b899d862ea0f4b42891b8713a3bd45dd4105c7fd51c2a72f39f3a5", size = 186402, upload-time = "2026-08-03T21:20:43.042Z" },
+]
+
+[[package]]
+name = "charset-normalizer"
+version = "3.5.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/33/1c/f41d4e74c28ab327ff3acd36053f7ea506c55872d7a90b0fa71aa3ab0c89/charset_normalizer-3.5.2.tar.gz", hash = "sha256:39de2a259fc954455c57274dc94c79d5842774e1247a016aff30bc0efed0f4ef", size = 172659, upload-time = "2026-09-30T04:39:23.398Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/ca/7aa91362a2f77ac8e9e28a9b902a74f7d0e11a851ef0d27a74308da8cd90/charset_normalizer-3.5.2-cp314-cp314-android_24_arm64_v8a.whl", hash = "sha256:1afb975bd5d68d5ce9f6b6d44fdf2f7e34b895a35e95708a7a91b20a3b51d187", size = 226010, upload-time = "2026-09-30T04:36:27.669Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/cf/ac8878d0322cf88a1aad4c7b147db32ca0bd806eb0060957b2e31486dbe6/charset_normalizer-3.5.2-cp314-cp314-android_24_x86_64.whl", hash = "sha256:bbbfc8e28816f19d7c0f1816664980c0a9875d01b27cdf8eedddb639d9e108ad", size = 239266, upload-time = "2026-09-30T04:36:29.434Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/6d/9a08d7e0b29b7208e2c6c01dc56c8e0520e7c7beadbbfb024b58fd69c8a5/charset_normalizer-3.5.2-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:7967d08cf06dee78443b874f98c98036f624f3a4e73e11f9f64f5be4d25393cf", size = 206783, upload-time = "2026-09-30T04:36:30.872Z" },
+    { url = "https://files.pythonhosted.org/packages/82/44/b0aa350280e6ff5a5492d17cf10460dd39d5ee848f872f7ba2df10607f60/charset_normalizer-3.5.2-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:4c2b5031f63e331e3839b40aed2dd6f191e9c07edbde303e7876846ea1946995", size = 210449, upload-time = "2026-09-30T04:36:32.625Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/8a/40db9aa9f5907bb0e6f8b6d64064bf8852fb33d4b813ff9414911df7647c/charset_normalizer-3.5.2-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:fcff63213e8e6e47770541a4607175404f47cbb3ebea7b6058cc82d524a0e424", size = 367815, upload-time = "2026-09-30T04:36:34.197Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/72/9c5e7707b57c8ddfa9ddf7b0b1d009d7fbab9e9e887d5b721060f37e307d/charset_normalizer-3.5.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8d86d6fc60743dc916eb79e2eb1ec4818e21e427731543af40a3021851174a13", size = 247095, upload-time = "2026-09-30T04:36:35.803Z" },
+    { url = "https://files.pythonhosted.org/packages/83/09/71e453691e927de4ddf792770cfaab3f49d494e222f66ea5e404bbd5e39c/charset_normalizer-3.5.2-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:7a881931aa470808df94a8c380eed2bbbc76cd9dc622310f99665658c821eb6d", size = 233942, upload-time = "2026-09-30T04:36:37.407Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/86/85c84e4da8b27dd409577d9437926ff581c5f9d3c66038dc68c1a526de51/charset_normalizer-3.5.2-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8024d00c3faf3fc0c16e07a69f4405e8eac7cc0ab15f65fe6cf43827c4cf72b4", size = 273762, upload-time = "2026-09-30T04:36:38.904Z" },
+    { url = "https://files.pythonhosted.org/packages/92/08/564955a4b5f2ccb410ab480bbe8c6a18063ff27f2d35458731c4a5335df9/charset_normalizer-3.5.2-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4d48f2d08b9de5864e2c8744d4461b862fb149a18274abc8b698c45975573438", size = 269514, upload-time = "2026-09-30T04:36:40.469Z" },
+    { url = "https://files.pythonhosted.org/packages/18/24/bad3ac4271589df29cf5ce2f5ae490518a5739358052bd0d61209e6fea54/charset_normalizer-3.5.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:34276fd796040bf0993ab33a369aa572e6979c7aab225a88893667ad8eac8f7a", size = 255056, upload-time = "2026-09-30T04:36:42.02Z" },
+    { url = "https://files.pythonhosted.org/packages/d6/3e/350d89ad49916b86554d6f5f2d03ec1152148f87e5ff735106c6a03b1a36/charset_normalizer-3.5.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0521c5665880b33d603717defa76c094048900010897909952397feb3039da56", size = 251311, upload-time = "2026-09-30T04:36:43.577Z" },
+    { url = "https://files.pythonhosted.org/packages/56/5b/4970a2d154df502e133402906dd04e3ae7cada7b3011283c88d0479a2585/charset_normalizer-3.5.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:eff0ac9dbe711a4aee69bf04a83896aa9b85f19641264053a9f6d48573abb7dd", size = 250190, upload-time = "2026-09-30T04:36:45.185Z" },
+    { url = "https://files.pythonhosted.org/packages/88/8c/f1a91bddc8fb47c2889e29ea7ea49a194eb0d9868675d786806519c00d76/charset_normalizer-3.5.2-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:1503bccbeb36d5527790c3930327704c39af22de3112f1b1666a9f3ce15ee204", size = 237098, upload-time = "2026-09-30T04:36:46.689Z" },
+    { url = "https://files.pythonhosted.org/packages/24/0e/bb5dace3cc7e79068425386a6589c19b5a2ab5fefc2a46abea6919683332/charset_normalizer-3.5.2-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:52aa6992700996af31f375de0c6bacd402b0097fe40b53c426b9f51a90ebabc7", size = 274228, upload-time = "2026-09-30T04:36:48.31Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/79/b849ad523017ea9f5a45581bbebed91439e0cf42fd2860a6f64e358eb5a6/charset_normalizer-3.5.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:e09a3942ecbdee5cce73ea9d42da82b81b72ac1bf031ce069b93b5adf4eac8cd", size = 252401, upload-time = "2026-09-30T04:36:50.091Z" },
+    { url = "https://files.pythonhosted.org/packages/89/8c/75469d690cf47200bce8f6cad7655724fc23148e147abfc5ce78b5f65863/charset_normalizer-3.5.2-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:c7c9ab723cde841fefb34efbad91e87f00a674b1fe1cd0784fde742bf2c154dc", size = 271846, upload-time = "2026-09-30T04:36:51.719Z" },
+    { url = "https://files.pythonhosted.org/packages/26/cd/6d52d3c7437cdcf2e310ce9f28f282e733d4ef60ed19105d1819c356255f/charset_normalizer-3.5.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:ddc7dacc8ece3a182e7f15cb862d1fd616b46d076cb1ae9dd232b2c38b655874", size = 258151, upload-time = "2026-09-30T04:36:53.234Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/4c/070b38bdb5f49a70199fce923ec0726a49536a63ab262abbfcaaf351110b/charset_normalizer-3.5.2-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:ee43c17b173d46a3212baa6ead3ae258eeabdae48c263a01ccf0218c366dd655", size = 143570, upload-time = "2026-09-30T04:36:54.816Z" },
+    { url = "https://files.pythonhosted.org/packages/81/84/9ebfc8ed6c8c4fcd8e726ff6bf220cc8deb3966e31dce9be8dd8aa017e64/charset_normalizer-3.5.2-cp314-cp314-win32.whl", hash = "sha256:4f87960d57feabfb618e4e0af6e7371645fa26a277860739d6e5d6e0012c92f0", size = 186412, upload-time = "2026-09-30T04:36:56.643Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/78/5ed86f743d4bc350db307e7636419a0a5ee1d91806d30c7f667bd5c80dae/charset_normalizer-3.5.2-cp314-cp314-win_amd64.whl", hash = "sha256:e4e81e09c1578b8df602e3db08b0b3ea0a6947ad612f52bf8dc5ea8d47691f0c", size = 210965, upload-time = "2026-09-30T04:36:58.205Z" },
+    { url = "https://files.pythonhosted.org/packages/53/94/a3a7698e9b1a395e1eb99ccd9a324be9347973bff4e72db2a06496d7cd27/charset_normalizer-3.5.2-cp314-cp314-win_arm64.whl", hash = "sha256:80d02b6f04e92601a081dd97b23d3128033098bff5d35d392ddcc0476ea11253", size = 200406, upload-time = "2026-09-30T04:36:59.764Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/48/c5dd00d5ef7791f02666de250a5bb6071e29b7e133cf4b835800b6d3bc27/charset_normalizer-3.5.2-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:dca9ab98072a5a54ebacebdc45f53e645336b320c667410b061be1ca588ae709", size = 396871, upload-time = "2026-09-30T04:37:01.543Z" },
+    { url = "https://files.pythonhosted.org/packages/12/c8/8379554b42e8368161d898476686947a0fdbd3e8865170d7909dcabfdee8/charset_normalizer-3.5.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f0aa869112ef88429ae17820d99c3dd9504c9e9c671d3c246f3d7442cb051084", size = 249711, upload-time = "2026-09-30T04:37:03.111Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/eb/2ddb1035d17320caa9f41682935123a9a250277b261c3efc86b2d2a21343/charset_normalizer-3.5.2-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:c0afc6800ba57ccc350374c5bd6150419915d95ce93cdbab2d783d75eaf30ecb", size = 231146, upload-time = "2026-09-30T04:37:04.721Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/24/2ecb4bde104322cd7859d6594fcfa74649f8d90b3221c9feecbef149875b/charset_normalizer-3.5.2-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7dcd882da75ef9adf94903b1e3b9419e8aa8fb4c7396822b834b9ef7fb96954f", size = 271552, upload-time = "2026-09-30T04:37:06.295Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/98/9d5f6ebc3aee9fef5d30b4aff11fb2ab7a1222b4064f8ef2c7c87cde217a/charset_normalizer-3.5.2-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2e06a3a98f916dd41d27f3105e02e7a40181c98c94b9158733d03a6f80506c09", size = 269810, upload-time = "2026-09-30T04:37:07.905Z" },
+    { url = "https://files.pythonhosted.org/packages/09/e1/a3b06a10461b1b7628853c934c644e03bc28e42767116afb52f19a56519b/charset_normalizer-3.5.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6bd128f206a7752ae1f2ab6c61bf8a24ba28913a10df8b14c2637b973ff97a80", size = 259845, upload-time = "2026-09-30T04:37:09.554Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/d3/6f561f74a296cf27d61775a1dc665ad13f3bff6a798810ca05907f37a7c4/charset_normalizer-3.5.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:c8f3d67aeaf55f017982b73683f0e7342ba2f6635a78f69ce89ebb26aa411e5c", size = 252825, upload-time = "2026-09-30T04:37:11.274Z" },
+    { url = "https://files.pythonhosted.org/packages/26/9f/69e13ca3b18f43e0eafcd34c04a45b732ae22a43b54a5fc9e119103356eb/charset_normalizer-3.5.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:fe9753dfee015c570d73df76f899f18444d41388bffcde097deba51c4fadbb9f", size = 252659, upload-time = "2026-09-30T04:37:12.941Z" },
+    { url = "https://files.pythonhosted.org/packages/73/a9/ace29806a0dae18939919c76ba526472d83214afa101105fabff2cf30625/charset_normalizer-3.5.2-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:92888bb3187c5ba50500b00b3b310c9f2c651709d28036077680cb5255450a03", size = 238819, upload-time = "2026-09-30T04:37:14.659Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/c1/6116d52a2e3311ec80f21f5fb5e17b27405f10b9608af8f6e69516841a1b/charset_normalizer-3.5.2-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:d008d90a7f2471519aef0c90dfbe73b3e6e4d5e66ac48e19154c17e89e98b604", size = 272973, upload-time = "2026-09-30T04:37:16.346Z" },
+    { url = "https://files.pythonhosted.org/packages/19/aa/9955c7e93bba10a9c7e8f7a5031b7ced66f3a1883a55c00712b8d5850ff3/charset_normalizer-3.5.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:31f3930700408d211f13378ccbe1c40845d8da54bd0681fac3a9b5aae81c7aa8", size = 253692, upload-time = "2026-09-30T04:37:18.212Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/33/2a6ae7fdc1b10cb581cef91addd8cdfc5f40d50abb5702309369d5834579/charset_normalizer-3.5.2-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:2a925889534b3748302dae5dead07cc13480de1dac3aea80a941b729b471ef93", size = 268757, upload-time = "2026-09-30T04:37:19.877Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/22/80992720a0282cd39bba1db35868e6b9c22f41281160143a836544bc1d8a/charset_normalizer-3.5.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f5ec61164adcec446f8969a3358ec3f9b26bbda3b9213e5586d219afa8df2915", size = 262220, upload-time = "2026-09-30T04:37:21.583Z" },
+    { url = "https://files.pythonhosted.org/packages/92/9f/181fd07e1bffea1d95cd80c84ac537354f50699c22cfc4d3c02b6fc16208/charset_normalizer-3.5.2-cp314-cp314t-win32.whl", hash = "sha256:598a11a2c7ebaa5334bf698bf29568c9c390abac6a154d8170fedecd1cea38c5", size = 197797, upload-time = "2026-09-30T04:37:23.235Z" },
+    { url = "https://files.pythonhosted.org/packages/49/1c/25d8415ec1c4f2f41f1680435e4c87cfb378ff2f677d950946f2a45d0632/charset_normalizer-3.5.2-cp314-cp314t-win_amd64.whl", hash = "sha256:7fdde2c9fd9e3eca40631e024664cf2584272cc8f96308cbe5fdfc930f51d8bc", size = 222765, upload-time = "2026-09-30T04:37:24.891Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/b4/46b48f013dadfc0d0d33b375438e31bdf5a989dc68389c6bf627054d4df9/charset_normalizer-3.5.2-cp314-cp314t-win_arm64.whl", hash = "sha256:d1befeed746d247c81127bb14de9dc3d30edb6e5976d34f83f86ed262b1d9105", size = 210985, upload-time = "2026-09-30T04:37:26.634Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/ab/176fbfd5b64939c55d652366aa5b9ef1d767af207a3aa6ebeb0d226c484d/charset_normalizer-3.5.2-cp37-abi3-macosx_10_9_universal2.whl", hash = "sha256:4275811936e2f06feff5e598fb42a1b7ae852da8e39605211892b56b81a34efd", size = 331815, upload-time = "2026-09-30T04:38:26.216Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/84/371eac6b30bdbcbf2d632a1a01809103459216fcaae61b8b8d922c1bfb8a/charset_normalizer-3.5.2-cp37-abi3-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:1c50fe28bbc2ced33386f298650d91218076c05420e6cbd790b913adc41659e7", size = 253276, upload-time = "2026-09-30T04:38:28.032Z" },
+    { url = "https://files.pythonhosted.org/packages/43/6f/c4fbae58febff71709c51bc7e18fdfa55341dc382704740f9f0cbf03817b/charset_normalizer-3.5.2-cp37-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:d19fbd981a488e22cd04883659ca6b08f50b5974f9fd7c95655ef6a043e5893f", size = 241239, upload-time = "2026-09-30T04:38:29.732Z" },
+    { url = "https://files.pythonhosted.org/packages/61/71/458c3f42164a07d0c5210798e9e704b39e540a6793b05aba67f3a35243a9/charset_normalizer-3.5.2-cp37-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0fed1d06615f022ee3b13caf5e8b180cfea32bb2c5aded8a9d44277afc040f93", size = 231121, upload-time = "2026-09-30T04:38:31.462Z" },
+    { url = "https://files.pythonhosted.org/packages/09/54/ab9e89367076f6331bb6c65c4bf14a5361fa5191cb6561bf534f18504e1b/charset_normalizer-3.5.2-cp37-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:838dcc90063569a0448120554591a1d6c4a4ffe11babf048908793154ab86ade", size = 260350, upload-time = "2026-09-30T04:38:33.239Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/c1/061431ecc688d9d76602502cb57cc01e691e682c18f1beb45f9673b5bbd2/charset_normalizer-3.5.2-cp37-abi3-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2ce45c6627b22c47e390bc91a41c3d13032192e699fa0bea96e9671b373d69b0", size = 255430, upload-time = "2026-09-30T04:38:34.865Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/1f/20c8949f0676f7ab811abdeb7f4d7f1cbc6e61ff20bef08b44edeb092bc8/charset_normalizer-3.5.2-cp37-abi3-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0774bf9bf620249fee3e0b8b9fd3065de213be30f3aa94ce2494b3b638949e26", size = 250612, upload-time = "2026-09-30T04:38:36.649Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/9e/46f2fa4c431fc98c4ae76a8cb5bdca54e0341e3cfc3fcfd8e82740250818/charset_normalizer-3.5.2-cp37-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:1db38f4c5496827c1a501846d64d14c3b80c7e6714e406cd7dc36a9899fa1011", size = 242083, upload-time = "2026-09-30T04:38:38.26Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/39/559be29a0c0f086e0bba6922babd38916cc5e0b58ced4de13ee01ea05508/charset_normalizer-3.5.2-cp37-abi3-musllinux_1_2_armv7l.whl", hash = "sha256:304d8e4d493af723536393eee0c689eb7813f4a474c8b479dee63f1fdd98f621", size = 232738, upload-time = "2026-09-30T04:38:39.81Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/6c/387b0e4f756a282831c1d9fc6aeb6c51ca4507ca202767c8de15ce9b12e2/charset_normalizer-3.5.2-cp37-abi3-musllinux_1_2_ppc64le.whl", hash = "sha256:9b7f416ff0978e2f2249330527f0ad6fa02f4932e6199692d3b52da2048c19e4", size = 260703, upload-time = "2026-09-30T04:38:41.346Z" },
+    { url = "https://files.pythonhosted.org/packages/96/92/1fdf015f09ef449f50d3ac4b67c90887c9c318b727daa95cc4f866e6521d/charset_normalizer-3.5.2-cp37-abi3-musllinux_1_2_riscv64.whl", hash = "sha256:01077390b03f7988f11d700a2194e69b119741a86b1a638b1db88891e3eced8e", size = 247622, upload-time = "2026-09-30T04:38:42.937Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/3c/8e7b8a5671ad5d433669fb2a76f1a0164df2d9b1718b0206bc2a16d840cc/charset_normalizer-3.5.2-cp37-abi3-musllinux_1_2_s390x.whl", hash = "sha256:7e841fb9010836c992c9f12fcbd43a831de93a5f726fc1ccd8ca1d0268c5014c", size = 257500, upload-time = "2026-09-30T04:38:44.604Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/f0/45b579df5cabc1d5d53ea1cc35e8437d3ca768c0acccc7041517cb6fbb32/charset_normalizer-3.5.2-cp37-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:9cae88599c7219005d879f98e5ed53341e9a122af585e1091200358a3003d2a0", size = 255100, upload-time = "2026-09-30T04:38:46.289Z" },
+    { url = "https://files.pythonhosted.org/packages/31/68/fdec18a343f5fb3f310588dd478b09ac4799e0b187dbade3a8cd776f03ef/charset_normalizer-3.5.2-cp37-abi3-win32.whl", hash = "sha256:01b0c0d2262a9e28e8484a278c7e1b5d650e3ac8cf2683d2967e25899f208bdf", size = 174499, upload-time = "2026-09-30T04:38:47.999Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/8a/b618149cc5207943a0242068d7a27897f56a62947b5a039085f2a22029f8/charset_normalizer-3.5.2-cp37-abi3-win_amd64.whl", hash = "sha256:9f56f72050826f63dcee7a7f55b0a77168cb3bfc553fd405e7f8f9ece75a4036", size = 200092, upload-time = "2026-09-30T04:38:49.707Z" },
+    { url = "https://files.pythonhosted.org/packages/03/cf/4c66866fa9e2b1c78e3c911516d1de497a677b7ac60f1eceda74ce777ca3/charset_normalizer-3.5.2-cp37-abi3-win_arm64.whl", hash = "sha256:40ab6bffa02ae10a0581e6c198be7d2d8ca5c2a0c64e4ed3465d766df457573e", size = 294363, upload-time = "2026-09-30T04:38:51.312Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/ad/d07d7862a62ffa6d79d68074d14823243dd235a77c45262acbf6adeb28bf/charset_normalizer-3.5.2-py3-none-any.whl", hash = "sha256:b6b751274acb69d77b3323d6b7dbaa3c7fdfc1eb829b7eb61d262f32e1af9685", size = 68872, upload-time = "2026-09-30T04:39:21.828Z" },
+]
+
+[[package]]
+name = "click"
+version = "8.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c7/0e/7fa0ef50764b67090eca4114772a2abf8b6148198475e54c660b97caeee6/click-8.5.0.tar.gz", hash = "sha256:ba0d2089de75ea0310e2dde03160e6ca10009947fb95a182f9b54021bb272e34", size = 382235, upload-time = "2026-08-26T13:33:14.56Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/50/6c0d534c5f134586a8e1ba4e330569e32f057e33372ae556463212fb4cd3/click-8.5.0-py3-none-any.whl", hash = "sha256:255bc9599cf7748b4b1a446ccc735421bd08a2ae529a8b88597d3de5664ee360", size = 125251, upload-time = "2026-08-26T13:33:12.928Z" },
+]
+
+[[package]]
+name = "colorama"
+version = "0.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
+]
+
+[[package]]
+name = "coverage"
+version = "7.16.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/2f/55/d1eaf3e73781174340a00dc1ba2aee8a65f82fadb18e2797b192b6b3925b/coverage-7.16.2.tar.gz", hash = "sha256:ca64d9f1f384f151b9511bec01126072acd2f313439f8ed015a22d8790aab6fa", size = 971999, upload-time = "2026-09-27T12:29:01.118Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/59/4c/577fc0803dab4155dcf808faffbdd7b159256781c0874a8586e17b81b149/coverage-7.16.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:4ee546b9e4872ffa194bf07ac87bfa1202ebb824d0795dc1ef22f175545ca90a", size = 224138, upload-time = "2026-09-27T12:27:05.141Z" },
+    { url = "https://files.pythonhosted.org/packages/75/9e/e3785ba3ecba2bd11efc74bfe2801ca4b78c4480b15a375648d809a59da3/coverage-7.16.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a2fac6895eb299a2e52d7bbb8fb3903502b9da8d3f5309ceb16ec40c646b58ee", size = 224445, upload-time = "2026-09-27T12:27:06.805Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/d0/963ff22d3fd27117da3b8cc442f5bdc91196f783321e1a8ff0ec43476772/coverage-7.16.2-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:57ff3783f99d75a1e81dd56a9737eb5665e6736a5d93258ba596b6dcad8fd05b", size = 256112, upload-time = "2026-09-27T12:27:08.43Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/d4/a306940c81c6ae759e82fff27d20b7fdc6896e422b821f51313cce212b6c/coverage-7.16.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:35f37886699cb9abd29958247d718628d5bc6f39e623dff66a09e546c42a7e03", size = 258727, upload-time = "2026-09-27T12:27:09.927Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/a3/d3d99d93b02517087aa05bc0cf2d04d372956b849e5443e059079901429b/coverage-7.16.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0fd7a86fdda7cb6d616d178654bd0ad6bc0f3f33c2e478aa598500a1a9e34eda", size = 259909, upload-time = "2026-09-27T12:27:11.55Z" },
+    { url = "https://files.pythonhosted.org/packages/08/44/39dd599181726758dd185ae4dc0c0ab3aeabf7ca70e68e145060feeaaa16/coverage-7.16.2-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ac0f3b379c94acc2f7dce5f5f0b24d44fa1cc6a509717ef83dfee07450c2117c", size = 262481, upload-time = "2026-09-27T12:27:13.17Z" },
+    { url = "https://files.pythonhosted.org/packages/99/e8/91ee43f6ded411460c359d7e1aebde4d6fd8f00a2e5394182d9d212eb23c/coverage-7.16.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7d0732c83746bc24123c581a85d9dd96b70ddb538c9076020aa1a041790361e9", size = 256012, upload-time = "2026-09-27T12:27:14.91Z" },
+    { url = "https://files.pythonhosted.org/packages/11/8c/e9499ddc33197bd7eabcb1118ca81756fc874457b324e2b479a4804b2ad2/coverage-7.16.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7b451c68218c150f616bc9649783ec8de76a59792c759b43aa0c9c0466a465e4", size = 257898, upload-time = "2026-09-27T12:27:16.588Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/6e/c081cb5991a0afba99f9c4ad6c74a5fce9513a38ddc64e3e6680c6fed9af/coverage-7.16.2-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:a56ac4fa5a75c7e182e8f62600cfb4aff43c5ed7356a034f3557659c3bec1d90", size = 255938, upload-time = "2026-09-27T12:27:18.19Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/42/1c3d819e8f9b6eb01c2fe90874d67a8882adb9507e0bbb09361ed131ea89/coverage-7.16.2-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:4cc4f73aa3fabc36e32046d6cd2971405948d8a903636508a3d3b2f9128b3a95", size = 260368, upload-time = "2026-09-27T12:27:19.903Z" },
+    { url = "https://files.pythonhosted.org/packages/19/4f/d70eac07901fd587b6ab05e659b52afe13959992aa5113bf6cce059cc572/coverage-7.16.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:723dcdab91357159b722935b500ee8abc0a66c8c432e1e9fabf4cc7598952de8", size = 255620, upload-time = "2026-09-27T12:27:21.621Z" },
+    { url = "https://files.pythonhosted.org/packages/34/5e/6d87af88317d3d9a9b18a9ca1bc1673eb516917f296e579d0d4a55cb3490/coverage-7.16.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5397e21a90dde0e9c6896b77ded8f0be26b66f8b22b33aed41f6043ed95d55e6", size = 257521, upload-time = "2026-09-27T12:27:23.358Z" },
+    { url = "https://files.pythonhosted.org/packages/79/bb/90c2641170d2fa1a6757b3f8450ba2740197317b0ddd749e9604b914e886/coverage-7.16.2-cp314-cp314-win32.whl", hash = "sha256:848893e1d361448c113dc2f0913503522a6f7be231d0e38333d2a22d9698a011", size = 226248, upload-time = "2026-09-27T12:27:25.153Z" },
+    { url = "https://files.pythonhosted.org/packages/30/08/d8d0478bb02c8eb0ae20a496fc80c40fcf4d3450bd184300d682ba2d28a6/coverage-7.16.2-cp314-cp314-win_amd64.whl", hash = "sha256:5a27b731c171e43dc8b5f32b76a5051dde2ec9b9366c87028f08a7088ebc2c7b", size = 226732, upload-time = "2026-09-27T12:27:26.907Z" },
+    { url = "https://files.pythonhosted.org/packages/32/3f/0001da22155b0a8ce063ec0f7e64ecbe17b373f306e7a74435f6d6accb72/coverage-7.16.2-cp314-cp314-win_arm64.whl", hash = "sha256:1c569a9fd25505f1cd6bea90588818f90373ce90e2632e2cacf19ddbd6e14fdb", size = 226645, upload-time = "2026-09-27T12:27:28.588Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/85/6d8813aff9b8b8586691a9d33c43c5604f7227622574da7cdc3d91a86861/coverage-7.16.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:d93db87adb6b1c1b408dce4763314b55d76a9f589e96783a84ac9e7689e48bdf", size = 224871, upload-time = "2026-09-27T12:27:30.32Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/70/444f3a4981ac2cda40fdcf4cc9b56a4e1a33c222abeb33e51ed3e3eb2a6b/coverage-7.16.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:aa62c85046473959c13ba9edca9dc90a77d5c1095b1ba313556314d77fe5b036", size = 225123, upload-time = "2026-09-27T12:27:32.33Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/c1/980681cd7b33eb66ac835044116ef0a92e11fcc7bdd866cc89d10b1130b9/coverage-7.16.2-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:db76506aa5416081f3e8974ae0f7965c58ada0bb0ef7339ac86099588dbb20d3", size = 265049, upload-time = "2026-09-27T12:27:34.085Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/e3/87679875c33bb2191f0f05544a1cc9adcc940fe0c35443a10f2df753dde5/coverage-7.16.2-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:a0f2285329dac10ab08f79cb11f5692c497018e6c7c511f95e6fd63a70b8f831", size = 267717, upload-time = "2026-09-27T12:27:36.025Z" },
+    { url = "https://files.pythonhosted.org/packages/76/64/5d372776d6eb523d4e93bafba2253f96984e3b18261c4cc56a50863c6d0d/coverage-7.16.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:382d3346d56b0eec1b793d53a4c88799c8053f516aa3a8d7c44315696954bacf", size = 270047, upload-time = "2026-09-27T12:27:37.96Z" },
+    { url = "https://files.pythonhosted.org/packages/be/c1/44082ff0cbf9f97d0043f57970a71204097ec7ba606361a9fd2065393669/coverage-7.16.2-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:648352b94507179d82637292e7ae8802508d95f78e2f00a705a50b6c48011681", size = 271360, upload-time = "2026-09-27T12:27:39.766Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/17/9a215efe25b5e0ecc87c89dbe525c4a87d14d87c8c0c7316ef140a5f6f3e/coverage-7.16.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:fb2bde05838fffae1a1bf75e5d411a6cac3e4e9bb97e6640fed8cd47888b33f0", size = 264736, upload-time = "2026-09-27T12:27:42.072Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/da/7f0a31af8e448107d4d32844bd684757f51ea907bc0c68c8fd537b2123ff/coverage-7.16.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:6a75180829efb8ae62b4aded25be6ddca1c888d138d2d82e21d93bfbd88f41cb", size = 267600, upload-time = "2026-09-27T12:27:43.85Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/a4/3bfecbd3366b775bacdcb3330394d356cf384b5d8f5b2146ac4b14b252b5/coverage-7.16.2-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:99704f73721e23859112072d522076e11c31744fc96b5652e5dd2018aa4359f7", size = 264767, upload-time = "2026-09-27T12:27:45.768Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/3f/5d62163732d87e4a0c4710a0eab30f0fd6a2d480112abe2029f014fe8c9d/coverage-7.16.2-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:29309ccc86b7f33df7db12813c299f215bbbc470ed6292d0bedd63ffae1ebf64", size = 269026, upload-time = "2026-09-27T12:27:47.787Z" },
+    { url = "https://files.pythonhosted.org/packages/49/4d/8e4579f225426535085a9be371cc75e3b026d058d679b80affbdfb4c3ef0/coverage-7.16.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:30c1b65d529e46569899fadca59e4a87c1faf2886923f1307ba61e654d4f3c20", size = 264147, upload-time = "2026-09-27T12:27:49.681Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/36/ef1f77e2c3f7bb03c2b13b9a2006f88700fdd75535ef158d70049f425c1c/coverage-7.16.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:dcf4bc2aab4e16b1c4c0c2005918f23a7dd5d7821ddae82caed9e3342dc2fcce", size = 266376, upload-time = "2026-09-27T12:27:51.551Z" },
+    { url = "https://files.pythonhosted.org/packages/be/79/0cb2bf4428830dec971c718c2c841a039c084415c99e67281f5a72841aab/coverage-7.16.2-cp314-cp314t-win32.whl", hash = "sha256:a9cd3de0a5bfe7b0e21ee10e1a14e3d61bf52efc88217ab1d95d6ace6970bd46", size = 226585, upload-time = "2026-09-27T12:27:53.945Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/f9/da17121c16667fd84998e972200ae226a41540f6ea4795776c6d99e8976f/coverage-7.16.2-cp314-cp314t-win_amd64.whl", hash = "sha256:611a44e5229a59d7483ce830160e1a0e85f700562c7a5651c7c63fb8f4eb528c", size = 227378, upload-time = "2026-09-27T12:27:55.778Z" },
+    { url = "https://files.pythonhosted.org/packages/74/89/01179c62d1b7e6e33bd5001566b02d7f778cf33d3ec1e81e94ca170c517f/coverage-7.16.2-cp314-cp314t-win_arm64.whl", hash = "sha256:22957cef43ce038641de78ba995de7568d2d6a37c6ddbf7fa0fd7d1ae2344d91", size = 227064, upload-time = "2026-09-27T12:27:57.496Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/0c/7a64e1ac90541a8edf50daef0914848011fb057a5bf55284a4811e21939a/coverage-7.16.2-py3-none-any.whl", hash = "sha256:11d28e9123a9156cb405d8d27b44256c9a58fb5decc2073a8f17862057e3aa0f", size = 215754, upload-time = "2026-09-27T12:28:59.075Z" },
+]
+
+[[package]]
+name = "cryptg"
+version = "0.6.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/9a/cc/3cc53619c07ab1def2f0ce7a958c10528c947e973821234714cfc61d7dd7/cryptg-0.6.0.tar.gz", hash = "sha256:f8fd59fea56398ab812f218c044b42fbbaeee8a9ae32771d3108a3cf210781aa", size = 15019, upload-time = "2026-04-12T13:31:09.978Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/68/ca/740ba5201f47d50cd24809719ddff38b8a5d950f9921e426a0d2990de084/cryptg-0.6.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:7eb4e335ac3df00333c202cf98e65edbecd8983c9a639c11d93f1f369ae64e05", size = 208586, upload-time = "2026-04-12T18:33:54.23Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/d0/cfc3664d4b8c57f2058278472de7052719d2e37aece5591512d07e14777e/cryptg-0.6.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:28f6ca127a907d00ad075252e8d970bbac55e7f3df0f66a277f52b986fab0a57", size = 238396, upload-time = "2026-04-12T18:35:19.201Z" },
+    { url = "https://files.pythonhosted.org/packages/16/59/abc03cb099cec7b5e28866a8401040b40e99c719f3bef49fa7a0b302e09a/cryptg-0.6.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:4127534527ff741026b981359083da660010ddd556eb5e0f22523b9ce0fe80a2", size = 250040, upload-time = "2026-04-12T18:35:38.802Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/6e/707de2c52842f093ab05811d002214e284c50f18057160352d7baa4ef1fa/cryptg-0.6.0-cp314-cp314-win32.whl", hash = "sha256:9c823319f6ff00c3c04be00cad78bd6555ccfc832fffc6b709eb983bbe0182b0", size = 112774, upload-time = "2026-04-12T18:36:08.654Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/49/6d8c6313789c3649f089a5f277369013072a5f8d96ba93d8c83def9c4a75/cryptg-0.6.0-cp314-cp314-win_amd64.whl", hash = "sha256:0776b0256cd79ff202dd4c187872eb309bbee7ea63b9be722f9063b232b42ecd", size = 112208, upload-time = "2026-04-12T18:36:10.289Z" },
+    { url = "https://files.pythonhosted.org/packages/de/31/3df7c7bfa022b8e49fba5bd511226eb8ab02b335832441dc9d5c07a154e7/cryptg-0.6.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:877e872b0967f03d008e2cb16a1aa44c8011b2f200bdf14771e6f783228e8bce", size = 207943, upload-time = "2026-04-12T18:33:55.483Z" },
+    { url = "https://files.pythonhosted.org/packages/06/81/dea9beefd7317c353484a5736ce3de69ef9c1e84a93ea46cbe47f04a7f18/cryptg-0.6.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:b8ba3ed799086af279c1efb7bfa72b226dc9427f85034ab0b05ff23bccb97b45", size = 236856, upload-time = "2026-04-12T18:35:21.006Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/f1/fcc52170486f35698229b573c0b6bc844f0504745f43fc47fde0cb61888e/cryptg-0.6.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:ae96b26dfb53968fe4986f70222f2419c82651936f2ef3b2c2dc47bc74e77d96", size = 250297, upload-time = "2026-04-12T18:35:40.577Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/d5/5041385f3a55d6eaa8f86c79e9fbb799d09680977619d506e35c09a9a3f9/cryptg-0.6.0-cp314-cp314t-win32.whl", hash = "sha256:e4988fd1657aa86d91bc98d8262b78b141dec8ef51a843f1ef78d69e8a81fdf0", size = 111989, upload-time = "2026-04-12T18:36:05.193Z" },
+    { url = "https://files.pythonhosted.org/packages/88/08/86db1d558e836c75724ef893c024d3f087886d1f8b173f2f64164505e256/cryptg-0.6.0-cp314-cp314t-win_amd64.whl", hash = "sha256:43f195810c642c6f6c552d291a216a5b5cb36b06aabe2832873db9dde3e65bb1", size = 111602, upload-time = "2026-04-12T18:36:06.81Z" },
+]
+
+[[package]]
+name = "cryptography"
+version = "50.0.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9d/af/182eb91b0df3fe75c4d9f26fe70684569566745f6ba7e5c9c73a862c5252/cryptography-50.0.2.tar.gz", hash = "sha256:7b46165bb56eb4704e2eaaf86f3c940d19154535d9b0ca7d6d590b04060e00d5", size = 880623, upload-time = "2026-09-30T15:30:04.884Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/56/d194340cc4a57535e82e1bee9e89667ac4b7c13b5d3f59686deae3094dd5/cryptography-50.0.2-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:fa8f5efb344d6908a1ce62f4a24e2e5780f825d6f53f5f50ec5ffacac72936cb", size = 3914904, upload-time = "2026-09-30T14:43:44.339Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/69/c9bd862c3bf43d6399c433caf002df16e2dffd4be49bdf515cda38038711/cryptography-50.0.2-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:79def8d059362e7831389ed3be0ecdf58a89386e1271e35dd9f5af84e81bffd0", size = 4731146, upload-time = "2026-09-30T14:43:47.113Z" },
+    { url = "https://files.pythonhosted.org/packages/21/69/64cef1f702bf6657e0cc186ed1a2891d50d29fb41586b254e1c07adea261/cryptography-50.0.2-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:630ebfea3bf689d075f82316324ff7433dc447fe6bc1bfc76524b74b4a9567d2", size = 4719841, upload-time = "2026-09-30T14:43:49.01Z" },
+    { url = "https://files.pythonhosted.org/packages/38/6b/61a3f8d8c5e1e49a6cddccafc4015cc1c0021360ab0acb4080e7a423644a/cryptography-50.0.2-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:f9f6143a8c75945eb960d9eb98905a441394abfa24afaae239d514ffb2586480", size = 4738340, upload-time = "2026-09-30T14:43:50.932Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/2e/7212ca32fd43dc91f2f41db20160b268098874b4c9a0e7be94d6835f5b2e/cryptography-50.0.2-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:a582ab2ae1d34f67112cadc86702774c9ea4374df6bca6afe672817203c99134", size = 5367029, upload-time = "2026-09-30T14:43:52.911Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/f1/b474e930c4d910328780e3940da76f5aa5cbc48ce1fc14e44d239d9ea9db/cryptography-50.0.2-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:4061c0079120205fb760c58acab6443e217307dcf05e3702cf970e0689972856", size = 4753050, upload-time = "2026-09-30T14:43:55.272Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/52/9af10e80ac16b0fcc2123f9cbd5e7afbd0fd5075bb7a607c592258a39cda/cryptography-50.0.2-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:ac9ed99d81760c62fe89d5f0815cdfa1ba9a35141cf30f1c2d044f04b4803d2e", size = 4376724, upload-time = "2026-09-30T14:43:57.24Z" },
+    { url = "https://files.pythonhosted.org/packages/71/37/6202e488cc1eb625ea110c292c6bda92823176e023f427d8d5660ce8d632/cryptography-50.0.2-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:87e9ce85beb6b328ba370cc6e6aea483c92617b4c95b1d33a49297eb662bfb04", size = 4737859, upload-time = "2026-09-30T14:43:59.541Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/30/e86d7d518489b0ae2497091a35287abcb1a2ce4037837a34afbe9b1d6964/cryptography-50.0.2-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:f265528741e048bce55c3463ed721fb0aa45a5888d8add8cfeccb3035451bbdc", size = 5324103, upload-time = "2026-09-30T14:44:01.901Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/69/2c833a049475e0a3444e94c7d0aca0aa51d166374a449b09e92ac98138de/cryptography-50.0.2-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:9dab55f57c74c3cad24c323bacbbd04be4705ba6eb0d92e920b1fc4837ed5079", size = 4752576, upload-time = "2026-09-30T14:44:04.545Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/5d/906970b83bbfc1f5bbfb677a143c181f2801f23b6a7204a3b47c42c97e65/cryptography-50.0.2-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:25784ce8b9621c90c643efb9e1e2162ab3b0224cae446ad5e70e7fcb1ce18b51", size = 4870819, upload-time = "2026-09-30T14:44:06.884Z" },
+    { url = "https://files.pythonhosted.org/packages/68/e3/f2298d3bb55e0c4a91841ec4d01b3f020ba8c5fbf15ccdcc6dcf03f97025/cryptography-50.0.2-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:85d0d9a31b9098e98534226d5686b47264b95e62ce459dc2e62fdfc809f9fe93", size = 5030152, upload-time = "2026-09-30T14:44:09.443Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/4f/adfc442765721292fff86d314ce385d3249d22db42295c0dd057727b60f3/cryptography-50.0.2-cp311-abi3-win_amd64.whl", hash = "sha256:7afa5a6602a9f29af1f3a2965f831bae7c9d5d597b7cbb716d41ab3b7d89879c", size = 3824692, upload-time = "2026-09-30T14:44:11.671Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/cb/52eb3770c0d0be2702a98c6e96065ddc0a2877cf0845aa9c23397c142cd4/cryptography-50.0.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:f785f6161f202ab04d8ca194158968798e480ca058943907972da5f12e2881e8", size = 3892731, upload-time = "2026-09-30T14:44:13.485Z" },
+    { url = "https://files.pythonhosted.org/packages/19/8e/aa1fc533d4546b127b45de8aa024eb5933d23eff9debfe25931e56861095/cryptography-50.0.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:0ecbc5652bdb6fc9eaf89a7d196e20941adfe812f43bc4ca05d9150496821047", size = 4710431, upload-time = "2026-09-30T14:44:15.427Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/64/72bc3f75176e7e406b748a3e3830432b8c51297b38368713df04dc04898a/cryptography-50.0.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:ab50ee449bf968271e820086f10a33d101dd060370abc10bcd22279be2656539", size = 4694824, upload-time = "2026-09-30T14:44:17.69Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/c6/62c77550edfa5ca3f14bf44a1e6739b9fa09d6e998a11d97ed8213bccc98/cryptography-50.0.2-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:a9f7355e6fab51f6c369b86fb7571cffa05edee2c2121e0380a37fb9ac1cd5c1", size = 4716967, upload-time = "2026-09-30T14:44:19.661Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/37/cce70f150c432914460157a6ecc161752e053aa5ec0ef3b3f7dc6e31039a/cryptography-50.0.2-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:94e5e9f108ee10471288214d3d233fbfbb492840a8457eb85178d643ddeb32c7", size = 5328676, upload-time = "2026-09-30T14:44:21.744Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/9a/6f2f0304d634ceafdeaf23e84537336664ac419b5d07611675c2ad3f6b7a/cryptography-50.0.2-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:241449bf940a5d27309bd317e6f9a2af6932113818bb2b8f5c59ddc7ef16da18", size = 4727698, upload-time = "2026-09-30T14:44:24.178Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/de/66bcf9244d118663b2e1aaded8990f4640e3d7b7411870a5765f252074d2/cryptography-50.0.2-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:d8947001be83df1394050758ce0e745dd74fb134eef0a4b5124208dfc3a68c37", size = 4354821, upload-time = "2026-09-30T14:44:26.263Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/e6/db28a28c7b6c676addce89136de3d8db49ea825a8c863472e36e42ead4ad/cryptography-50.0.2-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:4a20ce1e5cb4284a86692fdcba7cb8754185c6b2e5c56fcef3751cf451d3cdc2", size = 4716748, upload-time = "2026-09-30T14:44:28.447Z" },
+    { url = "https://files.pythonhosted.org/packages/30/96/01546c7f69ea0e2ab790a2e4f0934a4052fb9b388147fbf83c2fd72f1e57/cryptography-50.0.2-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:84f964e537f916e2cc85199e5a88742e964939b575ac8598b3f9d6cc416cdaf1", size = 5285085, upload-time = "2026-09-30T14:44:30.704Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/01/03263395f74d50b071e9e66daace3f8bef80493e5d410726f2ba8554736b/cryptography-50.0.2-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:828d49b0ff5a0e3975865571c5d91dbbdd0d38d8289b249a163e9425413a5e05", size = 4727268, upload-time = "2026-09-30T14:44:32.92Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/94/2bfe8f29ec0cc9c0d99359c4161adf32858e4934b72c6d100d2ac0bbe962/cryptography-50.0.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:deb9fde5c60e437ee4821bc9bc39ff31b42135c27e1dc61ef0a629389c1de62e", size = 4849503, upload-time = "2026-09-30T14:44:34.969Z" },
+    { url = "https://files.pythonhosted.org/packages/54/44/e80651ecbf0e42b62e2bb5f5768916e07eea72e1297338956a61df361f88/cryptography-50.0.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:8c71ba2cd31fc93748c38e1b613200ff1c2665cbfd5341fe3a61cfde35a1430e", size = 5004057, upload-time = "2026-09-30T14:44:37.064Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/cc/1d33befb3cd7ea7e77d2d73f43f2066471da1b21f24a6156efcaabf6d2e8/cryptography-50.0.2-cp314-cp314t-win_amd64.whl", hash = "sha256:78198641e5be9521beea5aa782bb551a58068d10e6eb04c9c680c1b69f2e7d45", size = 3795868, upload-time = "2026-09-30T14:44:39.71Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/49/93f6a6e7a87c9aa68d44d3e1cdb5fe8f60c90d5d2f46acae9a56892816b8/cryptography-50.0.2-cp315-abi3.abi3t-macosx_11_0_arm64.whl", hash = "sha256:edc3342adf8f697fc5f59c887a304356f147b397809440ed64e2fa6af2f50f37", size = 4133708, upload-time = "2026-09-30T14:44:41.807Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/75/32ac2a56243d778805c16ca6a32b8f74fb757df7e28d7ecb560afafb59cf/cryptography-50.0.2-cp315-abi3.abi3t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d370b8d1dfcdf7130178137f6fbee6140774a1acc6cacefc4b42643ec11d0a3a", size = 4956267, upload-time = "2026-09-30T14:44:43.693Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/a4/2c8d734e43d97f0842ee9f1b7b4bfb3d0cf5e19edebf43c2afe6675c2320/cryptography-50.0.2-cp315-abi3.abi3t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:f2f9bd7f90c64fe89253f0a2c05e3c4856072660429ce8831b4235bf29403a67", size = 4966465, upload-time = "2026-09-30T14:44:45.769Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/58/ee288c829a6f41f6235ae9dd33d82fd19b45442b65b4c8a3da36963d9f7a/cryptography-50.0.2-cp315-abi3.abi3t-manylinux_2_28_aarch64.whl", hash = "sha256:e275096ea1e60cc595cda2836fd4a6c725d1125108b868be17f53684d164e2cc", size = 4959356, upload-time = "2026-09-30T14:44:48.211Z" },
+    { url = "https://files.pythonhosted.org/packages/92/20/9ded6d51ddd9897f6b6e81fb9ebea7951d7cc5d6c890b0ed8abf77a51a80/cryptography-50.0.2-cp315-abi3.abi3t-manylinux_2_28_ppc64le.whl", hash = "sha256:b13478603dcd0a2479ff8e87e2c19a7d525734686fe3c49542472293a204212d", size = 5548822, upload-time = "2026-09-30T14:44:50.86Z" },
+    { url = "https://files.pythonhosted.org/packages/02/a8/8df951850d6b31d2a00218f19e2b3f999523437ed7a819df7fa427942fca/cryptography-50.0.2-cp315-abi3.abi3t-manylinux_2_28_x86_64.whl", hash = "sha256:58a0c478eeca76fe5e07993c5a0703def34a6dc6a0cda4f5564639b33112ffe7", size = 5001199, upload-time = "2026-09-30T14:44:53.379Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/f9/36b3022218ce75b7cdf068fb95f809f9bd0d820e4955ef43b90c255cc7ac/cryptography-50.0.2-cp315-abi3.abi3t-manylinux_2_31_armv7l.whl", hash = "sha256:d38cdff612d06fa6a32840d5e1b1f7a27cee4a349aa9085d94a67789d6bfd408", size = 4629333, upload-time = "2026-09-30T14:44:55.635Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/72/20f99a219f6af47cdd1cbd978c243b92d71496e168a746138af44ded4f29/cryptography-50.0.2-cp315-abi3.abi3t-manylinux_2_34_aarch64.whl", hash = "sha256:fdd28f912fccfec1846a94e2e1e8f9b0012f557f0c46fe4f3eb0d7a87afcf90b", size = 4958822, upload-time = "2026-09-30T14:44:59.639Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/20/196f112617fb08eb4d608a2a6c422373d46f9cc2857f38fc0667033c0899/cryptography-50.0.2-cp315-abi3.abi3t-manylinux_2_34_ppc64le.whl", hash = "sha256:cbc8738fd8526d80f35cb3a40d41f41a2e7030bb3b18b09a6778ef63d291c2fd", size = 5506351, upload-time = "2026-09-30T14:45:02.267Z" },
+    { url = "https://files.pythonhosted.org/packages/24/95/83378121ef3eaaaf71d4b781577ff794acb39b9e1b87a3f156898c8497ed/cryptography-50.0.2-cp315-abi3.abi3t-manylinux_2_34_x86_64.whl", hash = "sha256:e105ab60406787da31fccc883fc0f733af1efd78f0136a4599692c4083a73d0c", size = 5000859, upload-time = "2026-09-30T14:45:05.009Z" },
+    { url = "https://files.pythonhosted.org/packages/22/f7/70fd7ae4d1dbfa7ba29b02e1b9068771519a86027756510b700ce81086a8/cryptography-50.0.2-cp315-abi3.abi3t-musllinux_1_2_aarch64.whl", hash = "sha256:6f8700550aa1474a91e5dc07049c46f98b423b5b1ddd0483e0b51362eeeaf5be", size = 5092151, upload-time = "2026-09-30T15:29:15.932Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/be/688367b74de86984bd58d8efacfc7c9e68b89a6a22ced0fb4f38db50254a/cryptography-50.0.2-cp315-abi3.abi3t-musllinux_1_2_x86_64.whl", hash = "sha256:c71be1cbfa5cd9a41ee452acf1eccd82b2c05950358b106ec8ceb83411d1a020", size = 5286120, upload-time = "2026-09-30T15:29:18.309Z" },
+    { url = "https://files.pythonhosted.org/packages/39/d1/55f8a3f2ef5d1529e16835ef10cf0fe3d559ce237b46dddc440c0bba3649/cryptography-50.0.2-cp315-abi3.abi3t-win_amd64.whl", hash = "sha256:c423ab384a46c4dff7217b2ea5ba2e11cffdeab6441acd04cf65a369caf0366c", size = 4111557, upload-time = "2026-09-30T15:29:20.155Z" },
+    { url = "https://files.pythonhosted.org/packages/23/ad/ac987755d00e1e64273760228d2635ae38dae2be83e3c6e0d3289d91dec3/cryptography-50.0.2-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:0ec5f09541743261e66e291b4a0cbf0fb2997aeaab6d9e9c740b9dba1b58d1c2", size = 3943588, upload-time = "2026-09-30T15:29:22.265Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/8d/6d585339bedf85d45044c85d8412dac53f2bb6f918e8b7777efba1787844/cryptography-50.0.2-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:c5e67125c7dca78d199ec4e116aa93dbb83494808ecbb8211a2cb09b1bf41dbd", size = 4756166, upload-time = "2026-09-30T15:29:24.58Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/f1/1c1f6874e8550cfddd4b688ceb38cefb6ed15ceed224d56f133f3d88c214/cryptography-50.0.2-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:ee247f5c245c9a2fe7c8e2214e295918838e44e00a45a6718451e4004219e767", size = 4749145, upload-time = "2026-09-30T15:29:26.807Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/63/61b15dc1a8de03fe0adbe3fd7608b3ad5c73bf50993bbcb1faaa930afe33/cryptography-50.0.2-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:dfe9763530994147d9af1def057a5b9658b00e8f8fe8743d144d1e0911c2e454", size = 4763638, upload-time = "2026-09-30T15:29:28.588Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/35/b345bdfa40c9126df1a9d33236aa98418367931b8725f84fc3ae2b98dc59/cryptography-50.0.2-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:58ddb5a8e3179d12f19e4ea34d2d32e9d63a4baa142c875c1eb59f41b7243acd", size = 5382217, upload-time = "2026-09-30T15:29:30.589Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/87/ef344a9e616871f2519c22d6afcda79ddd5d35e9592d95eb6e677608d055/cryptography-50.0.2-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:f21e8a22c8605750c7af886bab299a363721264061b4ac0a30efb73cfd58efc5", size = 4781387, upload-time = "2026-09-30T15:29:32.605Z" },
+    { url = "https://files.pythonhosted.org/packages/90/5b/f2fdb13cd0b96f6f932c8627bb292a45f11c64d21620a8e120aee9a3b848/cryptography-50.0.2-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:9c8402a82ea0dc4ceeab793db05f0fafa8ca139ca34fcde5df0f596103c74107", size = 4403790, upload-time = "2026-09-30T15:29:34.374Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/ce/7e4f662b1e3c393513569e402cfc85ac7da0bd3d5435e122a3140219eb2d/cryptography-50.0.2-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:0ddc924c04591c2811ca024d62ecad4f7f6f08af8939c211438f48a16bd23602", size = 4764319, upload-time = "2026-09-30T15:29:36.149Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/3f/86ff33ce34cc0de6847fb96e035a1a760d81652e38643f617c02ad32ef7a/cryptography-50.0.2-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:a6557e5f38e065ca9fbdaf7cfc7435ecb1d113aa81a022d1b51921ee7432e227", size = 5338560, upload-time = "2026-09-30T15:29:39.053Z" },
+    { url = "https://files.pythonhosted.org/packages/40/cf/6b5c8e2fd9202d98988ab7cb5cc5c991704c4ad55f492ff408e4969f83f1/cryptography-50.0.2-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:1981f1db4630889b9ef7803fadef12b056f428cb6b85c27ba57b774793b6093c", size = 4780973, upload-time = "2026-09-30T15:29:41.251Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/8d6ebc7dded797bd0f0160d52188021211f011a2b164ef0ae1dac4587465/cryptography-50.0.2-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:7a8701d6b584d76e909e3d305b7d126b41439876a5aaf76cddc67fc230eafa2e", size = 4897738, upload-time = "2026-09-30T15:29:43.106Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/aa/f3f6e0de7e6253b8baa8b2d8fb9d50924fa75cee3d4624bd4bc1208ee923/cryptography-50.0.2-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ce47f66801c20ec6c6632453bb5960fe38939e9306970b48b3a5a26de7745d94", size = 5058280, upload-time = "2026-09-30T15:29:44.827Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/b6/a1faf3a27ae9405fb34b1713cc73b2d8a26b04d5c561578fa2e6ef3e5bb9/cryptography-50.0.2-cp39-abi3-win_amd64.whl", hash = "sha256:4e81d95e5bafc2d6e34e4bed780e53e4d5b9a2f928573428aa4d35fbec1eb0de", size = 3854095, upload-time = "2026-09-30T15:29:46.782Z" },
+]
+
+[[package]]
+name = "cyclonedx-python-lib"
+version = "11.12.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "license-expression" },
+    { name = "packageurl-python" },
+    { name = "py-serializable" },
+    { name = "sortedcontainers" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/17/40/6509e6cfd7f2f3255501690f46375fdd224949e21fd1e96f4f4c8a9041b1/cyclonedx_python_lib-11.12.0.tar.gz", hash = "sha256:16767c4039de90c04e9f03348f8f0ed4b8ff842eaa7eefcad3a95685f970dacf", size = 1445378, upload-time = "2026-08-13T07:52:18.675Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cf/f0/b2cb999244f2f4194df63ecff6939228178fa63a33be809c412684ca8db7/cyclonedx_python_lib-11.12.0-py3-none-any.whl", hash = "sha256:0e807521a921a5c3cb8ce1153f8a61d29eedfe76a46aac2796b7c6b573391a54", size = 529453, upload-time = "2026-08-13T07:52:16.836Z" },
+]
+
+[[package]]
+name = "defusedxml"
+version = "0.7.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0f/d5/c66da9b79e5bdb124974bfe172b4daf3c984ebd9c2a06e2b8a4dc7331c72/defusedxml-0.7.1.tar.gz", hash = "sha256:1bb3032db185915b62d7c6209c5a8792be6a32ab2fedacc84e01b52c51aa3e69", size = 75520, upload-time = "2021-03-08T10:59:26.269Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/07/6c/aa3f2f849e01cb6a001cd8554a88d4c77c5c1a31c95bdf1cf9301e6d9ef4/defusedxml-0.7.1-py2.py3-none-any.whl", hash = "sha256:a352e7e428770286cc899e2542b6cdaedb2b4953ff269a210103ec58f6198a61", size = 25604, upload-time = "2021-03-08T10:59:24.45Z" },
+]
+
+[[package]]
+name = "dnspython"
+version = "2.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ef/4a/50822184bd67cc6493f0fb6a880749158fcd31ab3fa07409acfd91f9fc85/dnspython-2.9.0.tar.gz", hash = "sha256:b44dc6b18f07a8b1c56676a19fbfdb5209415b046a9cece286baafa87ff3f7f1", size = 423560, upload-time = "2026-10-09T00:07:24.352Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/10/02/cdcc9b7c051786a103c3b09e1003a82fa0c66bcb91ffbdabcfbf7b4163b9/dnspython-2.9.0-py3-none-any.whl", hash = "sha256:9a4aedb833c3c1b49214d04d44d3032ab7a9135f7c1d29a549b4ff78fd82fda9", size = 354822, upload-time = "2026-10-09T00:07:22.622Z" },
+]
+
+[[package]]
+name = "fastapi"
+version = "0.143.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "opentelemetry-api" },
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8f/6a/ac6ec87026038fb7583018e0905f6c9d55bc8ee07d30d44c743f18b19435/fastapi-0.143.5.tar.gz", hash = "sha256:0b5c8e52d243cd2f015376b41e78db5bee585578782481abd145e1ab5a62a3ba", size = 470247, upload-time = "2026-10-18T09:12:55.556Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/eb/4e/5f7d1268900eb14a6697a42d94c8f7e3b8450d27301761f231672f928419/fastapi-0.143.5-py3-none-any.whl", hash = "sha256:09cc38ed8c6a95f407783ef4d98ceeb350e192fe8fbb8ed711070bcd5208fdfa", size = 144894, upload-time = "2026-10-18T09:12:54.125Z" },
+]
+
+[[package]]
+name = "filelock"
+version = "4.2.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/28/3893324bcadf8f89b1616637468d766af3f625008c0735bf704fdfa86617/filelock-4.2.4.tar.gz", hash = "sha256:c6d8663535e1650ee430507b4ffbac7b464dd64b7647ea0112a9f406499d163d", size = 652444, upload-time = "2026-10-19T01:57:51.001Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/1b/5e74289a1878e666bb4b65fe5805a04cafcac2aa5f519ef1ead67ef91c56/filelock-4.2.4-py3-none-any.whl", hash = "sha256:301241438c57936ef93f4243a94f2559022268bfcf9b375a9a72eb0f8db8358e", size = 162475, upload-time = "2026-10-19T01:57:49.419Z" },
+]
+
+[[package]]
+name = "frozenlist"
+version = "1.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/2d/f5/c831fac6cc817d26fd54c7eaccd04ef7e0288806943f7cc5bbf69f3ac1f0/frozenlist-1.8.0.tar.gz", hash = "sha256:3ede829ed8d842f6cd48fc7081d7a41001a56f1f38603f9d49bf3020d59a31ad", size = 45875, upload-time = "2025-10-06T05:38:17.865Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f1/c8/85da824b7e7b9b6e7f7705b2ecaf9591ba6f79c1177f324c2735e41d36a2/frozenlist-1.8.0-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:cee686f1f4cadeb2136007ddedd0aaf928ab95216e7691c63e50a8ec066336d0", size = 86127, upload-time = "2025-10-06T05:37:08.438Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/e8/a1185e236ec66c20afd72399522f142c3724c785789255202d27ae992818/frozenlist-1.8.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:119fb2a1bd47307e899c2fac7f28e85b9a543864df47aa7ec9d3c1b4545f096f", size = 49698, upload-time = "2025-10-06T05:37:09.48Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/93/72b1736d68f03fda5fdf0f2180fb6caaae3894f1b854d006ac61ecc727ee/frozenlist-1.8.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4970ece02dbc8c3a92fcc5228e36a3e933a01a999f7094ff7c23fbd2beeaa67c", size = 49749, upload-time = "2025-10-06T05:37:10.569Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/b2/fabede9fafd976b991e9f1b9c8c873ed86f202889b864756f240ce6dd855/frozenlist-1.8.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:cba69cb73723c3f329622e34bdbf5ce1f80c21c290ff04256cff1cd3c2036ed2", size = 231298, upload-time = "2025-10-06T05:37:11.993Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/3b/d9b1e0b0eed36e70477ffb8360c49c85c8ca8ef9700a4e6711f39a6e8b45/frozenlist-1.8.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:778a11b15673f6f1df23d9586f83c4846c471a8af693a22e066508b77d201ec8", size = 232015, upload-time = "2025-10-06T05:37:13.194Z" },
+    { url = "https://files.pythonhosted.org/packages/dc/94/be719d2766c1138148564a3960fc2c06eb688da592bdc25adcf856101be7/frozenlist-1.8.0-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:0325024fe97f94c41c08872db482cf8ac4800d80e79222c6b0b7b162d5b13686", size = 225038, upload-time = "2025-10-06T05:37:14.577Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/09/6712b6c5465f083f52f50cf74167b92d4ea2f50e46a9eea0523d658454ae/frozenlist-1.8.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:97260ff46b207a82a7567b581ab4190bd4dfa09f4db8a8b49d1a958f6aa4940e", size = 240130, upload-time = "2025-10-06T05:37:15.781Z" },
+    { url = "https://files.pythonhosted.org/packages/f8/d4/cd065cdcf21550b54f3ce6a22e143ac9e4836ca42a0de1022da8498eac89/frozenlist-1.8.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:54b2077180eb7f83dd52c40b2750d0a9f175e06a42e3213ce047219de902717a", size = 242845, upload-time = "2025-10-06T05:37:17.037Z" },
+    { url = "https://files.pythonhosted.org/packages/62/c3/f57a5c8c70cd1ead3d5d5f776f89d33110b1addae0ab010ad774d9a44fb9/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:2f05983daecab868a31e1da44462873306d3cbfd76d1f0b5b69c473d21dbb128", size = 229131, upload-time = "2025-10-06T05:37:18.221Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/52/232476fe9cb64f0742f3fde2b7d26c1dac18b6d62071c74d4ded55e0ef94/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:33f48f51a446114bc5d251fb2954ab0164d5be02ad3382abcbfe07e2531d650f", size = 240542, upload-time = "2025-10-06T05:37:19.771Z" },
+    { url = "https://files.pythonhosted.org/packages/5f/85/07bf3f5d0fb5414aee5f47d33c6f5c77bfe49aac680bfece33d4fdf6a246/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:154e55ec0655291b5dd1b8731c637ecdb50975a2ae70c606d100750a540082f7", size = 237308, upload-time = "2025-10-06T05:37:20.969Z" },
+    { url = "https://files.pythonhosted.org/packages/11/99/ae3a33d5befd41ac0ca2cc7fd3aa707c9c324de2e89db0e0f45db9a64c26/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:4314debad13beb564b708b4a496020e5306c7333fa9a3ab90374169a20ffab30", size = 238210, upload-time = "2025-10-06T05:37:22.252Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/60/b1d2da22f4970e7a155f0adde9b1435712ece01b3cd45ba63702aea33938/frozenlist-1.8.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:073f8bf8becba60aa931eb3bc420b217bb7d5b8f4750e6f8b3be7f3da85d38b7", size = 231972, upload-time = "2025-10-06T05:37:23.5Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/ab/945b2f32de889993b9c9133216c068b7fcf257d8595a0ac420ac8677cab0/frozenlist-1.8.0-cp314-cp314-win32.whl", hash = "sha256:bac9c42ba2ac65ddc115d930c78d24ab8d4f465fd3fc473cdedfccadb9429806", size = 40536, upload-time = "2025-10-06T05:37:25.581Z" },
+    { url = "https://files.pythonhosted.org/packages/59/ad/9caa9b9c836d9ad6f067157a531ac48b7d36499f5036d4141ce78c230b1b/frozenlist-1.8.0-cp314-cp314-win_amd64.whl", hash = "sha256:3e0761f4d1a44f1d1a47996511752cf3dcec5bbdd9cc2b4fe595caf97754b7a0", size = 44330, upload-time = "2025-10-06T05:37:26.928Z" },
+    { url = "https://files.pythonhosted.org/packages/82/13/e6950121764f2676f43534c555249f57030150260aee9dcf7d64efda11dd/frozenlist-1.8.0-cp314-cp314-win_arm64.whl", hash = "sha256:d1eaff1d00c7751b7c6662e9c5ba6eb2c17a2306ba5e2a37f24ddf3cc953402b", size = 40627, upload-time = "2025-10-06T05:37:28.075Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/c7/43200656ecc4e02d3f8bc248df68256cd9572b3f0017f0a0c4e93440ae23/frozenlist-1.8.0-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:d3bb933317c52d7ea5004a1c442eef86f426886fba134ef8cf4226ea6ee1821d", size = 89238, upload-time = "2025-10-06T05:37:29.373Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/29/55c5f0689b9c0fb765055629f472c0de484dcaf0acee2f7707266ae3583c/frozenlist-1.8.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:8009897cdef112072f93a0efdce29cd819e717fd2f649ee3016efd3cd885a7ed", size = 50738, upload-time = "2025-10-06T05:37:30.792Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/7d/b7282a445956506fa11da8c2db7d276adcbf2b17d8bb8407a47685263f90/frozenlist-1.8.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:2c5dcbbc55383e5883246d11fd179782a9d07a986c40f49abe89ddf865913930", size = 51739, upload-time = "2025-10-06T05:37:32.127Z" },
+    { url = "https://files.pythonhosted.org/packages/62/1c/3d8622e60d0b767a5510d1d3cf21065b9db874696a51ea6d7a43180a259c/frozenlist-1.8.0-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:39ecbc32f1390387d2aa4f5a995e465e9e2f79ba3adcac92d68e3e0afae6657c", size = 284186, upload-time = "2025-10-06T05:37:33.21Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/14/aa36d5f85a89679a85a1d44cd7a6657e0b1c75f61e7cad987b203d2daca8/frozenlist-1.8.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:92db2bf818d5cc8d9c1f1fc56b897662e24ea5adb36ad1f1d82875bd64e03c24", size = 292196, upload-time = "2025-10-06T05:37:36.107Z" },
+    { url = "https://files.pythonhosted.org/packages/05/23/6bde59eb55abd407d34f77d39a5126fb7b4f109a3f611d3929f14b700c66/frozenlist-1.8.0-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:2dc43a022e555de94c3b68a4ef0b11c4f747d12c024a520c7101709a2144fb37", size = 273830, upload-time = "2025-10-06T05:37:37.663Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/3f/22cff331bfad7a8afa616289000ba793347fcd7bc275f3b28ecea2a27909/frozenlist-1.8.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:cb89a7f2de3602cfed448095bab3f178399646ab7c61454315089787df07733a", size = 294289, upload-time = "2025-10-06T05:37:39.261Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/89/5b057c799de4838b6c69aa82b79705f2027615e01be996d2486a69ca99c4/frozenlist-1.8.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:33139dc858c580ea50e7e60a1b0ea003efa1fd42e6ec7fdbad78fff65fad2fd2", size = 300318, upload-time = "2025-10-06T05:37:43.213Z" },
+    { url = "https://files.pythonhosted.org/packages/30/de/2c22ab3eb2a8af6d69dc799e48455813bab3690c760de58e1bf43b36da3e/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:168c0969a329b416119507ba30b9ea13688fafffac1b7822802537569a1cb0ef", size = 282814, upload-time = "2025-10-06T05:37:45.337Z" },
+    { url = "https://files.pythonhosted.org/packages/59/f7/970141a6a8dbd7f556d94977858cfb36fa9b66e0892c6dd780d2219d8cd8/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:28bd570e8e189d7f7b001966435f9dac6718324b5be2990ac496cf1ea9ddb7fe", size = 291762, upload-time = "2025-10-06T05:37:46.657Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/15/ca1adae83a719f82df9116d66f5bb28bb95557b3951903d39135620ef157/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:b2a095d45c5d46e5e79ba1e5b9cb787f541a8dee0433836cea4b96a2c439dcd8", size = 289470, upload-time = "2025-10-06T05:37:47.946Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/83/dca6dc53bf657d371fbc88ddeb21b79891e747189c5de990b9dfff2ccba1/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:eab8145831a0d56ec9c4139b6c3e594c7a83c2c8be25d5bcf2d86136a532287a", size = 289042, upload-time = "2025-10-06T05:37:49.499Z" },
+    { url = "https://files.pythonhosted.org/packages/96/52/abddd34ca99be142f354398700536c5bd315880ed0a213812bc491cff5e4/frozenlist-1.8.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:974b28cf63cc99dfb2188d8d222bc6843656188164848c4f679e63dae4b0708e", size = 283148, upload-time = "2025-10-06T05:37:50.745Z" },
+    { url = "https://files.pythonhosted.org/packages/af/d3/76bd4ed4317e7119c2b7f57c3f6934aba26d277acc6309f873341640e21f/frozenlist-1.8.0-cp314-cp314t-win32.whl", hash = "sha256:342c97bf697ac5480c0a7ec73cd700ecfa5a8a40ac923bd035484616efecc2df", size = 44676, upload-time = "2025-10-06T05:37:52.222Z" },
+    { url = "https://files.pythonhosted.org/packages/89/76/c615883b7b521ead2944bb3480398cbb07e12b7b4e4d073d3752eb721558/frozenlist-1.8.0-cp314-cp314t-win_amd64.whl", hash = "sha256:06be8f67f39c8b1dc671f5d83aaefd3358ae5cdcf8314552c57e7ed3e6475bdd", size = 49451, upload-time = "2025-10-06T05:37:53.425Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/a3/5982da14e113d07b325230f95060e2169f5311b1017ea8af2a29b374c289/frozenlist-1.8.0-cp314-cp314t-win_arm64.whl", hash = "sha256:102e6314ca4da683dca92e3b1355490fed5f313b768500084fbe6371fddfdb79", size = 42507, upload-time = "2025-10-06T05:37:54.513Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/9a/e35b4a917281c0b8419d4207f4334c8e8c5dbf4f3f5f9ada73958d937dcc/frozenlist-1.8.0-py3-none-any.whl", hash = "sha256:0c18a16eab41e82c295618a77502e17b195883241c563b00f0aa5106fc4eaa0d", size = 13409, upload-time = "2025-10-06T05:38:16.721Z" },
+]
+
+[[package]]
+name = "greenlet"
+version = "3.5.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3e/6e/0091f175ccd02b02bc8811bbcbcc6ac2e980be116e3b2f7a736ca322bf84/greenlet-3.5.6.tar.gz", hash = "sha256:8e67c43bdfc88d5fee6db0d3e40175b362fc95fb85f0412d233b9b203c53a575", size = 207653, upload-time = "2026-09-14T15:42:51.806Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/66/c0/d254544ae2b8bdd311aef000fafc02828c2771b17d994b3075620ea7cc6e/greenlet-3.5.6-cp314-cp314-macosx_11_0_universal2.whl", hash = "sha256:8cddea1b8339451c2fb3388e138347b6126744f33b611bdb55b7357361cfef46", size = 295221, upload-time = "2026-09-14T14:25:11.583Z" },
+    { url = "https://files.pythonhosted.org/packages/18/18/eb54be16b9cc3971e09ca5b73334e1b8c804a4630d9addaaf218a4fe300f/greenlet-3.5.6-cp314-cp314-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c59acfa8eb73a1e0d484392dc002bdf001fd4ce73394e0132df3d1ab6093d7cb", size = 660992, upload-time = "2026-09-14T15:12:04.876Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/b4/e193efe65671dcf294bc51fcc59efb52d154adf8612c4ea016da0d2c486c/greenlet-3.5.6-cp314-cp314-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a3b4a01c6da07ef9f80d4fe8933b994bc99747bcea3eab0330a9c34d3c12655b", size = 673428, upload-time = "2026-09-14T15:20:45.756Z" },
+    { url = "https://files.pythonhosted.org/packages/fd/21/631bb45fafde1dca782152377c0676d182ec924820064047f533a3627b28/greenlet-3.5.6-cp314-cp314-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:dd0b83bed3405b586a3133629f1d1a5bc7bfd64822a3b7ab342bdc68e6dbc61b", size = 677688, upload-time = "2026-09-14T15:25:09.279Z" },
+    { url = "https://files.pythonhosted.org/packages/45/ac/28fa7a9e50f2859466214c4ac584d776db52c1604ad4dd158960a5af2a1f/greenlet-3.5.6-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9a09d59bef1db94f384b5bcc2d523694d338f3df6b757aeeaf7baca5d0c0be88", size = 670773, upload-time = "2026-09-14T14:36:02.577Z" },
+    { url = "https://files.pythonhosted.org/packages/40/30/2b0a73e68e1e18e30b601d0d183cfdfc2beca4de5a6843c630f0fc9fb90c/greenlet-3.5.6-cp314-cp314-manylinux_2_39_riscv64.whl", hash = "sha256:fdacf26402389bdd89857ad3c045a26fe8f3314f9a8b28226f82f88463a65b77", size = 480475, upload-time = "2026-09-14T15:28:40.741Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/cd/fb7d6cdd86ff3427c1494854f0e35437eba05142be91f530f6da75e09e19/greenlet-3.5.6-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:8b7c73d1cef3d9ae963e9ff03f6222df43efbb9054ffd2f1969c935b7fc84c02", size = 1631900, upload-time = "2026-09-14T15:10:09.745Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/40/143bdbb20a516628cb15074ae52ed17d850b450292609c7a6fccac6dbece/greenlet-3.5.6-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:8b27df301f56e3b3d2298095c8f7d6b68f2521f6b1693e901fa039bdbae34424", size = 1693740, upload-time = "2026-09-14T14:35:52.959Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/9e/019642432e6ae283301df1361227d47610709d2dc69a38f95edef266d713/greenlet-3.5.6-cp314-cp314-win_amd64.whl", hash = "sha256:f8f0bd690e1a41294ac87905e8121c81a3761ec2583c768f13467428606c8c7a", size = 327473, upload-time = "2026-09-14T14:28:12.948Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/7f/8aafc7bf70c948786dba7221d0dc0838e5329bebc6d434ef2208b4f0e760/greenlet-3.5.6-cp314-cp314-win_arm64.whl", hash = "sha256:8cda13494d86a4f12429641117cb6ac4bbbc9c30a33f711f7d3a2e5fbe4b0b7e", size = 311095, upload-time = "2026-09-14T14:28:00.7Z" },
+    { url = "https://files.pythonhosted.org/packages/14/7e/7a205688a5b3074933b18a906608d46d106e9a79d776bdab5a4abf4b4feb/greenlet-3.5.6-cp314-cp314t-macosx_11_0_universal2.whl", hash = "sha256:97c5a53e8c1754df58e73f047a99e287d4da1bdfe64b0072fb25c87000897951", size = 305352, upload-time = "2026-09-14T14:21:31.962Z" },
+    { url = "https://files.pythonhosted.org/packages/78/cb/9c4a57a9d9dd0256e20b8f7f4f06554c2c92badebf0ab73ce344321b78b9/greenlet-3.5.6-cp314-cp314t-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fea4427d1ffdb3b523d7daa6712038428a4c16c450b9777bdd1221cfee0eab49", size = 672671, upload-time = "2026-09-14T15:12:06.347Z" },
+    { url = "https://files.pythonhosted.org/packages/97/52/c6729681ebbd298f4decd28746815acc8a0b0a0fde21d2df33776fd4d042/greenlet-3.5.6-cp314-cp314t-manylinux_2_24_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:73a29b5ba642e35433166a03a3e02935e7238c4b3467fbd77523b99edea23e5b", size = 679489, upload-time = "2026-09-14T15:20:47.291Z" },
+    { url = "https://files.pythonhosted.org/packages/71/76/3c11c21e0716b1f1dc7c1a4b3d690abb1d3b448c69a9d32049fecb64010a/greenlet-3.5.6-cp314-cp314t-manylinux_2_24_s390x.manylinux_2_28_s390x.whl", hash = "sha256:61a61b4a95a4f97922c3a6f5606d3e360851584bd47e500a5161373c53810e3d", size = 681303, upload-time = "2026-09-14T15:25:11.088Z" },
+    { url = "https://files.pythonhosted.org/packages/58/c5/2b6c721ba8b8963da42d5a0f57f25b8aaeb1fe9bdd156875e57f3be648a2/greenlet-3.5.6-cp314-cp314t-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:460e70b033aba8ed47e2ac9b5d0d2157b05a34fbfa30a241400aef4118902cdc", size = 676608, upload-time = "2026-09-14T14:36:03.959Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/26/3ae402202452cd5941bbbd483e5a74297e2397e7aa3182c2a5e3ab7d5666/greenlet-3.5.6-cp314-cp314t-manylinux_2_39_riscv64.whl", hash = "sha256:fe3170a69fe039b18ad18171e66faa9a75f6fe9d78f968fd9b54e09fbd714d81", size = 510112, upload-time = "2026-09-14T15:28:42.112Z" },
+    { url = "https://files.pythonhosted.org/packages/b2/04/0d018e0d05bcdde19a0fcb907834155f1fc853a9bedd3f3f5e6acadcae19/greenlet-3.5.6-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:ca80a49b53ed1d22f7282da7255f7bb2fd1935fd0f623d8613fda38745f18961", size = 1641479, upload-time = "2026-09-14T15:10:11.216Z" },
+    { url = "https://files.pythonhosted.org/packages/59/bb/f02ef9073919158f6403fe3701d4ed4403d646720e7201dfc6e9d264bac3/greenlet-3.5.6-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:916f92f2a8db10508f739d0b5e00b83defe5d1115a997c54532a6d7cf8c95404", size = 1698758, upload-time = "2026-09-14T14:35:54.336Z" },
+    { url = "https://files.pythonhosted.org/packages/08/a5/1f48fe647473a2dcccfd1839b2ff2c78eb57009be776b4da071e901c9bff/greenlet-3.5.6-cp314-cp314t-win_amd64.whl", hash = "sha256:886bcf1870af74c32bc310fd00a6b803445e17e51b7d5a107c7b35c0f362cc16", size = 331574, upload-time = "2026-09-14T14:27:18.451Z" },
+]
+
+[[package]]
+name = "h11"
+version = "0.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
+]
+
+[[package]]
+name = "httpcore2"
+version = "2.13.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "h11" },
+    { name = "truststore" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/cb/f3/1db7aa2bc2524062192bb0e0323969492d1883152a232fe36eea65f4e35c/httpcore2-2.13.1.tar.gz", hash = "sha256:e0aa977abe17e69a3b820a24542a6fa88702676d83880b8d194dcd18408e5103", size = 68071, upload-time = "2026-09-23T07:47:22.372Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/09/ba/a4568248771ce81957bfb7cc600264a40fbcda092391ee1c415c50be4bea/httpcore2-2.13.1-py3-none-any.whl", hash = "sha256:e1e05d4f25f7d7d496bfb96748f6f4b67657b03da069b3a68c36069f3db73d0a", size = 83423, upload-time = "2026-09-23T07:47:19.365Z" },
+]
+
+[[package]]
+name = "httptools"
+version = "0.9.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/3a/ec/deed52912ab7ca6c0b12859330c571c60c61d7267b341b28951fcbf13694/httptools-0.9.0.tar.gz", hash = "sha256:d484ebb7e3a3f3597b0f645fbd1b85633674ca808c1f5ba11c2caf7c66f5c8b6", size = 282523, upload-time = "2026-10-09T19:57:04.301Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/31/39/0965023968452245ece67b161adbf7c5652f8d0697ac69312f9d21849411/httptools-0.9.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1a4050a651e1f2faf05eb028ce9f2168abbcee9e24b209f5c1f2eb96d8c569e4", size = 118142, upload-time = "2026-10-09T19:55:14.491Z" },
+    { url = "https://files.pythonhosted.org/packages/31/39/a6ec662d81059e505e953af709797038e83e489014df721e506f4fd0d3c5/httptools-0.9.0-cp314-cp314-macosx_11_0_x86_64.whl", hash = "sha256:130635fea6e611a6b2026120037965ddb88b3dafd11bb64e264b101a70a76630", size = 113943, upload-time = "2026-10-09T19:55:15.887Z" },
+    { url = "https://files.pythonhosted.org/packages/72/04/4ecb7251a6c55bef61b157bb93fd44678943c35702a5966e4d5ebda2d450/httptools-0.9.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:18d800aaa2d6bff7d889df810d1b19a5fde72b1f6c0ca96e8d9f28a692fe5460", size = 514397, upload-time = "2026-10-09T19:55:17.48Z" },
+    { url = "https://files.pythonhosted.org/packages/31/5a/0c26c98ee06f0f39608de715e7ca868baec942171a77feace5a0ba548ca6/httptools-0.9.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c0e45def4d9ce7073e2226535572442d9d6efb4047c7a5fd8960807e877ce70a", size = 514383, upload-time = "2026-10-09T19:55:19.221Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/6c/0f85d4f1f579c49aea6e4946dd304e9f33a680382b5117970ab887885bc7/httptools-0.9.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:1f6da814aeecbc6cb8872d6d3e85ed16e8ab1653f9557cea8658725ce212348a", size = 534993, upload-time = "2026-10-09T19:55:20.992Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/32/97a836533b7bc9e269fc6d075c2d27669ca9786bf43f229158b9b4b15021/httptools-0.9.0-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:8e1e037bb57dbc549c6fe20370b763ea74bdb09413cdcf857e4f14d9e4e2fb13", size = 461494, upload-time = "2026-10-09T19:55:22.785Z" },
+    { url = "https://files.pythonhosted.org/packages/67/cf/a2d5e8dc3bad9b0b966bb546170234b4614275346cccbc01f6cdb6fce3b3/httptools-0.9.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:cd3e55223a77d6e08d5730ebacb4930ecca5d2ce7c57e7ba10833be7e52903f1", size = 495859, upload-time = "2026-10-09T19:55:24.9Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/d9/7472c4ca2aa1cfe6d0f9923380784b034cb77addc88589f2e5c92fd3b4df/httptools-0.9.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:beb2c8a34cc90fb4d862b7284eafdb322030d6a8b2ee5eb6a744f84205beedc3", size = 516303, upload-time = "2026-10-09T19:55:26.84Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/dd/f9be002ba859714cc306fe86204b7cb12bac091be66a7e23d7bb25d259bb/httptools-0.9.0-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:0cc339a807c156d840b54f8bf050ba0fc265eb81692c24bca8535b52fbd797c6", size = 458188, upload-time = "2026-10-09T19:55:28.571Z" },
+    { url = "https://files.pythonhosted.org/packages/89/7a/ed8bb5344071afd12c87e57e8839fa65abc3895b92a5d065be79ecacb919/httptools-0.9.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:b6ee42112d785a913dd63ec0335435a3dddbea5040c151252db815b0095cf066", size = 498356, upload-time = "2026-10-09T19:55:30.301Z" },
+    { url = "https://files.pythonhosted.org/packages/04/8d/3f1390c901d4a266ad9d5b988c47c4883e322e6f6cc021c592b9a050fb19/httptools-0.9.0-cp314-cp314-win32.whl", hash = "sha256:d1e329a1866981efe0201d05a374617f6c6cf14434a501d78ab22793d1ab1fa6", size = 88479, upload-time = "2026-10-09T19:55:32.071Z" },
+    { url = "https://files.pythonhosted.org/packages/99/05/7de70a4eea3b52d31a95fe64eb5775ccdead01e4913e4741b4424e9ef180/httptools-0.9.0-cp314-cp314-win_amd64.whl", hash = "sha256:edd5aa045fa3cc57143db018dd32ce7962bd5b525d05230709015d7e570100aa", size = 94809, upload-time = "2026-10-09T19:55:33.423Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/79/7f6c354a8f8f74381fd473f365d2db3cd976ee8d1422b8dd7455dfc52b62/httptools-0.9.0-cp314-cp314-win_arm64.whl", hash = "sha256:6ff0145b34610e57c9fae20df4e133c8d54266447387de6fcc0bdabfe4db4569", size = 91508, upload-time = "2026-10-09T19:55:34.764Z" },
+    { url = "https://files.pythonhosted.org/packages/94/0c/f9e8148ca684b41b4b5d0ced0860530b9a9bcb7c38bf727d83dcbfea42d0/httptools-0.9.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:80eae881cfb69383303e9a4d7961a478025b89c24f38f2e69b30c516fa0d57f2", size = 123684, upload-time = "2026-10-09T19:55:36.445Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/54/3c1d910e8f0bc9ee0ba7867b687e3272c8ae4a7da2df2fbf1b2bce77f0f9/httptools-0.9.0-cp314-cp314t-macosx_11_0_x86_64.whl", hash = "sha256:b2ab3aad55d75d0b8df8d8a1b5920baaec9b161112cd5e95984848b4d2cd3dfe", size = 118378, upload-time = "2026-10-09T19:55:37.851Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/ce/3b9694880da927ae69b5629b8847cfe73d14584be2aa974a92ed2675b7da/httptools-0.9.0-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:db735a23ecb0f0450d2b24e0a05fb00a8a35c9db172919c4d3e023e7c7ee4c9b", size = 591295, upload-time = "2026-10-09T19:55:39.501Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/89/1ff2835b6adf5c08a477d3a199e72b71e7f26df55ceaaed7d7364d745a1d/httptools-0.9.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:995b52f7c260ac7023640221f27472303968753cb6fc6fce1ddfb0e9db59a398", size = 603709, upload-time = "2026-10-09T19:55:41.404Z" },
+    { url = "https://files.pythonhosted.org/packages/24/40/4f59a0d9dca6d60002e7cb5dbf1441b558ced5a65b5b4131d57cbbd7c806/httptools-0.9.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3af4e45ff455fce5511fdf2653c1ce428ef09c56fe37a83eb4d924c2d474f31e", size = 607379, upload-time = "2026-10-09T19:55:43.119Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/19/381d444a3ba704cd5c67eb4617ae7a08e920a8239c688f23ba0de07a270b/httptools-0.9.0-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ce8e723b4637034b76f5382a30a6b725518c332273e8d62a6c7d46e90837c947", size = 530031, upload-time = "2026-10-09T19:55:44.85Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/c5/c9ba7758bf266240f598934510af4a800edafd9c8eb1fcf15feac0427063/httptools-0.9.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:465bc1526debf53a3be92022a16ca0c38f891ea3b5c1587af4f52e44020f8a07", size = 575129, upload-time = "2026-10-09T19:55:46.536Z" },
+    { url = "https://files.pythonhosted.org/packages/db/87/c17f3a53616a3849681f7c8e913ce966487b95038504bbb035c38f5f2fbe/httptools-0.9.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:8463b34ebde3f000627e9dbd8a545f995ad49fbf7ff9dd5abc0cd507da98a603", size = 582996, upload-time = "2026-10-09T19:55:48.545Z" },
+    { url = "https://files.pythonhosted.org/packages/88/e3/cb33ba1348ddfa5853f96021f4c38674ac383b92c944492cf7638bd6bfd0/httptools-0.9.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:f9489c1d87160c126f73b004742fe8654fa1ce37ed89e9e01330a1c10aaecde4", size = 526150, upload-time = "2026-10-09T19:55:50.261Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/00/af0e2f33ba5be60803a492ad377e798714d0c970e76015e313849b351ef7/httptools-0.9.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:06bfe7fad972a417269d8a5fc53b87e4eca970354abf5e9e24336fd06d64292e", size = 571731, upload-time = "2026-10-09T19:55:52.422Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/35/e67e9c9dd3da036ebfcbd273eec44bd39213f952d638858b09b9f3ecaf3f/httptools-0.9.0-cp314-cp314t-win32.whl", hash = "sha256:c42424213c28804f8d0e20f5692106cfb57bf72e1dbc4092b8481fb2f9e4c707", size = 94622, upload-time = "2026-10-09T19:55:53.982Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/5c/af620c73de59b5f3d431ae778c7412d30bba7bf56ca8b4140107a8ac0e54/httptools-0.9.0-cp314-cp314t-win_amd64.whl", hash = "sha256:bb1533541c729ad422f870a780d8b4af924f9817d45b5f580390418cda72eaa2", size = 101934, upload-time = "2026-10-09T19:55:55.417Z" },
+    { url = "https://files.pythonhosted.org/packages/90/90/fc6019b5179d13007c6c3039346ea2696cf2e94369d6ca96e57f23b01989/httptools-0.9.0-cp314-cp314t-win_arm64.whl", hash = "sha256:6f9549ca354a1d6d6167c458a1f1b12147726b968f02dd64b6a5801dba91ae0f", size = 97211, upload-time = "2026-10-09T19:55:56.878Z" },
+]
+
+[[package]]
+name = "httpx2"
+version = "2.13.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio", marker = "sys_platform != 'emscripten'" },
+    { name = "httpcore2", marker = "sys_platform != 'emscripten'" },
+    { name = "httpx2-jsfetch", marker = "sys_platform == 'emscripten'" },
+    { name = "idna" },
+    { name = "truststore", marker = "sys_platform != 'emscripten'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d5/44/474bef2a0e9d90f1715d32cb98b0738695ca17ba324095fb2497ed7fbd59/httpx2-2.13.1.tar.gz", hash = "sha256:e48744a19e3af5ee48313d0ce5fe941d5422fae5705ea922a4aabf94d7800dfa", size = 100405, upload-time = "2026-09-23T07:47:23.052Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d8/9c/6fe8931fd9f381042a9e4c7d5a7b4cbf7016b252bec0c99a49fce42c3326/httpx2-2.13.1-py3-none-any.whl", hash = "sha256:6dff50fabc270ee5fd25d845d0b078ed20564579744d6d962850975996d2f9a4", size = 95597, upload-time = "2026-09-23T07:47:20.995Z" },
+]
+
+[[package]]
+name = "httpx2-jsfetch"
+version = "1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/c4/0e5636363151a2a1795e0a77617168b9ca438e1748ec05fc9b5687f93d64/httpx2_jsfetch-1.0.tar.gz", hash = "sha256:70a0e3eabfef7cce5ad9c629f7d01ca05e418f586646f4ddf14782e4c1454c60", size = 6872, upload-time = "2026-08-07T00:13:07.492Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/43/832f631d32e4f1211caa2ba368317739fe71f0b8530e4c9d15dc454bac2a/httpx2_jsfetch-1.0-py3-none-any.whl", hash = "sha256:cb916b707601e69a07721aabc8f3f6659be3a6893bc1ff5c6f9e02241df2da32", size = 6382, upload-time = "2026-08-07T00:13:06.567Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.20"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f5/08/8eea9d4b8302028f3abb2c0813953f7aec26d33b7a8960ed760e65ff29fa/idna-3.20.tar.gz", hash = "sha256:a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44", size = 216463, upload-time = "2026-09-17T14:11:04.752Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/58/a2/bb081bab032533a855d44de1d56f8e8426114ff1ba5d1f07a438a0a654f8/idna-3.20-py3-none-any.whl", hash = "sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c", size = 69583, upload-time = "2026-09-17T14:11:03.168Z" },
+]
+
+[[package]]
+name = "iniconfig"
+version = "2.3.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/e1/2069291243c926a2ff1cd706c7f3eeb9b62144bf60f77c9fb9ff2fb26bd3/iniconfig-2.3.1.tar.gz", hash = "sha256:67f4b9c50da0dedf52af349e7749a80a9057a5031199791b906c3bb3ae878960", size = 21209, upload-time = "2026-10-06T22:48:38.076Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/56/43/4ca9e49d27a1fcf6bece6f6aec0ea46bb9112489b93d4b688fb415457bdb/iniconfig-2.3.1-py3-none-any.whl", hash = "sha256:9121e2c1fdb355232495be3194c8dfe87ccc2d5dee45947b78e68f499790d7a7", size = 7552, upload-time = "2026-10-06T22:48:36.959Z" },
+]
+
+[[package]]
+name = "libarchive-c"
+version = "5.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/26/23/e72434d5457c24113e0c22605cbf7dd806a2561294a335047f5aa8ddc1ca/libarchive_c-5.3.tar.gz", hash = "sha256:5ddb42f1a245c927e7686545da77159859d5d4c6d00163c59daff4df314dae82", size = 54349, upload-time = "2025-05-22T08:08:04.604Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/88/3f/ff00c588ebd7eae46a9d6223389f5ae28a3af4b6d975c0f2a6d86b1342b9/libarchive_c-5.3-py3-none-any.whl", hash = "sha256:651550a6ec39266b78f81414140a1e04776c935e72dfc70f1d7c8e0a3672ffba", size = 17035, upload-time = "2025-05-22T08:08:03.045Z" },
+]
+
+[[package]]
+name = "license-expression"
+version = "30.4.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "boolean-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/40/71/d89bb0e71b1415453980fd32315f2a037aad9f7f70f695c7cec7035feb13/license_expression-30.4.4.tar.gz", hash = "sha256:73448f0aacd8d0808895bdc4b2c8e01a8d67646e4188f887375398c761f340fd", size = 186402, upload-time = "2025-07-22T11:13:32.17Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/af/40/791891d4c0c4dab4c5e187c17261cedc26285fd41541577f900470a45a4d/license_expression-30.4.4-py3-none-any.whl", hash = "sha256:421788fdcadb41f049d2dc934ce666626265aeccefddd25e162a26f23bcbf8a4", size = 120615, upload-time = "2025-07-22T11:13:31.217Z" },
+]
+
+[[package]]
+name = "markdown-it-py"
+version = "4.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mdurl" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
+]
+
+[[package]]
+name = "mdurl"
+version = "0.1.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
+]
+
+[[package]]
+name = "msgpack"
+version = "1.2.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0a/e7/bb605a7bab2d8425a64b3fa762b39dc1bf1c7e3f11ba6fb5413d6db0ff8c/msgpack-1.2.3.tar.gz", hash = "sha256:32edb81a2b5eb7cd7c9d941b2bfbbb082fd2cd09e0e725930316af6b708db186", size = 196517, upload-time = "2026-09-29T02:33:52.276Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3f/8e/f777f74e38731c428857933c8011596f2d2f3160c821152f23b6ffba862f/msgpack-1.2.3-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:3a31905206722103a84c1f72633fe30692cff6732c9d262e09a27dbc468797c8", size = 92042, upload-time = "2026-09-29T02:32:37.464Z" },
+    { url = "https://files.pythonhosted.org/packages/a0/71/551608543ee5d590f7e8d522267665d6d9946866ad2a2a70a770f7c70793/msgpack-1.2.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:3372475211a9ce1a23acefe512cb3e121d18c95dc74ed56cb1819ef40836ebf4", size = 90578, upload-time = "2026-09-29T02:32:38.883Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/11/6d78ce5a9a58bf9ba7b1b6a8f649173b030e6770c8019cf330b91825ee5d/msgpack-1.2.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9324c54995641c3d1f92a9d55093c8cde0ffa2fbc87a467a688ef60428393220", size = 454352, upload-time = "2026-09-29T02:32:40.34Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/08/feb9a196269ba7809f44f9117d9e4a601c41c313f6144fd0c337293a5488/msgpack-1.2.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:d8ef3a66e4b52d2d7fdd90df2984670124b2ff7546d76bb25dcf68ef47f7df58", size = 462562, upload-time = "2026-09-29T02:32:42.176Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/77/3a674f366def24140b103d1ffd4fd27b3d912a13e47da67422afa16bebb3/msgpack-1.2.3-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:902f3490db0e07a7d40b48536a85c9b28fbf1397e7e1658a45a55f958e303620", size = 418134, upload-time = "2026-09-29T02:32:43.693Z" },
+    { url = "https://files.pythonhosted.org/packages/48/82/944e71f280577490d99a3951cbce21aa4cbe04e7ab42cb373fd668af883c/msgpack-1.2.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:8e51eca14fbb65c4e0a5a9657346962bd3dca78c08e04e3d4dee70ef48687d30", size = 445937, upload-time = "2026-09-29T02:32:45.739Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/ec/feddd629c4a3edf1395313680450c525086cceab56dec0d4de9da9ccb618/msgpack-1.2.3-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:f42f146752eedb6765f07dcc04d72dab0a25779ec8d4a88c0085263ce114f22c", size = 416450, upload-time = "2026-09-29T02:32:47.558Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/59/263a10f8c4613ba0713f48cbda7695ac8dd6d6fab2fcbc9168f03f23a94d/msgpack-1.2.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:0ed5823c4efc20fe87d3530665f40ec18a002be003114814c21235cc8d256207", size = 459546, upload-time = "2026-09-29T02:32:49.145Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/21/addcfa1e583cfc8a22fbdc57526621b5decd7ad676ae12e9150b7be1be5d/msgpack-1.2.3-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:2487453ca1b6104442c6442f9a1a8fee1fe8f428a70d99d4cba799108b304150", size = 53462, upload-time = "2026-09-29T02:32:50.708Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/2c/3cb5c8524a1335ee27ca952c7ab78d375a16fea8e18ae3767ba0c880416c/msgpack-1.2.3-cp314-cp314-win32.whl", hash = "sha256:6df430419f2338cb71e4a34d6e64f83c88ccd321f91f40ba4513400b36d864ec", size = 70294, upload-time = "2026-09-29T02:32:52.037Z" },
+    { url = "https://files.pythonhosted.org/packages/23/f9/9172ff3cdb85d160ad06df5e2708a5fce7682982a5eee8d31869b9f69d2e/msgpack-1.2.3-cp314-cp314-win_amd64.whl", hash = "sha256:84a6616d396ec1bc18a1e83e67c96a393ec35dfe5e17434a5be7b9aa0fe988ab", size = 77778, upload-time = "2026-09-29T02:32:53.429Z" },
+    { url = "https://files.pythonhosted.org/packages/04/e8/b4c23178bcf605ae17cec48a75530dd69d49b0a5a6f5f4df5c47d59f746e/msgpack-1.2.3-cp314-cp314-win_arm64.whl", hash = "sha256:7a003b02c6ee2eea6dfe0bb08818631e3597e69f0131f2a8250488a1cc553290", size = 73794, upload-time = "2026-09-29T02:32:54.763Z" },
+    { url = "https://files.pythonhosted.org/packages/66/b1/92704be352c4f428b7e0a0e0fb210cb1aa2b1c42c102b8dc22d34b82fac0/msgpack-1.2.3-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:ccea05b5542f6d283fef3f0a8e93a7f0be90af0ddeeef84c25c0216ba76dcae1", size = 93721, upload-time = "2026-09-29T02:32:56.342Z" },
+    { url = "https://files.pythonhosted.org/packages/49/78/9c91f1e86cadcbc100b3780fd429c3715648704032a612e77a00646ebe79/msgpack-1.2.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b1631e12fe572e181cd77e831f69335d6cd5278eac22e3db3f33cf264ac2ac18", size = 94256, upload-time = "2026-09-29T02:32:58.056Z" },
+    { url = "https://files.pythonhosted.org/packages/91/4d/270f9725921ae88a29d37a774a77ac24f0ef1411fc960a63f5a4665e81b4/msgpack-1.2.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:e54394b7dbe2e12ab032d9d21feef7bb61a90a150a2623633ba3781ba69dcb1f", size = 471673, upload-time = "2026-09-29T02:32:59.886Z" },
+    { url = "https://files.pythonhosted.org/packages/48/b8/eaa8d930f72dc1d1dd79511dc2ccf965922b059f2f0ed3b30aebac8c4b11/msgpack-1.2.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:63bb7448a1e9111319ae2430c09a5596140c160422830d6271bc75730ff2ff9a", size = 466257, upload-time = "2026-09-29T02:33:01.517Z" },
+    { url = "https://files.pythonhosted.org/packages/5b/5a/97adc805037bc7e24c4e2f711bbcd3b28be8ec9aea3e778f18208cfbdb46/msgpack-1.2.3-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:382bc88fe90f29f5ac8a0b65c7046ff255356f2f2f3186c30e370215736fa1dc", size = 418484, upload-time = "2026-09-29T02:33:03.402Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/7e/1c53302606fe436ab48ba539ebafafe4a6a9efe12c4f04dc7eb36912d93e/msgpack-1.2.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c77e27790ad72989db783d5303825fba0b71550f00a490efba35cde7dc4b719f", size = 454064, upload-time = "2026-09-29T02:33:04.977Z" },
+    { url = "https://files.pythonhosted.org/packages/00/2d/9ee0170f638907b396c15c6cd26b3e54f869159efc6206683acfd8f696e1/msgpack-1.2.3-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:700bc0fc9e968a292b9137ee70e7a012f7e115bf0107ce45e3a88202788dfc1e", size = 417901, upload-time = "2026-09-29T02:33:06.489Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/d2/905c84490a75cd15a27065407cd085d201f7d392e1e0411f49f03fd31ade/msgpack-1.2.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5bd5f91ea75c45cafcc5433ba8fae59b708b736ec178d2441c40c499e9e079db", size = 459896, upload-time = "2026-09-29T02:33:08.361Z" },
+    { url = "https://files.pythonhosted.org/packages/37/cd/4ce5809b9ab3b114d7cca64863e436820fa1614b49d55ccb93d49824ac2d/msgpack-1.2.3-cp314-cp314t-win32.whl", hash = "sha256:7995a7c6a62a1d6e7df211b4a16de513bd99fd053525050a319f80f44fb8015e", size = 75983, upload-time = "2026-09-29T02:33:10.023Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/31/853bb580744c24be0dbd8b090c3e6987dce466a1fc840fe50c0ac2ef9044/msgpack-1.2.3-cp314-cp314t-win_amd64.whl", hash = "sha256:bfe7d5b62cbe7aa664f0b3e2c49077f10fcdd06183d3014f8271ff3c5edbfbf9", size = 83757, upload-time = "2026-09-29T02:33:11.441Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/49/9f1b2ee484414eef9e21ee2b2b23b482bb71433ab9bac1da03cbda15ebf5/msgpack-1.2.3-cp314-cp314t-win_arm64.whl", hash = "sha256:1f585407f740a9eac04a3bb82c61d68a0ea78f90e29e670bfb086b9ce3a518dd", size = 78128, upload-time = "2026-09-29T02:33:13.063Z" },
+]
+
+[[package]]
+name = "multidict"
+version = "7.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/79/84ddb5ba16c4eb2c69c71db76ae3c579fe546e511f7170c7e27eedbab7c1/multidict-7.1.0.tar.gz", hash = "sha256:61a4e5d81b8d4e4ad61964b230129e7a2b914793d96289029078fc9009f074ec", size = 362341, upload-time = "2026-10-09T20:31:38.279Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/a7/c9f5c08348a6f903143b631546e22becf1b704a1304b17f7e1b9850308d2/multidict-7.1.0-cp314-cp314-android_24_x86_64.whl", hash = "sha256:128ea4142f81a79d430f3d0eb55206093e5eda03a12abbc7b03c34748ff6116b", size = 100435, upload-time = "2026-10-09T20:28:26.111Z" },
+    { url = "https://files.pythonhosted.org/packages/82/60/92fe617008c74cc019483b1c59202c48738c6f637ad5b12b36f01e21db43/multidict-7.1.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:439a19f7fbbff232ce96682c57e27030b8ac3a4b8121484c94f04bf99d08bfff", size = 95267, upload-time = "2026-10-09T20:28:27.856Z" },
+    { url = "https://files.pythonhosted.org/packages/17/78/82182f311d673f17de15bc7f7465c7ea5cbd2987ca3a6bf6546fa721e9d8/multidict-7.1.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:8090c35199d6b7bc6426bb8bdaf341e64f295cc2624a1fda7860c0837f1acc03", size = 97233, upload-time = "2026-10-09T20:28:29.817Z" },
+    { url = "https://files.pythonhosted.org/packages/63/25/af4e482d053fd73b4b1d60de3ff5578c6cb1d319d39d3f2a454d65409835/multidict-7.1.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:b7cc5333fcbfb27327d12612ed72322f221b61c2b69deb1155078c964f86e1a1", size = 163070, upload-time = "2026-10-09T20:28:31.495Z" },
+    { url = "https://files.pythonhosted.org/packages/df/d5/eaed52e199451dac445305fb2631d3f4e7ac9536aeef01f23622a1d93f90/multidict-7.1.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:b0e0040b0d8dd89bd0af9ab18901981e344ffba68bb30b8eabb4eab6c303279b", size = 94582, upload-time = "2026-10-09T20:28:33.263Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/e3/ff58ecad5161baa98dec05716e2745449446f2424a9c727464bf452f7fd1/multidict-7.1.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:33376418ab2846b931a72b36cfa16810befc4f49485d0b3f4dc054a4d6d00038", size = 97406, upload-time = "2026-10-09T20:28:34.981Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/a2/ae4eadf02d4bc035baa7cadf5548ca4fa441517193f76ce1aeb5ed276ae3/multidict-7.1.0-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:1101aea5c3eb1d26e090b931c693488af0db9f3d52e68be8d4cdd807dad9841d", size = 449908, upload-time = "2026-10-09T20:28:36.659Z" },
+    { url = "https://files.pythonhosted.org/packages/91/55/bd5101ef760d1af4c3f246330b29b48ee22bfdd5a83150b713dd93b431e2/multidict-7.1.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f996b19ac89e0dae65821ce65f788619e4286f78c62d005ecd3b75b5d9c0892b", size = 471605, upload-time = "2026-10-09T20:28:38.561Z" },
+    { url = "https://files.pythonhosted.org/packages/4d/8f/3dea8a28b0416ab71d47c8ce274bb3cacedde2d9838647ac67cdaa3d48e6/multidict-7.1.0-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:e0d91a4bcb59ac0d7af0d8e0da737332e1b7fe6831e53e47819b1b5349d431b2", size = 433523, upload-time = "2026-10-09T20:28:40.913Z" },
+    { url = "https://files.pythonhosted.org/packages/24/97/805d2aa4f746cc43cf4b206f1b1bfe2566add95bbb145abd3d9cf61858bf/multidict-7.1.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e96d67914ddbf5466e4476a1cd7ff30a332cbab85ed895207acc3e58c979b6a7", size = 488277, upload-time = "2026-10-09T20:28:42.851Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/7b/eac247b7e76f6010071c7c2401da5255eeffd1b2ac981925e533413d21ec/multidict-7.1.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:170ba61761f59ab92afcc86ce5534a3f3d0b07c38b339b950a83213f22dd86ec", size = 501888, upload-time = "2026-10-09T20:28:44.75Z" },
+    { url = "https://files.pythonhosted.org/packages/87/58/de62e27b09dd15756265765945f68f1c0d1e23eaba09e2e109fbb4112425/multidict-7.1.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:33389fe084e5426d9fd85d7d9ca91a29cd0d88a83c7c96e411aca49a3f9967bc", size = 474883, upload-time = "2026-10-09T20:28:46.704Z" },
+    { url = "https://files.pythonhosted.org/packages/21/fd/afb4e50ce3b44707b5ee39c6b5fa1573bdb50c4be660bb35b040362b5170/multidict-7.1.0-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:77024596b9046572c4e90b34c1ff212346756dc48933f90c53cf6e233660788d", size = 424327, upload-time = "2026-10-09T20:28:48.681Z" },
+    { url = "https://files.pythonhosted.org/packages/23/70/96c9abf933c4edae53b8a1c8d3f038120a3a60d363f16c6d94eee9b04851/multidict-7.1.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:ff15531a376dc6f35984443fd1429e4b150c36ce27633e7cc52a9e5318546e20", size = 459255, upload-time = "2026-10-09T20:28:50.562Z" },
+    { url = "https://files.pythonhosted.org/packages/24/37/dbc1dba26dc1c9e42aa07ee01908131a67fee0e79ebe5c1d0e7fc00aad55/multidict-7.1.0-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:544f2642a456fa264614e975d921540ee8c3b368b04d5aa1ddbec33241b13e08", size = 432476, upload-time = "2026-10-09T20:28:52.361Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/0a/eac70cc1461668bad8253a2da727670a56293eaba112aeb4079af8cd37d9/multidict-7.1.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:08834fb8b20e1a985c70e8380a10940234b4162de62694458727330376e58b33", size = 450030, upload-time = "2026-10-09T20:28:54.252Z" },
+    { url = "https://files.pythonhosted.org/packages/23/2d/eb40652ea74f96df859c7c5d38f9997f420b9dc404300dda0c5745327a6f/multidict-7.1.0-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:b4908e17867930b7ac77f89a18dc67308c67c511f037d8580489be86fb585912", size = 476169, upload-time = "2026-10-09T20:28:56.819Z" },
+    { url = "https://files.pythonhosted.org/packages/44/d0/7454ab8335bc4ec9f8abcc4c83a314bab060f22db6da8436b396e07ed21a/multidict-7.1.0-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:9b24e1f93b9b586ec03bc7bea1bf021ec90bf2528c729195028a3ca1c266b3f9", size = 420459, upload-time = "2026-10-09T20:28:58.744Z" },
+    { url = "https://files.pythonhosted.org/packages/60/7a/cedb46b287b720a2c4eda2448faf162612d0b718beb32581e35ccd9219b3/multidict-7.1.0-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:5c93473d0d7cd9bbb370973a9679a62f381c7050d7dff4ad6aaa92e8650f5a79", size = 483071, upload-time = "2026-10-09T20:29:01.114Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/11/e7ded22b008546dd30ae8c979aa5ac3282cad98876f7d5bbe93c1f2409a0/multidict-7.1.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:bf14cfcc30b097583d698a6e2b8b68c9bcffab277c485d481881958360c2938d", size = 467470, upload-time = "2026-10-09T20:29:03.388Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/f3/0136144cb0b1731fd93475cea75d974a55009358d3bf61dd55e2709a3dca/multidict-7.1.0-cp314-cp314-win32.whl", hash = "sha256:86bc779a0896e59e4be30a5be5cd6eeffd0b40b6f0e75e730218736b7bfc6f5c", size = 80205, upload-time = "2026-10-09T20:29:05.736Z" },
+    { url = "https://files.pythonhosted.org/packages/74/d9/a62a690d780febc171026d3e3c5700fc8387aa3e5f77cd04ada33d23d3f4/multidict-7.1.0-cp314-cp314-win_amd64.whl", hash = "sha256:6c9fd50f636a8fa9cb6324cd3eac962fec2bc5bb432452a3b583583a1059acfc", size = 92923, upload-time = "2026-10-09T20:29:07.337Z" },
+    { url = "https://files.pythonhosted.org/packages/84/08/eb7a1c34dc37c5f2c6aef52e6861e6f1cdfc6c685dcb72581eb218c00953/multidict-7.1.0-cp314-cp314-win_arm64.whl", hash = "sha256:e6906aa4bc62cde2c8aeb8a99a7b4401b241e274ae7b11df67d863d61ab3d5de", size = 92851, upload-time = "2026-10-09T20:29:09.15Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/3a/019abd746e8fbed9edd74b81259f20b278c011cef918868506d9b5bd6566/multidict-7.1.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:fabfdd4cf97db033196b51af46b8a681d4785c2a66347f2a5af1b4bbb1182629", size = 177429, upload-time = "2026-10-09T20:29:10.989Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/41/c8dda935231305d9b83c4a4cc5b5b9e323615328d4704f00ba2cf6d89916/multidict-7.1.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:a177a0ee5cf19931dcaeb3f662bc562754cfa4f4ace2351d9da24a954ef7db94", size = 102003, upload-time = "2026-10-09T20:29:12.78Z" },
+    { url = "https://files.pythonhosted.org/packages/af/23/3c3e79a222eaaa59a32648cec34709d848657be5339f96876075731e7f8e/multidict-7.1.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:0ae91de396d5c4ac97cb24dbada3d5c91a51454781e0a70476b008f4e879e4f0", size = 104861, upload-time = "2026-10-09T20:29:14.591Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/5b/04637e7cea5729466fb89048520fde167c5404df1beedcc86f18aeabed7c/multidict-7.1.0-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:160bdb3520fdadcaa21e1b98aab2e011265070814ecab3804eb61674becbd400", size = 463221, upload-time = "2026-10-09T20:29:16.697Z" },
+    { url = "https://files.pythonhosted.org/packages/2d/42/b121767de213a9774399c200cb877b19c2e1e5a0b0a6bc8407c7325fa37e/multidict-7.1.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6c2144785e42527404bbd5cfd11981fee4abe59a22aded0e498eb711a831d3f3", size = 502241, upload-time = "2026-10-09T20:29:18.657Z" },
+    { url = "https://files.pythonhosted.org/packages/47/0a/1cccd17ebf39776df7d8a6c99d066fc3ac1823d044cfe86a22ebbf42b841/multidict-7.1.0-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:7d0b4fec6a8d02d7e95de5cfa913261820f1ce04bd4c0381924de0da523179b8", size = 457128, upload-time = "2026-10-09T20:29:20.589Z" },
+    { url = "https://files.pythonhosted.org/packages/19/a9/0616d20dee16255f8737d9017288d9304dabf3695ac0071baca25d00c713/multidict-7.1.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:943a9bce22180ad0f4d32d1b402a0949a4ecfe5a1257b47f54a1b51981d81b86", size = 511842, upload-time = "2026-10-09T20:29:22.569Z" },
+    { url = "https://files.pythonhosted.org/packages/91/68/5a406b82ecfeee50c097c05fd519c836a61815d81c4a9a8c523d90fb4b35/multidict-7.1.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:f76ceb623f7ff50df46ac57e1587c479d87a5766319c4f43d0c0a5158896afab", size = 519852, upload-time = "2026-10-09T20:29:24.527Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/da/d42234f9d4f0e33885c70149112bf62aa4436045090c15cec0810ada0b2f/multidict-7.1.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:98beff85392ce435b28a0971ec21cade61ce8be8b632c9d855475a28ef92d31a", size = 500322, upload-time = "2026-10-09T20:29:26.569Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/c6/323e921a9812a6ea82978d4e1d9713e0b709023be037e6e4c14efe5472eb/multidict-7.1.0-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:71196ebb8d523148e5975396a444de02367f204b53b14e26794c96b2be0ed742", size = 444070, upload-time = "2026-10-09T20:29:28.52Z" },
+    { url = "https://files.pythonhosted.org/packages/93/87/109b7170de2168294f3e562f9d10caaaf946628d614b5a57246279acc1a6/multidict-7.1.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:35534b366410a36bb3d6f788691e37a76e4d1da48326b0ada3e5032580dd76af", size = 484862, upload-time = "2026-10-09T20:29:30.504Z" },
+    { url = "https://files.pythonhosted.org/packages/51/cf/7f1f63c9cf13f47036c0c64c607e6eee87c94076e3c6876abb6990ee62ad/multidict-7.1.0-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:b4674b12701c3fcbdf7f88b9e4479701c93bec5da9eb576140d5fcc0092990af", size = 457314, upload-time = "2026-10-09T20:29:32.6Z" },
+    { url = "https://files.pythonhosted.org/packages/93/ce/7de8b4ee6a847cc951915c279fc388127ec32a7c14aa7a01c4ad692be575/multidict-7.1.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:0ead852a5e906a43fcb6784eeac480f6a67919a51d480c1f80d32ddf9d615475", size = 462672, upload-time = "2026-10-09T20:29:34.776Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/6c/02dd089475983b1f5b8729319caa0b02fa3a60b527f27c86b2d53c24ca11/multidict-7.1.0-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:afe36ca503c2ffe30fb6df82b20389fa3c4035b5d65888a61310921cf3ae91c5", size = 498109, upload-time = "2026-10-09T20:29:36.763Z" },
+    { url = "https://files.pythonhosted.org/packages/47/d9/b9bdc59aa8e3eaf1f9e5d2460bbe0c428a01250d44417f8ccf965a8f6fa6/multidict-7.1.0-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:a5f0bebb10aae010d3c9ee3abaf83ab2069c718457aea09c15532355dd7e061f", size = 442260, upload-time = "2026-10-09T20:29:38.872Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/83/21b044885ab81bf5c03ec5c4c16aa449977e428c5c122e38969481cec1df/multidict-7.1.0-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:b9d9b7d72975521434368fe8aed3f6b522060bf271adabaa5ca6c87c0c08e168", size = 498916, upload-time = "2026-10-09T20:29:41.091Z" },
+    { url = "https://files.pythonhosted.org/packages/95/8b/31686730092e349ee2255fa630945ca344fc62e76f0b18d65b0f3dbb0ecf/multidict-7.1.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:274023bf952f849e0d05eba28a4c1f65f9796430d2b09ec16539386c0f76554c", size = 493525, upload-time = "2026-10-09T20:29:43.192Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/d0/c9fddcd7ac42b70a46ac9cf15e21eb527874164e14d418fcb50ce7190a4b/multidict-7.1.0-cp314-cp314t-win32.whl", hash = "sha256:7e0bfa161df365ba3c88899ee3b7c94755200967284bdedef8c1b8b43e2c0f2b", size = 86481, upload-time = "2026-10-09T20:29:45.188Z" },
+    { url = "https://files.pythonhosted.org/packages/24/ab/ce727c06680e72b5d381caa8587f561cb6fea1bfab6ba20c877019768a6f/multidict-7.1.0-cp314-cp314t-win_amd64.whl", hash = "sha256:34a35be8fb82d37087e8176aba907b9459f03d0e293c80f574c6337a436f4eaa", size = 99676, upload-time = "2026-10-09T20:29:47.441Z" },
+    { url = "https://files.pythonhosted.org/packages/fa/e7/d116d7ce514d04d9bf63774ed55e8033e2ce15ab5655a597bb947c53dfb8/multidict-7.1.0-cp314-cp314t-win_arm64.whl", hash = "sha256:d7dd46a8fcd7653c09ebe67eae9d4cb6636c7a905d9cbaf587dabcbd4eca6013", size = 98726, upload-time = "2026-10-09T20:29:49.365Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/86/a3de309c5e28ee85b314d0e3ba0e0dea6fd361c313322a05e67be4656e1e/multidict-7.1.0-py3-none-any.whl", hash = "sha256:d9ef29cfd98e17085b4f91bba8fa1570bec6787d5c52ce653ed33a58785585d0", size = 28087, upload-time = "2026-10-09T20:31:35.945Z" },
+]
+
+[[package]]
+name = "opentelemetry-api"
+version = "1.45.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2e/02/6e0ae9cc61bd3169d401077b507b3ebc344745171e1051ab430be012dcd9/opentelemetry_api-1.45.1.tar.gz", hash = "sha256:aa38ed19bcc084ba42782a73255b3582283eced7ad6dddbd6695189e69adfb75", size = 72804, upload-time = "2026-10-06T17:32:58.133Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/41/f7dcf80b81ee8e71c1a2b59f14208bc723edbd89ed027a73b175abf6348e/opentelemetry_api-1.45.1-py3-none-any.whl", hash = "sha256:b31553efa588ae44bc306f863c785c5333a9ecc091248c6ee68b4b6c87fdedfb", size = 60256, upload-time = "2026-10-06T17:32:33.506Z" },
+]
+
+[[package]]
+name = "packageurl-python"
+version = "0.17.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f5/d6/3b5a4e3cfaef7a53869a26ceb034d1ff5e5c27c814ce77260a96d50ab7bb/packageurl_python-0.17.6.tar.gz", hash = "sha256:1252ce3a102372ca6f86eb968e16f9014c4ba511c5c37d95a7f023e2ca6e5c25", size = 50618, upload-time = "2025-11-24T15:20:17.998Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b1/2f/c7277b7615a93f51b5fbc1eacfc1b75e8103370e786fd8ce2abf6e5c04ab/packageurl_python-0.17.6-py3-none-any.whl", hash = "sha256:31a85c2717bc41dd818f3c62908685ff9eebcb68588213745b14a6ee9e7df7c9", size = 36776, upload-time = "2025-11-24T15:20:16.962Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412, upload-time = "2026-08-04T18:15:28.737Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
+]
+
+[[package]]
+name = "pip"
+version = "26.2.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ae/15/4500e320e6b101ec3b719ae85b697d9940b6cda672bc555bd6016fc60c6f/pip-26.2.1.tar.gz", hash = "sha256:f6ad667e89a1fe78046c8f13232b247200f5258d7828f3f7883d660878e0813f", size = 1848877, upload-time = "2026-08-04T22:51:14.148Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f3/6e/1736e5b4ae2b778ef2f81c47d797de9f891d4d8acb047a24ca37a60294dd/pip-26.2.1-py3-none-any.whl", hash = "sha256:71138adf1f4ca900cdb7d289c21b7494329f2332b6d85f0e1c42108c0384ed3e", size = 1816632, upload-time = "2026-08-04T22:51:12.472Z" },
+]
+
+[[package]]
+name = "pip-api"
+version = "0.0.35"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pip" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/fc/08/47dfc28aa16ef0dbc38dd7c6e4fe24d124c3ed3a722a4a3e5021584a588c/pip_api-0.0.35.tar.gz", hash = "sha256:14dea05d7b3b68f4c7582213e3ae8932bbba8e1f754bf06b95263d5fa6ab4363", size = 123884, upload-time = "2026-09-08T19:35:12.876Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1d/2e/d424c5b5877be862dd9a2c8b7e9ddb13382bb25e132e6dd50cc09c0a7dde/pip_api-0.0.35-py3-none-any.whl", hash = "sha256:66990d0da25378555cbb538db79384bab92d4617c6350dfd7a2126ba2a3a9894", size = 123943, upload-time = "2026-09-08T19:35:11.537Z" },
+]
+
+[[package]]
+name = "pip-audit"
+version = "2.10.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "cachecontrol", extra = ["filecache"] },
+    { name = "cyclonedx-python-lib" },
+    { name = "packaging" },
+    { name = "pip-api" },
+    { name = "pip-requirements-parser" },
+    { name = "platformdirs" },
+    { name = "requests" },
+    { name = "rich" },
+    { name = "tomli" },
+    { name = "tomli-w" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/66/a4/f21d5f0a0edabcbce31560b73c7c5a6f72ae87af4236fd1069c8f59a353d/pip_audit-2.10.1.tar.gz", hash = "sha256:1eb4565d19ebe5d48996f4b770b4d2b32887e12cb12cfa637f1a064011b55ffc", size = 54275, upload-time = "2026-06-10T22:17:01.744Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a3/a7/b0c504148114047bd1bc9d97447453c6850ca176bb2f3c0038835994e8b7/pip_audit-2.10.1-py3-none-any.whl", hash = "sha256:99ef3f600a317c1945f1e89e227ef26e1c2d618429b8bd3fa6f4f7c440c4611a", size = 62023, upload-time = "2026-06-10T22:17:00.309Z" },
+]
+
+[[package]]
+name = "pip-requirements-parser"
+version = "32.0.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "packaging" },
+    { name = "pyparsing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/5e/2a/63b574101850e7f7b306ddbdb02cb294380d37948140eecd468fae392b54/pip-requirements-parser-32.0.1.tar.gz", hash = "sha256:b4fa3a7a0be38243123cf9d1f3518da10c51bdb165a2b2985566247f9155a7d3", size = 209359, upload-time = "2022-12-21T15:25:22.732Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/54/d0/d04f1d1e064ac901439699ee097f58688caadea42498ec9c4b4ad2ef84ab/pip_requirements_parser-32.0.1-py3-none-any.whl", hash = "sha256:4659bc2a667783e7a15d190f6fccf8b2486685b6dba4c19c3876314769c57526", size = 35648, upload-time = "2022-12-21T15:25:21.046Z" },
+]
+
+[[package]]
+name = "platformdirs"
+version = "4.13.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/da/91/4a03cfdb03314cfca262921797fff04ff4054bd86a160aed76eddf8aa12b/platformdirs-4.13.3.tar.gz", hash = "sha256:5e567f664eb087ab8521c0179cd8d1bd60857d271136567a39719e28e2d383ce", size = 61559, upload-time = "2026-10-16T01:16:16.573Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/45/b8/fd1af06b079af236f5423f7c1821264419cc8f6b4803f79353acbb8bfa53/platformdirs-4.13.3-py3-none-any.whl", hash = "sha256:f6ad7f447f24f8a3b82cce5976387428bff894a0eca6c3488f4a17f153c130c4", size = 32762, upload-time = "2026-10-16T01:16:15.051Z" },
+]
+
+[[package]]
+name = "playwright"
+version = "1.64.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "greenlet" },
+    { name = "pyee" },
+]
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cc/b7/24e5c283694e7a63aa376ddde395031decd7d627c77b34a58953176e8a19/playwright-1.64.0-py3-none-macosx_10_13_x86_64.whl", hash = "sha256:d76a501c9930b5a097b00e2448cda2200122a1e8e4be762ff535c1b076277737", size = 44347913, upload-time = "2026-10-13T23:35:20.723Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/b3/99f6c07a7f59adb3830e42cda2e2093dc1c2cbd1f69fe4393ead30c88257/playwright-1.64.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:8de42430e9a7c8b04ec963856d484d36ffd452882318ebad2df3e6fb49a8197a", size = 43014183, upload-time = "2026-10-13T23:35:24.195Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/f4/e0ddecd32342cac462777ef9123de833486743709bd437458c49e004d750/playwright-1.64.0-py3-none-macosx_11_0_universal2.whl", hash = "sha256:61e4e0801bfd76b30e04635aaec45647df707881ccf14382471fcb0eaeb1d16f", size = 44347915, upload-time = "2026-10-13T23:35:27.476Z" },
+    { url = "https://files.pythonhosted.org/packages/65/8b/78c19b805d52323122385b9c3f000144608deac38635455978af6d14807b/playwright-1.64.0-py3-none-manylinux1_x86_64.whl", hash = "sha256:5a59af1b230b234008524a5d42b613b233d4256f73bc1dd25bf3f11db0c81b75", size = 48286664, upload-time = "2026-10-13T23:35:30.981Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/7e/c100ee3c59ff42e3199880d77e8f59f3230fdb0dd1ecfd21a0a203bb5a68/playwright-1.64.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:727d20be6a0884e946b2471774dd960ec95519ba533e61329038526d9aea9a23", size = 47972215, upload-time = "2026-10-13T23:35:34.976Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/6e/3746bca44a77ad29fb4bf1722ad3345d5e936d5363d8daffbf23b226d3a4/playwright-1.64.0-py3-none-win32.whl", hash = "sha256:8b9f18dc1c23143ac0a5b3c59015db30e9413cc52e1ddddfc2836a7fbad7165a", size = 38675586, upload-time = "2026-10-13T23:35:38.665Z" },
+    { url = "https://files.pythonhosted.org/packages/e9/be/1dd8a65e3713c50c64b2580f50494ece90a4a9ede6e23788ef120e54c1f2/playwright-1.64.0-py3-none-win_amd64.whl", hash = "sha256:2c14d105548876b15bea5e7eca77bf0d8ff4ba0c607c1ae931067f3d1b010369", size = 38675591, upload-time = "2026-10-13T23:35:42.078Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/53/683ee3eb28902208d1d0c1d2eb3d6ddd99bc0184063babc6a2a7886c5799/playwright-1.64.0-py3-none-win_arm64.whl", hash = "sha256:97a5c247f1130f3343f097caf3bb1e79358d6b6cfa3550d97ecd721d1905911a", size = 34593061, upload-time = "2026-10-13T23:35:45.768Z" },
+]
+
+[[package]]
+name = "pluggy"
+version = "1.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/bf/db/7fc19e6f2dc92a966727031389fc2e08b558f0f25eb7403c1119ad4713cd/pluggy-1.7.0.tar.gz", hash = "sha256:d1eaa46ebb595891b860ab086b4d09c8588af65ebd4361b8e8f4bb8920b90ba8", size = 123304, upload-time = "2026-10-15T09:50:58.343Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/40/9e/2b38731e0fc536806f16490e1a12d7f0dc2a1235aa8cc07bcc75416a7daa/pluggy-1.7.0-py3-none-any.whl", hash = "sha256:7dd7b0d8832ba3cb632c306926ded123429211b83641b35dc5c41ad2d34f9bec", size = 27082, upload-time = "2026-10-15T09:50:56.808Z" },
+]
+
+[[package]]
+name = "propcache"
+version = "0.5.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b3/9a/9fbf4e4ec0c2d7f1c32519fff782ef467859b8faa9fbc5331a96f6395d43/propcache-0.5.4.tar.gz", hash = "sha256:ff6b113f50bc066a698db5d944d2c6dc7507168dd3341e255a8892fd0715a558", size = 61545, upload-time = "2026-09-16T00:17:14.386Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/33/c9/07e227b930c8ae513b8ef1aae3793499be097bffcdf7aee4fb8b33db4cd1/propcache-0.5.4-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:e6720ba44ad7e72174314d0e1fb0172494cff5c73a3a8a2159c3d2402ff15565", size = 85933, upload-time = "2026-09-16T00:15:16.073Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/e1/6710bb44510c4e4a8e0f004bbaf3cecfd048141309c77bae56d4e5a6ebc1/propcache-0.5.4-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:4cfe0a92ae30151869e67a4b5f5e105e4e03ad30b3f38e5211b5bf77d0881993", size = 50179, upload-time = "2026-09-16T00:15:17.377Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/22/b533b493d7025456f44518b33e53e000021a20fe7c27b88cf3d341df7186/propcache-0.5.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1d759d05634f1b038fb625a66662a8c85e5a8fec912da381b5149ddac107482b", size = 51942, upload-time = "2026-09-16T00:15:18.589Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/74/70ac8430e28f21e442c7bcb964eb46c4363f6881ade4aa0e978bfd8d503a/propcache-0.5.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:251c63dd46a0659bb875cb254dc4c1e79ee91a847c737cd62373295afc2235dc", size = 232647, upload-time = "2026-09-16T00:15:19.905Z" },
+    { url = "https://files.pythonhosted.org/packages/72/95/f222f13b6fe623310be0eb61a673bf26df439ce27e563ca8e422d0818777/propcache-0.5.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7a8d5ff04eb1f85698a78d20c62a14676e7b960dcafde09a388d60ad377d355d", size = 241541, upload-time = "2026-09-16T00:15:21.3Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/3e/763e370340db16115c5e63ad46e21ef0770a7f06928b3d3b62d8f8edfca4/propcache-0.5.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:7b9100a93b372418d8688f3f2a3e5b45c64d70ca4d6176e121aca1e3bfc1e32f", size = 245332, upload-time = "2026-09-16T00:15:22.802Z" },
+    { url = "https://files.pythonhosted.org/packages/96/d3/e97cd6f5de2176bd90ed4076c7a9b5e09d0f0b9687d00a576507988bb62c/propcache-0.5.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:cc07876cfb079b6f6f36d21ce75784ad6c2c6b563eeac0ed26c2fa2669b85df9", size = 232757, upload-time = "2026-09-16T00:15:24.374Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/4c/6766e5f60bcda26d244333aa71d0a702c1c9b21b251d543c7af5953d1eee/propcache-0.5.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:0951315a6b3142ee2167404d707743f0157c110091342b1aa0accac5cf0e4acf", size = 204389, upload-time = "2026-09-16T00:15:25.667Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/5e/ec4bb09a70b26ea99d76a8292c3383b960b296de2b347ac9986678f1761c/propcache-0.5.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:bee7d3aed13d56f54e681df38c3a23031bc9e3863f687d9d598825c9146acd7d", size = 228217, upload-time = "2026-09-16T00:15:27.11Z" },
+    { url = "https://files.pythonhosted.org/packages/e1/7d/b53922ba7d9e5bf797324e63aa05906ec240871899f779628df068743e2d/propcache-0.5.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:4e985382be6d15da8d0c2710a6fa7b9070fc9ecdeefb7f580e88373984ec8be3", size = 216947, upload-time = "2026-09-16T00:15:28.532Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/39/b62eee45e5ea4de094a258cbb3b01c1e856ca51ddfd95b43135c5effd1eb/propcache-0.5.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:9e9ab13760aa8b6d0881ae7cb04fd891d8d490cd2554ea8e79bb278399169bcc", size = 233457, upload-time = "2026-09-16T00:15:29.977Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/a9/feec61ed296d993db9dd097e0f6723e3f576a647722367547495e4c5b05c/propcache-0.5.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:1b2f3bec4261a94019575481c726c29850f72e27907773c75b1de421e20e9f9d", size = 204131, upload-time = "2026-09-16T00:15:31.74Z" },
+    { url = "https://files.pythonhosted.org/packages/92/4d/411ef380cddad28dc001f1c6d75ec72c76cd3817030f68ec1ccfba0ec6c1/propcache-0.5.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:720cf832eb2d0b0dfee129cb3335a26f6ce3cc45ee1187e8f0731758caa16792", size = 234820, upload-time = "2026-09-16T00:15:33.087Z" },
+    { url = "https://files.pythonhosted.org/packages/15/37/c988229753629ef1cfd5198337a83e624780ea2b3787efe9e747c05aad2d/propcache-0.5.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:9fb0a5be8d9aa213150e8d8148a42aca4984b285bcad1e69587dc4298edd929b", size = 228350, upload-time = "2026-09-16T00:15:34.533Z" },
+    { url = "https://files.pythonhosted.org/packages/12/49/5ef1c5cf98591da3c5b952b39e6a298084cc1ce353bc70f85e82397a5036/propcache-0.5.4-cp314-cp314-win32.whl", hash = "sha256:30cc1cebaf9aef49db06357a50398323ae04d70460c0491837d026ab7d6452ea", size = 43578, upload-time = "2026-09-16T00:15:35.957Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/9e/a0ac821a2229186af5e2e3c3635a78abb23cfddca57f38513ab5d70420f3/propcache-0.5.4-cp314-cp314-win_amd64.whl", hash = "sha256:0a095db8e15a6020db149ecbed6461939fe74f6acaa3ae8b702a1fe8c38cd983", size = 46304, upload-time = "2026-09-16T00:15:37.655Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/19/c8d0d36a9d16cba5dcee67d389c9333b988c8986a653a61c00a451817a46/propcache-0.5.4-cp314-cp314-win_arm64.whl", hash = "sha256:45488d1a5f9ab5bd90aaa1ca20f50fe1922b8ffad71a2009d2adf41355897aac", size = 43440, upload-time = "2026-09-16T00:15:39.091Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/e9/42f1da77cacfc184e6ec929557ef653b7961bbf6f1da460b9221273948b3/propcache-0.5.4-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:53eaa697c4d0422ff4cb714d00231b43352064d97b944033b30c1d57cc506ec0", size = 90672, upload-time = "2026-09-16T00:15:40.306Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/2f/4b79940908c6ab8c795097c102999d7bc1f7e0b8604dfd1c232f9d99d67a/propcache-0.5.4-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:886b59c4d28ca97dd23b025fdfc50a0356be934efbbbca89ad26230067f86fe5", size = 52586, upload-time = "2026-09-16T00:15:41.575Z" },
+    { url = "https://files.pythonhosted.org/packages/eb/07/02196ae6320c110235bb343f90dbd34be41f8b8964a3ee30db84ec12579e/propcache-0.5.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:3fa15757fea1dfcd5b7745cad9f4638929605531bd4018ab2adff7955f1a403d", size = 54335, upload-time = "2026-09-16T00:15:43.027Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/44/f48b9a131985659924df5fa5093f68fe72c7ee375329802989ba3126efc6/propcache-0.5.4-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6f0093ac3e9daada202c2082439d414a625c57184727a46e112a3fb2a81cb788", size = 297567, upload-time = "2026-09-16T00:15:44.373Z" },
+    { url = "https://files.pythonhosted.org/packages/04/a1/418d956d2735139f77fc35262179f1f52c23aa666de5a8ab3819c1ae7854/propcache-0.5.4-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:3cd3a7edb6b95b9b33998135ebfa18d709da82290fb8f27c858970b5a12c8b56", size = 297477, upload-time = "2026-09-16T00:15:46.048Z" },
+    { url = "https://files.pythonhosted.org/packages/69/fd/ff811fdb6d3d3e67fd9bbfb75881675d34a42d0ef29a45d33e3e233dde07/propcache-0.5.4-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c174bfd1c48a1b51a3078e95586dde718374bac79719ab3541ec9e74aec40574", size = 302669, upload-time = "2026-09-16T00:15:47.458Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/57/527910c455b5ec62f6871bef45d4f79fea16cb8c966ba0d4a07f0339ddc4/propcache-0.5.4-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a219f0ac59817a9114dd2aa57c13180f993e819ba658c7ddab4b66ed1ee0d370", size = 287908, upload-time = "2026-09-16T00:15:48.99Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/86/f69ab82707534a0cb2057bdca04f9200a71214c7551800f9d34d6ac39e4f/propcache-0.5.4-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:17a7400cec0256f0a71ae71f9da398f9894c956ff6668a1c9d317b3367316320", size = 249804, upload-time = "2026-09-16T00:15:50.486Z" },
+    { url = "https://files.pythonhosted.org/packages/27/19/60677af50d93be4256213de7cd487f056944c048b9c0b6f2e45b3a30f666/propcache-0.5.4-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:978f28401afbc76cdc3df9e1717b4229a06b626a1dcc75db4e1f2beb3884c3e9", size = 282344, upload-time = "2026-09-16T00:15:52.029Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/f7/a0057808a91fb3b6a5f3602b528f0cdcb3d53e0ff8315d73fabdfdf8fec4/propcache-0.5.4-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:4a1f4f5ffa55dce6307631f3cb2948e117e665966ea512e0d502b16c24f567e7", size = 270167, upload-time = "2026-09-16T00:15:53.466Z" },
+    { url = "https://files.pythonhosted.org/packages/83/c8/f4a865490df0dc0c8531d4e59ac411cb6dc24bb255d2396a6f1c60a368f4/propcache-0.5.4-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:213bb68d9ced5cf2bf717b1071bf2b09b4b04c426256f9fe6d054c60318424c4", size = 286551, upload-time = "2026-09-16T00:15:54.995Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/67/b4faebde9da4e8173d0e5a30e8cd31335914af7ef350b988f27fec588cfd/propcache-0.5.4-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:286867fb156488c251a3721766e380ac4495e4fd6b51aaa1403d89ce7f4359d9", size = 249595, upload-time = "2026-09-16T00:15:56.505Z" },
+    { url = "https://files.pythonhosted.org/packages/f6/40/52e1dd5636e9f5a27f6b5a4b4e2f33c322fd72afe956c397d82523ec4a80/propcache-0.5.4-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:445ee3bfb46e85838387fb3c536a73cc0b994dc192b004e40e170adc54aa2a7e", size = 286700, upload-time = "2026-09-16T00:15:57.985Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/0e/30b2b324b93ff31a0bab539c102aae59e84e444031b2742150a7646aa1bb/propcache-0.5.4-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:48cb48c5346a97de792254af77715aa2529c2a1ebc5f586aa0aae44a02f1fe57", size = 280500, upload-time = "2026-09-16T00:15:59.487Z" },
+    { url = "https://files.pythonhosted.org/packages/64/36/721bb59f682ff060d0c8df64274fca8cd0521b1a54506c2eedaef795b7f5/propcache-0.5.4-cp314-cp314t-win32.whl", hash = "sha256:03b229037d25b801e7af53fd52b9fc49d9439b036fca1e087e02780631adfa97", size = 46121, upload-time = "2026-09-16T00:16:01.349Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/86/0b1b80fa1ac3a0aac44e2922a6964fbe9cd52af5eab8fa933bf9e90b030c/propcache-0.5.4-cp314-cp314t-win_amd64.whl", hash = "sha256:8a1fc236528c457cd739c88abe823da851b7ab645d72792f88658114cc340c12", size = 49154, upload-time = "2026-09-16T00:16:02.901Z" },
+    { url = "https://files.pythonhosted.org/packages/69/4f/9fe6f05a47cb550c823155052116f710064b6be5c6e8ec4e9faae7e18115/propcache-0.5.4-cp314-cp314t-win_arm64.whl", hash = "sha256:135036c5cfc93864affb0f9af9a27e5d7a71cb7bd745e7b6dbfc2d56cc30e827", size = 46005, upload-time = "2026-09-16T00:16:04.266Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/cd/785c64ed382f3f04201870267b02783f63b4678c2acfddc177a3ebcc2727/propcache-0.5.4-py3-none-any.whl", hash = "sha256:62c60aec739ed00124573cce1178138fd690c7676352d67a37328c1cf51d7468", size = 16338, upload-time = "2026-09-16T00:17:13.106Z" },
+]
+
+[[package]]
+name = "py-serializable"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "defusedxml" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/73/21/d250cfca8ff30c2e5a7447bc13861541126ce9bd4426cd5d0c9f08b5547d/py_serializable-2.1.0.tar.gz", hash = "sha256:9d5db56154a867a9b897c0163b33a793c804c80cee984116d02d49e4578fc103", size = 52368, upload-time = "2025-07-21T09:56:48.07Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/bf/7595e817906a29453ba4d99394e781b6fabe55d21f3c15d240f85dd06bb1/py_serializable-2.1.0-py3-none-any.whl", hash = "sha256:b56d5d686b5a03ba4f4db5e769dc32336e142fc3bd4d68a8c25579ebb0a67304", size = 23045, upload-time = "2025-07-21T09:56:46.848Z" },
+]
+
+[[package]]
+name = "pyaes"
+version = "1.6.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/44/66/2c17bae31c906613795711fc78045c285048168919ace2220daa372c7d72/pyaes-1.6.1.tar.gz", hash = "sha256:02c1b1405c38d3c370b085fb952dd8bea3fadcee6411ad99f312cc129c536d8f", size = 28536, upload-time = "2017-09-20T21:17:54.23Z" }
+
+[[package]]
+name = "pyasn1"
+version = "0.6.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a4/9a/23310166d960def5897e91fe20e5b724601b02a22e84ba1f94232c0b7f67/pyasn1-0.6.4.tar.gz", hash = "sha256:9c447d8431c947fe4c8febc4ed9e760bc29011a5b01e5c74b67025bd9fb8ce81", size = 151262, upload-time = "2026-07-09T01:12:33.988Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9a/3b/6163796d69c3977d1e4287bea4a6979161cbbdd170ebb430511e8e1999ce/pyasn1-0.6.4-py3-none-any.whl", hash = "sha256:deda9277cfd454080ec40b207fb6df82206a3a2688735233cdcd8d3d565f088b", size = 84410, upload-time = "2026-07-09T01:12:32.92Z" },
+]
+
+[[package]]
+name = "pycparser"
+version = "3.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/da/a8/c5fdbeee588bb8ada9458774f43adf1bdd30bd59157055142183e769a024/pycparser-3.11.tar.gz", hash = "sha256:d875f09c3507d00e1aba0eecc6dcadc1352f30fff09dc6bff2f1c2935e97c2bc", size = 113796, upload-time = "2026-10-09T12:56:59.539Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/90/11/0e6f11117525ff0eec40ebac3d313376f102df93ca44ad9e893ee85e4f89/pycparser-3.11-py3-none-any.whl", hash = "sha256:51d5a8ba2be0bbe440b99d2112604c95bbbc3c2748a64260186c541e1729cd80", size = 51178, upload-time = "2026-10-09T12:56:58.131Z" },
+]
+
+[[package]]
+name = "pydantic"
+version = "2.14.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-types" },
+    { name = "pydantic-core" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/7c/0b/8e10b2e693af8ec54346a14caf36221334775975a747c9ceaa3f8371d96d/pydantic-2.14.1.tar.gz", hash = "sha256:94f478203dd03404682a1ada216965651dd74b1d2d5ffd62e00e0837caab5c26", size = 900362, upload-time = "2026-10-11T18:37:55.396Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/35/ea/a56b9fe5066f3537b7882f77e9c5dfb26d8c2eefdaed9b5fc73d57b4dc22/pydantic-2.14.1-py3-none-any.whl", hash = "sha256:9195d967ec791692a04438115466764fb8b9a27b31f14a760437694f40d6b454", size = 488106, upload-time = "2026-10-11T18:37:53.437Z" },
+]
+
+[[package]]
+name = "pydantic-core"
+version = "2.50.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a6/24/af4ec4be49fbc810f35b0bdcacc3d433b56bbfa469fd3bfd4ae116cd9bf1/pydantic_core-2.50.1.tar.gz", hash = "sha256:e50d7b94baac6c7d09927fa5ca5800a0c7ee5015c7fcff65beb3a1931b5a6e09", size = 513515, upload-time = "2026-10-11T18:35:44.82Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/33/28b96e81677153715e3eafb9f26663a80841e859fde282a380359b0d3fa1/pydantic_core-2.50.1-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:1cf41f1ae3fa155cf167a72689ad044bcc1e3c97e064123677149bdfb5dafc4a", size = 2224428, upload-time = "2026-10-11T18:33:07.153Z" },
+    { url = "https://files.pythonhosted.org/packages/94/40/15c06410c9b7b8da5805d27b64e09bd3f900e986728106db2689dbc51513/pydantic_core-2.50.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:4df197990c15b5a37c5a277d131d9f2c67de6133f2e5dafd80d9bba4b99f46f9", size = 2023740, upload-time = "2026-10-11T18:33:08.763Z" },
+    { url = "https://files.pythonhosted.org/packages/a1/4e/5eb629f6efc2a27e421d789dd4bfacbb5f6d09c80c28b13d1e87d73163d5/pydantic_core-2.50.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0036473f5583e6a60e50b8b21651511564277a3f05cc5dab8cf579f552cd5f6c", size = 2049435, upload-time = "2026-10-11T18:33:10.366Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/8e/f195aebec49ad12318876ac2368c197a7939f5d52f8e156d2238ef8a4588/pydantic_core-2.50.1-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:992c3514ec891fa7858099183e4d64e6bd5a5d4ff452fae29df22faa77a006bb", size = 2172975, upload-time = "2026-10-11T18:33:12.368Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/f5/7ad9fb83010cd5ea0948409db105676ed779c4e709e2d3d89b9fe2558794/pydantic_core-2.50.1-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:739dc730e6be3bd5ec2f4ab5cfc7eb047cc45fc1497b3bafec74ff2ed07df597", size = 2364197, upload-time = "2026-10-11T18:33:14.244Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/fb/bf0aab3e78301d202b82a0322ec968cd703b11fc0623fde9a28708936f62/pydantic_core-2.50.1-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:32fad3a91e51b6d2039c572db04a5a873260b399f6bd62c3552671fa7a4a2899", size = 2444259, upload-time = "2026-10-11T18:33:15.79Z" },
+    { url = "https://files.pythonhosted.org/packages/45/35/38f6d6564fae57d9b12e5676dfa947e0e7d5c46dbeaa7eb3352261d6d299/pydantic_core-2.50.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:42b54c2c90ad348b5e3a85e03e715d572c1fde357ef104cdfe3b03b697a404ea", size = 2159857, upload-time = "2026-10-11T18:33:17.51Z" },
+    { url = "https://files.pythonhosted.org/packages/65/a0/fb0a3ca10f139dcf765b2d312d10cf0f65c57c59993229d00ad12b14ceff/pydantic_core-2.50.1-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:2df1ff41884de2bc4b307bafd7c40a691094fad2ff8e767e5b45a319257bcf4e", size = 2233954, upload-time = "2026-10-11T18:33:19.591Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/6a/e63842252702aa4ec6e6b7178ca85e541a77459076592c23ebe2d9840b33/pydantic_core-2.50.1-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:fe90228920fd8ff2be62622b6bb8a2b11acd65046d50c6b130614b5879605a20", size = 2243876, upload-time = "2026-10-11T18:33:21.393Z" },
+    { url = "https://files.pythonhosted.org/packages/39/25/5991cf8318b37e0dfab47b87541619a1df8501a793cba0d978846cba37a7/pydantic_core-2.50.1-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:844b869f118e22a41a091bdcedda8a71bc1b0f62c38d1a0c3211cece47e1d8fc", size = 2277908, upload-time = "2026-10-11T18:33:23.324Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/3e/3ee8baaa6cc25a6961c69168cf9ff0f002d56f4e0d541ad6724c18fb61f3/pydantic_core-2.50.1-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:2eb75304506894a281d346220a4f7481a1b8729577c5ed2a05395991966a8396", size = 2449285, upload-time = "2026-10-11T18:33:24.942Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/c7/acbec6deac13fe697a80c275a9b6661db62c4d323bac8a47347b1f39c7cd/pydantic_core-2.50.1-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:6b20a4bffabdad0db2927ac034ae3b8a681b1f7a0182f3e60b479ad2fde21ebb", size = 2479013, upload-time = "2026-10-11T18:33:26.925Z" },
+    { url = "https://files.pythonhosted.org/packages/10/08/21a3f237b264389f6219d053ee78fc1b5c2fd402c1b1cb2b6cb8b85f9834/pydantic_core-2.50.1-cp314-cp314-pyemscripten_2026_0_wasm32.whl", hash = "sha256:99ba9bc2b8062ea0c326a990f7f00e6530c23579de66dd246e72c4cafef950a5", size = 1484400, upload-time = "2026-10-11T18:33:28.693Z" },
+    { url = "https://files.pythonhosted.org/packages/09/ce/077a6d262d12ef09108377ac0717f029f420d773ace63cafd6143af75568/pydantic_core-2.50.1-cp314-cp314-win32.whl", hash = "sha256:cf356f70551d40374eaffb1aa63f1eb6d2006681cbd7a9faea173ce0f4dd7cd2", size = 2103222, upload-time = "2026-10-11T18:33:30.326Z" },
+    { url = "https://files.pythonhosted.org/packages/14/4c/350a2415209c43d670eb71d3c040f332c04a30583d39e311b05c7ac15762/pydantic_core-2.50.1-cp314-cp314-win_amd64.whl", hash = "sha256:d32f3acc081cc3923386d88f422cde8892335e95f034e0104bb4cf9310d9915f", size = 2171586, upload-time = "2026-10-11T18:33:32.139Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/92/9bea6ca96580a0902fed366f064f0829e404f41889b34543279a1162b888/pydantic_core-2.50.1-cp314-cp314-win_arm64.whl", hash = "sha256:bed5163e03b98bc1fa2eb05d74c63d9c5c95d8ed6254985481640fbf5e237dea", size = 2155773, upload-time = "2026-10-11T18:33:33.896Z" },
+    { url = "https://files.pythonhosted.org/packages/86/8c/f121f073cf32bdd5cba7e6230b1ce0ac845b0cf43e44dd597d95af272db2/pydantic_core-2.50.1-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:9572c1369e9c9da2d64a7b7992c786d90ff295abc93964cfe3125e4290768070", size = 2234017, upload-time = "2026-10-11T18:33:35.588Z" },
+    { url = "https://files.pythonhosted.org/packages/a4/69/2bb2bcd6146cffe98d760a46c42ae71efd5151d9b2f9c9bf6619a3b32083/pydantic_core-2.50.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:2005207aafe1231315718bf6ed5d064a7300fb4772754af35ee72fc68159492e", size = 2001016, upload-time = "2026-10-11T18:33:37.57Z" },
+    { url = "https://files.pythonhosted.org/packages/20/b3/fbf854c7d07ec114260c26e9e2071a4381740f9ae09641dbfcbdf2a18c45/pydantic_core-2.50.1-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:64f6047f62a6c5ae08d0a6afb035667aa2d97c3d20d69762e034c5ea144d92a5", size = 2023015, upload-time = "2026-10-11T18:33:39.433Z" },
+    { url = "https://files.pythonhosted.org/packages/65/20/6de55b2f92cdb614b745c6e9ced639fc4fd7e1e77604825a88bdece6fcbd/pydantic_core-2.50.1-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:1ef800dd7d85bcdadf4c3076e4c94e43939493558a3b69a1ea830c706d4617bb", size = 2192543, upload-time = "2026-10-11T18:33:41.381Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/d9/19e91c94bd5c405945ce2f15526808aea37e162c253160de8ed7bf70b406/pydantic_core-2.50.1-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:b0135bcdcaa0f23573f286e4cb5e0fd2962700964ed13df085b85f2b97aeab9e", size = 2388704, upload-time = "2026-10-11T18:33:43.167Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/bc/2e24c8415eae1a25ee5a5484946a917123bad2e9d01689a759236928175a/pydantic_core-2.50.1-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:0b3a6f334c6a2345ca15318ff894502a90012536404b37c844a976c76c846e0b", size = 2464118, upload-time = "2026-10-11T18:33:44.856Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/1f/945b8053cb061c64e102bcaf7bfb9ed740c0bd4349f9bb978a7d4ddff4ab/pydantic_core-2.50.1-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:06e01fbbfdb9be777b316a71b6c49efaf4a08b615d0a98d678cda3023f79d019", size = 2150142, upload-time = "2026-10-11T18:33:46.661Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/78/96a3e50bf0d64aaae781107eb9335b7529d05a85793ed6e7241c4cd1d931/pydantic_core-2.50.1-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:a29a061fec0b4e2d714f277e70a3a18125ecff803f2fea6eade2f2e53711d112", size = 2245577, upload-time = "2026-10-11T18:33:48.574Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/5d/a6038a0322232758a6ebfa709f4ca14a60bf5b93940cd0b345056a557da4/pydantic_core-2.50.1-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:f5187624823423e1d1b82b1072ac41dc837389e18d3d0572cc19bbee46cd550a", size = 2263728, upload-time = "2026-10-11T18:33:50.527Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/4b/76ded3333a457a9344c4f2d63f2d82d0101654b05178fa4ddfe7d3627674/pydantic_core-2.50.1-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:3e46a9eb0a0901dd6275e6b06ac3a464885ef350ec4121fe486869de8053e4bb", size = 2293630, upload-time = "2026-10-11T18:33:52.362Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/00/9eca378335c9c1b72bc779bf6e4c2a82ce784f14ec48a0e87102c9870e05/pydantic_core-2.50.1-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:756d669f04e62ec4148ecfe22be6a4484d9b1181a6ef32e205ebfd200540858b", size = 2468048, upload-time = "2026-10-11T18:33:54.118Z" },
+    { url = "https://files.pythonhosted.org/packages/35/ca/e3832e9cf93651251de43c8c5c029ed680a3c1a0a1b17ee26c81bed08cbd/pydantic_core-2.50.1-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:c516cc5367ca3448995d42cb994bf3f4c9002d2a7c22eac9622551269ad1b807", size = 2512159, upload-time = "2026-10-11T18:33:55.99Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/f2/773469b5a10a39116a2cb17edaf6d722f017dd8da07161b371465311c542/pydantic_core-2.50.1-cp314-cp314t-win32.whl", hash = "sha256:9d1bed94af6a63835461f3cf7502058eb166c58c4778e11d0f433cfb1bd69e19", size = 2098406, upload-time = "2026-10-11T18:33:58.043Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/42/0bb74f8f25204b259b11ab7c12dc7f180893b6bd706118b385147fb6efd5/pydantic_core-2.50.1-cp314-cp314t-win_amd64.whl", hash = "sha256:c8dce1f1e0e5358b682a6ad3fa5e31b31d4560997b8e61417e9217c8d60f8a0c", size = 2148481, upload-time = "2026-10-11T18:33:59.913Z" },
+    { url = "https://files.pythonhosted.org/packages/47/0d/d801646c9679a4e630e15cf521d4108b93854b42a6e6e02391bd4c6b1095/pydantic_core-2.50.1-cp314-cp314t-win_arm64.whl", hash = "sha256:ceff0acc940be2715bd6ad17b24c0e5304abf44f6efd0f81ee8499e640f9dc86", size = 2174972, upload-time = "2026-10-11T18:34:01.875Z" },
+]
+
+[[package]]
+name = "pydantic-settings"
+version = "2.16.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/2e/3b/a5d2294799b53b448319978cfb5bd139d5a9d45e862af91661614f14c922/pydantic_settings-2.16.0.tar.gz", hash = "sha256:5b6c578049ede4db0e2ef3b4eaa4ad4069cfa9211f83fb38df899dfade50a614", size = 301031, upload-time = "2026-10-14T12:44:09.998Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/53/f4/b987bf8c51e5b19a95fa66d1ee596074141e085d9c2ddf97920803c7029b/pydantic_settings-2.16.0-py3-none-any.whl", hash = "sha256:7e73acf7f61936a15e5a3b6eedaea29f133357faf7272f2607ba479b049dd7f2", size = 80364, upload-time = "2026-10-14T12:44:08.233Z" },
+]
+
+[[package]]
+name = "pyee"
+version = "14.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/1d/f1/fdedc2c75c3e31a330659c85e5793bb18b3397981fbf0844c6dee5b18926/pyee-14.0.0.tar.gz", hash = "sha256:76dd0f4314ecd27f02dc73589dea7fd3853f9b6176d8ef9b122860657e3602de", size = 98760, upload-time = "2026-08-13T04:26:11.021Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/81/12/5347938b1f9a6453f0dbdfcc3e2388a1320ef9b9ec17fbefbc4ab647ea98/pyee-14.0.0-py3-none-any.whl", hash = "sha256:3ac2d3229a9677f7de2c33d7f52fe25b638a46b19c413fea2edc8c6d0a644e4d", size = 15553, upload-time = "2026-08-13T04:26:09.916Z" },
+]
+
+[[package]]
+name = "pygments"
+version = "2.21.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/49/2e/ced460408999b33da6b31b0021b0f37d329e202d4169aeb164493778f25b/pygments-2.21.0.tar.gz", hash = "sha256:610ca751c9bc2492b38eb9a38a7fbc93edbbb2d7182edaf34e66ae493dee5c8c", size = 5005329, upload-time = "2026-08-17T08:02:48.824Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/71/46/17f022dd3e953bf20a04a028a21ec746d942f8d2af30fa0f124fa0e6a684/pygments-2.21.0-py3-none-any.whl", hash = "sha256:2363c69b61c4a97c838da3b130dcd6468f4848992b21a82f2a63ec34377137d9", size = 1250147, upload-time = "2026-08-17T08:02:44.912Z" },
+]
+
+[[package]]
+name = "pymongo"
+version = "4.19.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "dnspython" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/42/8b/a9d214044153cb7d9141229d3e1b171cdf4f460fa07cade9354c4ce2f84d/pymongo-4.19.0.tar.gz", hash = "sha256:3c510dd3c5d9b392d3b33bb5d2a594758acfe8f026fca654253f947ce0af9d40", size = 2689381, upload-time = "2026-10-14T19:48:19.629Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ee/e7/6e62d60303a1e5cc816cefaa4d57d74df8ee65753ee9fe154b5fad851de3/pymongo-4.19.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:08c354566ab8b5dce6d805f35d61b5575455d3ea1835d7b90151d53e8c32e669", size = 826849, upload-time = "2026-10-14T19:46:56.892Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/68/b2f67b99f22c5543a8be397c0ed8dee526c23717b4491405ae513138d88c/pymongo-4.19.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:06b9ee12c4ceb7fb6ff8a7ab0465814c1cb5e5c6c2c452cb18eab7435b38a5b2", size = 827363, upload-time = "2026-10-14T19:46:58.842Z" },
+    { url = "https://files.pythonhosted.org/packages/02/bb/35e17473d000bc0517190aabe1429853aa142499370dbd6d7ae3743e8833/pymongo-4.19.0-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:ec25ab536e42e48fde356c6fc86e66f548e5af0cc584365e2ec34d3683be5a63", size = 1049786, upload-time = "2026-10-14T19:47:00.537Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/2f/83cc2961d977c1ba36662f24ae55c9f5dbee2845ca615146fec0f4eda053/pymongo-4.19.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6e65783e95b37c3387ed1105fe01e2be6b1b394c22331c5e8cc2fed2c3a30a06", size = 1059425, upload-time = "2026-10-14T19:47:02.511Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/94/baa32ef582f9edf3112b00f6e271cf5f83c481edcf999e2f462898990e87/pymongo-4.19.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f3264b209b6319cae120306e266ed5fa9c7bc071b73ba5e13cbad23a6cbd73d2", size = 1082787, upload-time = "2026-10-14T19:47:04.38Z" },
+    { url = "https://files.pythonhosted.org/packages/37/eb/949a24776ceba31e9b731f7048dce4fbb913047afd16580a61723143afb9/pymongo-4.19.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:212dbc97f8e813a24639aaaef38503d84f7652d00b88b391f87762ba4c1f1709", size = 1073579, upload-time = "2026-10-14T19:47:06.247Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/b0/a577ab8eff3772cf7036118b4e407a8cbb53add7bbe322f011871eb6db44/pymongo-4.19.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:2faa34469b052635c81dcec6b07fc5757d4aba0ec60f94c6658c7fa6f887bc46", size = 1057865, upload-time = "2026-10-14T19:47:08.076Z" },
+    { url = "https://files.pythonhosted.org/packages/95/cf/81b1d8a35ac3e5d5dcd8fc466f9acdd8f67a5035da130afb0d76e2efd6ac/pymongo-4.19.0-cp314-cp314-win32.whl", hash = "sha256:eee3fc70ea4253c8c7a6bd7917be468c5ef0a2860898766dd55497a563ddda94", size = 823938, upload-time = "2026-10-14T19:47:10.086Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/c5/1aa13304c714ad81ab70feb6bd99f6514baafe8e6c84d243ffabae678379/pymongo-4.19.0-cp314-cp314-win_amd64.whl", hash = "sha256:ac673404456b23c568cea326ab996a6b35a6009e41d42bcb774db025d0918b7d", size = 831074, upload-time = "2026-10-14T19:47:12.088Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/a8/5de505ba380af3d10737a2d0ddd2c6752ff6e9a0fe484c992483efe74889/pymongo-4.19.0-cp314-cp314-win_arm64.whl", hash = "sha256:2bb0e7c422c14ff2b31ec8be3e6ecaad326c17fca17071bcfcd13482584a8e0f", size = 826686, upload-time = "2026-10-14T19:47:13.959Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/fc/eddcc314b76ab9f3ab1417ecc088f88336cc2bca5be1356c8aa3d183dda8/pymongo-4.19.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:b01cc054878931ea81fc0a57c4c10489db723b8d7275fb10070f7228149012f1", size = 829839, upload-time = "2026-10-14T19:47:15.761Z" },
+    { url = "https://files.pythonhosted.org/packages/87/51/caa4ac1f33d4b8a4de2469a0624ffc7f7fae7441f7d71d41c2be306734a4/pymongo-4.19.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:823f8b2fb59e4e635e296d5e92efa883e3d01a8faa477d515fc9dfe515368026", size = 830216, upload-time = "2026-10-14T19:47:17.789Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/e7/b3eb14aa900cfe7b6f7c0dd2349b5d0a488c17a9db76a8bfdf8bd30afd9d/pymongo-4.19.0-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:1435721737b46be9bab5aa2374cfe57de934dc4ac421d5473308aa94c9fa39c3", size = 1113851, upload-time = "2026-10-14T19:47:19.743Z" },
+    { url = "https://files.pythonhosted.org/packages/00/b7/ec2c2bdde80e23693703f01805a1e37509e088127177f2d5758ca05c9a79/pymongo-4.19.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9dee18feff3203fa128798c6673c7795ef8a46d0b32c0e6b920c7b3f46129447", size = 1133130, upload-time = "2026-10-14T19:47:21.617Z" },
+    { url = "https://files.pythonhosted.org/packages/40/df/4f1bada8fa02babd094a5c4ed8f4ea1dc76cfc1366b26238a2ad1fc55b51/pymongo-4.19.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:8d866560dfbe44bc5e1110e96af4b8d92ffe6368c345dac1c36c8060188ebba6", size = 1152659, upload-time = "2026-10-14T19:47:23.572Z" },
+    { url = "https://files.pythonhosted.org/packages/c3/cb/a97d315c4c4e362d1f2e216d306122ae0f713ab457f73730684f3606a349/pymongo-4.19.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:47f04522f786dca82c776d5c3ed3ff9d08d6bf4cd0074c42296da5fac4d816ad", size = 1144177, upload-time = "2026-10-14T19:47:25.554Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/59/2a6c68bdee03f326194361149c68ec6720a22460d11a2a43a0742a7d7fce/pymongo-4.19.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ac55cf643eaa6146822f5f05f07be4dedbed906f525bb2ee098a865c4892788a", size = 1125673, upload-time = "2026-10-14T19:47:27.582Z" },
+    { url = "https://files.pythonhosted.org/packages/20/c1/b108dda370e09db7a4dccfb2bb003e769a8dd98513135e4429040cb88b83/pymongo-4.19.0-cp314-cp314t-win32.whl", hash = "sha256:3bcebec2536a9aec1d490ad6fa9fc7ffc3329059fb1f99154efa5d594abdc98c", size = 826636, upload-time = "2026-10-14T19:47:29.463Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/55/a0da8479007f149838c094f6f863fc05c973abf6802654881a4dfc68858e/pymongo-4.19.0-cp314-cp314t-win_amd64.whl", hash = "sha256:24668c6990bef96e1558328ba0802279cc1f752a3bcc7b283c2f39099a01e28c", size = 835337, upload-time = "2026-10-14T19:47:31.313Z" },
+    { url = "https://files.pythonhosted.org/packages/98/d0/9837244d18d8280277e7b2e9366ee2b9d35338052362888a4704d77ad633/pymongo-4.19.0-cp314-cp314t-win_arm64.whl", hash = "sha256:542b0f4e47fe68e753c85503f8352d4baa81ac73593601c8ede0fa22ba5c0431", size = 827513, upload-time = "2026-10-14T19:47:33.367Z" },
+]
+
+[[package]]
+name = "pyparsing"
+version = "3.3.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e4/11/b213bebff182584360cb8d17c72c1677fec5c5c228de439e63bcf8ab1c8f/pyparsing-3.3.3.tar.gz", hash = "sha256:928ae7e20211f3b6f3915a72f06a0cfd29ab9d24279dd6346b6b1a7146397d36", size = 1050487, upload-time = "2026-09-20T20:59:05.609Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/38/bb/d215ee7c73b61497b28a5503f9f53523f294fcc936762b7caf90e0c1c2b5/pyparsing-3.3.3-py3-none-any.whl", hash = "sha256:ece8c00a69cf01b45d0b1dedabb469c90d8caf996d4fda40f147627a122849a4", size = 126420, upload-time = "2026-09-20T20:59:04.025Z" },
+]
+
+[[package]]
+name = "pytest"
+version = "9.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "iniconfig" },
+    { name = "packaging" },
+    { name = "pluggy" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/47/b9efed96c114afcfa3c9d3fe98a76a1d14c74a9e266d397cf6eb64be5e01/pytest-9.1.1.tar.gz", hash = "sha256:1088fbde8f2b49d95a549a195707afa7a76a3ce9bcadc26b6d71f0ffda5fe313", size = 1636369, upload-time = "2026-06-19T10:58:32.857Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/25/1de2678b631f5a49215c6c96fff41ba892b0a34df68d6d80292b1b48aa7f/pytest-9.1.1-py3-none-any.whl", hash = "sha256:37a86b45efb9a47a61a36449063e8e18d0cab3161329fc099eb21783169c4f0c", size = 386536, upload-time = "2026-06-19T10:58:31.347Z" },
+]
+
+[[package]]
+name = "pytest-asyncio"
+version = "1.4.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/43/7c/d36d04db312ecf4298932ef77e6e4a9e8ad017906e24e34f0b0c361a2473/pytest_asyncio-1.4.0.tar.gz", hash = "sha256:c6c0d2259945122819f171a32ecea2c349ead889ee28176caaf492143424be42", size = 58514, upload-time = "2026-05-26T09:56:04.083Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/03/e2/08a497ef684b88559c9cc5f4ad53a37e7b99e727094a86d6ea32536d5d3c/pytest_asyncio-1.4.0-py3-none-any.whl", hash = "sha256:933ca923a23075a87fb7070c0ec272a6848489824d887c85c812670932835aa1", size = 16930, upload-time = "2026-05-26T09:56:02.576Z" },
+]
+
+[[package]]
+name = "pytest-cov"
+version = "7.1.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "coverage" },
+    { name = "pluggy" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b1/51/a849f96e117386044471c8ec2bd6cfebacda285da9525c9106aeb28da671/pytest_cov-7.1.0.tar.gz", hash = "sha256:30674f2b5f6351aa09702a9c8c364f6a01c27aae0c1366ae8016160d1efc56b2", size = 55592, upload-time = "2026-03-21T20:11:16.284Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9d/7a/d968e294073affff457b041c2be9868a40c1c71f4a35fcc1e45e5493067b/pytest_cov-7.1.0-py3-none-any.whl", hash = "sha256:a0461110b7865f9a271aa1b51e516c9a95de9d696734a2f71e3e78f46e1d4678", size = 22876, upload-time = "2026-03-21T20:11:14.438Z" },
+]
+
+[[package]]
+name = "python-dotenv"
+version = "1.2.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/74/26/2fbeedb218a787a5eea551c7532cac4e009f83d689dd2faa0d0353473f86/python_dotenv-1.2.4.tar.gz", hash = "sha256:f0d53e69935a851c0dcc78f3ab7aaccd8cabef0b92382b576b824212902873c0", size = 60824, upload-time = "2026-10-01T05:36:10Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/60/d1/38f3a3405989a89ac18390803e70c6ad7c7760da4f9b83cbeca0c44a0c72/python_dotenv-1.2.4-py3-none-any.whl", hash = "sha256:42269a8a5b3fd54ffa6f3d84b18abed50064717576b4ecf03dc4a55d8aa04fdc", size = 23266, upload-time = "2026-10-01T05:36:08.633Z" },
+]
+
+[[package]]
+name = "python-multipart"
+version = "0.0.32"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/5b/42/55c32bb9b12693c092ad250a0e82edb5b31ddeda6eb772de5f308b3804ad/python_multipart-0.0.32.tar.gz", hash = "sha256:be54b7f3fa167bb83e4fcd936b887b708f4e57fe75911c02aebf53efaf8d938e", size = 46881, upload-time = "2026-06-04T16:18:58.647Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e1/04/e8135ebd1ad02c56ec633277529b2602ff99ff634be76cdba5744cf554fd/python_multipart-0.0.32-py3-none-any.whl", hash = "sha256:ff6d3f776f16878c894e52e107296ffc890e913c611b1a4ec6c44e2821fe2e23", size = 30042, upload-time = "2026-06-04T16:18:57.319Z" },
+]
+
+[[package]]
+name = "pyyaml"
+version = "6.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" },
+    { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" },
+    { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" },
+    { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" },
+    { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" },
+    { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
+]
+
+[[package]]
+name = "requests"
+version = "2.34.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "charset-normalizer" },
+    { name = "idna" },
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/ac/c3/e2a2b89f2d3e2179abd6d00ebd70bff6273f37fb3e0cc209f48b39d00cbf/requests-2.34.2.tar.gz", hash = "sha256:f288924cae4e29463698d6d60bc6a4da69c89185ad1e0bcc4104f584e960b9ed", size = 142856, upload-time = "2026-05-14T19:25:27.735Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a0/f4/c67b0b3f1b9245e8d266f0f112c500d50e5b4e83cb6f3b71b6528104182a/requests-2.34.2-py3-none-any.whl", hash = "sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0", size = 73075, upload-time = "2026-05-14T19:25:26.443Z" },
+]
+
+[[package]]
+name = "rich"
+version = "15.0.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+    { name = "pygments" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
+]
+
+[[package]]
+name = "rsa"
+version = "4.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyasn1" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/da/8a/22b7beea3ee0d44b1916c0c1cb0ee3af23b700b6da9f04991899d0c555d4/rsa-4.9.1.tar.gz", hash = "sha256:e7bdbfdb5497da4c07dfd35530e1a902659db6ff241e39d9953cad06ebd0ae75", size = 29034, upload-time = "2025-04-16T09:51:18.218Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/64/8d/0133e4eb4beed9e425d9a98ed6e081a55d195481b7632472be1af08d2f6b/rsa-4.9.1-py3-none-any.whl", hash = "sha256:68635866661c6836b8d39430f97a996acbd61bfa49406748ea243539fe239762", size = 34696, upload-time = "2025-04-16T09:51:17.142Z" },
+]
+
+[[package]]
+name = "ruff"
+version = "0.17.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f9/e7/e6d5749983b020e6cb1055abec0a6f361a8e94f0184cdcf56d4760995f02/ruff-0.17.1.tar.gz", hash = "sha256:5bb796c5112e9fb9527f2ef2faa0a130d6312d19de92bcfaddd70dbb2d41020f", size = 5323349, upload-time = "2026-10-15T15:23:18.64Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2e/78/90c46ca6250709f7c37e397b60d06061adee8d0f7d13959ed6a8e49b14fd/ruff-0.17.1-py3-none-linux_armv6l.whl", hash = "sha256:1796c41eafec66f4635125dd1e074a7aa27b8d20c187d484360acf11d247fc4a", size = 10147528, upload-time = "2026-10-15T15:22:33.667Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/d2/a2e28bc35b083ae51fa07dfba5280a667c8b01ecaee7802fc8849dcd5c46/ruff-0.17.1-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:8eadb09a788010be29c895418bdfa513e4e1c65e64b94e5b19e4cd381f6cc7fb", size = 10225974, upload-time = "2026-10-15T15:22:36.328Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/71/7a9029a81c8206ee01a98f6cfeeb56e6c095af86857581a37045c46d7e94/ruff-0.17.1-py3-none-macosx_11_0_arm64.whl", hash = "sha256:29b454f18ca3eeaf37fbf140841dcf27d36109e29dee9aae8acecb68c26c6f74", size = 9270361, upload-time = "2026-10-15T15:22:38.651Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/8c/e075e9c917cb0575297880c96768304e881240171c870cbd8d9b7b54bec2/ruff-0.17.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:872e03dd231744d6c5ec5c8af6be52b71323fc6ee096e4c8b34d9f844ee3b978", size = 9938300, upload-time = "2026-10-15T15:22:41.284Z" },
+    { url = "https://files.pythonhosted.org/packages/87/27/0b4bb926a49de2383f161272b4d863571a4c7ecdbf595a6bc58813a13367/ruff-0.17.1-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:4c0d6cb5f8fbac77eec9af49f4fc0eaf856b05545e372b0694d24b4e76b1c640", size = 9948464, upload-time = "2026-10-15T15:22:43.681Z" },
+    { url = "https://files.pythonhosted.org/packages/14/27/518d57e0e02aecb8ea4acac6b57b51a53173d25fa734952bfdd7d531e88e/ruff-0.17.1-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:78beced4a3c94dfedbee4b999b95b6a27b35820fdc0afbacc6d37a8da26c1cd1", size = 10638639, upload-time = "2026-10-15T15:22:46.081Z" },
+    { url = "https://files.pythonhosted.org/packages/01/82/d89a4e498ade59e6cee52d67f8da569019372212b87468c1fdeae884601c/ruff-0.17.1-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:7feefc63921202894f0e158b0e32f45a5950d70a7fb693ccb9264816c25b1c05", size = 11337238, upload-time = "2026-10-15T15:22:48.894Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/7c/3b0fdef9352656317c977086fe1d802902406e4f2a0d8578da90c0e6d1c5/ruff-0.17.1-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:684154861a819bf1f433669d2a0ce9c3e54677c65b8ebb866cc2a7ec86345785", size = 10896327, upload-time = "2026-10-15T15:22:51.45Z" },
+    { url = "https://files.pythonhosted.org/packages/62/86/5566290219708ce2928f3a29c4f843a1185b341ec6111c4631a33c5ceced/ruff-0.17.1-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a6ef98e51de8ef38082f90653ceeb84944bd7673783eea13e1647c5b9b064189", size = 10350811, upload-time = "2026-10-15T15:22:54.401Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/d2/ca8462dabb3c413990d49703ba306c30c862195a75448d080fa8fcce9775/ruff-0.17.1-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:8f9aa5b5bd5fa1937803ea609c8f153b8de39bf3e0e149897ae34b0c5b52f467", size = 10569994, upload-time = "2026-10-15T15:22:57.142Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/ad/dd1864c1f1db17c8cfb297ce70b352388e6977620f66f7182c52855407df/ruff-0.17.1-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:80e53b0e5faa3c5667f035daaa032893ae42b7cfe708c886d39ed131e54688ab", size = 10059672, upload-time = "2026-10-15T15:23:00.084Z" },
+    { url = "https://files.pythonhosted.org/packages/65/45/3f56cf1d2168c2165cdd5ac6f9668aee66a4cfdd4caf2b2cc5ccb2b1d568/ruff-0.17.1-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:056c5d5fa0ac790051ae165d7035c7bf956d02de2db557f2e9b31d877a505fca", size = 9947803, upload-time = "2026-10-15T15:23:03.132Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/4b/5457cb2be4c1d1ea5e919558131a0f197a4a454a0530d9e30820e8206e4c/ruff-0.17.1-py3-none-musllinux_1_2_i686.whl", hash = "sha256:bd8f5a55b10f371642eacd0e8665a42a8b97da15c9a7187c79e697b77b5e0ce4", size = 10351807, upload-time = "2026-10-15T15:23:05.628Z" },
+    { url = "https://files.pythonhosted.org/packages/49/fb/db15b4f8fa24a1e36b99e1401f42ef6df16ee299a48670d5d262b771e7d7/ruff-0.17.1-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:ce05e6f3973611d9550a600e04bb531061e368baba31610eb57c1509a8f21a0a", size = 10765716, upload-time = "2026-10-15T15:23:08.092Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/e8/1e186578076aff7a80735f625005fde678412ab609cd323ed182eb7d6b87/ruff-0.17.1-py3-none-win32.whl", hash = "sha256:1de0030a8aa78c65c5fecb84b2e5c390ac684c0452875a02afc7c083d49a496a", size = 9895093, upload-time = "2026-10-15T15:23:10.582Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/2e/da3d9589bae8e8b58f3a48bd5bc0b980232fb14a83bf02c3be7660f87c1b/ruff-0.17.1-py3-none-win_amd64.whl", hash = "sha256:5df76f16580fab58d0f6c98a3ac254a4abceb7b2489b8b678335869cff77b3d7", size = 10097955, upload-time = "2026-10-15T15:23:13.309Z" },
+    { url = "https://files.pythonhosted.org/packages/df/c9/0f2a4dea06a5e12c1191ee3d96b1e1233797d0d5e18f97a2b909a95a9836/ruff-0.17.1-py3-none-win_arm64.whl", hash = "sha256:42400b9a6ff8515ff27796f07f92e0195be011c86e81e381606f58ea5502fef4", size = 9853542, upload-time = "2026-10-15T15:23:16.05Z" },
+]
+
+[[package]]
+name = "sortedcontainers"
+version = "2.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e8/c4/ba2f8066cceb6f23394729afe52f3bf7adec04bf9ed2c820b39e19299111/sortedcontainers-2.4.0.tar.gz", hash = "sha256:25caa5a06cc30b6b83d11423433f65d1f9d76c4c6a0c90e3379eaa43b9bfdb88", size = 30594, upload-time = "2021-05-16T22:03:42.897Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/32/46/9cb0e58b2deb7f82b84065f37f3bffeb12413f947f9388e4cac22c4621ce/sortedcontainers-2.4.0-py2.py3-none-any.whl", hash = "sha256:a163dcaede0f1c021485e957a39245190e74249897e2ae4b2aa38595db237ee0", size = 29575, upload-time = "2021-05-16T22:03:41.177Z" },
+]
+
+[[package]]
+name = "starlette"
+version = "1.8.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e9/0c/6efb252d091ecccd7d62048ae11f0ea35cd75a4fbaeea5e30f9c3bf91d10/starlette-1.8.0.tar.gz", hash = "sha256:1565dc0b35d5737a271ed1e0e04e949f4e81198799f216d2667b0a0fb9cf9522", size = 2730457, upload-time = "2026-10-13T07:54:39.53Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c1/b0/5742e4ac7af5eb58ec3470a537a49d7aa507e5539413e504b3a65ef50ba8/starlette-1.8.0-py3-none-any.whl", hash = "sha256:dfdd6b29c26483288088d990eee59631dedadd66ce20d203402a7ca8e3c4656f", size = 79612, upload-time = "2026-10-13T07:54:38.019Z" },
+]
+
+[[package]]
+name = "stevedore"
+version = "5.9.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/db/a1/3b8ed9c1fc3aa6eebb57732d924ddaa0500ecc3b638d0454816320994383/stevedore-5.9.1.tar.gz", hash = "sha256:e97a2667923efda926e8713fde6a73616df68210a3cbc6f02b48967b676fd8bf", size = 518111, upload-time = "2026-08-20T15:25:14.754Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c5/97/bba6e7ec2f5498b9dcb7b1b6400086b80ae5a8ebaff4b25e8c8add75f439/stevedore-5.9.1-py3-none-any.whl", hash = "sha256:5c8ff3a9f336cc1a06ac0f597bc79d11a2f950bfd32e290ca56b5a301fafafbf", size = 54931, upload-time = "2026-08-20T15:25:13.602Z" },
+]
+
+[[package]]
+name = "telethon"
+version = "1.45.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pyaes" },
+    { name = "rsa" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/d5/07/b23b6cc73cd994763fbd641d196904f56cc966035eda841275b5689c6e5f/telethon-1.45.0.tar.gz", hash = "sha256:4cb7ae269b8ab9dad9fc490b859f0bc2f885121e990f5b20407b1faa0db2a1d9", size = 728057, upload-time = "2026-09-10T14:28:04.739Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/92/ac/241c09e6905215f225d8088438ceb1f32cc4b4865f3f49068cb402debfd7/telethon-1.45.0-py3-none-any.whl", hash = "sha256:339e24c83aedc9f12cbe389264627edc49779e4289c535aa90aafc4ce62f7972", size = 804098, upload-time = "2026-09-10T14:28:03.115Z" },
+]
+
+[[package]]
+name = "tgdrive"
+version = "2.0.0"
+source = { virtual = "." }
+dependencies = [
+    { name = "aiofiles" },
+    { name = "aiohttp" },
+    { name = "argon2-cffi" },
+    { name = "cryptg" },
+    { name = "cryptography" },
+    { name = "defusedxml" },
+    { name = "fastapi" },
+    { name = "libarchive-c" },
+    { name = "pydantic-settings" },
+    { name = "pymongo" },
+    { name = "python-multipart" },
+    { name = "telethon" },
+    { name = "uvicorn", extra = ["standard"] },
+]
+
+[package.dev-dependencies]
+dev = [
+    { name = "bandit" },
+    { name = "httpx2" },
+    { name = "pip-audit" },
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
+    { name = "pytest-cov" },
+    { name = "ruff" },
+]
+e2e = [
+    { name = "playwright" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "aiofiles", specifier = "==25.1.0" },
+    { name = "aiohttp", specifier = "==3.14.5" },
+    { name = "argon2-cffi", specifier = "==25.1.0" },
+    { name = "cryptg", specifier = "==0.6.0" },
+    { name = "cryptography", specifier = "==50.0.2" },
+    { name = "defusedxml", specifier = "==0.7.1" },
+    { name = "fastapi", specifier = "==0.143.5" },
+    { name = "libarchive-c", specifier = "==5.3" },
+    { name = "pydantic-settings", specifier = "==2.16.0" },
+    { name = "pymongo", specifier = "==4.19.0" },
+    { name = "python-multipart", specifier = "==0.0.32" },
+    { name = "telethon", specifier = "==1.45.0" },
+    { name = "uvicorn", extras = ["standard"], specifier = "==0.54.0" },
+]
+
+[package.metadata.requires-dev]
+dev = [
+    { name = "bandit", extras = ["toml"], specifier = "==1.9.4" },
+    { name = "httpx2", specifier = "==2.13.1" },
+    { name = "pip-audit", specifier = "==2.10.1" },
+    { name = "pytest", specifier = "==9.1.1" },
+    { name = "pytest-asyncio", specifier = "==1.4.0" },
+    { name = "pytest-cov", specifier = "==7.1.0" },
+    { name = "ruff", specifier = "==0.17.1" },
+]
+e2e = [{ name = "playwright", specifier = "==1.64.0" }]
+
+[[package]]
+name = "tomli"
+version = "2.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/b0/78/9ad63712633ed3ab5cc1a648d863d7e7da371e9425e209555a0fe711b695/tomli-2.5.0.tar.gz", hash = "sha256:264507556cd8b8c8e7c6ee037cdf443a463f03f4c958e57195e3d369711b8ff6", size = 17662, upload-time = "2026-10-07T12:23:37.892Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e4/49/caf6b307766eb9567664a8707e9d6be5fcc0e8903f18781c6677a60d80c7/tomli-2.5.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:d3182ee2d887e507bd67319a0a61105d1dd33facc111329559a233b772c1a105", size = 162899, upload-time = "2026-10-07T12:22:50.088Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/c8/68cfce773a2733a49c74f99d627fb461bd990756860099eac25617889585/tomli-2.5.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:521345fd1f19d45b8df87657aaa38b6f2ca3800059fadf428e7ebf479a383646", size = 162080, upload-time = "2026-10-07T12:22:51.558Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/b2/e5bb8651fdad593f670501a7d718b1a7f73f064d44dea15e04c04dfef45d/tomli-2.5.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6e95c7614e705bfe2b04b27aa124adec59752d15813df37e2156747cab3a006b", size = 273380, upload-time = "2026-10-07T12:22:52.918Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/d2/9e2d7f8b1dfe0e2b34c245986ebd55c4c553ea4ce6c47c443b332673253f/tomli-2.5.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7ac2027d37c3afbdf4bdd377f2676f6f1d2122a5be1f1137b49dced590b37e75", size = 283228, upload-time = "2026-10-07T12:22:54.173Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/df/ec7b876b7b1a2718bd74a3743c076fff565b04029ba33e8f61fac262739f/tomli-2.5.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c414be4ed9d3cac80c42e348fa5a956117d1a48227f48026e31f59cb4a7671eb", size = 277189, upload-time = "2026-10-07T12:22:55.342Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/7b/e192d9eed0b9cb80da799f4d77052297fb9a2c3cc9b19f571f56ea88add6/tomli-2.5.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:9b03d7dc168353b4132965bde20feceabaa470e570c6f59660dfae59b1f9eeb3", size = 283632, upload-time = "2026-10-07T12:22:56.735Z" },
+    { url = "https://files.pythonhosted.org/packages/84/50/ff94454e75461d75623e47401ed323d65c10aab8fe9033242c20cd2fdf32/tomli-2.5.0-cp314-cp314-win32.whl", hash = "sha256:6f041843c4d3a37245c0c056fd955b186bf8b1fb85690cbe40b81230891dc34b", size = 103535, upload-time = "2026-10-07T12:22:58.084Z" },
+    { url = "https://files.pythonhosted.org/packages/54/0b/bdacf05f963bd6026ebf6eeb0beda847d1d60e03e440725c64a4e08a0afd/tomli-2.5.0-cp314-cp314-win_amd64.whl", hash = "sha256:f4b653094e18f9031102d3a1da5c729c8f222d85225b18037dac621695e46e1a", size = 114621, upload-time = "2026-10-07T12:22:59.2Z" },
+    { url = "https://files.pythonhosted.org/packages/61/99/53f438fa6ae4f9d4ed0ddde3e7242b3bdc34b48c8f9948b72b9e9b127676/tomli-2.5.0-cp314-cp314-win_arm64.whl", hash = "sha256:3f89d10c1ff6a38d992c27fc8a4816af71a909e08a40ec66934240b1e74347c3", size = 111572, upload-time = "2026-10-07T12:23:00.479Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/20/1f88f19427d380a40e90a770e087489eaafe4aeee070ae88ed2bbec00acd/tomli-2.5.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:e9e15b4a6c7dd6b85b5fbab29488a73f1f70de516942308daa266bf0e0aeb0d4", size = 171814, upload-time = "2026-10-07T12:23:01.914Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/56/cbe5079c9f9a54b9b3e27fc82f08f3cb36edee75561679f53d2380c801d6/tomli-2.5.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:e12bbcd32897272fb05929110362ae9ff4c1b9bb26bd9e971e71dcd3275b4c3d", size = 171324, upload-time = "2026-10-07T12:23:03.18Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/30/1d53fd3b0f1cb3ba542e345ec32c26aefdddc4e829e4f3429af8a4f27782/tomli-2.5.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:20aa36de8f2cf87237143bc1fa1aae8d6612c09118f4da21c6a684db5dd1f6f9", size = 297441, upload-time = "2026-10-07T12:23:04.345Z" },
+    { url = "https://files.pythonhosted.org/packages/66/d9/0800acb6a111686f764c1b91ef15cc42a20a66a46013bb42220f1d2c61c1/tomli-2.5.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:22185fad8a1e622f064e78008018a0dd3323550dcb479cb7a1d296888d74024f", size = 307476, upload-time = "2026-10-07T12:23:05.671Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/63/30a8f3cd51b5bec37f04744bad0b0dc6160df84aad4f27b0e9283d66f221/tomli-2.5.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:984012f71908165449a951de2050d52f276bfe3aa5d5f570f63ddad814370374", size = 296113, upload-time = "2026-10-07T12:23:07.202Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/18/0b9ffc597e69c5a1e20a7823cb60d54b39a9f54e91edcb8574f022186758/tomli-2.5.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:f79203b3965b4000e91808aaa7c040206093f2b8bf86f455982f2274c9ccf442", size = 307725, upload-time = "2026-10-07T12:23:08.508Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/c7/18f8baae0b5607a60e8e19b4a7fedee43a8ff6458e3896dcbbadeeac9c22/tomli-2.5.0-cp314-cp314t-win32.whl", hash = "sha256:91294a9fb94a75542f6e46e4a2ae709bd8d9b51134098cae5cf3bea5478b6d03", size = 108546, upload-time = "2026-10-07T12:23:09.956Z" },
+    { url = "https://files.pythonhosted.org/packages/72/34/4cca9739254130627bde87500b3f2b512154fe2f278efa7e2a5e10ad4bcb/tomli-2.5.0-cp314-cp314t-win_amd64.whl", hash = "sha256:f15e3e0b835a6d68b10c86bf80a3149780498d6911c93c3ffd1861d19f9200f1", size = 117814, upload-time = "2026-10-07T12:23:11.486Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/fb/afa530d47dd80a78fce43beac6bc6e00f84558eafcffbc6f37b21e80d056/tomli-2.5.0-cp314-cp314t-win_arm64.whl", hash = "sha256:6664b7ae7af7294256c53960a6103077f4914cec8ff98479c352f622c6f6b2f0", size = 115188, upload-time = "2026-10-07T12:23:12.728Z" },
+    { url = "https://files.pythonhosted.org/packages/60/3f/3e3f8fd0919249b0200c80fbc4f9a1e70be19f9883da71dfb7f8b9ab8aca/tomli-2.5.0-py3-none-any.whl", hash = "sha256:32a7b79ac57a2e83670ce329ccf675798bc5a2094783a63676866b70503f2e2b", size = 14765, upload-time = "2026-10-07T12:23:36.875Z" },
+]
+
+[[package]]
+name = "tomli-w"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/19/75/241269d1da26b624c0d5e110e8149093c759b7a286138f4efd61a60e75fe/tomli_w-1.2.0.tar.gz", hash = "sha256:2dd14fac5a47c27be9cd4c976af5a12d87fb1f0b4512f81d69cce3b35ae25021", size = 7184, upload-time = "2025-01-15T12:07:24.262Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/18/c86eb8e0202e32dd3df50d43d7ff9854f8e0603945ff398974c1d91ac1ef/tomli_w-1.2.0-py3-none-any.whl", hash = "sha256:188306098d013b691fcadc011abd66727d3c414c571bb01b1a174ba8c983cf90", size = 6675, upload-time = "2025-01-15T12:07:22.074Z" },
+]
+
+[[package]]
+name = "truststore"
+version = "0.10.5"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ee/9f/c5201d42a484c061e528825fc8e2d565f5abd50a4ced6fb7d29c4ec99b2b/truststore-0.10.5.tar.gz", hash = "sha256:30d36967ccaded5cbb38d602c433f53600036c79d502f4533a49b60a03bbefcd", size = 28091, upload-time = "2026-10-12T22:27:31.808Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/51/e9/3a7820be2bb0fe53b6bc9c3be26d3d1158004e4c3ab953aa6840b955b1e9/truststore-0.10.5-py3-none-any.whl", hash = "sha256:9aaaedaefaf06d8b206278cf8b5012bc897f485a874503501e12d776df78951c", size = 19017, upload-time = "2026-10-12T22:27:30.377Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.16.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f6/cc/6253133b5bb138fc3306cebfbda2c520f545d36b5be2c7255cc528bb45d6/typing_extensions-4.16.0.tar.gz", hash = "sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5", size = 113555, upload-time = "2026-07-02T08:40:05.92Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/49/d3/b8441a820a491ddfc024b0b0cf0393375b75ea13866d9c66727e54c2fc80/typing_extensions-4.16.0-py3-none-any.whl", hash = "sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8", size = 45571, upload-time = "2026-07-02T08:40:04.659Z" },
+]
+
+[[package]]
+name = "typing-inspection"
+version = "0.4.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a3/26/b09b8010994eccc3c09092e6b34058f36a460eea2d4c3e8b910c695975a0/typing_inspection-0.4.4.tar.gz", hash = "sha256:547274fa6b0a561ccf549cc9524b999a578e737d015d8709d021f9d0d13bea47", size = 76928, upload-time = "2026-08-12T12:37:25.997Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/67/81/4add07e5172b7ac40d8ed5ff580409a7801a4fe26d529bdd915401dabfbe/typing_inspection-0.4.4-py3-none-any.whl", hash = "sha256:65b8397ba37ccbce054456aaccddfc91e6e3083c92824df348d96ca832f3f147", size = 14750, upload-time = "2026-08-12T12:37:24.648Z" },
+]
+
+[[package]]
+name = "urllib3"
+version = "2.8.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/05/b17359e1cefb4f909b5e40b1b90a496d987258916dbbf88e842c729f510e/urllib3-2.8.0.tar.gz", hash = "sha256:63bf2ead4c879426ebf22ef2a781eeb4aa3b4ae798a0435506f8687fd5bb9b63", size = 458972, upload-time = "2026-09-15T19:29:36.253Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/92/9d/c4e665119135114480843e7ab388fa94d8480650450e6f8e26b70d323a4c/urllib3-2.8.0-py3-none-any.whl", hash = "sha256:0cf3cae568d36aa9576b28dfb35f11328f1cb974ca7647d9475ebb86c75ac6e3", size = 135717, upload-time = "2026-09-15T19:29:34.577Z" },
+]
+
+[[package]]
+name = "uvicorn"
+version = "0.54.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "h11" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/da/34/30e9280707135d2cfc589dfff3cb796bd07a3aeb1a3e415ba09dd89d7bb4/uvicorn-0.54.0.tar.gz", hash = "sha256:a2e33cbfaa0306f8e6b0c13e0cb89d7d7a2da3e62b90c66e18c33d9807b28620", size = 112283, upload-time = "2026-09-25T06:52:37.601Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/38/0c/b54a4fdd7f90a3af8b02ebc9ce6712c2c208b7926a2f7bad95c33ebbe943/uvicorn-0.54.0-py3-none-any.whl", hash = "sha256:505bdb0f318731d45f1f712071fc781a8981f6847a31c902c9f5e652d4f67faf", size = 87427, upload-time = "2026-09-25T06:52:35.829Z" },
+]
+
+[package.optional-dependencies]
+standard = [
+    { name = "httptools" },
+    { name = "python-dotenv" },
+    { name = "pyyaml" },
+    { name = "uvloop", marker = "platform_python_implementation != 'PyPy' and sys_platform != 'cygwin' and sys_platform != 'win32'" },
+    { name = "watchfiles" },
+    { name = "websockets" },
+]
+
+[[package]]
+name = "uvloop"
+version = "0.23.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/fa/42/02c739ce85fb2ee8d99212c61417da8140c6b87e9d97c430bea520d76044/uvloop-0.23.0.tar.gz", hash = "sha256:28d160f51ab4da3b187063652e643dea6831072add4adc1e6d62afbe73b6be27", size = 2559185, upload-time = "2026-10-01T03:17:04.4Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/4e/a4/00e85345871c59c834a23c136c1771205856028ecc8ba940b3951178e59b/uvloop-0.23.0-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:b90397a50ad6332ed3e459c648ac20d182cce24a557354363ad85fc9ea4a17cd", size = 1421363, upload-time = "2026-10-01T03:16:02.599Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/a9/e5f0f3cfde30af3ec32eba8ec07bccdba2b5116afbd1ecc53edfeb0a0790/uvloop-0.23.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:be53e1d5f83de43dc175c87612ecc128d444b38e5c56cb3f807f5a73d6887476", size = 785177, upload-time = "2026-10-01T03:16:04.018Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/79/9ddf78f8cd75a15c14a09a57f59c587b8cd9d82802c5c8368b9c3ebefa0b/uvloop-0.23.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6b3cbc4f96ddfa1fb88a78a69dd851369825b7816d9702eee8c4461505ba172e", size = 4381060, upload-time = "2026-10-01T03:16:05.642Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/20/57d63c44d32326878fcad5c63854afc9deb394ed95673c1b1a429178c79d/uvloop-0.23.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:31e0cf90bc8fd88784f6802cdba968a51fb1aec1cc3feec74d862b2d371d1330", size = 4418891, upload-time = "2026-10-01T03:16:07.326Z" },
+    { url = "https://files.pythonhosted.org/packages/12/c5/0795abecda2cc3dfe41033f880a32a9ff103be4e6b177ac736833c153a0e/uvloop-0.23.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:fa8ed556fcc87a4091cf61587ef172fa104323dc89ecc085a618ba7ff8629a8f", size = 4214811, upload-time = "2026-10-01T03:16:09.13Z" },
+    { url = "https://files.pythonhosted.org/packages/20/18/9010dacd5221eec1bd79a4a83ac68f3db6a42d7bb657f7b640c4838ca6b6/uvloop-0.23.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:f3fbfe82829d8e381426a289b87e59e585278728361db9ce975b88b51f64f410", size = 4294876, upload-time = "2026-10-01T03:16:10.875Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/08/f6384a03c771d00067cba4f542a69b2fc1a982e9fd78b357c2f788678d72/uvloop-0.23.0-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:7e35c9bc977760981693e1a7a51493b58ee5a501f9ebb1e547565ee40b6c6208", size = 1494811, upload-time = "2026-10-01T03:16:12.399Z" },
+    { url = "https://files.pythonhosted.org/packages/ac/01/756a4fb24a449f313cf4a153eb0c6210b49cfe5539255ec9fb1e17d2c4ef/uvloop-0.23.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:5bb9be71d9ee39b4359b832f9569518ec9bc08704194034e79e4958e6bc4d46d", size = 819396, upload-time = "2026-10-01T03:16:14.094Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/45/e314b0c600b14f53dad3a3c2d7a922a249a88225fd727652b53e1854b9dd/uvloop-0.23.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1e84575f11873c109cf3962ad0bdf679094466184125f4cadcc41a73febff41f", size = 4734966, upload-time = "2026-10-01T03:16:15.815Z" },
+    { url = "https://files.pythonhosted.org/packages/66/0d/8686a7f0b1b2d55ebd770ba21f8e0e4ffa0cde5ab738f43ffb8264499052/uvloop-0.23.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bbbdb8fcd5e7062e546eec1ac78c28bb21ae7df54c18f8e4b06e15a18d661a49", size = 4584963, upload-time = "2026-10-01T03:16:18.198Z" },
+    { url = "https://files.pythonhosted.org/packages/78/b2/034a2d47e435ac02357c42956246887167bdc0357bdd6ad31c5f6d94497b/uvloop-0.23.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:76345f51367fb1f23e08605c6efb18374f669be5b223658fbab6b17627950507", size = 4421388, upload-time = "2026-10-01T03:16:19.953Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/77/131f4b583e6b4b715c404a66b51c812d701db20f25c9018b188a2b00062c/uvloop-0.23.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6c7ef4701a96553514b2688e342ef1bf2beae6cfd172d89a76c768292aabf405", size = 4402414, upload-time = "2026-10-01T03:16:21.716Z" },
+]
+
+[[package]]
+name = "watchfiles"
+version = "1.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/68/e6aa0b77d217b31f8f486ec0cdfe5e00e6e38dc0be657e7d85819b9faf0a/watchfiles-1.3.0.tar.gz", hash = "sha256:99aee4a07847c06820765fd7b1b49ceac4f3f711ccb7d104655a33231de1c207", size = 108119, upload-time = "2026-09-21T09:08:55.664Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/68/fa/c0b840d5d8bafe640925408ce11095948c8945bb61be1e67d0ab629b872a/watchfiles-1.3.0-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:000b9688fc8133037a8b075c8ebf98f32844ff8964dda61e85c1db547dafc441", size = 399703, upload-time = "2026-09-21T09:08:13.518Z" },
+    { url = "https://files.pythonhosted.org/packages/c7/8a/894799b485fe9473ad10422a0d9668e53fb78e3a2b5cc6061159572844ad/watchfiles-1.3.0-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:bbc1198edfdc90fda0600f825aa94150f428dfcbf8138746f55998e0e660d64c", size = 397647, upload-time = "2026-09-21T09:08:15.16Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/61/f277cd5ead05f5d37b98b41fbdd0c943ee0c04d49738f62e902cb291cf43/watchfiles-1.3.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4af9c464d410e8c44b58ddf1cbec7c3a02c1cb2c6c80df9c74659ba2fbda0ab5", size = 454994, upload-time = "2026-09-21T09:08:16.587Z" },
+    { url = "https://files.pythonhosted.org/packages/46/66/ea4c01382975e53b1ac1b0a0ea1b353416b8127fb6e04f5c1c313119aab6/watchfiles-1.3.0-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:eb94e40b9a0db19636b5e3fed0a9803452ecc7381df13b385272abb779ee83ca", size = 460105, upload-time = "2026-09-21T09:08:17.961Z" },
+    { url = "https://files.pythonhosted.org/packages/31/c3/1a501b597817096c9831c255f6270c124ce0e2faeb74124be24dcc93b86d/watchfiles-1.3.0-cp310-abi3-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7398930a2b76b9dc67a4e6b8bfc7baf30946892a86f417a3920c07bdd6febc30", size = 493761, upload-time = "2026-09-21T09:08:19.327Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/16/77352d05e152c7786a016e9f1decdb4507e8aa5bcf3343c72142a0413d14/watchfiles-1.3.0-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:025b108f2d5cc2799cb941f79380df3e8b22bfb589c218e801767fe78d598c95", size = 577500, upload-time = "2026-09-21T09:08:20.723Z" },
+    { url = "https://files.pythonhosted.org/packages/95/fe/81001c55b24466fe9911135e50269fd3a29f43e446627a92adfab54553b6/watchfiles-1.3.0-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:be9ef3cd403d756a304a0a08a112163c63da7ec72c8c9d083c98818291ff8f29", size = 469209, upload-time = "2026-09-21T09:08:22.346Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/cf/e3ad894ed5909a7c44b0707e89bc25d19a3d78b3a7aec846119443b6ae56/watchfiles-1.3.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b5768b49e426fd5b550b012c866db347cdf15c398ef98dc557b6e6b72fa74cd1", size = 458353, upload-time = "2026-09-21T09:08:23.7Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/f5/2f106829e6e2bc91ad74614730f6df484202b9a4d20d927dbf2f08d37d44/watchfiles-1.3.0-cp310-abi3-manylinux_2_31_riscv64.whl", hash = "sha256:d36c72fcdc08f143d87316a4c4c3b064e340da2c7383d39803950740ed418935", size = 468707, upload-time = "2026-09-21T09:08:25.167Z" },
+    { url = "https://files.pythonhosted.org/packages/15/37/2741ab776b978669c1f3bba1e573f1a184f727ab8b4d3a6d9c61090800ed/watchfiles-1.3.0-cp310-abi3-musllinux_1_1_aarch64.whl", hash = "sha256:f0c9865240e065a2247f4b5248528ae3d01e0e8ae071462c250c884dc16e3ee3", size = 632510, upload-time = "2026-09-21T09:08:26.532Z" },
+    { url = "https://files.pythonhosted.org/packages/48/64/db4a4684275fe9b696ee5118c194705c1423b3d42181c3f8ee70194d5c73/watchfiles-1.3.0-cp310-abi3-musllinux_1_1_x86_64.whl", hash = "sha256:380f513d26cc2e598266b88d66456e07d67ef4be8f0f435a1154d9c44b43d509", size = 661723, upload-time = "2026-09-21T09:08:28.004Z" },
+    { url = "https://files.pythonhosted.org/packages/52/80/95ddb24f6a2f595c031c24432ab7b8aa7d6d1ada0c6d63a552166e06e8d1/watchfiles-1.3.0-cp310-abi3-win32.whl", hash = "sha256:509d9f74d2bec5c1f4cd868ddcfe0c9601f7ea53066dfcb19d8ede742c4de661", size = 277761, upload-time = "2026-09-21T09:08:29.335Z" },
+    { url = "https://files.pythonhosted.org/packages/48/a1/1c4a1b3c8030cd03206232612be8a6e8799093490c220b0fcb935d02b75a/watchfiles-1.3.0-cp310-abi3-win_amd64.whl", hash = "sha256:1acabde19b67e673274e89a04d613b7fb1f122e2c4b8ec9a581e59c149264b61", size = 290643, upload-time = "2026-09-21T09:08:30.45Z" },
+    { url = "https://files.pythonhosted.org/packages/82/e0/d2db577c632d26d08078c4390dd870b8555c4e558df25d22270f0166c71f/watchfiles-1.3.0-cp310-abi3-win_arm64.whl", hash = "sha256:d978cc1dd7ba44f5590d7de74f7a9c8be7262d9e469c2c0efb8bbfc2574321dc", size = 285510, upload-time = "2026-09-21T09:08:31.561Z" },
+    { url = "https://files.pythonhosted.org/packages/4f/55/a122743607939429ab6a7272672f49303aa02bbd34c3f06676765a3861de/watchfiles-1.3.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:e0204f90677b7fb8d3a824279a71a01166bea9f6e53923b8056592d87b33b0b6", size = 395978, upload-time = "2026-09-21T09:08:32.747Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/9d/0ee1b0ea42acfe72afa2484f0222e2386dd09992e9034a81e63cc3cdab0a/watchfiles-1.3.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7c1125e99f84934a92996ae343501285617373acd66f16b59fd5654b27ad8d80", size = 387997, upload-time = "2026-09-21T09:08:33.953Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/f2/4319c6b683e8bd28465dfc53c750617a2a07f072eb2e3ab0182ccf812229/watchfiles-1.3.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a85e243c87109d9f48a2e0d10d6abdee8768cc114848b32281ec83d7f81d86ef", size = 448067, upload-time = "2026-09-21T09:08:35.104Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/71/9f37ac192a51a24de3a2d7fe9aac1e99b2b2668300674ff7a9f85d95beb1/watchfiles-1.3.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:dd538c71766c59c732e2c5cedc39323c99c11897b99f93eac773438e54af206a", size = 452881, upload-time = "2026-09-21T09:08:36.238Z" },
+    { url = "https://files.pythonhosted.org/packages/34/07/1224667c32a4a96876ddd642da69733cbfe6a15897db0865aec5a882cebc/watchfiles-1.3.0-cp314-cp314t-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:da213822ec9082b62cadf3008e07a8c690ec7a3c89f6dc5e55a8cf07b56a1b26", size = 484802, upload-time = "2026-09-21T09:08:37.717Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/4d/7f29cd87e1f826df86fc0418d0b8f370ca0311c29c618406dc492aad9951/watchfiles-1.3.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d4593392e87669836670f87d62fc754059eaeb0e6157af44060a46558cebe5a3", size = 567522, upload-time = "2026-09-21T09:08:38.94Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/ac/3aa1f84abd4dbbfbae99a817dd931f77b439261c911189cad4c30fdfd470/watchfiles-1.3.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:26b81bc515a0f03f66a69a6fea86eea54c8eca4173c46dd7222569f79dd2f977", size = 461997, upload-time = "2026-09-21T09:08:40.142Z" },
+    { url = "https://files.pythonhosted.org/packages/82/1c/27c66764d5b0dbb70a36770a32eca217eba739c28b24e8583a035087a3d7/watchfiles-1.3.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ca39661934749df580d89f3dde266f2af7c6968f4c21c72ce2dc387d299e6aa7", size = 451856, upload-time = "2026-09-21T09:08:41.305Z" },
+    { url = "https://files.pythonhosted.org/packages/1e/b3/a45827084d953c1d0dd3d75abf85dcac26a0f5d115ad2fe0b7e9e931573b/watchfiles-1.3.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:04c5500faa725d69a99b0f63750e80795e455bb951849e9c98a811b4324997c4", size = 459889, upload-time = "2026-09-21T09:08:42.58Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/3d/07740d23ce2bb23419bb24055c435a9abe5fe03efdaea1ba0720b831aab6/watchfiles-1.3.0-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:ec3cd4bb181a7b6329134204c2277c7144ab5f62cce9c5335d6f901ee7ce8d6a", size = 624482, upload-time = "2026-09-21T09:08:44.064Z" },
+    { url = "https://files.pythonhosted.org/packages/91/46/9540f8123eaec86df989f26d7704cad0448d9fb7271763a4f8f9fe23617d/watchfiles-1.3.0-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:e5871d4a7f788a9f64fb06f5793389d29d171e5c32d37c3ebfd520b017cc7694", size = 653724, upload-time = "2026-09-21T09:08:45.257Z" },
+    { url = "https://files.pythonhosted.org/packages/25/9d/b9deb52f1e4528ffe44338c5ebab95c32ed79203082da661de50288e130a/watchfiles-1.3.0-cp314-cp314t-win32.whl", hash = "sha256:81c989d7267bfb7b676cd32c83bec97914e396870983cbf493e29415037bff5e", size = 270863, upload-time = "2026-09-21T09:08:46.518Z" },
+    { url = "https://files.pythonhosted.org/packages/59/59/8b1881afccbafda06248be4185e28034dd73c80c85e4da24f2cb0c1321eb/watchfiles-1.3.0-cp314-cp314t-win_amd64.whl", hash = "sha256:d754e049006e81a9be49dc78ba7802081cee426e968cbc63ee19e164fa2d0e39", size = 286879, upload-time = "2026-09-21T09:08:47.874Z" },
+    { url = "https://files.pythonhosted.org/packages/46/dd/41c12ae9745d5d72f709333287679d71cbba68ad7678fed872207bba94f4/watchfiles-1.3.0-cp314-cp314t-win_arm64.whl", hash = "sha256:a5b631db08fd3032db57ec6a92d1777cd60f88803287e4e941a4858c53aab1e0", size = 276924, upload-time = "2026-09-21T09:08:48.976Z" },
+]
+
+[[package]]
+name = "websockets"
+version = "17.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/01/89/3f825ab71c242fffb62ea8fe638741c290f62f8d7aadf8125ff897747af3/websockets-17.2.tar.gz", hash = "sha256:36c2fb94c990cc2545143b12690e2de6c16300f9dbe5b4f33fa300cf57dc8792", size = 188355, upload-time = "2026-10-03T14:56:53.5Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8b/74/6bc991a28ac983600e65de408ebd1b1413d554ed0468ae5c831bc52dded6/websockets-17.2-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:ecb748910e9ba4624ebe2057791df51dcbffb48c37108ab94a3c593472023c9e", size = 217791, upload-time = "2026-10-03T14:54:26.381Z" },
+    { url = "https://files.pythonhosted.org/packages/cb/2f/158e99426be6e71d09520bae53f29294fbb614b2fc5fbf8867b1d08395a7/websockets-17.2-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:2ab9af5cb7265899e659f079eb71691375a1025b6d5fbd3caa495dd08f70833a", size = 215486, upload-time = "2026-10-03T14:54:27.962Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/09/1abf942723c0001d9c2fca1551907dade6304517b982b0bf10bba107fa81/websockets-17.2-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:06e46da092bca3a52e98f0458c66b247993ce501a07cd09c858be3296511ab7d", size = 215699, upload-time = "2026-10-03T14:54:29.523Z" },
+    { url = "https://files.pythonhosted.org/packages/a7/1d/1ade03963ef497c47e6bad79e24370827b2fe6145fa8f58070ff2b7dcbac/websockets-17.2-cp314-cp314-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:fcce735ffd72ac4056db05325d9f0232382b74826f0196eb6a15ca903abdaa0f", size = 225081, upload-time = "2026-10-03T14:54:31.278Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/fd/47b8a0361c49da939b976a07b27a72a9f893d01dfcf4d2a28b53419ce1ef/websockets-17.2-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:42cbca10f82a8b2fb1536e8a0830ca6ceeb6bb3d8d64b766e0795369135654a8", size = 225430, upload-time = "2026-10-03T14:54:32.917Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/26/f4d4c76264ee037c5556ab5f50fcba302746dabf7528955534e4dda9965e/websockets-17.2-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:c63ff5a21f26bd0e6a8464b53fadbe174825c8718ac14180df45665eaacdb6af", size = 226676, upload-time = "2026-10-03T14:54:34.833Z" },
+    { url = "https://files.pythonhosted.org/packages/37/b3/c8b1c981322a050c4babfd327ffc9880f9c3834f5b15d2574e37eeb8768c/websockets-17.2-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:63f543463601c1558b755f8dd7618b6ec3dd0934dda051d3b7030d8c76e54de2", size = 228048, upload-time = "2026-10-03T14:54:36.424Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/5a/1cb29ddb23e6bc27ffd1c5316cd3616360d1ba0c3854eaa134ee3207bd28/websockets-17.2-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:4c32eb565ad9ce8a6444248e5b7a19dbb86a81c811fe5fcc2fba7a735aed5163", size = 227281, upload-time = "2026-10-03T14:54:38.01Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/64/135274572dc0c845fc1111e2b932c807c395daac75d6eae6cfa148d8a208/websockets-17.2-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5d459bbb6c22f26dcebea56924a362aba50d453b9867912862c970434fcf0d94", size = 226025, upload-time = "2026-10-03T14:54:39.613Z" },
+    { url = "https://files.pythonhosted.org/packages/58/75/f1e386aec3124489411caf5138cdd5a2bc43d3fd4a681c69adcf5f6272a5/websockets-17.2-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:f19ca1a21871f024e38faf4107b433047df27558dff1b72a1dac31481e2c1fe5", size = 223277, upload-time = "2026-10-03T14:54:41.165Z" },
+    { url = "https://files.pythonhosted.org/packages/60/eb/24733a0f568c2eb99e60f9faa620a98fb228c06a01e7e2f348b33290ed9c/websockets-17.2-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c76b4bcbf0f713194591673fc86a42820e14da6bbd1bb445d3d002cc4d1e4521", size = 226148, upload-time = "2026-10-03T14:54:42.779Z" },
+    { url = "https://files.pythonhosted.org/packages/55/6d/ea66a30af74f5983cae31ebb9ef78b178b366a12856a414e1472225c4a34/websockets-17.2-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:30201a7f69833b015556c72feb69ea501b645986fd0b90dab13f589e995ff428", size = 224615, upload-time = "2026-10-03T14:54:44.41Z" },
+    { url = "https://files.pythonhosted.org/packages/87/80/c6f2228ad89774429d270179375ebddb657119215f52d1df7c680d65cad7/websockets-17.2-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:0c8600aec354cc259f1691b0b42816f04a9886a953f82cb227246df76057f97a", size = 225398, upload-time = "2026-10-03T14:54:46.063Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/4a/3d8da19732ad468d4be7f1e3ac298078b60bdda55edde6589bef84a5eb7e/websockets-17.2-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:307fc22ea496be8542d67b82ae8c867a978dfd19ac35573d4f15943fd9277dfe", size = 226571, upload-time = "2026-10-03T14:54:47.672Z" },
+    { url = "https://files.pythonhosted.org/packages/58/22/1231657122d9cc24791bb90af13cc2f4e84cf0d3a454cb37e3abfdcb2fd9/websockets-17.2-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:9c88697fa943bd4ef67cc919a17d81de6581846f52bfa8c6f64a916098986556", size = 224125, upload-time = "2026-10-03T14:54:49.537Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/04/350ca2445da758bc42cdb4218b44d4ce0d5a9c1d5e4cc4a58d64348ad9da/websockets-17.2-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:f7eac84d4969da82166d5e90d9c38d2f416fe24f9708a7013569b193745b9a31", size = 225081, upload-time = "2026-10-03T14:54:51.075Z" },
+    { url = "https://files.pythonhosted.org/packages/da/c4/dec952b0df3a5d918ed2a545abb0c25ae519c3bc2d9aba3b7c46abae8f05/websockets-17.2-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:313f6703023d53baabab6d6c5c37cf637b2c4fee255acf2ed5e92ad69e28f1b7", size = 225376, upload-time = "2026-10-03T14:54:52.675Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/b4/198a260afbcc086ff4979774e51834ed7fb5b95f9ef305e0c4924630b857/websockets-17.2-cp314-cp314-win32.whl", hash = "sha256:08d90cf344bdb971ba3a826b78d4da9bfd56cc6a97a604d9b88cbd40bfa6c735", size = 217760, upload-time = "2026-10-03T14:54:54.247Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/9e/0523f8bc2f7aaddf39562d4fa01b4d38fa61b23d980917a16d2dd19c8dac/websockets-17.2-cp314-cp314-win_amd64.whl", hash = "sha256:dac93bf7a9beb215be3282b8441173cd50806c41c007b8be9bb24e03c60ad563", size = 218104, upload-time = "2026-10-03T14:54:55.845Z" },
+    { url = "https://files.pythonhosted.org/packages/55/17/7b8bb4cb64a199e7082f1f9be784d657842fefc327ac777d6c1493504804/websockets-17.2-cp314-cp314-win_arm64.whl", hash = "sha256:2ab742249f953d148a9ba696c8b9944361e8cb92e8bc61ba2dd53a178403afd3", size = 217989, upload-time = "2026-10-03T14:54:57.376Z" },
+    { url = "https://files.pythonhosted.org/packages/ee/76/f54ed054b6e860f1e0bbc7019542a048352d41231fdff6d904b379f881c7/websockets-17.2-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:a69ce25be5f1330ee1c74eb6fabbbceaa96b384beedd2627cecded7546490c40", size = 218125, upload-time = "2026-10-03T14:54:58.943Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/4c/0f3375cea66a125ae01d21fb9c537aae955ef499bfe7e2b2376a34362f2a/websockets-17.2-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:8e24b878cf54843a63985d90480f163ca7f692689fbcbe9cdbd8165521083a8b", size = 215658, upload-time = "2026-10-03T14:55:00.674Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/05/7c871a67bfb4b61adc1fe13583db97803f87dfeca644fe6ef51df7bb276d/websockets-17.2-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:f33c7908a6885dcae9f462a4a8347b637053b4ff2b96beb4c23fba1cf7818e5f", size = 215858, upload-time = "2026-10-03T14:55:02.379Z" },
+    { url = "https://files.pythonhosted.org/packages/41/8e/59df4d9cd357e902d1c74b13c3c0c3841c8df6e4b1b3d131bf26a23fdcb1/websockets-17.2-cp314-cp314t-manylinux1_i686.manylinux_2_28_i686.manylinux_2_5_i686.whl", hash = "sha256:c796a1bb3e4015249639849f30e8e680df8a431b45d417ba8acf843d2451d95f", size = 225443, upload-time = "2026-10-03T14:55:03.966Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/64/5e486a3a44e041203c62eccf1fc89c7f8824e21104a7b82b182e5b21c228/websockets-17.2-cp314-cp314t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:983bcdc898662f6ba9d6a025c30d29946ff0986d9ad60d400af0da3671f7cbf3", size = 225726, upload-time = "2026-10-03T14:55:05.797Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/98/b6eb53121c91fbe8b6897aba06861ce60f9ab58faffc6bca5750cbc21681/websockets-17.2-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:35e0f088ddfd9d9bc5019e27ff3767411779e92b59db5bb1507f2731a5b61158", size = 226895, upload-time = "2026-10-03T14:55:07.626Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/18/8c091321b99c91eb3eaec9acbd940e69308b4e465b5605c430af0cf7d3a5/websockets-17.2-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:19e2511412ad3393191de652513bc7a0ca3c93af143b32d96d46e59fbbddf1d4", size = 229040, upload-time = "2026-10-03T14:55:09.321Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/96/3a92f944305b7de42fcb7530b9fa69607b4b4ce993c36a9f2330dbc318ba/websockets-17.2-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:cb5e2bf969ac99a6ae3c71208a5eb05cfde973192540ffa6e1068b57fb78c4f8", size = 227469, upload-time = "2026-10-03T14:55:10.935Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/a9/624f6d75ba326c22d03698b34c0ada984f1d76196322a62f6c22903b831d/websockets-17.2-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:691780fca2be3dec512cb603cb91060271968cb4af86b51d07c57445c5754a37", size = 226202, upload-time = "2026-10-03T14:55:12.536Z" },
+    { url = "https://files.pythonhosted.org/packages/47/af/1e6e8c625aeb268830af2c4227fe05e8db59f4f4debe1dadfd0ada214895/websockets-17.2-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:2d39c19b1ba6a6791050383fd69efdd3b63533e2254693d0263879cd5f5921ba", size = 223743, upload-time = "2026-10-03T14:55:14.164Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/81/33c5280f4f6f81637c93ae065c6a594dfe35935622af135a5f7c3768bf22/websockets-17.2-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e48ac2b302986c6f55cf61e8e36b4dd97d0132c5078a713a697a940934ba422e", size = 226492, upload-time = "2026-10-03T14:55:15.796Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/f3/7aa9fc36e67caccbcfee2c48f4ada41e9da512d41523c024d039f0f22ba3/websockets-17.2-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:e136197f1262620ef2e507afc3ea759c1ae7d221886da20eec5f4c9f2618c2aa", size = 224940, upload-time = "2026-10-03T14:55:17.661Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/8c/457aff7081a63d1261608bb4d7b0b0f9dfe780697a2a334671745742850b/websockets-17.2-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:3eb44019a2b0b3b91bac95998f1e4e5589730421170e060fe654a2b7be727dc7", size = 225835, upload-time = "2026-10-03T14:55:19.607Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/c3/7a13a3b3050db2c36772ded49f8d48f99eb080948e9f6f762e7529925ab5/websockets-17.2-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:e5855e574804398859c5fbaf4fc7882b96278b7f6572a3d889627e6eb6cfca59", size = 226848, upload-time = "2026-10-03T14:55:21.274Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/3e/d5b2c1e473b1031a4a0ec0e10de69df5b981ab4a10aa482bb45c18dd43f5/websockets-17.2-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:5dc29815520c329f5662f6eb3ebadecf0d4f8c82dfa416d4d6efbf8f39245559", size = 224541, upload-time = "2026-10-03T14:55:22.874Z" },
+    { url = "https://files.pythonhosted.org/packages/79/5d/bb81976cc1aa546afb51395ce42913521e9dea062bb34a61308cfff30726/websockets-17.2-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:d1a4f9462da6496b6cb79bbb09c60d17f7e63e8a1df136797b3afabec9560e4d", size = 225315, upload-time = "2026-10-03T14:55:24.443Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/6b/314962d5440c61b4c107914599c13ceeecc6bdb6e2e73a5f7e566a7d1f26/websockets-17.2-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9496bff5541086478264678bac73c0a75b2fde94fdf6568893bca1f7c6d50d18", size = 225747, upload-time = "2026-10-03T14:55:26.033Z" },
+    { url = "https://files.pythonhosted.org/packages/98/fc/9eb64b34a3a4458eb08f3f24bde01508f72a00790330723c158ebb965048/websockets-17.2-cp314-cp314t-win32.whl", hash = "sha256:e1e3bc8090a7eae79fdf634b63bdbfa3c93999991023c37c6fd3b469fc8ff5dc", size = 217891, upload-time = "2026-10-03T14:55:27.681Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/ed/3a4e2a09b0822d6e525cbc6e44a4885669bad5b22ab9c64fa2444bc15325/websockets-17.2-cp314-cp314t-win_amd64.whl", hash = "sha256:65a89a5bde227bfe908016f35b5bd347970cd1e5b0360f389502eba1c7fde6e0", size = 218229, upload-time = "2026-10-03T14:55:29.314Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/66/cffb75ee746dd060984c3c3e2eac7f875a866225a30dfa53e2cd18232565/websockets-17.2-cp314-cp314t-win_arm64.whl", hash = "sha256:1c27339934109dfaca83f18ab2c23db06714e9d5deca2c8e37e8f492ab90d20b", size = 218146, upload-time = "2026-10-03T14:55:31.001Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/58/835cd51934d6780fa586f275b5d9901eead6d81569b4343b3767cdbaae4c/websockets-17.2-py3-none-any.whl", hash = "sha256:6aa59f0ef92e796b2db6f5f26550c4713c0e4036899fadf02f55e2ed4db0b7ae", size = 211883, upload-time = "2026-10-03T14:56:51.898Z" },
+]
+
+[[package]]
+name = "yarl"
+version = "1.25.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "idna" },
+    { name = "multidict" },
+    { name = "propcache" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/75/16/e8be8e2fb175bbf41a0680381a319f1199fae256588241a2ac8677eafb49/yarl-1.25.1.tar.gz", hash = "sha256:03dd38de09bc213e9a8b29761eec33ee1d5318dac0e49d8af36e4d27830e23a7", size = 246245, upload-time = "2026-09-15T19:35:02.264Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/80/cf/54023edfab7aa773b860503db0c56e962ccab0922803ee97988c176ea090/yarl-1.25.1-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:a9ca696eb02e5c02a8afd872ada510eba9b7fe6e68b9572c2e9a9b1941e31e2e", size = 143975, upload-time = "2026-09-15T19:32:16.416Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/a8/e6c1be0e6761d0f2d10bbf33a3e1e02b99dc83874d92945d7b461a72481e/yarl-1.25.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:a5877f2255aab518ebe528289037699201d5dc5f045f2396cb30aa02db22f57f", size = 104018, upload-time = "2026-09-15T19:32:18.364Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/bb/dda344765ffd3430afe1a1c66c866a57fae67786537d4f14607df6505ac1/yarl-1.25.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:7a5c3115595995779ee21f2567035793911c3802a43c74f3fbb0314929ec67ac", size = 104156, upload-time = "2026-09-15T19:32:20.459Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/5f/ed1538bcd06009fe990d6d283dd7667f639e62a81e35c6d8c6ef6c08fb3c/yarl-1.25.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:77e5099b99b37f3cf79c246998ca9f7313a78054cd1809ec46bc1afad47e1c4c", size = 116025, upload-time = "2026-09-15T19:32:22.766Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/af/2185daf56b99830d3356ecfada46faaa49945de6626e842b7728088d4980/yarl-1.25.1-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:6efaf45df6a849cef613a03a94c845647456662f85438c886bb67a9c027c8c2c", size = 106985, upload-time = "2026-09-15T19:32:24.749Z" },
+    { url = "https://files.pythonhosted.org/packages/c1/65/bc1ae564fb4b04a30b6a8f250e787772581c57e4c3d5cf07ac3359de3103/yarl-1.25.1-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:d5f90e44653c4e0f78501ed9bb7d3fce835a8d62b7c6ed0cb16557534087e743", size = 123030, upload-time = "2026-09-15T19:32:27.084Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/3e/e2afcde10d74e53b3fa889960991efb3019beda2b1682a01de720a302056/yarl-1.25.1-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:632da579b2d879f6bad20f2cfa35ded1efe2f4f77f8abb26a6234a5b236acd2f", size = 126765, upload-time = "2026-09-15T19:32:29.332Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/be/415b00c0fe5a0615b062a456b26623d7ec91c2bee20faea1a14045aa0469/yarl-1.25.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:30eec96e8a91bd588ce897c9543f6d5d8d34b28fbcba28a4dedf20ebeae9fe57", size = 117199, upload-time = "2026-09-15T19:32:31.49Z" },
+    { url = "https://files.pythonhosted.org/packages/97/27/3d8c63ddd3e8bcfd033748ab93876678ce59bacd66e4cb1ed851c9c5b37e/yarl-1.25.1-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:12b6bc4906e11f5e1a1cdcb12296e7afbd366c783cc8073403cd2fb74334e453", size = 115187, upload-time = "2026-09-15T19:32:34.137Z" },
+    { url = "https://files.pythonhosted.org/packages/39/b7/7a81d0be1a502a26a0d4326c6f2ecb736c824f570ea1c6529f2b0b227b50/yarl-1.25.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:9d6ed3d17bccce4c05343e1ca8da13bc5c02c812a4e7282ddd05e8769322d3fc", size = 116085, upload-time = "2026-09-15T19:32:36.438Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/69/39fff459916aa0fab42215dc47b759586fd80f94aa56dfc4a7c15ba6e0dc/yarl-1.25.1-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:f38a70074041d3b7e138e452799f5174198bae5bd5ab2000917badf403908c5f", size = 107996, upload-time = "2026-09-15T19:32:38.959Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/39/80b9a55a3335590451d9ecf3eb593a8c635351f4c905ef056d7e8a8fd9e7/yarl-1.25.1-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:4ca89e4e21854ed27ec753297dde84b16c9f8e53b14a4866fb44457d643c19f8", size = 122549, upload-time = "2026-09-15T19:32:41.151Z" },
+    { url = "https://files.pythonhosted.org/packages/42/7d/a179c6757818bb59372a4adafd09f7f26a3b4a0f04c3ae404b544c0b0c82/yarl-1.25.1-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:1ab7618921a93767387a4b83776f751588f5b5ae9bb5bc96620e2e2e00bca868", size = 115107, upload-time = "2026-09-15T19:32:43.072Z" },
+    { url = "https://files.pythonhosted.org/packages/32/2b/a773ac867e4ab53a98ed98e5cefe3bae31e6f550252ca9d1de266f1a40c5/yarl-1.25.1-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:0ae12ff2b805fa02c4dab838005caef735e39986322698c48588d3beacb65c62", size = 120666, upload-time = "2026-09-15T19:32:45.061Z" },
+    { url = "https://files.pythonhosted.org/packages/bc/41/52be6505e85b0f76b4f85b01b5de7e06a0512201abc2c95e14e099549174/yarl-1.25.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:90c30ed53546da833c700115c0064c22120d1b1560f474699fd31f22dd668233", size = 117505, upload-time = "2026-09-15T19:32:47.177Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/01/349c0386caedbbe488d519f252df54efac8a1459282d466c474bdd84a620/yarl-1.25.1-cp314-cp314-win_amd64.whl", hash = "sha256:acfa7e22aa6c6e7a5996a41d275bfa01efa7ea56ab890590280e9063e2cf5c1b", size = 103446, upload-time = "2026-09-15T19:32:49.615Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/f0/8ec63180f77912f0dc4e5a42760cb8c08d20da1d5ace3578a01b84d1f3d8/yarl-1.25.1-cp314-cp314-win_arm64.whl", hash = "sha256:8e7d98cdbb6d71e726f7d525952867096053d1f290dd4e3c50d7d313a136f414", size = 99159, upload-time = "2026-09-15T19:32:51.686Z" },
+    { url = "https://files.pythonhosted.org/packages/47/7d/92d2220d6886b70ab1ed8579533ac2af2dfac716d5d929001daff7986df9/yarl-1.25.1-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:d21f0fa80a02d05299207eeaafef345d812ace96d5306e4ef265e1d419a615fa", size = 150071, upload-time = "2026-09-15T19:32:53.911Z" },
+    { url = "https://files.pythonhosted.org/packages/64/fc/b245e448124bcda9340df38e3553fa222b50260fca027a84095e9bd8642d/yarl-1.25.1-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:17c9877a89fb6e2bca6f9087eb24cd7fb434653946ef5075e470d23d49b52287", size = 106780, upload-time = "2026-09-15T19:32:56.443Z" },
+    { url = "https://files.pythonhosted.org/packages/51/e2/9a6ce2e334ebf218a30335ae76fb1696459430d42f733b8cb0d7d65b84d3/yarl-1.25.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:29273edf1530e397bd07cb784db1fbe0d2590b77569f2e24679a9c0a2d763b94", size = 107361, upload-time = "2026-09-15T19:32:58.827Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/70/66e8c76b569b450d16e190f15071c916c3df70b0e33927e415ac497cf0c2/yarl-1.25.1-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b7abffdf37af1cec6a2ad69b827aa84320db5894791bc8ed932dc93fb274b7e9", size = 114396, upload-time = "2026-09-15T19:33:02.24Z" },
+    { url = "https://files.pythonhosted.org/packages/73/23/0d82838a05c57fdc05bc8b66e8c92dcc0df15e27463a5f163142d521c682/yarl-1.25.1-cp314-cp314t-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:2239a02249d9326655419e0168a28ca9008938eaab31dc29fc875c217927a6c0", size = 104882, upload-time = "2026-09-15T19:33:04.494Z" },
+    { url = "https://files.pythonhosted.org/packages/86/d4/ea08615c4edaa6049a13a2f1128944d068d1893abda7d708d4d7ea01599a/yarl-1.25.1-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:664ec6a520b74a1df2810666eb67695fcb77fa663e6ea0a25aaf2e529cb24dfa", size = 119485, upload-time = "2026-09-15T19:33:06.583Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/82/0898bdce9b1ae403b308b9c733d0d24af4a3464270c2c081f457b16c3e0d/yarl-1.25.1-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:4f1c91f5a5980a937ff8e238e98e6897e1ad74a4b1e2c0d68c73b5ffbb3f5c0b", size = 122490, upload-time = "2026-09-15T19:33:08.653Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/38/97d79b81c342b78246cfedb74809e68841f3198d21653e10d3232bd9c622/yarl-1.25.1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7c88edaec8c349ad4c5ad4c486a3defcc4b80ceb2f074436ffa0a87caf5e76a6", size = 115336, upload-time = "2026-09-15T19:33:11.056Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/9d/2577896554cd310dc470adb6da0b7dd0b435cb63e2565204a7ac240e504c/yarl-1.25.1-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:35dcbea443fafb3eece757ad4e514560ddeb6c34cfae1582c620d7b293d7feee", size = 111825, upload-time = "2026-09-15T19:33:13.204Z" },
+    { url = "https://files.pythonhosted.org/packages/29/6b/7ac49d8ba84a5c4bd73415a4c949d22c749cb3762579b3d50e48019a78aa/yarl-1.25.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:882569ff613758cac762a457a5d72d6e211b28d4bcfea89d1d71ea942b02eac0", size = 114655, upload-time = "2026-09-15T19:33:15.553Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/18/e5942a16723f5b72f9b1297fd5a85a54f6300cd15c0dcb5005b90cd89156/yarl-1.25.1-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:d0f1489233a254bb3643d2f05de7d59019254d81daeca6b9162fe9edef57e0c7", size = 106395, upload-time = "2026-09-15T19:33:17.599Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/2d/549fa46240781513ebc47ae7eb418df428a163a2a3d644cc9cbb3ecb7846/yarl-1.25.1-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:f41753a76f4f63927d03a0d8ba8f5ce0f2083bec29a8cfaccc55371b1564b96b", size = 119277, upload-time = "2026-09-15T19:33:19.973Z" },
+    { url = "https://files.pythonhosted.org/packages/76/16/4763f78dcdc0b3b9fb3842b04afe72b9320857c6a69300c62a0eab03d119/yarl-1.25.1-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:8fb0eb4955adf0579001581f2f71a126e8781ba61bcd120f127b0401163c6c2d", size = 112504, upload-time = "2026-09-15T19:33:22.464Z" },
+    { url = "https://files.pythonhosted.org/packages/ae/b4/974e3edfe0d188393ce1cb9de400111c63fe61f4eb3b772a500d84c970d1/yarl-1.25.1-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:a1e32763e641a1566507d90a8d3b19bfc3cc04a9d4e5ae3e32189874ed4b58a3", size = 116243, upload-time = "2026-09-15T19:33:24.788Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/aa/157b940428da80c104ca09666a740e51c94963df65d5b112e06b52e4d7a8/yarl-1.25.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:65b5b2066651b7432d389e9799d979c703bcc6ef44266bb8153ef54e91e4aab3", size = 115822, upload-time = "2026-09-15T19:33:26.886Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/af/19fbdce41412e1b96825544cc52cd7029d3724655d0988237972f078bd29/yarl-1.25.1-cp314-cp314t-win_amd64.whl", hash = "sha256:734f6e5400352ac4254456003d462866c684703570929cff7a7bde015d0cb371", size = 107386, upload-time = "2026-09-15T19:33:29.009Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/99/f6431c8968e89be608d74b28ae2d024521b2953f27dd44e0dece5e04f67a/yarl-1.25.1-cp314-cp314t-win_arm64.whl", hash = "sha256:287e99ff5aa4dc1c7630bfc683ded6f106d756c99dec432a2d7f197a784f51c6", size = 102094, upload-time = "2026-09-15T19:33:31.151Z" },
+    { url = "https://files.pythonhosted.org/packages/54/22/318c7980066769c6bcd9221ed2248294f5698811da099013098c670565ed/yarl-1.25.1-py3-none-any.whl", hash = "sha256:681c758b0490f9e96b78e5fa8e8dc6e648e9185bb6eaebe73183c33ea0c445f3", size = 63617, upload-time = "2026-09-15T19:34:59.616Z" },
+]
diff --git a/website/.prettierrc.json b/website/.prettierrc.json
new file mode 100644
index 00000000..d866bf87
--- /dev/null
+++ b/website/.prettierrc.json
@@ -0,0 +1,9 @@
+{
+    "printWidth": 80,
+    "tabWidth": 4,
+    "useTabs": false,
+    "semi": true,
+    "singleQuote": false,
+    "trailingComma": "all",
+    "endOfLine": "lf"
+}
diff --git a/website/VideoPlayer.html b/website/VideoPlayer.html
deleted file mode 100644
index 6ded8a37..00000000
--- a/website/VideoPlayer.html
+++ /dev/null
@@ -1,166 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>TGDrive - Video Player</title>
-    <meta name="theme-color" content="#ffffff">
-    <meta name="description" content="Stream files stored in Telegram with TGDrive.">
-    <link rel="icon" href="/static/brand/favicon.ico" sizes="16x16 32x32 48x48">
-    <link rel="icon" type="image/svg+xml" href="/static/brand/favicon.svg" sizes="any">
-    <link rel="apple-touch-icon" href="/static/brand/apple-touch-icon.png" sizes="180x180">
-    <link rel="manifest" href="/static/brand/manifest.json">
-    <meta property="og:type" content="website">
-    <meta property="og:title" content="TGDrive - Video Player">
-    <meta property="og:description" content="Stream files stored in Telegram with TGDrive.">
-    <meta property="og:image" content="https://raw.githubusercontent.com/TechShreyash/TGDrive/main/website/static/brand/social-preview.png">
-    <meta property="og:image:width" content="1200">
-    <meta property="og:image:height" content="630">
-    <meta property="og:image:alt" content="TGDrive — your files in Telegram, your drive in the browser.">
-    <meta name="twitter:card" content="summary_large_image">
-    <meta name="twitter:title" content="TGDrive - Video Player">
-    <meta name="twitter:description" content="Stream files stored in Telegram with TGDrive.">
-    <meta name="twitter:image" content="https://raw.githubusercontent.com/TechShreyash/TGDrive/main/website/static/brand/social-preview.png">
-    <meta name="twitter:image:alt" content="TGDrive — your files in Telegram, your drive in the browser.">
-
-    <link href="//vjs.zencdn.net/8.3.0/video-js.min.css" rel="stylesheet">
-    <script src="//vjs.zencdn.net/8.3.0/video.min.js"></script>
-    <style>
-        body {
-            display: flex;
-            flex-direction: column;
-            align-items: center;
-            justify-content: center;
-            height: 100vh;
-            margin: 0;
-            font-family: Arial, sans-serif;
-        }
-
-        .brand-link {
-            display: inline-flex;
-            align-items: center;
-            min-height: 44px;
-            max-width: calc(100% - 32px);
-            flex-shrink: 0;
-            margin-bottom: 20px;
-        }
-
-        .brand-link:focus-visible {
-            outline: 2px solid #3157ff;
-            outline-offset: 4px;
-        }
-
-        .brand-logo {
-            display: block;
-            width: 180px;
-            max-width: 100%;
-            height: auto;
-        }
-
-        .video-container {
-            width: 90%;
-            max-width: 800px;
-        }
-
-        .buttons-container {
-            margin-top: 20px;
-            display: flex;
-            justify-content: space-evenly;
-            width: 90%;
-            max-width: 800px;
-        }
-
-        .copy-button {
-            padding: 10px 20px;
-            font-size: 16px;
-            cursor: pointer;
-            background-color: #007bff;
-            color: white;
-            border: none;
-            border-radius: 5px;
-            transition: background-color 0.3s ease;
-        }
-
-        .copy-button:hover {
-            background-color: #0056b3;
-        }
-    </style>
-</head>
-
-<body>
-
-    <a class="brand-link" href="/" aria-label="TGDrive home">
-        <img class="brand-logo" src="/static/brand/tgdrive-logo.svg" alt="TGDrive" width="180" height="36">
-    </a>
-
-    <div class="video-container">
-        <video id="my-player" class="video-js vjs-fluid" controls preload="auto" data-setup='{}'>
-            <source id="video-src" src="" type="video/mp4">
-            </source>
-            <p class="vjs-no-js">
-                To view this video please enable JavaScript, and consider upgrading to a
-                web browser that
-                <a href="https://videojs.com/html5-video-support/" target="_blank">
-                    supports HTML5 video
-                </a>
-            </p>
-        </video>
-    </div>
-
-    <div class="buttons-container">
-        <button class="copy-button" onclick="copyStreamUrl()">Copy Stream URL</button>
-        <button class="copy-button" onclick="copyDownloadUrl()">Copy Download URL</button>
-    </div>
-
-    <script>
-        const downloadUrl = (new URL(window.location.href)).searchParams.get('url');
-        document.getElementById('video-src').src = downloadUrl;
-
-
-        function copyTextToClipboard(text) {
-            if (navigator.clipboard && navigator.clipboard.writeText) {
-                navigator.clipboard.writeText(text).then(function () {
-                    alert('Link copied to clipboard!');
-                }).catch(function (err) {
-                    console.error('Could not copy text: ', err);
-                    fallbackCopyTextToClipboard(text);
-                });
-            } else {
-                fallbackCopyTextToClipboard(text);
-            }
-        }
-
-        function fallbackCopyTextToClipboard(text) {
-            const textArea = document.createElement('textarea');
-            textArea.value = text;
-            document.body.appendChild(textArea);
-            textArea.focus();
-            textArea.select();
-
-            try {
-                const successful = document.execCommand('copy');
-                if (successful) {
-                    alert('Link copied to clipboard!');
-                } else {
-                    alert('Failed to copy the link.');
-                }
-            } catch (err) {
-                console.error('Fallback: Oops, unable to copy', err);
-            }
-
-            document.body.removeChild(textArea);
-        }
-
-        function copyStreamUrl() {
-            copyTextToClipboard(window.location.href);
-        }
-
-        function copyDownloadUrl() {
-            copyTextToClipboard(downloadUrl);
-        }
-    </script>
-
-</body>
-
-</html>
diff --git a/website/home.html b/website/home.html
deleted file mode 100644
index 14b0a436..00000000
--- a/website/home.html
+++ /dev/null
@@ -1,178 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-
-<head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>TGDrive</title>
-    <meta name="theme-color" content="#f8fafd" />
-    <meta name="description" content="Manage, upload and share files stored in Telegram with TGDrive." />
-    <link rel="icon" href="/static/brand/favicon.ico" sizes="16x16 32x32 48x48" />
-    <link rel="icon" type="image/svg+xml" href="/static/brand/favicon.svg" sizes="any" />
-    <link rel="apple-touch-icon" href="/static/brand/apple-touch-icon.png" sizes="180x180" />
-    <link rel="manifest" href="/static/brand/manifest.json" />
-    <meta property="og:type" content="website" />
-    <meta property="og:title" content="TGDrive" />
-    <meta property="og:description" content="Manage, upload and share files stored in Telegram with TGDrive." />
-    <meta property="og:image" content="https://raw.githubusercontent.com/TechShreyash/TGDrive/main/website/static/brand/social-preview.png" />
-    <meta property="og:image:width" content="1200" />
-    <meta property="og:image:height" content="630" />
-    <meta property="og:image:alt" content="TGDrive — your files in Telegram, your drive in the browser." />
-    <meta name="twitter:card" content="summary_large_image" />
-    <meta name="twitter:title" content="TGDrive" />
-    <meta name="twitter:description" content="Manage, upload and share files stored in Telegram with TGDrive." />
-    <meta name="twitter:image" content="https://raw.githubusercontent.com/TechShreyash/TGDrive/main/website/static/brand/social-preview.png" />
-    <meta name="twitter:image:alt" content="TGDrive — your files in Telegram, your drive in the browser." />
-    <link rel="stylesheet" href="static/home.css" />
-
-    <!-- Fonts Start -->
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-    <link
-        href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100;0,300;0,400;0,500;0,700;0,900;1,100;1,300;1,400;1,500;1,700;1,900&display=swap"
-        rel="stylesheet" />
-    <!-- Fonts End -->
-</head>
-
-<body>
-    <div class="container">
-        <!-- Sidebar Start -->
-        <div class="sidebar">
-            <div class="sidebar-header">
-                <a class="brand-link" href="/" aria-label="TGDrive home">
-                    <img class="brand-logo" src="/static/brand/tgdrive-logo.svg" alt="TGDrive" width="180" height="36" />
-                </a>
-            </div>
-
-            <button id="new-button" class="new-button">
-                <img src="static/assets/plus-icon.svg" />New
-            </button>
-
-            <div id="new-upload" class="new-upload">
-                <input id="new-upload-focus" type="text"
-                    style="height: 0px; width: 0px; border: none; position: absolute" readonly />
-                <div id="new-folder-btn">
-                    <img src="static/assets/folder-icon.svg" />
-                    New Folder
-                </div>
-                <hr />
-                <div id="file-upload-btn">
-                    <img src="static/assets/upload-icon.svg" />
-                    File Upload
-                </div>
-                <input type="file" id="fileInput" style="height: 0px; width: 0px; border: none; position: absolute" />
-                <hr />
-                <div id="url-upload-btn">
-                    <img src="static/assets/link-icon.svg" />
-                    URL Upload
-                </div>
-            </div>
-
-            <div class="sidebar-menu">
-                <a class="selected-item" href="/?path=/"><img src="static/assets/home-icon.svg" />Home</a>
-                <a class="unselected-item" href="/?path=/trash"><img src="static/assets/trash-icon.svg" />Trash</a>
-            </div>
-        </div>
-        <!-- Sidebar End -->
-
-        <div id="bg-blur" class="bg-blur"></div>
-
-        <!-- Create New Folder Start -->
-        <div id="create-new-folder" class="create-new-folder">
-            <span>New Folder</span>
-            <input type="text" id="new-folder-name" placeholder="Enter Folder Name" autocomplete="off" />
-            <div>
-                <button id="new-folder-cancel">Cancel</button>
-                <button id="new-folder-create">Create</button>
-            </div>
-        </div>
-        <!-- Create New Folder End -->
-
-        <!-- File / Folder Rename Start -->
-        <div id="rename-file-folder" class="create-new-folder">
-            <span>Edit File/Folder Name</span>
-            <input type="text" id="rename-name" placeholder="Enter File/Folder Name" autocomplete="off" />
-            <div>
-                <button id="rename-cancel">Cancel</button>
-                <button id="rename-create">Rename</button>
-            </div>
-        </div>
-        <!-- File / Folder Rename End -->
-
-        <!-- Remote Upload Start -->
-        <div id="new-url-upload" class="create-new-folder">
-            <span>Url Upload</span>
-            <input type="text" id="remote-url" placeholder="Enter Direct Download Link Of File" autocomplete="off" />
-            <div id="single-threaded-div">
-                <input type="checkbox" name="single-threaded-toggle" id="single-threaded-toggle">
-                <label for="single-threaded-toggle">Single Threaded</label>
-                <a href="#"><img src="static/assets/info-icon-small.svg" alt="Info"></a>
-            </div>
-            <div>
-                <button id="remote-cancel">Cancel</button>
-                <button id="remote-start">Upload</button>
-            </div>
-        </div>
-        <!-- Remote Upload End -->
-
-        <!-- Get Password Start -->
-        <div id="get-password" class="create-new-folder">
-            <img class="login-brand" src="/static/brand/tgdrive-logo.svg" alt="TGDrive" width="180" height="36" />
-            <span>Admin Login</span>
-            <input type="text" id="auth-pass" placeholder="Enter Password" autocomplete="off" />
-            <div>
-                <button id="pass-login">Login</button>
-            </div>
-        </div>
-        <!-- Get Password End -->
-
-        <!-- File Uploader Start -->
-        <div id="file-uploader" class="file-uploader">
-            <span class="upload-head">🚀 Uploading File...</span>
-            <span id="upload-filename" class="upload-info">Filename : </span>
-            <span id="upload-filesize" class="upload-info">Filesize :</span>
-            <span id="upload-status" class="upload-info">Status : </span>
-            <span id="upload-percent" class="upload-info">Progress : </span>
-            <div class="progress">
-                <div class="progress-bar" id="progress-bar"></div>
-            </div>
-            <div class="btn-div">
-                <button id="cancel-file-upload">Cancel Upload</button>
-            </div>
-        </div>
-        <!-- File Uploader End -->
-
-        <!-- Main Content Start -->
-        <div class="main-content">
-            <div class="header">
-                <div class="search-bar">
-                    <img src="static/assets/search-icon.svg" />
-                    <form id="search-form">
-                        <input id="file-search" type="text" placeholder="Search in Drive" autocomplete="off" />
-                    </form>
-
-                </div>
-            </div>
-
-            <div class="directory">
-                <table>
-                    <thead>
-                        <tr>
-                            <th>Name</th>
-                            <th>File Size</th>
-                            <th>More</th>
-                        </tr>
-                    </thead>
-                    <tbody id="directory-data"></tbody>
-                </table>
-            </div>
-        </div>
-    </div>
-    <script src="static/js/extra.js"></script>
-    <script src="static/js/apiHandler.js"></script>
-    <script src="static/js/sidebar.js"></script>
-    <script src="static/js/fileClickHandler.js"></script>
-    <script src="static/js/main.js"></script>
-</body>
-
-</html>
diff --git a/website/index.html b/website/index.html
new file mode 100644
index 00000000..72048ce1
--- /dev/null
+++ b/website/index.html
@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <meta name="color-scheme" content="light dark" />
+        <meta name="theme-color" content="#f5f7f9" />
+        <meta
+            name="description"
+            content="Your private Telegram-backed file drive."
+        />
+        <title>TGDrive</title>
+        <link
+            rel="icon"
+            type="image/svg+xml"
+            href="/static/brand/favicon.svg"
+        />
+        <link
+            rel="icon"
+            type="image/png"
+            sizes="32x32"
+            href="/static/brand/favicon-32.png"
+        />
+        <link
+            rel="icon"
+            type="image/png"
+            sizes="16x16"
+            href="/static/brand/favicon-16.png"
+        />
+        <link rel="shortcut icon" href="/static/brand/favicon.ico" />
+        <link
+            rel="apple-touch-icon"
+            sizes="180x180"
+            href="/static/brand/apple-touch-icon.png"
+        />
+        <meta property="og:type" content="website" />
+        <meta property="og:title" content="TGDrive" />
+        <meta
+            property="og:description"
+            content="Your private Telegram-backed file drive."
+        />
+        <meta property="og:image" content="/static/brand/social-preview.png" />
+        <meta property="og:image:width" content="1200" />
+        <meta property="og:image:height" content="630" />
+        <meta
+            property="og:image:alt"
+            content="TGDrive — your private Telegram-backed file drive"
+        />
+        <meta name="twitter:card" content="summary_large_image" />
+        <meta name="twitter:image" content="/static/brand/social-preview.png" />
+        <meta
+            name="twitter:image:alt"
+            content="TGDrive — your private Telegram-backed file drive"
+        />
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>
diff --git a/website/package-lock.json b/website/package-lock.json
new file mode 100644
index 00000000..25050e1d
--- /dev/null
+++ b/website/package-lock.json
@@ -0,0 +1,2457 @@
+{
+    "name": "tgdrive-web",
+    "version": "2.0.0",
+    "lockfileVersion": 3,
+    "requires": true,
+    "packages": {
+        "": {
+            "name": "tgdrive-web",
+            "version": "2.0.0",
+            "dependencies": {
+                "@mantine/core": "9.7.3",
+                "@mantine/hooks": "9.7.3",
+                "lucide-react": "1.58.0",
+                "movi-player": "file:vendor/movi-player-0.4.1-tgdrive.1.tgz",
+                "pdfjs-dist": "file:vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz",
+                "react": "19.3.1",
+                "react-dom": "19.3.1"
+            },
+            "devDependencies": {
+                "@types/node": "24.19.2",
+                "@types/react": "19.3.0",
+                "@types/react-dom": "19.3.0",
+                "@vitejs/plugin-react": "6.1.2",
+                "prettier": "3.9.10",
+                "typescript": "7.0.2",
+                "vite": "8.3.4",
+                "vitest": "5.0.5"
+            },
+            "engines": {
+                "node": ">=24.22.0 <25"
+            }
+        },
+        "node_modules/@floating-ui/core": {
+            "version": "1.8.0",
+            "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.8.0.tgz",
+            "integrity": "sha512-0CIZ5itps/8x7BG8dEIhs53BvCUH2PCoogtakwRTut+Arm58sJooJ0AuZhLw2HJYIR5cMLNPBSS728sPho2khQ==",
+            "license": "MIT",
+            "dependencies": {
+                "@floating-ui/utils": "^0.2.12"
+            }
+        },
+        "node_modules/@floating-ui/dom": {
+            "version": "1.8.0",
+            "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.8.0.tgz",
+            "integrity": "sha512-yXSrzeHZBTZadLOlfyhCkJHNeLJnHRnRInwdZ40L7ZiaAtrBwoYlsDrX3v5zB1Utk7CLfzcOVnVVWoXEky7Ceg==",
+            "license": "MIT",
+            "dependencies": {
+                "@floating-ui/core": "^1.8.0",
+                "@floating-ui/utils": "^0.2.12"
+            }
+        },
+        "node_modules/@floating-ui/react": {
+            "version": "0.27.20",
+            "resolved": "https://registry.npmjs.org/@floating-ui/react/-/react-0.27.20.tgz",
+            "integrity": "sha512-CMqMy7OaXl9W0eq1Uy7L7i2Y/anPvHmFmESd2CEw0t5YvZhcVCeo4MBevAmswRllX7Y2dEidA4ozGPunLSTQpw==",
+            "license": "MIT",
+            "dependencies": {
+                "@floating-ui/react-dom": "^2.1.9",
+                "@floating-ui/utils": "^0.2.12",
+                "tabbable": "^6.0.0"
+            },
+            "peerDependencies": {
+                "react": ">=17.0.0",
+                "react-dom": ">=17.0.0"
+            }
+        },
+        "node_modules/@floating-ui/react-dom": {
+            "version": "2.1.9",
+            "resolved": "https://registry.npmjs.org/@floating-ui/react-dom/-/react-dom-2.1.9.tgz",
+            "integrity": "sha512-JDjEFGCpImxDCA7JJKviA0M9+RtmJdj0m/NVU5IMgBK+AmZouAQQ7/+2GLH0GXXY0YMw9oXPB8hKdbPYg5QLYg==",
+            "license": "MIT",
+            "dependencies": {
+                "@floating-ui/dom": "^1.8.0"
+            },
+            "peerDependencies": {
+                "react": ">=16.8.0",
+                "react-dom": ">=16.8.0"
+            }
+        },
+        "node_modules/@floating-ui/utils": {
+            "version": "0.2.12",
+            "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.12.tgz",
+            "integrity": "sha512-HpCo8tmWzLVad5s2d19EhAz5zqrrQ6s69qd6moPMQvkOuSwDT1YgRfWSVuc4ennqrgv3OHppiOGMQ7oC13yIww==",
+            "license": "MIT"
+        },
+        "node_modules/@jridgewell/resolve-uri": {
+            "version": "3.1.2",
+            "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+            "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=6.0.0"
+            }
+        },
+        "node_modules/@jridgewell/sourcemap-codec": {
+            "version": "1.6.0",
+            "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz",
+            "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/@jridgewell/trace-mapping": {
+            "version": "0.3.31",
+            "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+            "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jridgewell/resolve-uri": "^3.1.0",
+                "@jridgewell/sourcemap-codec": "^1.4.14"
+            }
+        },
+        "node_modules/@mantine/core": {
+            "version": "9.7.3",
+            "resolved": "https://registry.npmjs.org/@mantine/core/-/core-9.7.3.tgz",
+            "integrity": "sha512-wYJ9Bd82a7HqwJ+hubFqUIocBGMuw6txzdPnnleHvv1h0NlnkESevK/WHTRh4FtOw33B5N2ADT34s3x1/8d8jg==",
+            "license": "MIT",
+            "dependencies": {
+                "@floating-ui/react": "^0.27.20",
+                "clsx": "^2.1.1",
+                "react-number-format": "^5.4.5",
+                "react-remove-scroll": "^2.7.2",
+                "type-fest": "^5.10.0"
+            },
+            "peerDependencies": {
+                "@mantine/hooks": "9.7.3",
+                "react": "^19.2.0",
+                "react-dom": "^19.2.0"
+            }
+        },
+        "node_modules/@mantine/hooks": {
+            "version": "9.7.3",
+            "resolved": "https://registry.npmjs.org/@mantine/hooks/-/hooks-9.7.3.tgz",
+            "integrity": "sha512-GMHoMS1qul1dBLIHd/N9ef2Pr8UKYYHfuM+g2ej3gYqU0kH4sTiR9FNHksoTQi0PzATRoaNlUYjjMe9rbDRw5A==",
+            "license": "MIT",
+            "peerDependencies": {
+                "react": "^19.2.0"
+            }
+        },
+        "node_modules/@napi-rs/canvas": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas/-/canvas-1.0.11.tgz",
+            "integrity": "sha512-vt5tog1cr+QKadIddGe+3LrcX0EmjEd0izF717Uwf92mBmgYfq2XRmL2r4bZU40spB69exxhrBn9I91HYEr/7w==",
+            "license": "MIT",
+            "optional": true,
+            "workspaces": [
+                "e2e/*"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            },
+            "optionalDependencies": {
+                "@napi-rs/canvas-android-arm64": "1.0.11",
+                "@napi-rs/canvas-darwin-arm64": "1.0.11",
+                "@napi-rs/canvas-darwin-x64": "1.0.11",
+                "@napi-rs/canvas-linux-arm-gnueabihf": "1.0.11",
+                "@napi-rs/canvas-linux-arm64-gnu": "1.0.11",
+                "@napi-rs/canvas-linux-arm64-musl": "1.0.11",
+                "@napi-rs/canvas-linux-riscv64-gnu": "1.0.11",
+                "@napi-rs/canvas-linux-x64-gnu": "1.0.11",
+                "@napi-rs/canvas-linux-x64-musl": "1.0.11",
+                "@napi-rs/canvas-win32-arm64-msvc": "1.0.11",
+                "@napi-rs/canvas-win32-x64-msvc": "1.0.11"
+            }
+        },
+        "node_modules/@napi-rs/canvas-android-arm64": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-android-arm64/-/canvas-android-arm64-1.0.11.tgz",
+            "integrity": "sha512-dtJS4FQEfH9OwSYLtMrEnj7T8DzBbJc/97LI/OkiWOYpW/iW5t6R/gcxVrUXS8l45gCVpwMufgucRe/pe0ISqA==",
+            "cpu": [
+                "arm64"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-darwin-arm64": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-darwin-arm64/-/canvas-darwin-arm64-1.0.11.tgz",
+            "integrity": "sha512-J/JylWoJTG8OQqZaiqly4IODyAxNofUlZo0wtSBJtHk6AdymbdIkPynAM1JvQaZpPaG5h+msk9QuK8y4i1ooqw==",
+            "cpu": [
+                "arm64"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-darwin-x64": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-darwin-x64/-/canvas-darwin-x64-1.0.11.tgz",
+            "integrity": "sha512-nlecCk3xy06eAGC7krZtzNDm9UNTHKuHQYK8ZYegdjzgSL8anGt/eLJZm86OWaNgZkwQwvDqfSmG8Nqe6MPZNQ==",
+            "cpu": [
+                "x64"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-linux-arm-gnueabihf": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-arm-gnueabihf/-/canvas-linux-arm-gnueabihf-1.0.11.tgz",
+            "integrity": "sha512-DKImmG+sTPolE0kGPsYPBxTtOjb3INALp32O2lW2CfSr0bAzSEKKuu+GrQbtilClyoPOahUErS3OrznFDraoWA==",
+            "cpu": [
+                "arm"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-linux-arm64-gnu": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-arm64-gnu/-/canvas-linux-arm64-gnu-1.0.11.tgz",
+            "integrity": "sha512-55sykACGENj5j1rhj+81AO8JbR9HYgGjRZ7/H+pNr4VE1DvINKYNMTcutk8ZmWxk276jAQvUKJ3+Kdj9GXU3lQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "libc": [
+                "glibc"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-linux-arm64-musl": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-arm64-musl/-/canvas-linux-arm64-musl-1.0.11.tgz",
+            "integrity": "sha512-6Jz6jys17yXydO+WdJgu7JhoB4K7/w9sWHByzzTmLjQghUx3TDMWvLv+UcCdnWhg4oprET67EMymnrETdeGNAg==",
+            "cpu": [
+                "arm64"
+            ],
+            "libc": [
+                "musl"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-linux-riscv64-gnu": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-riscv64-gnu/-/canvas-linux-riscv64-gnu-1.0.11.tgz",
+            "integrity": "sha512-lf2XeEebWiUYVOVEjLXxF7dfXrBBSEOBn9AqBh39VYXrPt5cDqI+1t58IFSjn8npqkg5jIOs8TQbjKABbFW1gQ==",
+            "cpu": [
+                "riscv64"
+            ],
+            "libc": [
+                "glibc"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-linux-x64-gnu": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-x64-gnu/-/canvas-linux-x64-gnu-1.0.11.tgz",
+            "integrity": "sha512-iDapw7nFSE5tsmQxcH2+KotJhyfVPmHd6vUOQN/Em+8WNbkZJwJ/rDowlJMFnMl0SYSDSfgKCNUGi6Sn5++Smg==",
+            "cpu": [
+                "x64"
+            ],
+            "libc": [
+                "glibc"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-linux-x64-musl": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-linux-x64-musl/-/canvas-linux-x64-musl-1.0.11.tgz",
+            "integrity": "sha512-26q26AyITo3CGZX4HWFIMgBMA1lu3YN07gxzBm4tW6Hglq/OVyTP50kDrmWuKybCX6dh3m8Ly+c7YhI+sqCgCQ==",
+            "cpu": [
+                "x64"
+            ],
+            "libc": [
+                "musl"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-win32-arm64-msvc": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-win32-arm64-msvc/-/canvas-win32-arm64-msvc-1.0.11.tgz",
+            "integrity": "sha512-cUO96IdsfvIj2S+2PNcDSkTcLhjPj8pIOEWRV1Kj70MOP4wnE9zSk7N4C1EKHlFGRcgdR5AkbnBZj0dfHK9nbQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@napi-rs/canvas-win32-x64-msvc": {
+            "version": "1.0.11",
+            "resolved": "https://registry.npmjs.org/@napi-rs/canvas-win32-x64-msvc/-/canvas-win32-x64-msvc-1.0.11.tgz",
+            "integrity": "sha512-DFYp/ZQRdKunI/LPc0UkRXG1vlNjJKOJf8O8Ctb8+wm2Nt2ELg9Eamc31D2VoakkfGo8L+z0Iejz6WtFbQwyGw==",
+            "cpu": [
+                "x64"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 10"
+            },
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/Brooooooklyn"
+            }
+        },
+        "node_modules/@oxc-project/types": {
+            "version": "0.154.0",
+            "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.154.0.tgz",
+            "integrity": "sha512-KYOUGQFlLWR+s4QMV2Q9ko38TZm7EdO87Qm7rvZLqk/webse/cDjtyxKhg/47l0byCbs/k46LT8qc4PKjAikzA==",
+            "dev": true,
+            "license": "MIT",
+            "funding": {
+                "url": "https://github.com/sponsors/oxc-project"
+            }
+        },
+        "node_modules/@rolldown/binding-android-arm-eabi": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.14.tgz",
+            "integrity": "sha512-aWR+XKH9+rW7m5fWq/5360J3mHycrx/o6xZM2DQFdJnTMdyP7/WzxPjhtLbVWdKo2y612/4U1bWqb3HQhiF7vg==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-android-arm64": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.2.14.tgz",
+            "integrity": "sha512-QiVxHofl6A8lQU7WAtOUY4QMVZXohxwz7WJJoeh8NBEUyKfIkMRKhYyq8az/1RypNiIXzNTtiS6KwHz0erxYRQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-darwin-arm64": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.2.14.tgz",
+            "integrity": "sha512-lTQOzHuBIooh3jIr5XINQkjPGEuGy+Dsy0meXDr6Sjty0b99kYgGh4uBC/8mJX1T0kC8d6S0aPP1Y+bHkh6aBw==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-darwin-x64": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.2.14.tgz",
+            "integrity": "sha512-hyMKEGatjmBYCs/Q4sbIcL/GqpFEqsX3wc+HYVQ/85A4rxc1o7rPm4DUI4GV4k/h0ITddwFSGpqQunI14GXjTA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-freebsd-x64": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.2.14.tgz",
+            "integrity": "sha512-u371GbXoVXrEgP20PwzoGNOdAOqAMhzo19JzzY+V4YmmnC+DTOoqdbMu+O+54emM59Mik/UdrtWgcuEDKWRPKA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.2.14.tgz",
+            "integrity": "sha512-BqwKsdZQf6EqVWr8fv2MrDYzAvOZ7+NYFSJESRGs87fkseEhs0TU9TXgRJTkZoRRkxTizyEg1LKUXfU3/78uqg==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-linux-arm64-gnu": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.14.tgz",
+            "integrity": "sha512-SD9kY8M009x/7s57Z1dgUVlP5+uYBgKQK0Tkr1WIWngrtUJmRCW1RJFMY7QDla2khXhmg2i5Io7MUjcmZNZ/KQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-linux-arm64-musl": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.14.tgz",
+            "integrity": "sha512-BJ2CL19M6uuWesMgnqJzgxoI+N+eV7b0A9O9vLV42y+gitC41fNa8KElau1tHVzuLWX5GzEuxMPhAO0tQXQMkg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-linux-ppc64-gnu": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.2.14.tgz",
+            "integrity": "sha512-4+Kl8daPV8NDHaD7mfCcc1pRM+Qg7ab8DyMm5FG5WoZgv4h2i3KFN1CybYBNbQqmuYm7ftJLvmMI1eHYJ22S/Q==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-linux-s390x-gnu": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.2.14.tgz",
+            "integrity": "sha512-V/h8ePq1fKDrmtFMz6xcCN3DKvuvMRrwwD1q0PkBeeo4DpK64biaKvqWGVxqCeYKqeRk7gE7/iKPxLCn08O97A==",
+            "cpu": [
+                "s390x"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-linux-x64-gnu": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.14.tgz",
+            "integrity": "sha512-WxalXzgrLVpKC93xfpaJ3gCXUWzeCr+FRCbDVD2mUAy4L6Vo3lNVz0epUEUpxPWJkLNYUwM4OSIikv36OJ9mLg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-linux-x64-musl": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.14.tgz",
+            "integrity": "sha512-3G3tnAmTpdk9jO3GQtyHXqeFD2SlecfTws/Y3M2mmj9nMBwwuLT4kur8sZKeu7ENUHSpVO3cIsm5A52LEWWwlg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-openharmony-arm64": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.2.14.tgz",
+            "integrity": "sha512-qyr5XiNGxm2ytx17vvtcJ9nXn6v1gENETi503bJx3OGwZ1tSonj7BosxbMa/xeAfSl5iS9X6KjEWYXLu6v1L7Q==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "openharmony"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-win32-arm64-msvc": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.14.tgz",
+            "integrity": "sha512-oA4o5o0S2yB199YyYXDzKUv1Z56Rc+mgOjwm7Z/vJ9Z8igiDPYvoOuDyo6g7AK/ZaF09nPhDKVnGBcYHO11GXA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/binding-win32-x64-msvc": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.14.tgz",
+            "integrity": "sha512-9mE94bf2GZUaR/fUSXCMpBoWkctu421Mi0ORpm4zqfbkjKep7RxzPFa5etcGs5h+2KApoWBOA/hAJa/7saGgEQ==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            }
+        },
+        "node_modules/@rolldown/pluginutils": {
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz",
+            "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/@svta/cml-608": {
+            "version": "1.0.2",
+            "resolved": "https://registry.npmjs.org/@svta/cml-608/-/cml-608-1.0.2.tgz",
+            "integrity": "sha512-ZEJ68330gcLKfvVv6Qifr1HR7+GldDUxzkjqSbqRK7jHtHSLSV1JAyDwlYe8+C7ABuY1bp8MpgJ4/Gg+jl+pLQ==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=20"
+            }
+        },
+        "node_modules/@svta/cml-cmcd": {
+            "version": "2.3.2",
+            "resolved": "https://registry.npmjs.org/@svta/cml-cmcd/-/cml-cmcd-2.3.2.tgz",
+            "integrity": "sha512-SKBBjLmci0WK8HMjuv+36tVIMktonoOoxsXblOFZmB+ePPV2zjRMTD+2ZmE/1VEPJkKHENyhSjSHgJyeOlvZ1A==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-structured-field-values": "1.1.3",
+                "@svta/cml-utils": "1.5.0"
+            }
+        },
+        "node_modules/@svta/cml-cmsd": {
+            "version": "1.0.6",
+            "resolved": "https://registry.npmjs.org/@svta/cml-cmsd/-/cml-cmsd-1.0.6.tgz",
+            "integrity": "sha512-LUORV6bb0TbU4rSC2HoPqUCix1igLrXkRQXWiIyJo2OMzb14kAK/1jsW0mzY6up6w1GrjKQcjc6OwqJdo/zd/g==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-cta": "1.0.6",
+                "@svta/cml-structured-field-values": "1.1.3",
+                "@svta/cml-utils": "1.5.0"
+            }
+        },
+        "node_modules/@svta/cml-cta": {
+            "version": "1.0.6",
+            "resolved": "https://registry.npmjs.org/@svta/cml-cta/-/cml-cta-1.0.6.tgz",
+            "integrity": "sha512-l13/4myTX1EbRd38nY8J1umVY5UdR/nZO6CeKqVLXnMMIayg7/fu0TueZckjTA9Loal55MGK1xbHnXVjz7OUUw==",
+            "license": "Apache-2.0",
+            "peer": true,
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-structured-field-values": "1.1.3",
+                "@svta/cml-utils": "1.5.0"
+            }
+        },
+        "node_modules/@svta/cml-dash": {
+            "version": "1.0.6",
+            "resolved": "https://registry.npmjs.org/@svta/cml-dash/-/cml-dash-1.0.6.tgz",
+            "integrity": "sha512-4XtHYlPrzL/dRe/8XmRQoLnTo9S86tISgrl67eUqKl5MtNTpZBYTncuPrspslPZPZROBBWNrBuepYfYUtU9CKA==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-utils": "1.5.0"
+            }
+        },
+        "node_modules/@svta/cml-id3": {
+            "version": "1.0.6",
+            "resolved": "https://registry.npmjs.org/@svta/cml-id3/-/cml-id3-1.0.6.tgz",
+            "integrity": "sha512-63j8gkAnPOmOBWlp0hIZPvsIioZttdbg6/TgwITqMYbSLYVJ+6QGa/UtIP0I84NsfstANw6QdCn7i8SS08kn1A==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-utils": "1.5.0"
+            }
+        },
+        "node_modules/@svta/cml-request": {
+            "version": "1.0.12",
+            "resolved": "https://registry.npmjs.org/@svta/cml-request/-/cml-request-1.0.12.tgz",
+            "integrity": "sha512-4sJvnnoNpq58j2mCGP8k+MF6wVy/qa4gbt6kfT1dPIKmn3mPxw+JVfilhcWsUi+peK2yCZxOJJYyHj1cAcQE1w==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-cmcd": "2.3.2",
+                "@svta/cml-utils": "1.5.0",
+                "@svta/cml-xml": "1.1.4"
+            }
+        },
+        "node_modules/@svta/cml-structured-field-values": {
+            "version": "1.1.3",
+            "resolved": "https://registry.npmjs.org/@svta/cml-structured-field-values/-/cml-structured-field-values-1.1.3.tgz",
+            "integrity": "sha512-XqLzQOTznz6kh/nsSh8dy1kV7GQjL4csG+2U5EvLGhAqNuNUczbVg5EAsDobKDVg8xhdthdXx2UuwM+ZHQCxSg==",
+            "license": "Apache-2.0",
+            "peer": true,
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-utils": "1.5.0"
+            }
+        },
+        "node_modules/@svta/cml-utils": {
+            "version": "1.5.0",
+            "resolved": "https://registry.npmjs.org/@svta/cml-utils/-/cml-utils-1.5.0.tgz",
+            "integrity": "sha512-JMqclD7Akd+GSJiuaYNUHOP2wNtf/nauKeszlYeivSHfi0Lp3pmSW5PXDvJ2dO4aPmmSOQbF0ztTsW9Vcs2Whw==",
+            "license": "Apache-2.0",
+            "peer": true,
+            "engines": {
+                "node": ">=20"
+            }
+        },
+        "node_modules/@svta/cml-xml": {
+            "version": "1.1.4",
+            "resolved": "https://registry.npmjs.org/@svta/cml-xml/-/cml-xml-1.1.4.tgz",
+            "integrity": "sha512-jbixqjiJIc16SGxylHwiOzO+DuhkGfuP+fJ9AHeVJKdFDKnabgfCDpnp6dvZpZnjMj4nHvzVtuUV7RISPIwYXw==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=20"
+            },
+            "peerDependencies": {
+                "@svta/cml-utils": "1.5.0"
+            }
+        },
+        "node_modules/@types/chai": {
+            "version": "5.2.3",
+            "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+            "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@types/deep-eql": "*",
+                "assertion-error": "^2.0.1"
+            }
+        },
+        "node_modules/@types/deep-eql": {
+            "version": "4.0.2",
+            "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+            "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/@types/estree": {
+            "version": "1.0.9",
+            "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+            "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/@types/node": {
+            "version": "24.19.2",
+            "resolved": "https://registry.npmjs.org/@types/node/-/node-24.19.2.tgz",
+            "integrity": "sha512-93d49wCWJkCyN87MxLpNN6KXPCwFw7bVUg79mGUV1OS40JGWwVCr8n61DXCSqz7CV6/VfPkb7xec7uP2M+QHWQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "undici-types": ">=7.24.0 <7.24.7"
+            }
+        },
+        "node_modules/@types/react": {
+            "version": "19.3.0",
+            "resolved": "https://registry.npmjs.org/@types/react/-/react-19.3.0.tgz",
+            "integrity": "sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==",
+            "devOptional": true,
+            "license": "MIT",
+            "dependencies": {
+                "csstype": "^3.2.2"
+            }
+        },
+        "node_modules/@types/react-dom": {
+            "version": "19.3.0",
+            "resolved": "https://registry.npmjs.org/@types/react-dom/-/react-dom-19.3.0.tgz",
+            "integrity": "sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q==",
+            "dev": true,
+            "license": "MIT",
+            "peerDependencies": {
+                "@types/react": "^19.3.0"
+            }
+        },
+        "node_modules/@typescript/typescript-aix-ppc64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-aix-ppc64/-/typescript-aix-ppc64-7.0.2.tgz",
+            "integrity": "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "aix"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-darwin-arm64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-arm64/-/typescript-darwin-arm64-7.0.2.tgz",
+            "integrity": "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-darwin-x64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-x64/-/typescript-darwin-x64-7.0.2.tgz",
+            "integrity": "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-freebsd-arm64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-arm64/-/typescript-freebsd-arm64-7.0.2.tgz",
+            "integrity": "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-freebsd-x64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-x64/-/typescript-freebsd-x64-7.0.2.tgz",
+            "integrity": "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-arm": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm/-/typescript-linux-arm-7.0.2.tgz",
+            "integrity": "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-arm64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm64/-/typescript-linux-arm64-7.0.2.tgz",
+            "integrity": "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-loong64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-loong64/-/typescript-linux-loong64-7.0.2.tgz",
+            "integrity": "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==",
+            "cpu": [
+                "loong64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-mips64el": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-mips64el/-/typescript-linux-mips64el-7.0.2.tgz",
+            "integrity": "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==",
+            "cpu": [
+                "mips64el"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-ppc64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-ppc64/-/typescript-linux-ppc64-7.0.2.tgz",
+            "integrity": "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==",
+            "cpu": [
+                "ppc64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-riscv64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-riscv64/-/typescript-linux-riscv64-7.0.2.tgz",
+            "integrity": "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==",
+            "cpu": [
+                "riscv64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-s390x": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-s390x/-/typescript-linux-s390x-7.0.2.tgz",
+            "integrity": "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==",
+            "cpu": [
+                "s390x"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-linux-x64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-x64/-/typescript-linux-x64-7.0.2.tgz",
+            "integrity": "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-netbsd-arm64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-arm64/-/typescript-netbsd-arm64-7.0.2.tgz",
+            "integrity": "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "netbsd"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-netbsd-x64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-x64/-/typescript-netbsd-x64-7.0.2.tgz",
+            "integrity": "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "netbsd"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-openbsd-arm64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-arm64/-/typescript-openbsd-arm64-7.0.2.tgz",
+            "integrity": "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "openbsd"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-openbsd-x64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-x64/-/typescript-openbsd-x64-7.0.2.tgz",
+            "integrity": "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "openbsd"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-sunos-x64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-sunos-x64/-/typescript-sunos-x64-7.0.2.tgz",
+            "integrity": "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "sunos"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-win32-arm64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-arm64/-/typescript-win32-arm64-7.0.2.tgz",
+            "integrity": "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@typescript/typescript-win32-x64": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-x64/-/typescript-win32-x64-7.0.2.tgz",
+            "integrity": "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "Apache-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">=16.20.0"
+            }
+        },
+        "node_modules/@vitejs/plugin-react": {
+            "version": "6.1.2",
+            "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-6.1.2.tgz",
+            "integrity": "sha512-fhJNGUdscQa4HkI0xFxwonWyhnVReCPDbXI7FH7jmzpnVCrFQI7PRrhWecO263610vOrs9tr2Y4xcf8uAdFxbw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@rolldown/pluginutils": "^1.0.1"
+            },
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            },
+            "peerDependencies": {
+                "@rolldown/plugin-babel": "^0.1.7 || ^0.2.0",
+                "babel-plugin-react-compiler": "^1.0.0",
+                "oxc-transform-react": "^0.152.0",
+                "vite": "^8.0.0"
+            },
+            "peerDependenciesMeta": {
+                "@rolldown/plugin-babel": {
+                    "optional": true
+                },
+                "babel-plugin-react-compiler": {
+                    "optional": true
+                },
+                "oxc-transform-react": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/@vitest/mocker": {
+            "version": "5.0.5",
+            "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-5.0.5.tgz",
+            "integrity": "sha512-xLL3lkDegJZw+MGoGaCCsFayDZthGgpAtr3Vziyfc4p7xH89K7KRPcRBBh/kEYm0Aqkt5DtTmkYpBtRV/FrHZg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jridgewell/trace-mapping": "0.3.31",
+                "@vitest/spy": "5.0.5",
+                "estree-walker": "^3.0.3",
+                "magic-string": "^1.4.3"
+            },
+            "funding": {
+                "url": "https://opencollective.com/vitest"
+            },
+            "peerDependencies": {
+                "msw": "^2.4.9 || ^3.0.0",
+                "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+            },
+            "peerDependenciesMeta": {
+                "msw": {
+                    "optional": true
+                },
+                "vite": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/@vitest/spy": {
+            "version": "5.0.5",
+            "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-5.0.5.tgz",
+            "integrity": "sha512-lwJRExuH417257Q5wv9QYugN9IMJkoxcrKrYxGPQkBzl7wlNpTUxD/5yNX4ESKVUIShKPgkGchYPFMWOOk0wzw==",
+            "dev": true,
+            "license": "MIT",
+            "funding": {
+                "url": "https://opencollective.com/vitest"
+            }
+        },
+        "node_modules/assertion-error": {
+            "version": "2.0.1",
+            "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+            "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=12"
+            }
+        },
+        "node_modules/bcp-47-match": {
+            "version": "2.0.3",
+            "resolved": "https://registry.npmjs.org/bcp-47-match/-/bcp-47-match-2.0.3.tgz",
+            "integrity": "sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ==",
+            "license": "MIT",
+            "funding": {
+                "type": "github",
+                "url": "https://github.com/sponsors/wooorm"
+            }
+        },
+        "node_modules/chai": {
+            "version": "6.3.0",
+            "resolved": "https://registry.npmjs.org/chai/-/chai-6.3.0.tgz",
+            "integrity": "sha512-XWAtwJ6OHO+tj0EKCs0Y2UamnyOxseZWltU4x2U2wh8g4AigdjwvtUjvLP2tqkA/avxHEtzxNaqGq/YGNwckKg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/clsx": {
+            "version": "2.1.1",
+            "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+            "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=6"
+            }
+        },
+        "node_modules/codem-isoboxer": {
+            "version": "0.3.10",
+            "resolved": "https://registry.npmjs.org/codem-isoboxer/-/codem-isoboxer-0.3.10.tgz",
+            "integrity": "sha512-eNk3TRV+xQMJ1PEj0FQGY8KD4m0GPxT487XJ+Iftm7mVa9WpPFDMWqPt+46buiP5j5Wzqe5oMIhqBcAeKfygSA==",
+            "license": "MIT"
+        },
+        "node_modules/csstype": {
+            "version": "3.2.3",
+            "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
+            "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
+            "devOptional": true,
+            "license": "MIT"
+        },
+        "node_modules/dashjs": {
+            "version": "5.2.1",
+            "resolved": "https://registry.npmjs.org/dashjs/-/dashjs-5.2.1.tgz",
+            "integrity": "sha512-axcJmLeJCTJMLUfQRErUJB1KOiU5iHF+DMLBc3FKeox1HPYtGUQlC6Xm5Mm6vhBUR3CHHLIPOqw0JDIqMtP+Dw==",
+            "license": "BSD-3-Clause",
+            "dependencies": {
+                "@svta/cml-608": "1.0.2",
+                "@svta/cml-cmcd": "2.3.2",
+                "@svta/cml-cmsd": "1.0.6",
+                "@svta/cml-dash": "1.0.6",
+                "@svta/cml-id3": "1.0.6",
+                "@svta/cml-request": "1.0.12",
+                "@svta/cml-xml": "1.1.4",
+                "bcp-47-match": "^2.0.3",
+                "codem-isoboxer": "0.3.10",
+                "fast-deep-equal": "3.1.3",
+                "html-entities": "^2.6.0",
+                "imsc": "^1.1.5",
+                "localforage": "^1.10.0",
+                "path-browserify": "^1.0.1"
+            },
+            "engines": {
+                "node": ">=20"
+            }
+        },
+        "node_modules/detect-libc": {
+            "version": "2.1.2",
+            "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+            "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=8"
+            }
+        },
+        "node_modules/detect-node-es": {
+            "version": "1.1.0",
+            "resolved": "https://registry.npmjs.org/detect-node-es/-/detect-node-es-1.1.0.tgz",
+            "integrity": "sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==",
+            "license": "MIT"
+        },
+        "node_modules/es-module-lexer": {
+            "version": "2.3.2",
+            "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
+            "integrity": "sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/estree-walker": {
+            "version": "3.0.3",
+            "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+            "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@types/estree": "^1.0.0"
+            }
+        },
+        "node_modules/expect-type": {
+            "version": "1.4.0",
+            "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
+            "integrity": "sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=12.0.0"
+            }
+        },
+        "node_modules/fast-deep-equal": {
+            "version": "3.1.3",
+            "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+            "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+            "license": "MIT"
+        },
+        "node_modules/fdir": {
+            "version": "6.5.0",
+            "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+            "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=12.0.0"
+            },
+            "peerDependencies": {
+                "picomatch": "^3 || ^4"
+            },
+            "peerDependenciesMeta": {
+                "picomatch": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/fsevents": {
+            "version": "2.3.3",
+            "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+            "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+            "dev": true,
+            "hasInstallScript": true,
+            "license": "MIT",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+            }
+        },
+        "node_modules/get-nonce": {
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/get-nonce/-/get-nonce-1.0.1.tgz",
+            "integrity": "sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=6"
+            }
+        },
+        "node_modules/hls.js": {
+            "version": "1.7.3",
+            "resolved": "https://registry.npmjs.org/hls.js/-/hls.js-1.7.3.tgz",
+            "integrity": "sha512-MsPlx6yVW4Qv4C7mEVou4/gk/5cN2dVxOTnrNjPSmyH2f0Ln+/UkG10Ax1PE6OvrmTVPKgQYozTtBaPOuCzq7A==",
+            "license": "Apache-2.0"
+        },
+        "node_modules/html-entities": {
+            "version": "2.6.0",
+            "resolved": "https://registry.npmjs.org/html-entities/-/html-entities-2.6.0.tgz",
+            "integrity": "sha512-kig+rMn/QOVRvr7c86gQ8lWXq+Hkv6CbAH1hLu+RG338StTpE8Z0b44SDVaqVu7HGKf27frdmUYEs9hTUX/cLQ==",
+            "funding": [
+                {
+                    "type": "github",
+                    "url": "https://github.com/sponsors/mdevils"
+                },
+                {
+                    "type": "patreon",
+                    "url": "https://patreon.com/mdevils"
+                }
+            ],
+            "license": "MIT"
+        },
+        "node_modules/immediate": {
+            "version": "3.0.6",
+            "resolved": "https://registry.npmjs.org/immediate/-/immediate-3.0.6.tgz",
+            "integrity": "sha512-XXOFtyqDjNDAQxVfYxuF7g9Il/IbWmmlQg2MYKOH8ExIT1qg6xc4zyS3HaEEATgs1btfzxq15ciUiY7gjSXRGQ==",
+            "license": "MIT"
+        },
+        "node_modules/imsc": {
+            "version": "1.1.5",
+            "resolved": "https://registry.npmjs.org/imsc/-/imsc-1.1.5.tgz",
+            "integrity": "sha512-V8je+CGkcvGhgl2C1GlhqFFiUOIEdwXbXLiu1Fcubvvbo+g9inauqT3l0pNYXGoLPBj3jxtZz9t+wCopMkwadQ==",
+            "license": "BSD-2-Clause",
+            "dependencies": {
+                "sax": "1.2.1"
+            }
+        },
+        "node_modules/lie": {
+            "version": "3.1.1",
+            "resolved": "https://registry.npmjs.org/lie/-/lie-3.1.1.tgz",
+            "integrity": "sha512-RiNhHysUjhrDQntfYSfY4MU24coXXdEOgw9WGcKHNeEwffDYbF//u87M1EWaMGzuFoSbqW0C9C6lEEhDOAswfw==",
+            "license": "MIT",
+            "dependencies": {
+                "immediate": "~3.0.5"
+            }
+        },
+        "node_modules/lightningcss": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss/-/lightningcss-1.33.0.tgz",
+            "integrity": "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==",
+            "dev": true,
+            "license": "MPL-2.0",
+            "dependencies": {
+                "detect-libc": "^2.0.3"
+            },
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            },
+            "optionalDependencies": {
+                "lightningcss-android-arm64": "1.33.0",
+                "lightningcss-darwin-arm64": "1.33.0",
+                "lightningcss-darwin-x64": "1.33.0",
+                "lightningcss-freebsd-x64": "1.33.0",
+                "lightningcss-linux-arm-gnueabihf": "1.33.0",
+                "lightningcss-linux-arm64-gnu": "1.33.0",
+                "lightningcss-linux-arm64-musl": "1.33.0",
+                "lightningcss-linux-x64-gnu": "1.33.0",
+                "lightningcss-linux-x64-musl": "1.33.0",
+                "lightningcss-win32-arm64-msvc": "1.33.0",
+                "lightningcss-win32-x64-msvc": "1.33.0"
+            }
+        },
+        "node_modules/lightningcss-android-arm64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-android-arm64/-/lightningcss-android-arm64-1.33.0.tgz",
+            "integrity": "sha512-gEpRTalKdosp4Bb8qWtc2iOgE5SeIHlpS1up9bFq2wAyYhl1UdTObYiHe98zEM9SQvSoqQZ1IQD0JNpg3Ml5pg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "android"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-darwin-arm64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-darwin-arm64/-/lightningcss-darwin-arm64-1.33.0.tgz",
+            "integrity": "sha512-Sciaz8eenNTKn9b3t7+xr0ipTp9YxKQY4npwQ3mrRuL0BAVHBLyZxofhaKBAVtzmtRZ/zTyo0/to4B1uWG/Djg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-darwin-x64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-darwin-x64/-/lightningcss-darwin-x64-1.33.0.tgz",
+            "integrity": "sha512-Z5UPAxzrjlWNNyGy6i65cJzzvgJ5D3T6wMvs+gWpY9d7qRhANrxqAp6LhxIgZhWEw18RfJTGcRxjuLIBr+m8XQ==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "darwin"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-freebsd-x64": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-freebsd-x64/-/lightningcss-freebsd-x64-1.33.0.tgz",
+            "integrity": "sha512-QQM/Ti/hQajJwCY+RiWuCZ9sdtI/XQk7nDK5vC8kkdwixezOlDgvDx7+RT+QjK6FcFT4MpsuoBnHIo/O3StRRg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "freebsd"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm-gnueabihf": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm-gnueabihf/-/lightningcss-linux-arm-gnueabihf-1.33.0.tgz",
+            "integrity": "sha512-N7FVBe6iS24MlM6R/4RBTxGhQheZGs7tiQ9U32UtF75NzP5Q7xWPRqLBCKxlRQRk3rY1jCIPLzx7WzOhuUIRLQ==",
+            "cpu": [
+                "arm"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm64-gnu": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-gnu/-/lightningcss-linux-arm64-gnu-1.33.0.tgz",
+            "integrity": "sha512-j2v/itmy4HlNxlc6voKXYgBqNi0Ng2LShg4z7GufpEgs05P+2suBVyi9I6YHq5uoVFx9ETin3eCEhLVyXGQnKg==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-arm64-musl": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-arm64-musl/-/lightningcss-linux-arm64-musl-1.33.0.tgz",
+            "integrity": "sha512-yiO5ROMuYQgXbC60yjZU5CYSFZGKXL0HFATXt9mHJn1+zW55oCtMI9NfcVhYLMFDL7gV7oBPon/EmMMGg2OvtQ==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-x64-gnu": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-gnu/-/lightningcss-linux-x64-gnu-1.33.0.tgz",
+            "integrity": "sha512-ar+Ju7LmcN0Jo4FpL4hpFybwNG9/3A/Br5KW2n2jyODg3MEZXaDYADdemoNS+BDNfMgKvylJLj4S5tyRActuAg==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "glibc"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-linux-x64-musl": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-linux-x64-musl/-/lightningcss-linux-x64-musl-1.33.0.tgz",
+            "integrity": "sha512-RYiYbkokw0trfKqqzfF55lginwEPrD3OJDfTuJzFs1MK6iFnDenaz1fqLLtX4ITG3OktJQXOeTaw1awrBAlZPw==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "libc": [
+                "musl"
+            ],
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "linux"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-win32-arm64-msvc": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-win32-arm64-msvc/-/lightningcss-win32-arm64-msvc-1.33.0.tgz",
+            "integrity": "sha512-1K+MPfLSFVpphzpdbfkhlWk6wBrTObBzS2T6db10PNOZgR9GoVsAWzwNyuhUYYbTp23j+4RrncfujZ4uAzXvwA==",
+            "cpu": [
+                "arm64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/lightningcss-win32-x64-msvc": {
+            "version": "1.33.0",
+            "resolved": "https://registry.npmjs.org/lightningcss-win32-x64-msvc/-/lightningcss-win32-x64-msvc-1.33.0.tgz",
+            "integrity": "sha512-OlEICDx/Xl0FqSp4bry8zFnCvGpig3Gl4gCquvYwHuqJKEC1+n9NgDniFvqHGmMv1ZkqDJrDqKKSykTDX+ehuA==",
+            "cpu": [
+                "x64"
+            ],
+            "dev": true,
+            "license": "MPL-2.0",
+            "optional": true,
+            "os": [
+                "win32"
+            ],
+            "engines": {
+                "node": ">= 12.0.0"
+            },
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/parcel"
+            }
+        },
+        "node_modules/localforage": {
+            "version": "1.10.0",
+            "resolved": "https://registry.npmjs.org/localforage/-/localforage-1.10.0.tgz",
+            "integrity": "sha512-14/H1aX7hzBBmmh7sGPd+AOMkkIrHM3Z1PAyGgZigA1H1p5O5ANnMyWzvpAETtG68/dC4pC0ncy3+PPGzXZHPg==",
+            "license": "Apache-2.0",
+            "dependencies": {
+                "lie": "3.1.1"
+            }
+        },
+        "node_modules/lucide-react": {
+            "version": "1.58.0",
+            "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.58.0.tgz",
+            "integrity": "sha512-hXaFNm6mk6QVtBnDGBn1YAs8j2tGUk0A4s/CpclIcczfxeXiW1rdOLVo6zCsoIih9XXsGvDODQerl749a2n7bA==",
+            "license": "ISC",
+            "peerDependencies": {
+                "@types/react": "*",
+                "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+            },
+            "peerDependenciesMeta": {
+                "@types/react": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/magic-string": {
+            "version": "1.4.3",
+            "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-1.4.3.tgz",
+            "integrity": "sha512-z12OxmaPGE0F4xlpGdjuAUckipLpQlTAuAmyGhNoD7ODpYUzvDfvtxUbjM/jwznyP178oju/KDdyi220wNJ0RQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@jridgewell/sourcemap-codec": "^1.6.0"
+            }
+        },
+        "node_modules/movi-player": {
+            "version": "0.4.1-tgdrive.1",
+            "resolved": "file:vendor/movi-player-0.4.1-tgdrive.1.tgz",
+            "integrity": "sha512-7TVpUAklTBPtgdxJGWh8771ZNvLt8uF6aQ8R7i7iNOu/np0gEMTVmfv0WRwKEwnTnJvBBUnA9qMaZwnSLGx2Eg==",
+            "license": "Apache-2.0",
+            "dependencies": {
+                "dashjs": "^5.2.0",
+                "hls.js": "^1.6.16",
+                "shaka-player": "^4.11.2"
+            },
+            "engines": {
+                "node": ">=18"
+            },
+            "peerDependencies": {
+                "react": ">=17",
+                "svelte": ">=4",
+                "vue": ">=3.3"
+            },
+            "peerDependenciesMeta": {
+                "react": {
+                    "optional": true
+                },
+                "svelte": {
+                    "optional": true
+                },
+                "vue": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/nanoid": {
+            "version": "3.3.20",
+            "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.20.tgz",
+            "integrity": "sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==",
+            "dev": true,
+            "funding": [
+                {
+                    "type": "github",
+                    "url": "https://github.com/sponsors/ai"
+                }
+            ],
+            "license": "MIT",
+            "bin": {
+                "nanoid": "bin/nanoid.cjs"
+            },
+            "engines": {
+                "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+            }
+        },
+        "node_modules/obug": {
+            "version": "3.0.0",
+            "resolved": "https://registry.npmjs.org/obug/-/obug-3.0.0.tgz",
+            "integrity": "sha512-5vvB5+W7ePv+p3uqxi+RcW1XAzLW0/hxt3/4X4Lc4qHudzOhmBiBwOY6DRob4WnanAEGvNcLjF+KNOufrUoEQw==",
+            "dev": true,
+            "funding": [
+                "https://github.com/sponsors/sxzz",
+                "https://opencollective.com/debug"
+            ],
+            "license": "MIT",
+            "engines": {
+                "node": ">=12.20.0"
+            }
+        },
+        "node_modules/path-browserify": {
+            "version": "1.0.1",
+            "resolved": "https://registry.npmjs.org/path-browserify/-/path-browserify-1.0.1.tgz",
+            "integrity": "sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==",
+            "license": "MIT"
+        },
+        "node_modules/pdfjs-dist": {
+            "version": "6.4.299-tgdrive.1",
+            "resolved": "file:vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz",
+            "integrity": "sha512-+Ff7Uf04N7pZmoje7r0m7NLP5PmaH6sTwg6lt+GktFSF8ShHQStFAnSTR4fcKQJ50O+jcjX7YHJliJZPj0zf1Q==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=22.13.0 || >=24"
+            },
+            "optionalDependencies": {
+                "@napi-rs/canvas": "^1.0.10"
+            }
+        },
+        "node_modules/picocolors": {
+            "version": "1.1.1",
+            "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+            "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+            "dev": true,
+            "license": "ISC"
+        },
+        "node_modules/picomatch": {
+            "version": "4.0.7",
+            "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz",
+            "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=12"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/jonschlinkert"
+            }
+        },
+        "node_modules/postcss": {
+            "version": "8.5.30",
+            "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.30.tgz",
+            "integrity": "sha512-zkd+e9S1AQHhmaBKye9zlFHWjOwVgqXl1q3ECYy8561K7qxR2cREf/STLskulBFd78k6AOFeA+ff1TtEzk9bAA==",
+            "dev": true,
+            "funding": [
+                {
+                    "type": "opencollective",
+                    "url": "https://opencollective.com/postcss/"
+                },
+                {
+                    "type": "tidelift",
+                    "url": "https://tidelift.com/funding/github/npm/postcss"
+                },
+                {
+                    "type": "github",
+                    "url": "https://github.com/sponsors/ai"
+                }
+            ],
+            "license": "MIT",
+            "dependencies": {
+                "nanoid": "^3.3.20",
+                "picocolors": "^1.1.1",
+                "source-map-js": "^1.2.2"
+            },
+            "engines": {
+                "node": "^10 || ^12 || >=14"
+            }
+        },
+        "node_modules/prettier": {
+            "version": "3.9.10",
+            "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.9.10.tgz",
+            "integrity": "sha512-skGHTH1Yb9QvaTC4hWnRTzEYtCpApF0UMBPz+t/0ZPzP8ihefo/btKd+QA7pUE0fEwA1SbS/NmhyEcstdXOIdA==",
+            "dev": true,
+            "license": "MIT",
+            "bin": {
+                "prettier": "bin/prettier.cjs"
+            },
+            "engines": {
+                "node": ">=14"
+            },
+            "funding": {
+                "url": "https://github.com/prettier/prettier?sponsor=1"
+            }
+        },
+        "node_modules/react": {
+            "version": "19.3.1",
+            "resolved": "https://registry.npmjs.org/react/-/react-19.3.1.tgz",
+            "integrity": "sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
+        "node_modules/react-dom": {
+            "version": "19.3.1",
+            "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.3.1.tgz",
+            "integrity": "sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ==",
+            "license": "MIT",
+            "dependencies": {
+                "scheduler": "^0.28.0"
+            },
+            "peerDependencies": {
+                "react": "^19.3.1"
+            }
+        },
+        "node_modules/react-number-format": {
+            "version": "5.4.5",
+            "resolved": "https://registry.npmjs.org/react-number-format/-/react-number-format-5.4.5.tgz",
+            "integrity": "sha512-y8O2yHHj3w0aE9XO8d2BCcUOOdQTRSVq+WIuMlLVucAm5XNjJAy+BoOJiuQMldVYVOKTMyvVNfnbl2Oqp+YxGw==",
+            "license": "MIT",
+            "peerDependencies": {
+                "react": "^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+                "react-dom": "^0.14 || ^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+            }
+        },
+        "node_modules/react-remove-scroll": {
+            "version": "2.7.2",
+            "resolved": "https://registry.npmjs.org/react-remove-scroll/-/react-remove-scroll-2.7.2.tgz",
+            "integrity": "sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==",
+            "license": "MIT",
+            "dependencies": {
+                "react-remove-scroll-bar": "^2.3.7",
+                "react-style-singleton": "^2.2.3",
+                "tslib": "^2.1.0",
+                "use-callback-ref": "^1.3.3",
+                "use-sidecar": "^1.1.3"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "peerDependencies": {
+                "@types/react": "*",
+                "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+            },
+            "peerDependenciesMeta": {
+                "@types/react": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/react-remove-scroll-bar": {
+            "version": "2.3.8",
+            "resolved": "https://registry.npmjs.org/react-remove-scroll-bar/-/react-remove-scroll-bar-2.3.8.tgz",
+            "integrity": "sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==",
+            "license": "MIT",
+            "dependencies": {
+                "react-style-singleton": "^2.2.2",
+                "tslib": "^2.0.0"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "peerDependencies": {
+                "@types/react": "*",
+                "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+            },
+            "peerDependenciesMeta": {
+                "@types/react": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/react-style-singleton": {
+            "version": "2.2.3",
+            "resolved": "https://registry.npmjs.org/react-style-singleton/-/react-style-singleton-2.2.3.tgz",
+            "integrity": "sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==",
+            "license": "MIT",
+            "dependencies": {
+                "get-nonce": "^1.0.0",
+                "tslib": "^2.0.0"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "peerDependencies": {
+                "@types/react": "*",
+                "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+            },
+            "peerDependenciesMeta": {
+                "@types/react": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/rolldown": {
+            "version": "1.2.14",
+            "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.14.tgz",
+            "integrity": "sha512-eTBTTqMR6uHKLgcUqpJP8ntzDI6V4LYA8negAMBEI7gkgVvOdrx6VsvS2Ym+83KhOPdLCHWJu0w7UQFJZhHKNw==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@oxc-project/types": "=0.154.0",
+                "@rolldown/pluginutils": "^1.0.0"
+            },
+            "bin": {
+                "rolldown": "bin/cli.mjs"
+            },
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            },
+            "optionalDependencies": {
+                "@rolldown/binding-android-arm-eabi": "1.2.14",
+                "@rolldown/binding-android-arm64": "1.2.14",
+                "@rolldown/binding-darwin-arm64": "1.2.14",
+                "@rolldown/binding-darwin-x64": "1.2.14",
+                "@rolldown/binding-freebsd-x64": "1.2.14",
+                "@rolldown/binding-linux-arm-gnueabihf": "1.2.14",
+                "@rolldown/binding-linux-arm64-gnu": "1.2.14",
+                "@rolldown/binding-linux-arm64-musl": "1.2.14",
+                "@rolldown/binding-linux-ppc64-gnu": "1.2.14",
+                "@rolldown/binding-linux-s390x-gnu": "1.2.14",
+                "@rolldown/binding-linux-x64-gnu": "1.2.14",
+                "@rolldown/binding-linux-x64-musl": "1.2.14",
+                "@rolldown/binding-openharmony-arm64": "1.2.14",
+                "@rolldown/binding-win32-arm64-msvc": "1.2.14",
+                "@rolldown/binding-win32-x64-msvc": "1.2.14"
+            }
+        },
+        "node_modules/sax": {
+            "version": "1.2.1",
+            "resolved": "https://registry.npmjs.org/sax/-/sax-1.2.1.tgz",
+            "integrity": "sha512-8I2a3LovHTOpm7NV5yOyO8IHqgVsfK4+UuySrXU8YXkSRX7k6hCV9b3HrkKCr3nMpgj+0bmocaJJWpvp1oc7ZA==",
+            "license": "ISC"
+        },
+        "node_modules/scheduler": {
+            "version": "0.28.0",
+            "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.28.0.tgz",
+            "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
+            "license": "MIT"
+        },
+        "node_modules/shaka-player": {
+            "version": "4.16.53",
+            "resolved": "https://registry.npmjs.org/shaka-player/-/shaka-player-4.16.53.tgz",
+            "integrity": "sha512-XrOjsMMv/lIn1rlKl7shlw+QtO+DseiHvpKryCeR36EaIVCfQ50YZnbOr3ZqM7mBDkYx1vo1MaV6xPG5P4vbxg==",
+            "license": "Apache-2.0",
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/source-map-js": {
+            "version": "1.2.2",
+            "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
+            "integrity": "sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==",
+            "dev": true,
+            "license": "BSD-3-Clause",
+            "engines": {
+                "node": ">=0.10.0"
+            }
+        },
+        "node_modules/std-env": {
+            "version": "4.3.0",
+            "resolved": "https://registry.npmjs.org/std-env/-/std-env-4.3.0.tgz",
+            "integrity": "sha512-OtU/EgQ1kIm5KwqQpBC6ZEMXrZRui11w8zgfTWp8cdO9B8OaPsbA8bTHO2P+HNo1VlUTGMVBwPhydu6poeXiag==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/tabbable": {
+            "version": "6.5.0",
+            "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.5.0.tgz",
+            "integrity": "sha512-wieBHXygIm7OyQOu5hQlkk62/WyCFYGlWg7L6/ZCUZwx0o398Zkn4pVmMyfYhfMG8kGrj/Krt8eIk6UKC6VzwA==",
+            "license": "MIT"
+        },
+        "node_modules/tagged-tag": {
+            "version": "1.0.0",
+            "resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
+            "integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=20"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
+        "node_modules/tinybench": {
+            "version": "6.2.2",
+            "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-6.2.2.tgz",
+            "integrity": "sha512-nIZ2N2dFpjBsg2hgitKu7mA+FvsIJuGJOwysRngmVRRmWgR/UyPjwJj8c/fT/dhm8EkHnF5EOogRf+0Z2qrimA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=20.0.0"
+            }
+        },
+        "node_modules/tinyexec": {
+            "version": "1.3.1",
+            "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz",
+            "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==",
+            "dev": true,
+            "license": "MIT",
+            "engines": {
+                "node": ">=18"
+            }
+        },
+        "node_modules/tinyglobby": {
+            "version": "0.2.17",
+            "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.17.tgz",
+            "integrity": "sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "fdir": "^6.5.0",
+                "picomatch": "^4.0.4"
+            },
+            "engines": {
+                "node": ">=12.0.0"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/SuperchupuDev"
+            }
+        },
+        "node_modules/tslib": {
+            "version": "2.8.1",
+            "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+            "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+            "license": "0BSD"
+        },
+        "node_modules/type-fest": {
+            "version": "5.10.0",
+            "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.10.0.tgz",
+            "integrity": "sha512-NoSdpq/WEiAg5sjmBkmV/hfxv6HJH4NqPNrqjtSO5CwRmpsDfaf4begxW34KdJykH/l1yHtwBWQkCRdoXO8mPA==",
+            "license": "(MIT OR CC0-1.0)",
+            "dependencies": {
+                "tagged-tag": "^1.0.0"
+            },
+            "engines": {
+                "node": ">=20"
+            },
+            "funding": {
+                "url": "https://github.com/sponsors/sindresorhus"
+            }
+        },
+        "node_modules/typescript": {
+            "version": "7.0.2",
+            "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",
+            "integrity": "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==",
+            "dev": true,
+            "license": "Apache-2.0",
+            "bin": {
+                "tsc": "bin/tsc"
+            },
+            "engines": {
+                "node": ">=16.20.0"
+            },
+            "optionalDependencies": {
+                "@typescript/typescript-aix-ppc64": "7.0.2",
+                "@typescript/typescript-darwin-arm64": "7.0.2",
+                "@typescript/typescript-darwin-x64": "7.0.2",
+                "@typescript/typescript-freebsd-arm64": "7.0.2",
+                "@typescript/typescript-freebsd-x64": "7.0.2",
+                "@typescript/typescript-linux-arm": "7.0.2",
+                "@typescript/typescript-linux-arm64": "7.0.2",
+                "@typescript/typescript-linux-loong64": "7.0.2",
+                "@typescript/typescript-linux-mips64el": "7.0.2",
+                "@typescript/typescript-linux-ppc64": "7.0.2",
+                "@typescript/typescript-linux-riscv64": "7.0.2",
+                "@typescript/typescript-linux-s390x": "7.0.2",
+                "@typescript/typescript-linux-x64": "7.0.2",
+                "@typescript/typescript-netbsd-arm64": "7.0.2",
+                "@typescript/typescript-netbsd-x64": "7.0.2",
+                "@typescript/typescript-openbsd-arm64": "7.0.2",
+                "@typescript/typescript-openbsd-x64": "7.0.2",
+                "@typescript/typescript-sunos-x64": "7.0.2",
+                "@typescript/typescript-win32-arm64": "7.0.2",
+                "@typescript/typescript-win32-x64": "7.0.2"
+            }
+        },
+        "node_modules/undici-types": {
+            "version": "7.24.6",
+            "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz",
+            "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==",
+            "dev": true,
+            "license": "MIT"
+        },
+        "node_modules/use-callback-ref": {
+            "version": "1.3.3",
+            "resolved": "https://registry.npmjs.org/use-callback-ref/-/use-callback-ref-1.3.3.tgz",
+            "integrity": "sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==",
+            "license": "MIT",
+            "dependencies": {
+                "tslib": "^2.0.0"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "peerDependencies": {
+                "@types/react": "*",
+                "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+            },
+            "peerDependenciesMeta": {
+                "@types/react": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/use-sidecar": {
+            "version": "1.1.3",
+            "resolved": "https://registry.npmjs.org/use-sidecar/-/use-sidecar-1.1.3.tgz",
+            "integrity": "sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==",
+            "license": "MIT",
+            "dependencies": {
+                "detect-node-es": "^1.1.0",
+                "tslib": "^2.0.0"
+            },
+            "engines": {
+                "node": ">=10"
+            },
+            "peerDependencies": {
+                "@types/react": "*",
+                "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc"
+            },
+            "peerDependenciesMeta": {
+                "@types/react": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/vite": {
+            "version": "8.3.4",
+            "resolved": "https://registry.npmjs.org/vite/-/vite-8.3.4.tgz",
+            "integrity": "sha512-IftLE8phJhdNRIGNEV4JCCvfNScoZQVfcXaN8TQropWGJtOHcu+iAB9pHcuGvmEb/kddw0LBe/jS8ztdC6xdiQ==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "lightningcss": "^1.33.0",
+                "picomatch": "^4.0.7",
+                "postcss": "^8.5.29",
+                "rolldown": "~1.2.12",
+                "tinyglobby": "^0.2.17"
+            },
+            "bin": {
+                "vite": "bin/vite.js"
+            },
+            "engines": {
+                "node": "^20.19.0 || >=22.12.0"
+            },
+            "funding": {
+                "url": "https://github.com/vitejs/vite?sponsor=1"
+            },
+            "optionalDependencies": {
+                "fsevents": "~2.3.3"
+            },
+            "peerDependencies": {
+                "@types/node": "^20.19.0 || >=22.12.0",
+                "@vitejs/devtools": "^0.7.1",
+                "esbuild": "^0.27.0 || ^0.28.0",
+                "jiti": ">=1.21.0",
+                "less": "^4.0.0",
+                "sass": "^1.70.0",
+                "sass-embedded": "^1.70.0",
+                "stylus": ">=0.54.8",
+                "sugarss": "^5.0.0",
+                "terser": "^5.16.0",
+                "tsx": "^4.8.1",
+                "yaml": "^2.4.2"
+            },
+            "peerDependenciesMeta": {
+                "@types/node": {
+                    "optional": true
+                },
+                "@vitejs/devtools": {
+                    "optional": true
+                },
+                "esbuild": {
+                    "optional": true
+                },
+                "jiti": {
+                    "optional": true
+                },
+                "less": {
+                    "optional": true
+                },
+                "sass": {
+                    "optional": true
+                },
+                "sass-embedded": {
+                    "optional": true
+                },
+                "stylus": {
+                    "optional": true
+                },
+                "sugarss": {
+                    "optional": true
+                },
+                "terser": {
+                    "optional": true
+                },
+                "tsx": {
+                    "optional": true
+                },
+                "yaml": {
+                    "optional": true
+                }
+            }
+        },
+        "node_modules/vitest": {
+            "version": "5.0.5",
+            "resolved": "https://registry.npmjs.org/vitest/-/vitest-5.0.5.tgz",
+            "integrity": "sha512-cPODOMF8YnkiiYtDdHo6n4wWmBrOBBbOIYH2d33M4l3CdNn72h+qMmO6uXffUN6A5AZFXNND/d+krS9mgkXRfg==",
+            "dev": true,
+            "license": "MIT",
+            "dependencies": {
+                "@types/chai": "^5.2.2",
+                "@vitest/mocker": "5.0.5",
+                "chai": "^6.3.0",
+                "es-module-lexer": "^2.3.2",
+                "expect-type": "^1.4.0",
+                "magic-string": "^1.4.3",
+                "obug": "^3.0.0",
+                "picomatch": "^4.0.7",
+                "std-env": "^4.3.0",
+                "tinybench": "^6.2.2",
+                "tinyexec": "^1.3.1",
+                "tinyglobby": "^0.2.17",
+                "why-is-node-running": "3.2.1"
+            },
+            "bin": {
+                "vitest": "vitest.mjs"
+            },
+            "engines": {
+                "node": "^22.12.0 || ^24.0.0 || >=26.0.0"
+            },
+            "funding": {
+                "url": "https://opencollective.com/vitest"
+            },
+            "peerDependencies": {
+                "@edge-runtime/vm": "*",
+                "@opentelemetry/api": "^1.9.0",
+                "@types/node": "^22.0.0 || >=24.0.0",
+                "@vitest/browser-playwright": "5.0.5",
+                "@vitest/browser-preview": "5.0.5",
+                "@vitest/browser-webdriverio": "^5.0.0-beta.5 || >=5.0.0",
+                "@vitest/coverage-istanbul": "5.0.5",
+                "@vitest/coverage-v8": "5.0.5",
+                "@vitest/ui": "5.0.5",
+                "happy-dom": "*",
+                "jsdom": "*",
+                "vite": "^6.4.0 || ^7.0.0 || ^8.0.0"
+            },
+            "peerDependenciesMeta": {
+                "@edge-runtime/vm": {
+                    "optional": true
+                },
+                "@opentelemetry/api": {
+                    "optional": true
+                },
+                "@types/node": {
+                    "optional": true
+                },
+                "@vitest/browser-playwright": {
+                    "optional": true
+                },
+                "@vitest/browser-preview": {
+                    "optional": true
+                },
+                "@vitest/browser-webdriverio": {
+                    "optional": true
+                },
+                "@vitest/coverage-istanbul": {
+                    "optional": true
+                },
+                "@vitest/coverage-v8": {
+                    "optional": true
+                },
+                "@vitest/ui": {
+                    "optional": true
+                },
+                "happy-dom": {
+                    "optional": true
+                },
+                "jsdom": {
+                    "optional": true
+                },
+                "vite": {
+                    "optional": false
+                }
+            }
+        },
+        "node_modules/why-is-node-running": {
+            "version": "3.2.1",
+            "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-3.2.1.tgz",
+            "integrity": "sha512-Tb2FUhB4vUsGQlfSquQLYkApkuPAFQXGFzxWKHHumVz2dK+X1RUm/HnID4+TfIGYJ1kTcwOaCk/buYCEJr6YjQ==",
+            "dev": true,
+            "license": "MIT",
+            "bin": {
+                "why-is-node-running": "cli.js"
+            },
+            "engines": {
+                "node": ">=20.11"
+            }
+        }
+    }
+}
diff --git a/website/package.json b/website/package.json
new file mode 100644
index 00000000..3ba8f72d
--- /dev/null
+++ b/website/package.json
@@ -0,0 +1,38 @@
+{
+    "name": "tgdrive-web",
+    "version": "2.0.0",
+    "private": true,
+    "type": "module",
+    "engines": {
+        "node": ">=24.22.0 <25"
+    },
+    "scripts": {
+        "dev": "vite --host 127.0.0.1",
+        "typecheck": "tsc --noEmit",
+        "check": "npm run typecheck",
+        "format": "prettier --write src",
+        "format:check": "prettier --check src",
+        "build": "tsc --noEmit && vite build",
+        "pretest": "node --test scripts/check-movi-player.js scripts/check-pdf-worker.js",
+        "test": "vitest run"
+    },
+    "dependencies": {
+        "@mantine/core": "9.7.3",
+        "@mantine/hooks": "9.7.3",
+        "lucide-react": "1.58.0",
+        "movi-player": "file:vendor/movi-player-0.4.1-tgdrive.1.tgz",
+        "pdfjs-dist": "file:vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz",
+        "react": "19.3.1",
+        "react-dom": "19.3.1"
+    },
+    "devDependencies": {
+        "@types/node": "24.19.2",
+        "@types/react": "19.3.0",
+        "@types/react-dom": "19.3.0",
+        "@vitejs/plugin-react": "6.1.2",
+        "prettier": "3.9.10",
+        "typescript": "7.0.2",
+        "vite": "8.3.4",
+        "vitest": "5.0.5"
+    }
+}
diff --git a/website/public/VideoPlayer.html b/website/public/VideoPlayer.html
new file mode 100644
index 00000000..e44b5a65
--- /dev/null
+++ b/website/public/VideoPlayer.html
@@ -0,0 +1,130 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="color-scheme" content="dark" />
+        <meta name="theme-color" content="#0d1424" />
+        <meta name="description" content="Stream a video from TGDrive." />
+        <title>Video · TGDrive</title>
+        <link
+            rel="icon"
+            type="image/svg+xml"
+            href="/static/brand/favicon.svg"
+        />
+        <link
+            rel="icon"
+            type="image/png"
+            sizes="32x32"
+            href="/static/brand/favicon-32.png"
+        />
+        <link
+            rel="icon"
+            type="image/png"
+            sizes="16x16"
+            href="/static/brand/favicon-16.png"
+        />
+        <link rel="shortcut icon" href="/static/brand/favicon.ico" />
+        <link
+            rel="apple-touch-icon"
+            sizes="180x180"
+            href="/static/brand/apple-touch-icon.png"
+        />
+        <meta property="og:type" content="website" />
+        <meta property="og:title" content="Video · TGDrive" />
+        <meta
+            property="og:description"
+            content="Stream a video from TGDrive."
+        />
+        <meta property="og:image" content="/static/brand/social-preview.png" />
+        <meta property="og:image:width" content="1200" />
+        <meta property="og:image:height" content="630" />
+        <meta
+            property="og:image:alt"
+            content="TGDrive — your private Telegram-backed file drive"
+        />
+        <meta name="twitter:card" content="summary_large_image" />
+        <meta name="twitter:image" content="/static/brand/social-preview.png" />
+        <meta
+            name="twitter:image:alt"
+            content="TGDrive — your private Telegram-backed file drive"
+        />
+        <link rel="stylesheet" href="/static/player.css?v=2.0.0-r3" />
+        <script
+            type="module"
+            src="/static/js/video-player.js?v=2.0.0-r2"
+        ></script>
+    </head>
+    <body>
+        <main class="player-shell">
+            <header class="player-header">
+                <a
+                    class="player-brand"
+                    href="/?path=/"
+                    aria-label="Back to TGDrive"
+                >
+                    <img
+                        src="/static/brand/tgdrive-logo-dark.svg"
+                        width="2010"
+                        height="401"
+                        alt="TGDrive"
+                    />
+                </a>
+                <a class="back-link" href="/?path=/">Back to files</a>
+            </header>
+
+            <section class="player-card" aria-labelledby="player-title">
+                <div class="video-frame">
+                    <video
+                        id="video-player"
+                        controls
+                        playsinline
+                        preload="metadata"
+                    >
+                        Your browser does not support HTML video playback.
+                    </video>
+                    <div
+                        class="player-error"
+                        id="player-error"
+                        role="alert"
+                        hidden
+                    >
+                        <strong>Video unavailable</strong>
+                        <p id="player-error-message">
+                            This video could not be loaded.
+                        </p>
+                    </div>
+                </div>
+
+                <div class="player-details">
+                    <div>
+                        <p class="eyebrow">TGDrive stream</p>
+                        <h1 id="player-title">Video player</h1>
+                        <p id="player-status" role="status">
+                            Preparing your video…
+                        </p>
+                    </div>
+                    <div class="player-actions">
+                        <button id="copy-stream" type="button">
+                            Copy stream link
+                        </button>
+                        <button id="copy-file" type="button">
+                            Copy file link
+                        </button>
+                        <a id="download-link" href="#" download
+                            >Download original</a
+                        >
+                    </div>
+                </div>
+            </section>
+        </main>
+
+        <div
+            class="player-toast"
+            id="player-toast"
+            role="status"
+            aria-live="polite"
+            hidden
+        ></div>
+    </body>
+</html>
diff --git a/website/static/brand/app-icon-192.png b/website/public/static/brand/app-icon-192.png
similarity index 100%
rename from website/static/brand/app-icon-192.png
rename to website/public/static/brand/app-icon-192.png
diff --git a/website/static/brand/app-icon-512.png b/website/public/static/brand/app-icon-512.png
similarity index 100%
rename from website/static/brand/app-icon-512.png
rename to website/public/static/brand/app-icon-512.png
diff --git a/website/static/brand/apple-touch-icon.png b/website/public/static/brand/apple-touch-icon.png
similarity index 100%
rename from website/static/brand/apple-touch-icon.png
rename to website/public/static/brand/apple-touch-icon.png
diff --git a/website/static/brand/favicon-16.png b/website/public/static/brand/favicon-16.png
similarity index 100%
rename from website/static/brand/favicon-16.png
rename to website/public/static/brand/favicon-16.png
diff --git a/website/static/brand/favicon-32.png b/website/public/static/brand/favicon-32.png
similarity index 100%
rename from website/static/brand/favicon-32.png
rename to website/public/static/brand/favicon-32.png
diff --git a/website/static/brand/favicon-48.png b/website/public/static/brand/favicon-48.png
similarity index 100%
rename from website/static/brand/favicon-48.png
rename to website/public/static/brand/favicon-48.png
diff --git a/website/static/brand/favicon.ico b/website/public/static/brand/favicon.ico
similarity index 100%
rename from website/static/brand/favicon.ico
rename to website/public/static/brand/favicon.ico
diff --git a/website/static/brand/favicon.svg b/website/public/static/brand/favicon.svg
similarity index 100%
rename from website/static/brand/favicon.svg
rename to website/public/static/brand/favicon.svg
diff --git a/website/static/brand/manifest.json b/website/public/static/brand/manifest.json
similarity index 100%
rename from website/static/brand/manifest.json
rename to website/public/static/brand/manifest.json
diff --git a/website/static/brand/social-preview.png b/website/public/static/brand/social-preview.png
similarity index 100%
rename from website/static/brand/social-preview.png
rename to website/public/static/brand/social-preview.png
diff --git a/website/static/brand/tgdrive-icon.png b/website/public/static/brand/tgdrive-icon.png
similarity index 100%
rename from website/static/brand/tgdrive-icon.png
rename to website/public/static/brand/tgdrive-icon.png
diff --git a/website/static/brand/tgdrive-icon.svg b/website/public/static/brand/tgdrive-icon.svg
similarity index 100%
rename from website/static/brand/tgdrive-icon.svg
rename to website/public/static/brand/tgdrive-icon.svg
diff --git a/website/static/brand/tgdrive-logo-dark.png b/website/public/static/brand/tgdrive-logo-dark.png
similarity index 100%
rename from website/static/brand/tgdrive-logo-dark.png
rename to website/public/static/brand/tgdrive-logo-dark.png
diff --git a/website/static/brand/tgdrive-logo-dark.svg b/website/public/static/brand/tgdrive-logo-dark.svg
similarity index 100%
rename from website/static/brand/tgdrive-logo-dark.svg
rename to website/public/static/brand/tgdrive-logo-dark.svg
diff --git a/website/static/brand/tgdrive-logo.png b/website/public/static/brand/tgdrive-logo.png
similarity index 100%
rename from website/static/brand/tgdrive-logo.png
rename to website/public/static/brand/tgdrive-logo.png
diff --git a/website/static/brand/tgdrive-logo.svg b/website/public/static/brand/tgdrive-logo.svg
similarity index 100%
rename from website/static/brand/tgdrive-logo.svg
rename to website/public/static/brand/tgdrive-logo.svg
diff --git a/website/public/static/fonts/InterVariable.woff2 b/website/public/static/fonts/InterVariable.woff2
new file mode 100644
index 00000000..5a8d3e72
Binary files /dev/null and b/website/public/static/fonts/InterVariable.woff2 differ
diff --git a/website/public/static/js/video-player.js b/website/public/static/js/video-player.js
new file mode 100755
index 00000000..393279a2
--- /dev/null
+++ b/website/public/static/js/video-player.js
@@ -0,0 +1,128 @@
+const player = document.getElementById("video-player");
+const errorPanel = document.getElementById("player-error");
+const errorMessage = document.getElementById("player-error-message");
+const status = document.getElementById("player-status");
+const copyButton = document.getElementById("copy-stream");
+const copyFileButton = document.getElementById("copy-file");
+const downloadLink = document.getElementById("download-link");
+const toast = document.getElementById("player-toast");
+
+let toastTimer = null;
+
+function showToast(message) {
+    toast.textContent = message;
+    toast.hidden = false;
+    if (toastTimer) {
+        window.clearTimeout(toastTimer);
+    }
+    toastTimer = window.setTimeout(() => {
+        toast.hidden = true;
+        toastTimer = null;
+    }, 4000);
+}
+
+function showError(message) {
+    errorMessage.textContent = message;
+    errorPanel.hidden = false;
+    status.textContent = "Playback unavailable";
+}
+
+function buildDownloadUrl(path, auth) {
+    const fileUrl = new URL("/file", window.location.origin);
+    fileUrl.searchParams.set("path", path);
+    if (auth) {
+        fileUrl.searchParams.set("auth", auth);
+    }
+    return fileUrl;
+}
+
+async function copyText(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+    } catch {
+        const textArea = document.createElement("textarea");
+        textArea.className = "clipboard-helper";
+        textArea.value = text;
+        textArea.setAttribute("readonly", "");
+        document.body.append(textArea);
+        textArea.select();
+        const copied = document.execCommand("copy");
+        textArea.remove();
+        if (!copied) {
+            throw new Error("Clipboard access was denied.");
+        }
+    }
+}
+
+function initializePlayer() {
+    const pageUrl = new URL(window.location.href);
+    const path = pageUrl.searchParams.get("path");
+    const auth = pageUrl.searchParams.get("auth") || "";
+
+    if (!path) {
+        showError("The video link is missing a file path.");
+        copyButton.disabled = true;
+        copyFileButton.disabled = true;
+        downloadLink.removeAttribute("href");
+        return;
+    }
+
+    const fileUrl = buildDownloadUrl(path, auth);
+    player.src = fileUrl;
+    const downloadUrl = new URL(fileUrl);
+    downloadUrl.searchParams.set("download", "1");
+    downloadLink.href = downloadUrl;
+    downloadLink.setAttribute("download", "");
+    status.textContent = "Ready to play";
+
+    player.addEventListener("loadstart", () => {
+        status.textContent = "Loading video…";
+    });
+    player.addEventListener("canplay", () => {
+        status.textContent = "Ready to play";
+    });
+    player.addEventListener("playing", () => {
+        status.textContent = "Playing";
+    });
+    player.addEventListener("pause", () => {
+        if (!player.ended) {
+            status.textContent = "Paused";
+        }
+    });
+    player.addEventListener("ended", () => {
+        status.textContent = "Playback complete";
+    });
+    player.addEventListener("error", () => {
+        showError(
+            "The file is unavailable or its format is not supported by this browser.",
+        );
+    });
+
+    copyButton.addEventListener("click", async () => {
+        try {
+            await copyText(pageUrl.toString());
+            showToast("Stream link copied.");
+        } catch (error) {
+            showToast(
+                error instanceof Error
+                    ? error.message
+                    : "Could not copy the stream link.",
+            );
+        }
+    });
+
+    copyFileButton.addEventListener("click", async () => {
+        try {
+            await copyText(fileUrl.toString());
+            showToast("File link copied.");
+        } catch (error) {
+            showToast(
+                error instanceof Error
+                    ? error.message
+                    : "Could not copy the file link.",
+            );
+        }
+    });
+}
+
+initializePlayer();
diff --git a/website/public/static/player.css b/website/public/static/player.css
new file mode 100755
index 00000000..97f777d8
--- /dev/null
+++ b/website/public/static/player.css
@@ -0,0 +1,309 @@
+:root {
+    color-scheme: dark;
+    font-family:
+        Inter,
+        ui-sans-serif,
+        system-ui,
+        -apple-system,
+        BlinkMacSystemFont,
+        "Segoe UI",
+        sans-serif;
+    --bg: #0d1424;
+    --surface: #151e31;
+    --surface-soft: #1b263d;
+    --line: #2b3853;
+    --text: #f4f7ff;
+    --muted: #9eabc1;
+    --primary: #86a2ff;
+    --primary-strong: #6685f0;
+}
+
+* {
+    box-sizing: border-box;
+}
+
+html,
+body {
+    min-width: 320px;
+    min-height: 100%;
+}
+
+body {
+    min-height: 100vh;
+    margin: 0;
+    color: var(--text);
+    background:
+        radial-gradient(
+            circle at 75% -10%,
+            rgba(89, 119, 226, 0.25),
+            transparent 34rem
+        ),
+        radial-gradient(
+            circle at -10% 100%,
+            rgba(55, 95, 160, 0.16),
+            transparent 32rem
+        ),
+        var(--bg);
+    font-size: 15px;
+    line-height: 1.5;
+}
+
+button,
+a {
+    font: inherit;
+}
+
+a {
+    color: inherit;
+}
+
+button,
+a {
+    -webkit-tap-highlight-color: transparent;
+}
+
+:focus-visible {
+    outline: 3px solid rgba(134, 162, 255, 0.48);
+    outline-offset: 3px;
+}
+
+[hidden] {
+    display: none !important;
+}
+
+.player-shell {
+    width: min(1180px, calc(100% - 40px));
+    margin: 0 auto;
+    padding: 24px 0 50px;
+}
+
+.player-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 20px;
+    min-height: 52px;
+    margin-bottom: 22px;
+}
+
+.player-brand {
+    display: inline-flex;
+    align-items: center;
+    flex: 0 0 auto;
+    text-decoration: none;
+}
+
+.player-brand img {
+    display: block;
+    width: 160px;
+    height: auto;
+    aspect-ratio: 2010 / 401;
+    object-fit: contain;
+}
+
+.back-link {
+    padding: 9px 13px;
+    color: var(--muted);
+    text-decoration: none;
+    border-radius: 10px;
+    font-weight: 700;
+}
+
+.back-link:hover {
+    color: var(--text);
+    background: rgba(255, 255, 255, 0.06);
+}
+
+.player-card {
+    overflow: hidden;
+    background: rgba(21, 30, 49, 0.94);
+    border: 1px solid var(--line);
+    border-radius: 24px;
+    box-shadow: 0 28px 75px rgba(0, 0, 0, 0.35);
+}
+
+.video-frame {
+    position: relative;
+    display: grid;
+    min-height: 360px;
+    place-items: center;
+    overflow: hidden;
+    background: #05070d;
+    aspect-ratio: 16 / 9;
+}
+
+video {
+    display: block;
+    width: 100%;
+    height: 100%;
+    background: #05070d;
+    object-fit: contain;
+}
+
+.player-error {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-direction: column;
+    padding: 30px;
+    color: var(--text);
+    background: rgba(7, 11, 20, 0.94);
+    text-align: center;
+}
+
+.player-error strong {
+    font-size: 22px;
+}
+
+.player-error p {
+    max-width: 480px;
+    margin: 8px 0 0;
+    color: var(--muted);
+}
+
+.player-details {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 28px;
+    padding: 25px 28px 28px;
+}
+
+.eyebrow {
+    margin: 0 0 4px;
+    color: var(--primary);
+    font-size: 11px;
+    font-weight: 850;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+}
+
+h1 {
+    margin: 0;
+    font-size: clamp(23px, 3vw, 32px);
+    line-height: 1.2;
+    letter-spacing: -0.035em;
+}
+
+#player-status {
+    margin: 8px 0 0;
+    color: var(--muted);
+}
+
+.player-actions {
+    display: flex;
+    flex: 0 0 auto;
+    flex-wrap: wrap;
+    gap: 10px;
+    justify-content: flex-end;
+}
+
+.player-actions button,
+.player-actions a {
+    display: inline-flex;
+    min-height: 44px;
+    align-items: center;
+    justify-content: center;
+    padding: 10px 15px;
+    color: var(--text);
+    background: var(--surface-soft);
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    font-weight: 750;
+    text-decoration: none;
+    transition:
+        background-color 150ms ease,
+        border-color 150ms ease,
+        transform 150ms ease;
+}
+
+.player-actions button:hover,
+.player-actions a:hover {
+    transform: translateY(-1px);
+    background: #24314d;
+    border-color: #435475;
+}
+
+.player-actions a {
+    color: #fff;
+    background: var(--primary-strong);
+    border-color: var(--primary-strong);
+}
+
+.player-actions a:hover {
+    background: #5776e1;
+}
+
+.player-toast {
+    position: fixed;
+    right: 20px;
+    bottom: 20px;
+    max-width: min(380px, calc(100vw - 40px));
+    padding: 12px 15px;
+    color: #fff;
+    background: #2e426d;
+    border: 1px solid #4f638d;
+    border-radius: 12px;
+    box-shadow: 0 16px 40px rgba(0, 0, 0, 0.32);
+}
+
+.clipboard-helper {
+    position: fixed;
+    top: -1000px;
+    left: -1000px;
+    width: 1px;
+    height: 1px;
+    opacity: 0;
+}
+
+@media (max-width: 720px) {
+    .player-shell {
+        width: min(100% - 20px, 1180px);
+        padding-top: 12px;
+    }
+
+    .player-header {
+        margin-bottom: 12px;
+        padding-inline: 5px;
+    }
+
+    .player-card {
+        border-radius: 18px;
+    }
+
+    .video-frame {
+        min-height: 190px;
+    }
+
+    .player-details {
+        align-items: stretch;
+        flex-direction: column;
+        gap: 20px;
+        padding: 20px;
+    }
+
+    .player-actions {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+    }
+}
+
+@media (max-width: 430px) {
+    .player-brand img {
+        width: 160px;
+    }
+
+    .back-link {
+        font-size: 13px;
+    }
+
+    .video-frame {
+        min-height: 170px;
+    }
+
+    .player-actions {
+        grid-template-columns: 1fr;
+    }
+}
diff --git a/website/public/third-party/FFmpeg-LGPL-2.1.txt b/website/public/third-party/FFmpeg-LGPL-2.1.txt
new file mode 100644
index 00000000..40924c2a
--- /dev/null
+++ b/website/public/third-party/FFmpeg-LGPL-2.1.txt
@@ -0,0 +1,502 @@
+                  GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 2.1, February 1999
+
+ Copyright (C) 1991, 1999 Free Software Foundation, Inc.
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+[This is the first released version of the Lesser GPL.  It also counts
+ as the successor of the GNU Library Public License, version 2, hence
+ the version number 2.1.]
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+Licenses are intended to guarantee your freedom to share and change
+free software--to make sure the software is free for all its users.
+
+  This license, the Lesser General Public License, applies to some
+specially designated software packages--typically libraries--of the
+Free Software Foundation and other authors who decide to use it.  You
+can use it too, but we suggest you first think carefully about whether
+this license or the ordinary General Public License is the better
+strategy to use in any particular case, based on the explanations below.
+
+  When we speak of free software, we are referring to freedom of use,
+not price.  Our General Public Licenses are designed to make sure that
+you have the freedom to distribute copies of free software (and charge
+for this service if you wish); that you receive source code or can get
+it if you want it; that you can change the software and use pieces of
+it in new free programs; and that you are informed that you can do
+these things.
+
+  To protect your rights, we need to make restrictions that forbid
+distributors to deny you these rights or to ask you to surrender these
+rights.  These restrictions translate to certain responsibilities for
+you if you distribute copies of the library or if you modify it.
+
+  For example, if you distribute copies of the library, whether gratis
+or for a fee, you must give the recipients all the rights that we gave
+you.  You must make sure that they, too, receive or can get the source
+code.  If you link other code with the library, you must provide
+complete object files to the recipients, so that they can relink them
+with the library after making changes to the library and recompiling
+it.  And you must show them these terms so they know their rights.
+
+  We protect your rights with a two-step method: (1) we copyright the
+library, and (2) we offer you this license, which gives you legal
+permission to copy, distribute and/or modify the library.
+
+  To protect each distributor, we want to make it very clear that
+there is no warranty for the free library.  Also, if the library is
+modified by someone else and passed on, the recipients should know
+that what they have is not the original version, so that the original
+author's reputation will not be affected by problems that might be
+introduced by others.
+
+  Finally, software patents pose a constant threat to the existence of
+any free program.  We wish to make sure that a company cannot
+effectively restrict the users of a free program by obtaining a
+restrictive license from a patent holder.  Therefore, we insist that
+any patent license obtained for a version of the library must be
+consistent with the full freedom of use specified in this license.
+
+  Most GNU software, including some libraries, is covered by the
+ordinary GNU General Public License.  This license, the GNU Lesser
+General Public License, applies to certain designated libraries, and
+is quite different from the ordinary General Public License.  We use
+this license for certain libraries in order to permit linking those
+libraries into non-free programs.
+
+  When a program is linked with a library, whether statically or using
+a shared library, the combination of the two is legally speaking a
+combined work, a derivative of the original library.  The ordinary
+General Public License therefore permits such linking only if the
+entire combination fits its criteria of freedom.  The Lesser General
+Public License permits more lax criteria for linking other code with
+the library.
+
+  We call this license the "Lesser" General Public License because it
+does Less to protect the user's freedom than the ordinary General
+Public License.  It also provides other free software developers Less
+of an advantage over competing non-free programs.  These disadvantages
+are the reason we use the ordinary General Public License for many
+libraries.  However, the Lesser license provides advantages in certain
+special circumstances.
+
+  For example, on rare occasions, there may be a special need to
+encourage the widest possible use of a certain library, so that it becomes
+a de-facto standard.  To achieve this, non-free programs must be
+allowed to use the library.  A more frequent case is that a free
+library does the same job as widely used non-free libraries.  In this
+case, there is little to gain by limiting the free library to free
+software only, so we use the Lesser General Public License.
+
+  In other cases, permission to use a particular library in non-free
+programs enables a greater number of people to use a large body of
+free software.  For example, permission to use the GNU C Library in
+non-free programs enables many more people to use the whole GNU
+operating system, as well as its variant, the GNU/Linux operating
+system.
+
+  Although the Lesser General Public License is Less protective of the
+users' freedom, it does ensure that the user of a program that is
+linked with the Library has the freedom and the wherewithal to run
+that program using a modified version of the Library.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.  Pay close attention to the difference between a
+"work based on the library" and a "work that uses the library".  The
+former contains code derived from the library, whereas the latter must
+be combined with the library in order to run.
+
+                  GNU LESSER GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License Agreement applies to any software library or other
+program which contains a notice placed by the copyright holder or
+other authorized party saying it may be distributed under the terms of
+this Lesser General Public License (also called "this License").
+Each licensee is addressed as "you".
+
+  A "library" means a collection of software functions and/or data
+prepared so as to be conveniently linked with application programs
+(which use some of those functions and data) to form executables.
+
+  The "Library", below, refers to any such software library or work
+which has been distributed under these terms.  A "work based on the
+Library" means either the Library or any derivative work under
+copyright law: that is to say, a work containing the Library or a
+portion of it, either verbatim or with modifications and/or translated
+straightforwardly into another language.  (Hereinafter, translation is
+included without limitation in the term "modification".)
+
+  "Source code" for a work means the preferred form of the work for
+making modifications to it.  For a library, complete source code means
+all the source code for all modules it contains, plus any associated
+interface definition files, plus the scripts used to control compilation
+and installation of the library.
+
+  Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running a program using the Library is not restricted, and output from
+such a program is covered only if its contents constitute a work based
+on the Library (independent of the use of the Library in a tool for
+writing it).  Whether that is true depends on what the Library does
+and what the program that uses the Library does.
+
+  1. You may copy and distribute verbatim copies of the Library's
+complete source code as you receive it, in any medium, provided that
+you conspicuously and appropriately publish on each copy an
+appropriate copyright notice and disclaimer of warranty; keep intact
+all the notices that refer to this License and to the absence of any
+warranty; and distribute a copy of this License along with the
+Library.
+
+  You may charge a fee for the physical act of transferring a copy,
+and you may at your option offer warranty protection in exchange for a
+fee.
+
+  2. You may modify your copy or copies of the Library or any portion
+of it, thus forming a work based on the Library, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) The modified work must itself be a software library.
+
+    b) You must cause the files modified to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    c) You must cause the whole of the work to be licensed at no
+    charge to all third parties under the terms of this License.
+
+    d) If a facility in the modified Library refers to a function or a
+    table of data to be supplied by an application program that uses
+    the facility, other than as an argument passed when the facility
+    is invoked, then you must make a good faith effort to ensure that,
+    in the event an application does not supply such function or
+    table, the facility still operates, and performs whatever part of
+    its purpose remains meaningful.
+
+    (For example, a function in a library to compute square roots has
+    a purpose that is entirely well-defined independent of the
+    application.  Therefore, Subsection 2d requires that any
+    application-supplied function or table used by this function must
+    be optional: if the application does not supply it, the square
+    root function must still compute square roots.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Library,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Library, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote
+it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Library.
+
+In addition, mere aggregation of another work not based on the Library
+with the Library (or with a work based on the Library) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may opt to apply the terms of the ordinary GNU General Public
+License instead of this License to a given copy of the Library.  To do
+this, you must alter all the notices that refer to this License, so
+that they refer to the ordinary GNU General Public License, version 2,
+instead of to this License.  (If a newer version than version 2 of the
+ordinary GNU General Public License has appeared, then you can specify
+that version instead if you wish.)  Do not make any other change in
+these notices.
+
+  Once this change is made in a given copy, it is irreversible for
+that copy, so the ordinary GNU General Public License applies to all
+subsequent copies and derivative works made from that copy.
+
+  This option is useful when you wish to copy part of the code of
+the Library into a program that is not a library.
+
+  4. You may copy and distribute the Library (or a portion or
+derivative of it, under Section 2) in object code or executable form
+under the terms of Sections 1 and 2 above provided that you accompany
+it with the complete corresponding machine-readable source code, which
+must be distributed under the terms of Sections 1 and 2 above on a
+medium customarily used for software interchange.
+
+  If distribution of object code is made by offering access to copy
+from a designated place, then offering equivalent access to copy the
+source code from the same place satisfies the requirement to
+distribute the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  5. A program that contains no derivative of any portion of the
+Library, but is designed to work with the Library by being compiled or
+linked with it, is called a "work that uses the Library".  Such a
+work, in isolation, is not a derivative work of the Library, and
+therefore falls outside the scope of this License.
+
+  However, linking a "work that uses the Library" with the Library
+creates an executable that is a derivative of the Library (because it
+contains portions of the Library), rather than a "work that uses the
+library".  The executable is therefore covered by this License.
+Section 6 states terms for distribution of such executables.
+
+  When a "work that uses the Library" uses material from a header file
+that is part of the Library, the object code for the work may be a
+derivative work of the Library even though the source code is not.
+Whether this is true is especially significant if the work can be
+linked without the Library, or if the work is itself a library.  The
+threshold for this to be true is not precisely defined by law.
+
+  If such an object file uses only numerical parameters, data
+structure layouts and accessors, and small macros and small inline
+functions (ten lines or less in length), then the use of the object
+file is unrestricted, regardless of whether it is legally a derivative
+work.  (Executables containing this object code plus portions of the
+Library will still fall under Section 6.)
+
+  Otherwise, if the work is a derivative of the Library, you may
+distribute the object code for the work under the terms of Section 6.
+Any executables containing that work also fall under Section 6,
+whether or not they are linked directly with the Library itself.
+
+  6. As an exception to the Sections above, you may also combine or
+link a "work that uses the Library" with the Library to produce a
+work containing portions of the Library, and distribute that work
+under terms of your choice, provided that the terms permit
+modification of the work for the customer's own use and reverse
+engineering for debugging such modifications.
+
+  You must give prominent notice with each copy of the work that the
+Library is used in it and that the Library and its use are covered by
+this License.  You must supply a copy of this License.  If the work
+during execution displays copyright notices, you must include the
+copyright notice for the Library among them, as well as a reference
+directing the user to the copy of this License.  Also, you must do one
+of these things:
+
+    a) Accompany the work with the complete corresponding
+    machine-readable source code for the Library including whatever
+    changes were used in the work (which must be distributed under
+    Sections 1 and 2 above); and, if the work is an executable linked
+    with the Library, with the complete machine-readable "work that
+    uses the Library", as object code and/or source code, so that the
+    user can modify the Library and then relink to produce a modified
+    executable containing the modified Library.  (It is understood
+    that the user who changes the contents of definitions files in the
+    Library will not necessarily be able to recompile the application
+    to use the modified definitions.)
+
+    b) Use a suitable shared library mechanism for linking with the
+    Library.  A suitable mechanism is one that (1) uses at run time a
+    copy of the library already present on the user's computer system,
+    rather than copying library functions into the executable, and (2)
+    will operate properly with a modified version of the library, if
+    the user installs one, as long as the modified version is
+    interface-compatible with the version that the work was made with.
+
+    c) Accompany the work with a written offer, valid for at
+    least three years, to give the same user the materials
+    specified in Subsection 6a, above, for a charge no more
+    than the cost of performing this distribution.
+
+    d) If distribution of the work is made by offering access to copy
+    from a designated place, offer equivalent access to copy the above
+    specified materials from the same place.
+
+    e) Verify that the user has already received a copy of these
+    materials or that you have already sent this user a copy.
+
+  For an executable, the required form of the "work that uses the
+Library" must include any data and utility programs needed for
+reproducing the executable from it.  However, as a special exception,
+the materials to be distributed need not include anything that is
+normally distributed (in either source or binary form) with the major
+components (compiler, kernel, and so on) of the operating system on
+which the executable runs, unless that component itself accompanies
+the executable.
+
+  It may happen that this requirement contradicts the license
+restrictions of other proprietary libraries that do not normally
+accompany the operating system.  Such a contradiction means you cannot
+use both them and the Library together in an executable that you
+distribute.
+
+  7. You may place library facilities that are a work based on the
+Library side-by-side in a single library together with other library
+facilities not covered by this License, and distribute such a combined
+library, provided that the separate distribution of the work based on
+the Library and of the other library facilities is otherwise
+permitted, and provided that you do these two things:
+
+    a) Accompany the combined library with a copy of the same work
+    based on the Library, uncombined with any other library
+    facilities.  This must be distributed under the terms of the
+    Sections above.
+
+    b) Give prominent notice with the combined library of the fact
+    that part of it is a work based on the Library, and explaining
+    where to find the accompanying uncombined form of the same work.
+
+  8. You may not copy, modify, sublicense, link with, or distribute
+the Library except as expressly provided under this License.  Any
+attempt otherwise to copy, modify, sublicense, link with, or
+distribute the Library is void, and will automatically terminate your
+rights under this License.  However, parties who have received copies,
+or rights, from you under this License will not have their licenses
+terminated so long as such parties remain in full compliance.
+
+  9. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Library or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Library (or any work based on the
+Library), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Library or works based on it.
+
+  10. Each time you redistribute the Library (or any work based on the
+Library), the recipient automatically receives a license from the
+original licensor to copy, distribute, link with or modify the Library
+subject to these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties with
+this License.
+
+  11. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Library at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Library by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Library.
+
+If any portion of this section is held invalid or unenforceable under any
+particular circumstance, the balance of the section is intended to apply,
+and the section as a whole is intended to apply in other circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  12. If the distribution and/or use of the Library is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Library under this License may add
+an explicit geographical distribution limitation excluding those countries,
+so that distribution is permitted only in or among countries not thus
+excluded.  In such case, this License incorporates the limitation as if
+written in the body of this License.
+
+  13. The Free Software Foundation may publish revised and/or new
+versions of the Lesser General Public License from time to time.
+Such new versions will be similar in spirit to the present version,
+but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Library
+specifies a version number of this License which applies to it and
+"any later version", you have the option of following the terms and
+conditions either of that version or of any later version published by
+the Free Software Foundation.  If the Library does not specify a
+license version number, you may choose any version ever published by
+the Free Software Foundation.
+
+  14. If you wish to incorporate parts of the Library into other free
+programs whose distribution conditions are incompatible with these,
+write to the author to ask for permission.  For software which is
+copyrighted by the Free Software Foundation, write to the Free
+Software Foundation; we sometimes make exceptions for this.  Our
+decision will be guided by the two goals of preserving the free status
+of all derivatives of our free software and of promoting the sharing
+and reuse of software generally.
+
+                            NO WARRANTY
+
+  15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
+WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
+OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
+KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
+LIBRARY IS WITH YOU.  SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
+THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
+AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
+FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+           How to Apply These Terms to Your New Libraries
+
+  If you develop a new library, and you want it to be of the greatest
+possible use to the public, we recommend making it free software that
+everyone can redistribute and change.  You can do so by permitting
+redistribution under these terms (or, alternatively, under the terms of the
+ordinary General Public License).
+
+  To apply these terms, attach the following notices to the library.  It is
+safest to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the library's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+Also add information on how to contact you by electronic and paper mail.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the library, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the
+  library `Frob' (a library for tweaking knobs) written by James Random Hacker.
+
+  <signature of Ty Coon>, 1 April 1990
+  Ty Coon, President of Vice
+
+That's all there is to it!
diff --git a/website/public/third-party/Inter-OFL-1.1.txt b/website/public/third-party/Inter-OFL-1.1.txt
new file mode 100644
index 00000000..9b2ca37b
--- /dev/null
+++ b/website/public/third-party/Inter-OFL-1.1.txt
@@ -0,0 +1,92 @@
+Copyright (c) 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/website/public/third-party/README.txt b/website/public/third-party/README.txt
new file mode 100644
index 00000000..92199c03
--- /dev/null
+++ b/website/public/third-party/README.txt
@@ -0,0 +1,113 @@
+TGDrive bundled viewer notices
+==============================
+
+These files accompany browser assets built from the exact versions in
+website/package-lock.json. Vite copies this directory unchanged into dist;
+Docker copies that dist directory into its runtime image.
+
+Movi Player 0.4.1
+-----------------
+Package: https://www.npmjs.com/package/movi-player/v/0.4.1
+Source: https://github.com/MrUjjwalG/movi-player/tree/v0.4.1
+Published npm git revision: eaaa3088aba65454176a180ece2a2ef2af513fa3
+Source archive:
+https://github.com/MrUjjwalG/movi-player/archive/eaaa3088aba65454176a180ece2a2ef2af513fa3.tar.gz
+WASM build recipe:
+https://github.com/MrUjjwalG/movi-player/blob/eaaa3088aba65454176a180ece2a2ef2af513fa3/docker/build-ffmpeg.sh
+Build environment:
+https://github.com/MrUjjwalG/movi-player/blob/eaaa3088aba65454176a180ece2a2ef2af513fa3/docker/Dockerfile
+
+movi-player-LICENSE.txt is copied unchanged from the published npm package.
+It contains the Apache-2.0 player license and bundled component notices,
+including FFmpeg LGPL-2.1-or-later, dav1d BSD-2-Clause, and Signalsmith MIT.
+FFmpeg-LGPL-2.1.txt supplies the full LGPL-2.1 text from upstream FFmpeg.
+Preserve these notices when redistributing the emitted JS and WASM assets.
+
+TGDrive ships its reviewed modified JavaScript in a local pinned npm archive
+under website/vendor. The original license and WASM remain unchanged. See
+movi-player-TGDrive-patch-NOTICE.txt, website/vendor/manifest.json and
+website/scripts/patch-movi-player.js for the changes and upstream identity.
+Normal development/build/test commands do not mutate the installed package.
+
+Source and relinking archive (served from the same TGDrive origin):
+/third-party/movi-player-0.4.1-sources.tar.gz
+
+The archive supplies complete FFmpeg n9.0.2 and dav1d 1.5.3 source tarballs,
+pinned Movi application/build/Signalsmith sources, published WASM-target static
+libraries and headers, licenses, SHA-256 manifests and rebuild/relink steps.
+
+The original notice labels FFmpeg n8.1.2; the published Dockerfile selects
+n9.0.2. The installed package headers/static-library metadata and delivered
+WASM identify libavcodec 63.1.102, agreeing with the n9.0.2 recipe rather than
+n8.1.2's 62.28.102. The WASM identifies dav1d 1.5.3-0-gb546257. This is provenance
+evidence, not an independent byte-identical rebuild. The exact FFmpeg patch
+source selection is inferred from the published build recipe. Preserve the
+unchanged original notice alongside this clarification and source materials.
+
+PDF.js 6.4.299
+-------------
+Package: https://www.npmjs.com/package/pdfjs-dist/v/6.4.299
+Source: https://github.com/mozilla/pdf.js
+Source tag: https://github.com/mozilla/pdf.js/tree/v6.4.299
+pdfjs-LICENSE.txt is copied unchanged from the installed pdfjs-dist package.
+The bundled PDF.js JS and worker use Apache-2.0. The reviewed modified worker
+is installed from the local pinned package archive in website/vendor; see
+pdfjs-TGDrive-patch-NOTICE.txt. CMaps, ICC profiles, standard fonts and decoder
+WASM are served locally under /static/pdfjs/<upstream-version>/ with their
+original resource-directory notices. No external viewer asset CDN is required.
+
+Inter Variable 4.1
+------------------
+Project: https://rsms.me/inter/
+Font source: https://rsms.me/inter/font-files/InterVariable.woff2
+License: https://raw.githubusercontent.com/rsms/inter/v4.1/LICENSE.txt
+Local asset: /static/fonts/InterVariable.woff2
+Font bytes: 352240
+SHA-256: 693b77d4f32ee9b8bfc995589b5fad5e99adf2832738661f5402f9978429a8e3
+License bytes: 4380
+License SHA-256: 262481e844521b326f5ecd053e59b98c8b2da78c8ee1bdbb6e8174305e54935a
+
+The regular variable WOFF2 is bundled unchanged under SIL OFL 1.1.
+Inter-OFL-1.1.txt preserves the copyright notice and complete license.
+Runtime font requests stay on this TGDrive origin; no font CDN is contacted.
+
+React, React DOM and Scheduler
+------------------------------
+React 19.3.1, React DOM 19.3.1 and Scheduler 0.28.0 are bundled under MIT.
+Source project: https://github.com/facebook/react
+Published packages: https://www.npmjs.com/package/react/v/19.3.1
+https://www.npmjs.com/package/react-dom/v/19.3.1
+https://www.npmjs.com/package/scheduler/v/0.28.0
+
+Lucide React 1.58.0
+-------------------
+Package: https://www.npmjs.com/package/lucide-react/v/1.58.0
+Source: https://github.com/lucide-icons/lucide
+Its complete notice includes ISC and the MIT notice for Feather-derived icons.
+
+The following license files are copied byte-for-byte from these installed
+locked packages. Preserve their copyright and permission notices with the
+redistributed browser bundle; minification does not embed those full texts.
+
+react-LICENSE.txt (react 19.3.1)
+SHA-256: da6d3703ed11cbe42bd212c725957c98da23cbff1998c05fa4b3d976d1a58e93
+react-dom-LICENSE.txt (react-dom 19.3.1)
+SHA-256: da6d3703ed11cbe42bd212c725957c98da23cbff1998c05fa4b3d976d1a58e93
+scheduler-LICENSE.txt (scheduler 0.28.0)
+SHA-256: da6d3703ed11cbe42bd212c725957c98da23cbff1998c05fa4b3d976d1a58e93
+lucide-react-LICENSE.txt (lucide-react 1.58.0)
+SHA-256: b495047bd93a9b06913511076f504daba17d5bbeb3e0650f3bb53a4220329c57
+
+Mantine UI component foundation
+-------------------------------
+@mantine/core and @mantine/hooks are pinned together at 9.7.3.
+https://mantine.dev/ and https://github.com/mantinedev/mantine
+ui-components-LICENSES.txt preserves the library and new dependency license texts,
+including the upstream notice for react-remove-scroll-bar whose npm package omits it.
+Preserve this file with emitted assets.
+
+Primer Octicons GitHub mark
+--------------------------
+The GitHub repository link uses mark-github-16 from Primer Octicons.
+Source: https://github.com/primer/octicons/blob/main/icons/mark-github-16.svg
+License: MIT, GitHub Inc. The complete notice is in octicons-MIT.txt.
diff --git a/website/public/third-party/lucide-react-LICENSE.txt b/website/public/third-party/lucide-react-LICENSE.txt
new file mode 100644
index 00000000..718bb3f0
--- /dev/null
+++ b/website/public/third-party/lucide-react-LICENSE.txt
@@ -0,0 +1,43 @@
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/website/public/third-party/movi-player-0.4.1-sources.tar.gz b/website/public/third-party/movi-player-0.4.1-sources.tar.gz
new file mode 100644
index 00000000..12c9a8d7
Binary files /dev/null and b/website/public/third-party/movi-player-0.4.1-sources.tar.gz differ
diff --git a/website/public/third-party/movi-player-LICENSE.txt b/website/public/third-party/movi-player-LICENSE.txt
new file mode 100644
index 00000000..9418c915
--- /dev/null
+++ b/website/public/third-party/movi-player-LICENSE.txt
@@ -0,0 +1,392 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright 2026 Ujjawal Kashyap
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+================================================================================
+
+THIRD-PARTY LICENSES
+
+================================================================================
+
+Signalsmith Stretch
+-------------------
+
+Location: wasm/signalsmith/signalsmith-stretch/ and wasm/signalsmith/
+signalsmith-linear/ (compiled to WebAssembly and statically linked into the
+movi WASM module; used for pitch-preserving time-stretching)
+
+Copyright (c) 2022 Geraint Luff / Signalsmith Audio Ltd. (signalsmith-stretch)
+Copyright (c) 2025 Signalsmith Audio (signalsmith-linear)
+
+Licensed under the MIT License.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Project: https://signalsmith-audio.co.uk/code/stretch/
+
+FFmpeg
+------
+
+Location: dist/wasm/ (compiled to WebAssembly and statically linked into the
+movi WASM module; build recipe in docker/build-ffmpeg.sh and docker/Dockerfile)
+
+Copyright (c) the FFmpeg developers
+
+Version: n8.1.2 (https://github.com/FFmpeg/FFmpeg)
+
+Licensed under the GNU Lesser General Public License, Version 2.1 or later.
+
+This project builds FFmpeg as an LGPL library: the FFmpeg configure step
+enables NEITHER --enable-gpl NOR --enable-nonfree, so no GPL-licensed or
+non-free components are included. The libavcodec, libavformat, libavutil,
+libswresample and libswscale libraries are used unmodified from upstream.
+
+FFmpeg is free software; you can redistribute it and/or modify it under the
+terms of the GNU Lesser General Public License as published by the Free
+Software Foundation; either version 2.1 of the License, or (at your option)
+any later version. It is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
+for more details.
+
+The complete corresponding FFmpeg source is available at the URL above, and
+the exact configuration and build steps used to produce the bundled binary
+are in this repository (docker/build-ffmpeg.sh, docker/Dockerfile). Because
+those build scripts allow the FFmpeg component to be rebuilt and re-linked
+from source, the relinking requirement of the LGPL is satisfied.
+
+Full LGPL 2.1 License: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
+FFmpeg Legal / Licensing: https://ffmpeg.org/legal.html
+
+dav1d
+-----
+
+Location: bundled into the FFmpeg WASM build via --enable-libdav1d (used as the
+AV1 decoder; build recipe in docker/Dockerfile)
+
+Copyright (c) 2018-2024, VideoLAN and dav1d authors
+All rights reserved.
+
+Version: 1.5.3 (https://code.videolan.org/videolan/dav1d)
+
+Licensed under the BSD 2-Clause License.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+zlib
+----
+
+Location: bundled into the FFmpeg WASM build via --enable-zlib / USE_ZLIB
+
+Copyright (c) 1995-2024 Jean-loup Gailly and Mark Adler
+
+Licensed under the zlib License.
+
+This software is provided 'as-is', without any express or implied warranty. In
+no event will the authors be held liable for any damages arising from the use
+of this software. Permission is granted to anyone to use this software for any
+purpose, including commercial applications, and to alter it and redistribute it
+freely, subject to the restrictions stated in the zlib license.
+
+Full zlib License: https://zlib.net/zlib_license.html
+
+hls.js
+------
+
+Location: bundled into the standalone build (used unmodified as the Tier-2 HLS
+stream engine; imported in src/render/HLSPlayerWrapper.ts)
+
+Copyright (c) 2017 Dailymotion (http://www.dailymotion.com)
+
+Licensed under the Apache License, Version 2.0. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE-2.0 (the same license text
+this project is distributed under, reproduced at the top of this file).
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+Project: https://github.com/video-dev/hls.js
+
+dash.js
+-------
+
+Location: bundled into the standalone build (used unmodified as the Tier-2 DASH
+stream engine; imported in src/render/DASHPlayerWrapper.ts)
+
+Copyright (c) 2015, Dash Industry Forum. All rights reserved.
+
+Licensed under the BSD 3-Clause License.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+* Neither the name of the Dash Industry Forum nor the names of its contributors
+  may be used to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Project: https://github.com/Dash-Industry-Forum/dash.js
+
+Shaka Player
+------------
+
+Location: bundled into the standalone build (used unmodified as the Tier-1
+HLS/DASH stream engine; imported in src/render/ShakaPlayerWrapper.ts)
+
+Copyright 2016 Google LLC
+
+Licensed under the Apache License, Version 2.0. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE-2.0 (the same license text
+this project is distributed under, reproduced at the top of this file).
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+Project: https://github.com/shaka-project/shaka-player
diff --git a/website/public/third-party/movi-player-TGDrive-patch-NOTICE.txt b/website/public/third-party/movi-player-TGDrive-patch-NOTICE.txt
new file mode 100644
index 00000000..2a0981bf
--- /dev/null
+++ b/website/public/third-party/movi-player-TGDrive-patch-NOTICE.txt
@@ -0,0 +1,51 @@
+TGDrive modifications to Movi Player 0.4.1, 26 October 2026
+
+Movi Player is Copyright Ujjawal Kashyap and its contributors, licensed under
+Apache License 2.0. The original license is distributed alongside this notice
+as movi-player-LICENSE.txt. Upstream: https://github.com/mrujjwalg/movi-player
+
+TGDrive modifies the slim JavaScript bundle's seek-completion condition to use
+the existing coordinated audio/video buffering path when playable audio is
+still priming. This prevents high-latency audio outputs from starting silent
+video and then moving the media clock backward when audio arrives. Deliberately
+dropped audio, absent/disabled audio and media after the audio tail retain the
+upstream behavior.
+
+The exact version and original bundle SHA256 are checked by
+website/scripts/patch-movi-player.js. The reviewed modified package is shipped in
+website/vendor and installed from that local archive. Normal development and
+builds do not rewrite dependencies.
+scripts/vendor_viewers.py verifies upstream package integrity and applies the
+reviewed recipe only during deliberate vendor regeneration.
+
+TGDrive additionally requires an active audio track before the shared-demux
+audio read-ahead branch can bypass video decoder backpressure (2026-10-23).
+Video-only previews retain the custom demux/decoder/canvas pipeline.
+
+TGDrive applies the configured HTTP cache budget before load and uses a bounded
+window up to that budget, instead of resizing populated buffers after load or
+selecting only 8% of medium-sized sources (2026-10-23).
+
+TGDrive separates compressed network read-ahead from decoded frame admission,
+targets 90 seconds within the configured byte cap, refills below 75% of that
+goal, and scales range requests to the goal. At EOF, hardware decoders drain
+pending output instead of taking the HEVC seek-recreation path (2026-10-23).
+
+The compressed source window grows toward its time goal within a device-derived
+memory ceiling. Growth preserves retained data and stream state; background
+writers refresh storage after awaited reads. Allocation failure retains the
+existing window and caps subsequent growth for the opening (2026-10-23).
+
+The read-ahead gate counts bytes only within the current source window. Distant
+seeks do not count the skipped file gap as already buffered, allowing the first
+range at the new position to arrive before the demuxer advances (2026-10-23).
+
+The decoder EOF drain is bounded and ignores obsolete decoder generations.
+In-flight demuxer reads can receive their required byte range without being
+blocked by the speculative read-ahead target. Native chapter navigation uses
+chapter titles and times without extracting frames unless thumbnails or a
+storyboard are explicitly enabled (2026-10-26).
+
+Disconnecting the native element revokes picked subtitle Blob URLs and clears
+their ownership list, including when source reset and disconnect both run
+(2026-10-26).
diff --git a/website/public/third-party/octicons-MIT.txt b/website/public/third-party/octicons-MIT.txt
new file mode 100644
index 00000000..aa1fa80e
--- /dev/null
+++ b/website/public/third-party/octicons-MIT.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GitHub Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/website/public/third-party/pdfjs-LICENSE.txt b/website/public/third-party/pdfjs-LICENSE.txt
new file mode 100644
index 00000000..f433b1a5
--- /dev/null
+++ b/website/public/third-party/pdfjs-LICENSE.txt
@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
diff --git a/website/public/third-party/pdfjs-TGDrive-patch-NOTICE.txt b/website/public/third-party/pdfjs-TGDrive-patch-NOTICE.txt
new file mode 100644
index 00000000..53b45537
--- /dev/null
+++ b/website/public/third-party/pdfjs-TGDrive-patch-NOTICE.txt
@@ -0,0 +1,16 @@
+TGDrive modifications to PDF.js 6.4.299, 26 October 2026
+
+PDF.js is Copyright Mozilla Foundation and contributors, licensed under the
+Apache License 2.0. The unchanged license accompanies this notice in
+pdfjs-LICENSE.txt. Upstream: https://github.com/mozilla/pdf.js
+
+TGDrive modifies build/pdf.worker.mjs to defer shared PDF image streams until
+the corresponding image is painted. Required masks and color resources load
+before decoding, after image dimension and configured image-size rejection.
+This preserves selective range loading for PDFs with shared page resources.
+
+The reviewed modified package is shipped in website/vendor. The maintenance
+command scripts/vendor_viewers.py verifies the exact upstream archive and applies
+website/scripts/patch-pdf-worker.js. Normal builds do not rewrite dependencies.
+The original licenses and rendering-resource notices are retained. Local CMaps,
+standard fonts, ICC profiles and decoder WASM are served with their notices.
diff --git a/website/public/third-party/react-LICENSE.txt b/website/public/third-party/react-LICENSE.txt
new file mode 100644
index 00000000..b93be905
--- /dev/null
+++ b/website/public/third-party/react-LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/website/public/third-party/react-dom-LICENSE.txt b/website/public/third-party/react-dom-LICENSE.txt
new file mode 100644
index 00000000..b93be905
--- /dev/null
+++ b/website/public/third-party/react-dom-LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/website/public/third-party/scheduler-LICENSE.txt b/website/public/third-party/scheduler-LICENSE.txt
new file mode 100644
index 00000000..b93be905
--- /dev/null
+++ b/website/public/third-party/scheduler-LICENSE.txt
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/website/public/third-party/ui-components-LICENSES.txt b/website/public/third-party/ui-components-LICENSES.txt
new file mode 100644
index 00000000..4550ac22
--- /dev/null
+++ b/website/public/third-party/ui-components-LICENSES.txt
@@ -0,0 +1,573 @@
+@floating-ui/core 1.8.0
+================================================================
+MIT License
+
+Copyright (c) 2021-present Floating UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+@floating-ui/dom 1.8.0
+================================================================
+MIT License
+
+Copyright (c) 2021-present Floating UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+@floating-ui/react 0.27.20
+================================================================
+MIT License
+
+Copyright (c) 2021-present Floating UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+@floating-ui/react-dom 2.1.9
+================================================================
+MIT License
+
+Copyright (c) 2021-present Floating UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+@floating-ui/utils 0.2.12
+================================================================
+MIT License
+
+Copyright (c) 2021-present Floating UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+@mantine/core 9.7.3
+================================================================
+MIT License
+
+Copyright (c) 2021 Vitaly Rtishchev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+@mantine/hooks 9.7.3
+================================================================
+MIT License
+
+Copyright (c) 2021 Vitaly Rtishchev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+clsx 2.1.1
+================================================================
+MIT License
+
+Copyright (c) Luke Edwards <luke.edwards05@gmail.com> (lukeed.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+detect-node-es 1.1.0
+================================================================
+MIT License
+
+Copyright (c) 2017 Ilya Kantor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+get-nonce 1.0.1
+================================================================
+MIT License
+
+Copyright (c) 2020 Anton Korzunov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+react-number-format 5.4.5
+================================================================
+MIT License
+
+Copyright (c) 2020-present Sudhanshu Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+react-remove-scroll 2.7.2
+================================================================
+MIT License
+
+Copyright (c) 2017 Anton Korzunov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+react-remove-scroll-bar 2.3.8
+================================================================
+Published package declares MIT but omits a license file. Unchanged upstream license retrieved 2026-10-20:
+https://raw.githubusercontent.com/theKashey/react-remove-scroll-bar/master/LICENSE
+MIT License
+
+Copyright (c) 2025 Anton Korzunov <thekashey@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+react-style-singleton 2.2.3
+================================================================
+MIT License
+
+Copyright (c) 2017 Anton Korzunov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+tabbable 6.5.0
+================================================================
+The MIT License (MIT)
+
+Copyright (c) 2015 David Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+
+tagged-tag 1.0.0
+================================================================
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+tslib 2.8.1
+================================================================
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+
+type-fest 5.10.0
+================================================================
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.
+
+
+use-callback-ref 1.3.3
+================================================================
+MIT License
+
+Copyright (c) 2017 Anton Korzunov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+use-sidecar 1.1.3
+================================================================
+MIT License
+
+Copyright (c) 2017 Anton Korzunov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
diff --git a/website/scripts/check-movi-player.js b/website/scripts/check-movi-player.js
new file mode 100644
index 00000000..62001858
--- /dev/null
+++ b/website/scripts/check-movi-player.js
@@ -0,0 +1,697 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import {
+    patchMoviSource,
+    VERSION,
+    ORIGINAL_SHA256,
+    BEFORE,
+    AFTER,
+    NOTICE,
+    PATCHES,
+    VIDEO_ONLY_AFTER,
+    GATE_AFTER,
+    RESIZE_AFTER,
+    EOF_SETTLED_AFTER,
+    digest,
+} from "./patch-movi-player.js";
+
+const installed = await readFile(
+    process.env.TGDRIVE_MOVI_SOURCE ||
+        new URL(
+            "../node_modules/movi-player/dist/element.slim.js",
+            import.meta.url,
+        ),
+    "utf8",
+);
+let original = installed.startsWith(NOTICE)
+    ? installed.slice(NOTICE.length)
+    : installed;
+for (const [before, after] of PATCHES)
+    original = original.replace(after, before);
+
+test("the pinned bundle has exactly the reviewed source identity", () => {
+    assert.equal(digest(original), ORIGINAL_SHA256);
+    assert.equal(original.split(BEFORE).length, 2);
+});
+// Exercise the shipped policy, including its hysteresis, without downloading
+// megabytes or waiting through a long media fixture in every integrity check.
+const SourcePolicy = new Function(
+    `const EA=2097152; return class {
+    ${GATE_AFTER}
+  }`,
+)();
+function policy(rate, ceilingMiB = 128, duration = 600) {
+    const source = new SourcePolicy();
+    Object.assign(source, {
+        size: rate * duration,
+        maxBufferSizeMB: ceilingMiB,
+        bufferSize: Math.min(32, ceilingMiB) * 1024 ** 2,
+        position: 0,
+        bufferEnd: 0,
+        getPosition() {
+            return this.position;
+        },
+        atomicGetBufferStart() {
+            return this.windowStart || 0;
+        },
+        atomicIsStreaming() {
+            return true;
+        },
+        resizeBuffer(size) {
+            this.bufferSize = Math.min(size, ceilingMiB * 1024 ** 2);
+        },
+    });
+    source.setPlaybackBufferGoal(0, duration, rate * 8);
+    return source;
+}
+test("compressed read-ahead covers time across bitrates within a memory cap", () => {
+    for (const rate of [64_000, 512_000, 1_000_000]) {
+        const source = policy(rate);
+        assert.equal(source.playbackAheadBytes / rate, 90);
+    }
+    assert.equal(policy(10_000_000).playbackAheadBytes, 0.8 * 128 * 1024 ** 2);
+});
+test("higher device budgets accommodate 90 seconds of high bitrate video", () => {
+    const rate = 32_000_000 / 8;
+    const source = policy(rate, 512);
+    assert.equal(source.playbackAheadBytes / rate, 90);
+    assert.ok(source.bufferSize <= 512 * 1024 ** 2);
+    assert.ok(source.bufferSize >= source.playbackAheadBytes / 0.8);
+    assert.ok(policy(64_000, 512).bufferSize < source.bufferSize);
+});
+test("short clips fit completely without applying headroom to their whole size", () => {
+    const source = policy(1_875_000, 512, 24);
+    assert.equal(source.playbackAheadBytes, source.size);
+    assert.equal(source.bufferSize, source.size);
+});
+const atomicsStart = original.indexOf("  atomicGetWritePos() {");
+const atomicsEnd = original.indexOf(
+    "  _prefetchThrottled = false;",
+    atomicsStart,
+);
+const streamingStart = original.indexOf("  atomicIsStreaming() {");
+const streamingEnd = original.indexOf(
+    "  async resolveSize() {",
+    streamingStart,
+);
+function memorySource(shared, ArrayType = Uint8Array) {
+    const Source = new Function(
+        "crossOriginIsolated",
+        "Uint8Array",
+        `const EA=2097152; return class {
+      bufferWaiters = new Set();
+      ${RESIZE_AFTER}
+      ${original.slice(atomicsStart, atomicsEnd)}
+      ${original.slice(streamingStart, streamingEnd)}
+      getBuffer() { return this.useSharedBuffer ? this.dataView : this.fallbackBuffer; }
+    }`,
+    )(shared, ArrayType);
+    const source = new Source();
+    source.maxBufferSizeMB = 16;
+    source.resizeBuffer(2 * 1024 ** 2);
+    return source;
+}
+for (const shared of [false, true]) {
+    test(`source growth retains bytes, offsets and stream state (shared=${shared})`, () => {
+        const source = memorySource(shared);
+        const bytes = Uint8Array.from({ length: 300_000 }, (_, i) => i % 251);
+        source.getBuffer().set(bytes);
+        source.atomicSetBufferStart(1_000_000);
+        source.atomicSetWritePos(bytes.length);
+        source.atomicSetStreaming(true);
+        if (shared) Atomics.store(source.headerView, 5, 7);
+        source.resizeBuffer(8 * 1024 ** 2);
+        assert.equal(source.bufferSize, 8 * 1024 ** 2);
+        assert.deepEqual(source.getBuffer().slice(0, bytes.length), bytes);
+        assert.equal(source.atomicGetBufferStart(), 1_000_000);
+        assert.equal(source.atomicGetWritePos(), bytes.length);
+        assert.equal(source.atomicIsStreaming(), true);
+        if (shared) assert.equal(Atomics.load(source.headerView, 5), 7);
+        source.resizeBuffer(2 * 1024 ** 2);
+        assert.equal(source.bufferSize, 8 * 1024 ** 2);
+    });
+}
+test("failed allocation keeps the working buffer and lowers the growth ceiling", () => {
+    let refused = 0;
+    function LimitedArray(size) {
+        if (size > 4 * 1024 ** 2) {
+            refused++;
+            throw new RangeError("fixture limit");
+        }
+        return new Uint8Array(size);
+    }
+    const source = memorySource(false, LimitedArray);
+    const old = source.getBuffer();
+    old[0] = 71;
+    source.atomicSetWritePos(1);
+    source.resizeBuffer(8 * 1024 ** 2);
+    source.resizeBuffer(16 * 1024 ** 2);
+    assert.equal(source.getBuffer(), old);
+    assert.equal(old[0], 71);
+    assert.equal(refused, 1);
+    assert.equal(source.allocationLimitBytes, old.length);
+});
+test("network fetches continue with a full decoder queue and refill early", async () => {
+    const source = policy(512_000);
+    source.decoderQueue = 100;
+    source.bufferEnd = 512_000 * 5;
+    await source.awaitPrefetchGate();
+    assert.equal(source.playbackPrefetchHeld, false);
+    // Keep fetching when only a few seconds have been decoded; hold at the goal.
+    source.bufferEnd = source.playbackAheadBytes;
+    setTimeout(() => {
+        source.position = source.bufferEnd * 0.1;
+    }, 10);
+    setTimeout(() => {
+        source.position = source.bufferEnd * 0.3;
+    }, 160);
+    const started = Date.now();
+    await source.awaitPrefetchGate();
+    assert.ok(Date.now() - started >= 150);
+    assert.equal(source.playbackPrefetchHeld, false);
+});
+test("source closure releases a held read-ahead gate", async () => {
+    const source = policy(512_000);
+    source.bufferEnd = source.playbackAheadBytes;
+    setTimeout(() => {
+        source.closed = true;
+    }, 10);
+    await source.awaitPrefetchGate();
+    assert.equal(source.closed, true);
+});
+test("variable bitrate observations increase the time buffer without following seeks", () => {
+    const source = policy(100_000);
+    source.position = 500_000;
+    source.setPlaybackBufferGoal(1, 600, 800_000);
+    assert.equal(source.playbackAheadBytes, 45_000_000);
+    source.position = 59_000_000;
+    source.setPlaybackBufferGoal(2, 600, 800_000, true);
+    assert.equal(source.playbackRateSample, null);
+    source.setPlaybackBufferGoal(400, 600, 800_000);
+    assert.equal(source.playbackAheadBytes, 45_000_000);
+});
+test("EOF drains queued hardware frames without recreating the HEVC decoder", async () => {
+    const patched = patchMoviSource(original, VERSION);
+    const start = patched.indexOf("  async flush(drain = false) {");
+    const method = patched.slice(
+        start,
+        patched.indexOf("\n  reset() {", start),
+    );
+    const decoder = new Function(`return ({${method}})`)();
+    let drains = 0;
+    Object.assign(decoder, {
+        decoder: {
+            async flush() {
+                drains++;
+            },
+        },
+        _drainGeneration: 0,
+        lastConfig: { codec: "hvc1.1.6.L150.b0" },
+        pendingChunks: [1, 2],
+        softRecreateDecoder() {
+            throw Error("EOF must not recreate the decoder");
+        },
+        setWaitingForKeyframe() {
+            throw Error("EOF must not discard pending state");
+        },
+    });
+    await decoder.flush(true);
+    assert.equal(drains, 1);
+    assert.deepEqual(decoder.pendingChunks, [1, 2]);
+});
+test("the portable patch is deterministic and idempotent", () => {
+    const patched = patchMoviSource(original, VERSION);
+    assert.ok(patched.startsWith(NOTICE));
+    assert.equal(patched.split(AFTER).length, 2);
+    assert.equal(patched.split(VIDEO_ONLY_AFTER).length, 2);
+    assert.equal(patchMoviSource(patched, VERSION), patched);
+});
+test("unknown versions and tampered original/patched bundles fail clearly", () => {
+    assert.throws(
+        () => patchMoviSource(original, "0.4.2"),
+        /Review the upstream fix/,
+    );
+    assert.throws(
+        () => patchMoviSource(original + " ", VERSION),
+        /does not match/,
+    );
+    assert.throws(
+        () =>
+            patchMoviSource(patchMoviSource(original, VERSION) + " ", VERSION),
+        /was modified/,
+    );
+});
+
+test(
+    "distant forward and backward seeks do not count the skipped file gap as buffered",
+    { timeout: 1000 },
+    async () => {
+        for (const offset of [3 * 1024 ** 3, 5 * 1024 ** 3]) {
+            const source = policy(8_000_000, 512, 734);
+            source.position = 67 * 1024 ** 2;
+            source.windowStart = offset;
+            source.bufferEnd = offset;
+            source.playbackPrefetchHeld = true;
+            await source.awaitPrefetchGate();
+            assert.equal(source.playbackPrefetchHeld, false);
+            source.position = offset + 1_000_000;
+            source.windowStart = 0;
+            source.bufferEnd = 0;
+            await source.awaitPrefetchGate();
+            assert.equal(source.playbackPrefetchHeld, false);
+        }
+    },
+);
+
+const patched = patchMoviSource(original, VERSION);
+
+test("picked subtitle URLs are revoked once across disconnect and source reset", () => {
+    const disconnectStart = patched.indexOf("  disconnectedCallback() {");
+    const disconnectEnd = patched.indexOf(
+        "\n  attributeChangedCallback(",
+        disconnectStart,
+    );
+    const disposeStart = patched.indexOf("  dispose() {", disconnectEnd);
+    const disposeEnd = patched.indexOf("\n  get theme() {", disposeStart);
+    assert.ok(disconnectStart >= 0 && disconnectEnd > disconnectStart);
+    assert.ok(disposeStart >= 0 && disposeEnd > disposeStart);
+
+    for (const urls of [[], ["blob:first-subtitle", "blob:second-subtitle"]]) {
+        for (const steps of [
+            ["disconnectedCallback", "dispose", "disconnectedCallback"],
+            ["dispose", "disconnectedCallback", "dispose"],
+        ]) {
+            const revoked = [];
+            const tornDown = [];
+            const Lifecycle = new Function(
+                "URL",
+                "document",
+                "window",
+                "navigator",
+                `return class {
+                    ${patched.slice(disconnectStart, disconnectEnd)}
+                    ${patched.slice(disposeStart, disposeEnd)}
+                };`,
+            )(
+                { revokeObjectURL: (url) => revoked.push(url) },
+                { removeEventListener() {} },
+                { removeEventListener() {} },
+                {},
+            );
+            const element = new Lifecycle();
+            const noop = () => {};
+            Object.assign(element, {
+                _pickedSubtitleUrls: [...urls],
+                _sourceAbort: { abort: noop },
+                _roundingTimers: new Set(),
+                _spinnerDelayTimer: null,
+                _captionClickTimer: null,
+                _nativeAudioCheckTimer: null,
+                _engineTried: new Set(),
+                eventHandlers: new Set([() => tornDown.push("event-handlers")]),
+                canvas: { removeEventListener: noop },
+                classList: { remove: noop },
+                player: { destroy: () => tornDown.push("player") },
+                _subtitleRenderer: {
+                    destroy: () => tornDown.push("subtitle-renderer"),
+                },
+            });
+            for (const method of [
+                "abortSourceRequests",
+                "cancelAutoAdvance",
+                "closeAllBottomMenus",
+                "closeSettingsPage",
+                "resetStutterHint",
+                "resetTimeline",
+                "setPipUiTimer",
+                "stopAmbientColorSampling",
+                "stopQoeHeartbeat",
+                "stopResumeSaving",
+                "stopStutterMonitor",
+                "syncThumbnailRotation",
+                "updateControlsState",
+                "updatePlayPauseIcon",
+                "updateProgressBar",
+            ])
+                element[method] = noop;
+
+            for (const step of steps) {
+                element[step]();
+                assert.deepEqual(element._pickedSubtitleUrls, []);
+                assert.deepEqual(revoked, urls);
+            }
+            assert.equal(element.player, null);
+            assert.equal(element._subtitleRenderer, null);
+            assert.deepEqual(tornDown.toSorted(), [
+                "event-handlers",
+                "player",
+                "subtitle-renderer",
+            ]);
+        }
+    }
+});
+
+function httpSourceForTest() {
+    const start = patched.indexOf("class HttpSource {");
+    const end = patched.indexOf("\nasync function eA(", start);
+    assert.ok(start >= 0 && end > start);
+    return new Function(
+        "fetch",
+        `const crossOriginIsolated = false;
+     const QA="HttpSource", EA=2097152, iA=262144000, tA=131072;
+     const g = {debug(){}, info(){}, warn(){}, error(){}};
+     ${patched.slice(start, end)}
+     return HttpSource;`,
+    )(async (_url, options) => {
+        const range = /^bytes=(\d+)-(\d+)$/.exec(options.headers.Range);
+        assert.ok(range, "the source must retain bounded range requests");
+        return new Response(
+            new Uint8Array(Number(range[2]) - Number(range[1]) + 1).fill(91),
+            {
+                status: 206,
+            },
+        );
+    });
+}
+
+test(
+    "a demux read larger than the time goal completes through the real range reader",
+    {
+        timeout: 1500,
+    },
+    async () => {
+        const Source = httpSourceForTest();
+        const source = new Source("https://fixture.invalid/video", {}, 128);
+        source.size = 50 * 1024 ** 2;
+        source.resizeBuffer(32 * 1024 ** 2);
+        source.setPlaybackBufferGoal(0, 3600);
+        assert.equal(source.playbackAheadBytes, 2 * 1024 ** 2);
+        let timer;
+        try {
+            const bytes = await Promise.race([
+                source.read(0, 3 * 1024 ** 2),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(
+                        () =>
+                            reject(
+                                new Error(
+                                    "demux read stayed behind its own gate",
+                                ),
+                            ),
+                        750,
+                    );
+                }),
+            ]);
+            assert.equal(bytes.byteLength, 3 * 1024 ** 2);
+            assert.equal(new Uint8Array(bytes).at(-1), 91);
+            assert.equal(source.pendingReadEnds.size, 0);
+        } finally {
+            clearTimeout(timer);
+            source.close();
+        }
+    },
+);
+
+test("pending read demands are removed after failure and belong to their stream generation", async () => {
+    const Source = httpSourceForTest();
+    const source = new Source("https://fixture.invalid/video", {}, 128);
+    const failure = new Error("fixture reader failed");
+    source.streamGeneration = 7;
+    source.waitForDataUnchecked = async () => {
+        assert.deepEqual(
+            [...source.pendingReadEnds],
+            [{ end: 300, generation: 7 }],
+        );
+        throw failure;
+    };
+    await assert.rejects(source.waitForData(100, 200), failure);
+    assert.equal(source.pendingReadEnds.size, 0);
+    source.close();
+
+    const held = policy(512_000);
+    held.streamGeneration = 2;
+    held.pendingReadEnds = new Set([{ end: 1e9, generation: 1 }]);
+    held.bufferEnd = held.playbackAheadBytes;
+    setTimeout(() => {
+        held.closed = true;
+    }, 10);
+    await held.awaitPrefetchGate();
+    assert.equal(
+        held.closed,
+        true,
+        "a superseded read must not open the current gate",
+    );
+});
+
+function drainHarness(flush) {
+    const start = patched.indexOf("  async flush(drain = false) {");
+    const end = patched.indexOf("\n  get configuredCodec() {", start);
+    const timers = new Map();
+    let nextTimer = 0;
+    const Decoder = new Function(
+        "setTimeout",
+        "clearTimeout",
+        "g",
+        "YA",
+        `
+    return class {
+      _drainGeneration = 0;
+      ${patched.slice(start, end)}
+    };
+  `,
+    )(
+        (callback, delay) => {
+            const id = ++nextTimer;
+            timers.set(id, { callback, delay });
+            return id;
+        },
+        (id) => timers.delete(id),
+        { warn() {}, error() {} },
+        "fixture decoder",
+    );
+    const wrapper = new Decoder();
+    const calls = { resets: 0, configurations: 0 };
+    Object.assign(wrapper, {
+        decoder: {
+            decodeQueueSize: 20,
+            flush,
+            reset() {
+                calls.resets++;
+            },
+            configure() {
+                calls.configurations++;
+            },
+        },
+        lastConfig: { codec: "hvc1.fixture" },
+        pendingChunks: [1, 2],
+        pendingFrames: [],
+    });
+    return {
+        wrapper,
+        calls,
+        timers,
+        expire() {
+            assert.equal(timers.size, 1);
+            const timer = [...timers.values()][0];
+            assert.equal(timer.delay, 1200);
+            timer.callback();
+        },
+    };
+}
+
+test("EOF hardware drains settle on decoder failure or timeout and clear their timers", async () => {
+    for (const behavior of ["resolve", "reject", "stall"]) {
+        const failure = new Error("decoder refused drain");
+        const fixture = drainHarness(() =>
+            behavior === "stall"
+                ? new Promise(() => {})
+                : behavior === "reject"
+                  ? Promise.reject(failure)
+                  : Promise.resolve(),
+        );
+        const draining = fixture.wrapper.flush(true);
+        if (behavior === "stall") fixture.expire();
+        if (behavior === "resolve") {
+            await draining;
+            assert.equal(fixture.calls.resets, 0);
+        } else {
+            await assert.rejects(
+                draining,
+                behavior === "reject" ? failure : /EOF decoder drain timed out/,
+            );
+            assert.equal(fixture.calls.resets, 1);
+            assert.equal(fixture.calls.configurations, 1);
+        }
+        assert.equal(fixture.timers.size, 0);
+        assert.deepEqual(fixture.wrapper.pendingChunks, [1, 2]);
+    }
+});
+
+test("a stale EOF drain never resets a decoder owned by a newer reset or replacement", async () => {
+    for (const action of ["reset", "replace"]) {
+        const fixture = drainHarness(() => new Promise(() => {}));
+        const draining = fixture.wrapper.flush(true);
+        if (action === "reset") fixture.wrapper.reset();
+        else
+            fixture.wrapper.decoder = {
+                reset() {
+                    throw new Error("new decoder must not be reset");
+                },
+                configure() {
+                    throw new Error("new decoder must not be reconfigured");
+                },
+            };
+        const resets = fixture.calls.resets;
+        fixture.expire();
+        await assert.rejects(draining, /EOF decoder drain timed out/);
+        assert.equal(fixture.calls.resets, resets);
+        assert.equal(fixture.calls.configurations, 0);
+        assert.equal(fixture.timers.size, 0);
+    }
+});
+
+test("a stale EOF completion cannot replace the current loop-preroll sequence", () => {
+    const settle = new Function("A4", EOF_SETTLED_AFTER);
+    const player = { _eofFlushSeq: 4, _eofFlushSettledSeq: 4 };
+    settle.call(player, 3);
+    assert.equal(player._eofFlushSettledSeq, 4);
+    player._eofFlushSettledSeq = 2;
+    settle.call(player, 4);
+    assert.equal(player._eofFlushSettledSeq, 4);
+});
+
+function timelineFixture(chapters, options = {}) {
+    function element(tag = "div") {
+        const classes = new Set();
+        return {
+            tag,
+            children: [],
+            style: {},
+            dataset: {},
+            events: {},
+            classList: {
+                add: (name) => classes.add(name),
+                remove: (name) => classes.delete(name),
+                contains: (name) => classes.has(name),
+            },
+            appendChild(child) {
+                this.children.push(child);
+            },
+            addEventListener(event, handler) {
+                this.events[event] = handler;
+            },
+            querySelector(selector) {
+                return selector === "img"
+                    ? this.children.find((child) => child.tag === "img")
+                    : null;
+            },
+        };
+    }
+    const start = patched.indexOf("  async generateTimelineStrip(A2) {");
+    const end = patched.indexOf("\n  get muted() {", start);
+    const timeline = new Function(
+        "document",
+        "URL",
+        `return ({${patched.slice(start, end)}});`,
+    )({ createElement: element }, { createObjectURL: () => "blob:fixture" });
+    const strip = element(),
+        status = element(),
+        title = element();
+    const previewChoices = [],
+        frameTimes = [];
+    Object.assign(timeline, {
+        _thumb: false,
+        _storyboard: null,
+        _timelineNextIndex: 0,
+        _currentManualRotation: 0,
+        updateTimelineCurrent() {
+            this.updated = true;
+        },
+        player: {
+            setPreviewsEnabled(enabled) {
+                previewChoices.push(enabled);
+            },
+            getVideoTracks: () => [],
+            getChapters: () => chapters,
+            getDuration: () => 60,
+            async getPreviewFrame(time) {
+                frameTimes.push(time);
+                return new Blob(["fixture"]);
+            },
+        },
+        ...options,
+    });
+    const panel = {
+        querySelector: (selector) =>
+            ({
+                ".movi-timeline-strip": strip,
+                ".movi-timeline-status": status,
+                ".movi-timeline-title": title,
+            })[selector],
+    };
+    return {
+        timeline,
+        strip,
+        status,
+        title,
+        previewChoices,
+        frameTimes,
+        panel,
+    };
+}
+
+test("native chapter cards retain titles, times and seeking without decoding preview frames", async () => {
+    const fixture = timelineFixture([
+        { start: 0, title: "Opening" },
+        { start: 30, title: "Finale" },
+    ]);
+    await fixture.timeline.generateTimelineStrip(fixture.panel);
+    assert.deepEqual(fixture.previewChoices, [false]);
+    assert.deepEqual(fixture.frameTimes, []);
+    assert.equal(fixture.strip.children.length, 2);
+    const card = fixture.strip.children[1];
+    assert.equal(card.classList.contains("movi-timeline-noframe"), true);
+    assert.deepEqual(
+        card.children[0].children.map((child) => child.textContent),
+        ["Finale", "0:30"],
+    );
+    card.events.click({ stopPropagation() {} });
+    assert.equal(fixture.timeline.currentTime, 30);
+    assert.equal(fixture.timeline.updated, true);
+    assert.equal(fixture.timeline._timelineGenerating, false);
+});
+
+test("timeline decoding remains opt-in for thumbnails or a storyboard", async () => {
+    for (const options of [{ _thumb: true }, { _storyboard: "fixture.vtt" }]) {
+        const fixture = timelineFixture(
+            [{ start: 0, title: "Opening" }],
+            options,
+        );
+        await fixture.timeline.generateTimelineStrip(fixture.panel);
+        assert.deepEqual(fixture.previewChoices, [true]);
+        assert.deepEqual(fixture.frameTimes, [0]);
+        assert.equal(fixture.strip.children[0].children[0].tag, "img");
+    }
+});
+
+test("a title-only timeline with no chapters never generates the twenty-frame strip", async () => {
+    const fixture = timelineFixture([]);
+    await fixture.timeline.generateTimelineStrip(fixture.panel);
+    assert.deepEqual(fixture.frameTimes, []);
+    assert.equal(fixture.status.textContent, "No chapters");
+    assert.equal(fixture.timeline._timelineComplete, true);
+    assert.equal(fixture.timeline._timelineGenerating, false);
+});
+
+test("unrecognized earlier patch variants are rejected instead of migrated", () => {
+    const older = patched.replace(
+        GATE_AFTER,
+        GATE_AFTER.replace(
+            /      \/\/ A pending demux read[\s\S]+?return;/,
+            "      if (!this._prefetchThrottled && !this.playbackPrefetchHeld) return;",
+        ),
+    );
+    assert.notEqual(older, patched);
+    assert.throws(() => patchMoviSource(older, VERSION), /was modified/);
+});
diff --git a/website/scripts/check-pdf-worker.js b/website/scripts/check-pdf-worker.js
new file mode 100644
index 00000000..59b7b364
--- /dev/null
+++ b/website/scripts/check-pdf-worker.js
@@ -0,0 +1,109 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import { patchPdfSource, VERSION } from "./patch-pdf-worker.js";
+const source = await readFile(
+    process.env.TGDRIVE_PDF_SOURCE ||
+        new URL(
+            "../node_modules/pdfjs-dist/build/pdf.worker.mjs",
+            import.meta.url,
+        ),
+    "utf8",
+);
+test("PDF patch is idempotent on the exact pinned worker", () => {
+    const patched = patchPdfSource(source, VERSION);
+    assert.equal(patchPdfSource(patched, VERSION), patched);
+});
+test("PDF patch rejects unknown versions and modified source", () => {
+    assert.throws(() => patchPdfSource(source, "0.0.0"));
+    assert.throws(() => patchPdfSource(source + "\nmodified", VERSION));
+});
+
+function imageBoundsFixture({
+    width,
+    height,
+    inline = false,
+    ignoreErrors = true,
+}) {
+    const patched = patchPdfSource(source, VERSION);
+    const start = patched.indexOf("  async buildPaintImageXObject({");
+    const end = patched.indexOf("    let optionalContent;", start);
+    assert.ok(start >= 0 && end > start);
+    const loads = [];
+    class Dict {
+        entries = new Map();
+        set(key, value) {
+            this.entries.set(key, value);
+        }
+        get(key) {
+            return this.entries.get(key);
+        }
+    }
+    const evaluator = new Function(
+        "Dict",
+        "ObjectLoader",
+        "warn",
+        `return ({
+    ${patched.slice(start, end)}
+      return "accepted";
+    }
+  });`,
+    )(
+        Dict,
+        {
+            async load(...args) {
+                loads.push(args);
+            },
+        },
+        () => {},
+    );
+    evaluator.options = { maxImageSize: 16777216, ignoreErrors };
+    evaluator.xref = { fixture: true };
+    const image = {
+        dict: {
+            objId: "fixture image",
+            get(key) {
+                return key === "W" ? width : key === "H" ? height : undefined;
+            },
+        },
+    };
+    return {
+        loads,
+        evaluator,
+        image,
+        run: () =>
+            evaluator.buildPaintImageXObject({ image, isInline: inline }),
+    };
+}
+
+test("missing or oversized image dimensions are rejected before payload dependencies load", async () => {
+    for (const size of [
+        { width: undefined, height: 10 },
+        { width: 10, height: 0 },
+        { width: 10000, height: 10000 },
+    ]) {
+        const fixture = imageBoundsFixture(size);
+        assert.equal(await fixture.run(), undefined);
+        assert.equal(fixture.loads.length, 0);
+    }
+    const strict = imageBoundsFixture({
+        width: 10000,
+        height: 10000,
+        ignoreErrors: false,
+    });
+    await assert.rejects(strict.run(), /Image exceeded maximum allowed size/);
+    assert.equal(strict.loads.length, 0);
+});
+
+test("accepted external images load their selected dependency graph before decode", async () => {
+    const fixture = imageBoundsFixture({ width: 4096, height: 4096 });
+    assert.equal(await fixture.run(), "accepted");
+    assert.equal(fixture.loads.length, 1);
+    const [selected, keys, xref] = fixture.loads[0];
+    assert.equal(selected.get("Image"), fixture.image);
+    assert.deepEqual(keys, ["Image"]);
+    assert.equal(xref, fixture.evaluator.xref);
+    const inline = imageBoundsFixture({ width: 1, height: 1, inline: true });
+    assert.equal(await inline.run(), "accepted");
+    assert.equal(inline.loads.length, 0);
+});
diff --git a/website/scripts/patch-movi-player.js b/website/scripts/patch-movi-player.js
new file mode 100644
index 00000000..5cc393e0
--- /dev/null
+++ b/website/scripts/patch-movi-player.js
@@ -0,0 +1,311 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+// Movi 0.4.1 can resume a seek on video alone on high-latency audio outputs.
+// Late audio then pulls playback back to the requested seek position. Reuse
+// its coordinated buffering path until playable sound is actually ready.
+// Configure the HTTP ceiling before load and preserve retained bytes during
+// growth. Video-only input must also obey video decoder backpressure.
+export const VERSION = "0.4.1";
+export const ORIGINAL_SHA256 =
+    "834efaa395f82503fdea3538e03c2ad83f01a7fc409ca93d93dea500affa63c7";
+export const BEFORE = "if (this.needsSeekResumeQueue()) return";
+export const AFTER =
+    "if (this.needsSeekResumeQueue() || (!this.audioRenderer.isDroppingAudio() && !this.noSoundLeftToWaitFor() && this.audioSideStillPriming())) return";
+export const VIDEO_ONLY_BEFORE =
+    "const Y2 = !this.disableAudio && !this.audioDemuxer,";
+export const VIDEO_ONLY_AFTER =
+    "const Y2 = !this.disableAudio && !this.audioDemuxer && !!this.trackManager.getActiveAudioTrack(),";
+export const CACHE_BEFORE = 'cache: { type: "lru", maxSizeMB: 520 }';
+export const CACHE_AFTER =
+    'cache: { type: "lru", maxSizeMB: this._bufferSize > 0 ? this._bufferSize : 520 }';
+export const SIZE_BEFORE =
+    "C2 = I2 ? this.size : Math.floor(0.08 * this.size);";
+export const SIZE_AFTER = "C2 = Math.min(this.size, A2, 33554432);";
+export const WINDOW_LOG_BEFORE =
+    'I2 ? "(full file cache)" : "(8% sliding window)"';
+export const WINDOW_LOG_AFTER =
+    'this.bufferSize >= this.size ? "(full file cache)" : "(adaptive sliding window)"';
+export const WINDOW_BEFORE =
+    "g2 = this.size <= I2 ? this.size : Math.floor(0.08 * this.size);";
+export const WINDOW_AFTER = "g2 = Math.min(this.size, I2, 33554432);";
+export const RESIZE_BEFORE = `  resizeBuffer(A2) {
+    const I2 = 1024 * this.maxBufferSizeMB * 1024, C2 = Math.max(EA, Math.min(I2, A2));
+    if (this.bufferSize !== C2 || !this.sharedBuffer && !this.fallbackBuffer) {
+      this.bufferSize = C2;
+      try {
+        "undefined" != typeof SharedArrayBuffer && crossOriginIsolated ? (this.sharedBuffer = new SharedArrayBuffer(24 + this.bufferSize), this.headerView = new Int32Array(this.sharedBuffer, 0, 6), this.dataView = new Uint8Array(this.sharedBuffer, 24, this.bufferSize), this.useSharedBuffer = true, g.info(QA, \`Using SharedArrayBuffer for zero-copy streaming (\${(this.bufferSize / 1024 / 1024).toFixed(2)} MB)\`)) : (this.fallbackBuffer = new Uint8Array(this.bufferSize), g.info(QA, \`Using standard ArrayBuffer (\${(this.bufferSize / 1024 / 1024).toFixed(2)} MB)\`));
+      } catch {
+        this.fallbackBuffer = new Uint8Array(this.bufferSize), g.warn(QA, \`SharedArrayBuffer init failed, using fallback (\${(this.bufferSize / 1024 / 1024).toFixed(2)} MB)\`);
+      }
+    }
+  }`;
+export const RESIZE_AFTER = `  allocationLimitBytes = Infinity;
+  resizeBuffer(requested) {
+    const old = this.useSharedBuffer ? this.dataView : this.fallbackBuffer;
+    const capacity = Math.max(EA, Math.min(1024 * this.maxBufferSizeMB * 1024,
+      this.allocationLimitBytes, requested));
+    const written = old ? this.atomicGetWritePos() : 0;
+    if (old && (capacity === old.length || written > 0 && capacity < old.length)) return;
+    if (this.headerView && Atomics.load(this.headerView, 3) !== 0) return;
+    const start = old ? this.atomicGetBufferStart() : 0;
+    const streaming = old ? this.atomicIsStreaming() : false;
+    const header = this.headerView?.slice();
+    let shared = null, view;
+    try {
+      if (typeof SharedArrayBuffer !== "undefined" && crossOriginIsolated) {
+        shared = new SharedArrayBuffer(24 + capacity);
+        view = new Uint8Array(shared, 24, capacity);
+      } else view = new Uint8Array(capacity);
+    } catch {
+      if (old) {
+        this.allocationLimitBytes = old.length;
+        return;
+      }
+      view = new Uint8Array(capacity);
+    }
+    if (old && written > 0) view.set(old.subarray(0, written));
+    this.bufferSize = capacity;
+    this.sharedBuffer = shared;
+    this.headerView = shared ? new Int32Array(shared, 0, 6) : null;
+    this.dataView = shared ? view : null;
+    this.fallbackBuffer = shared ? null : view;
+    this.useSharedBuffer = !!shared;
+    if (this.headerView && header) this.headerView.set(header);
+    this.atomicSetBufferStart(start);
+    this.atomicSetWritePos(written);
+    this.atomicSetStreaming(streaming);
+  }`;
+// Keep compressed read-ahead independent of decoder admission. A time goal
+// avoids treating an identical byte count as enough for every video bitrate.
+export const GATE_BEFORE = `  async awaitPrefetchGate() {
+    for (; this._prefetchThrottled && this.atomicIsStreaming(); ) await new Promise((A2) => setTimeout(A2, 100));
+  }`;
+export const GATE_AFTER = `  playbackAheadBytes = Infinity;
+  playbackPrefetchHeld = false;
+  playbackRateSample = null;
+  playbackPeakBytesPerSecond = 0;
+  setPlaybackBufferGoal(time, duration, bitRate = 0, seeking = false) {
+    if (!(duration > 0 && this.size > 0 && Number.isFinite(time))) return;
+    const previous = this.playbackRateSample;
+    const position = this.getPosition();
+    if (seeking) this.playbackRateSample = null;
+    else if (previous) {
+      const elapsed = time - previous.time, bytes = position - previous.position;
+      if (elapsed >= 1 && elapsed <= 3 && bytes > 0)
+        this.playbackPeakBytesPerSecond = Math.max(bytes / elapsed,
+          this.playbackPeakBytesPerSecond * 0.98);
+      if (elapsed < 0 || elapsed >= 1) this.playbackRateSample = {time, position};
+    } else this.playbackRateSample = {time, position};
+    const rate = Math.max(this.size / duration, bitRate / 8,
+      this.playbackPeakBytesPerSecond);
+    const ceiling = Math.min(1024 * this.maxBufferSizeMB * 1024,
+      this.allocationLimitBytes ?? Infinity);
+    const shortClip = duration <= 120 && this.size <= ceiling;
+    const wanted = shortClip ? this.size : Math.min(this.size, ceiling,
+      Math.max(33554432, Math.ceil(90 * rate / 0.8 / 8388608) * 8388608));
+    // Non-range readers hold their initial storage for sequential writes.
+    if (!this.rangeUnsupported && wanted > this.bufferSize) this.resizeBuffer(wanted);
+    this.playbackAheadBytes = shortClip && this.bufferSize >= this.size
+      ? this.size : Math.max(EA, Math.min(0.8 * this.bufferSize, 90 * rate));
+  }
+  async awaitPrefetchGate() {
+    while (this.atomicIsStreaming() && !this.closed) {
+      // A distant seek starts a new source window before the demuxer can
+      // finish its first read and advance position. Skipped bytes are not
+      // buffered data; counting that gap deadlocks the new window at zero.
+      const consumed = Math.max(this.atomicGetBufferStart(), this.getPosition());
+      const ahead = Math.max(0, this.bufferEnd - consumed);
+      if (ahead >= this.playbackAheadBytes) this.playbackPrefetchHeld = true;
+      else if (ahead < 0.75 * this.playbackAheadBytes)
+        this.playbackPrefetchHeld = false;
+      // A pending demux read must complete before position can advance.
+      const readerNeedsData = [...(this.pendingReadEnds || [])].some((read) =>
+        read.generation === this.streamGeneration && read.end > this.bufferEnd);
+      if (!this._prefetchThrottled &&
+          (readerNeedsData || !this.playbackPrefetchHeld)) return;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }`;
+export const WAIT_BEFORE = `  async waitForData(A2, I2, C2 = 3e4) {`;
+export const WAIT_AFTER = `  pendingReadEnds = new Set();
+  async waitForData(offset, length, timeout = 3e4) {
+    const read = {end: offset + length, generation: this.streamGeneration};
+    this.pendingReadEnds.add(read);
+    try {
+      return await this.waitForDataUnchecked(offset, length, timeout);
+    } finally {
+      this.pendingReadEnds.delete(read);
+    }
+  }
+  async waitForDataUnchecked(A2, I2, C2 = 3e4) {`;
+export const GOAL_BEFORE = `    const A2 = this.mediaInfo.duration;
+    if (A2 <= 0) return 0;`;
+export const GOAL_AFTER = `    const A2 = this.mediaInfo.duration;
+    if (A2 <= 0) return 0;
+    this.source.setPlaybackBufferGoal?.(this.getCurrentTime(), A2,
+      this.mediaInfo.bitRate || 0, this.stateManager.is("seeking"));`;
+export const RANGE_BEFORE = `C3 = Math.min(g2, I3 ? 8388608 : this.firstRangeBytes);`;
+export const RANGE_AFTER = `C3 = Math.min(g2, I3 ? 8388608 : this.firstRangeBytes,
+        Number.isFinite(this.playbackAheadBytes)
+          ? Math.max(262144, Math.ceil(this.playbackAheadBytes / 12)) : Infinity);`;
+export const WRITER_BEFORE = `      const w2 = this.getBuffer();
+      let R2, y2, c2;`;
+export const WRITER_AFTER = `      let w2 = this.getBuffer();
+      let R2, y2, c2;`;
+export const REFRESH_BEFORE = `        const { done: B3, value: Q3 } = await G2.read();
+        if (B3) {`;
+export const REFRESH_AFTER = `        const { done: B3, value: Q3 } = await G2.read();
+        w2 = this.getBuffer();
+        if (B3) {`;
+// EOF must drain queued HEVC frames. Seek flush intentionally recreates that
+// decoder, which drops its output and is unsuitable for the end-of-file path.
+export const DRAIN_BEFORE = `  async flush() {
+    if (this.openGopErrorCount = 0, this.justFlushed = true,`;
+export const DRAIN_AFTER = `  _drainGeneration = 0;
+  async flush(drain = false) {
+    const generation = ++this._drainGeneration;
+    if (drain && this.decoder && !this.useSoftware && !this.swDecoder) {
+      const decoder = this.decoder;
+      const queued = decoder.decodeQueueSize || 0;
+      const timeout = Math.min(30000, Math.max(1000, 60 * queued));
+      let timer;
+      try {
+        await Promise.race([decoder.flush(), new Promise((resolve, reject) => {
+          timer = setTimeout(() => reject(new Error(
+            "EOF decoder drain timed out after " + timeout + "ms")), timeout);
+        })]);
+      } catch (error) {
+        // A newer seek, configuration or reset owns the decoder now.
+        if (this._drainGeneration === generation && this.decoder === decoder) {
+          try {
+            decoder.reset();
+            if (this.lastConfig) decoder.configure(this.lastConfig);
+          } catch {}
+        }
+        throw error;
+      } finally {
+        clearTimeout(timer);
+      }
+      return;
+    }
+    if (this.openGopErrorCount = 0, this.justFlushed = true,`;
+export const EOF_BEFORE = `        const A4 = ++this._eofFlushSeq;
+        this.videoDecoder.flush().catch(() => {`;
+export const EOF_AFTER = `        const A4 = ++this._eofFlushSeq;
+        this.videoDecoder.flush(true).catch(() => {`;
+export const EOF_SETTLED_BEFORE = `          this._eofFlushSettledSeq = A4;`;
+export const EOF_SETTLED_AFTER = `          if (A4 === this._eofFlushSeq) this._eofFlushSettledSeq = A4;`;
+export const DRAIN_RESET_BEFORE = `  reset() {
+    if (this.openGopErrorCount = 0, this.swDecoder`;
+export const DRAIN_RESET_AFTER = `  reset() {
+    ++this._drainGeneration;
+    if (this.openGopErrorCount = 0, this.swDecoder`;
+export const DRAIN_CONFIG_BEFORE = `  async configure(A2, I2, C2 = 0) {
+    if (this.currentTrack = A2,`;
+export const DRAIN_CONFIG_AFTER = `  async configure(A2, I2, C2 = 0) {
+    ++this._drainGeneration;
+    if (this.currentTrack = A2,`;
+export const TIMELINE_BEFORE = `    if (this._timelineGenerating) return;
+    this.player.setPreviewsEnabled(true);`;
+export const TIMELINE_AFTER = `    if (this._timelineGenerating) return;
+    this.player.setPreviewsEnabled(this._thumb || !!this._storyboard);`;
+export const CHAPTER_PREVIEW_BEFORE = `const C3 = h2[A3], B3 = C3.image ? null : await this.player.getPreviewFrame(C3.start, null, true);`;
+export const CHAPTER_PREVIEW_AFTER = `const C3 = h2[A3], B3 = C3.image || !(this._thumb || this._storyboard) ? null : await this.player.getPreviewFrame(C3.start, null, true);`;
+export const EMPTY_TIMELINE_BEFORE = `        C2 && (C2.textContent = "Timeline"), g2.textContent = "Generating...";`;
+export const EMPTY_TIMELINE_AFTER = `        if (!(this._thumb || this._storyboard)) {
+          if (C2) C2.textContent = "Chapters";
+          g2.textContent = "No chapters";
+          this._timelineComplete = true;
+          return;
+        }
+        C2 && (C2.textContent = "Timeline"), g2.textContent = "Generating...";`;
+export const SUBTITLE_DISCONNECT_BEFORE = `    this.player && (this.player.destroy(), this.player = null);
+  }
+  attributeChangedCallback(A2, I2, C2) {`;
+export const SUBTITLE_DISCONNECT_AFTER = `    this.player && (this.player.destroy(), this.player = null);
+    for (const A2 of this._pickedSubtitleUrls) URL.revokeObjectURL(A2);
+    this._pickedSubtitleUrls = [];
+  }
+  attributeChangedCallback(A2, I2, C2) {`;
+export const PATCHES = [
+    [BEFORE, AFTER],
+    [VIDEO_ONLY_BEFORE, VIDEO_ONLY_AFTER],
+    [CACHE_BEFORE, CACHE_AFTER],
+    [SIZE_BEFORE, SIZE_AFTER],
+    [WINDOW_LOG_BEFORE, WINDOW_LOG_AFTER],
+    [WINDOW_BEFORE, WINDOW_AFTER],
+    [RESIZE_BEFORE, RESIZE_AFTER],
+    [GATE_BEFORE, GATE_AFTER],
+    [WAIT_BEFORE, WAIT_AFTER],
+    [GOAL_BEFORE, GOAL_AFTER],
+    [RANGE_BEFORE, RANGE_AFTER],
+    [WRITER_BEFORE, WRITER_AFTER],
+    [REFRESH_BEFORE, REFRESH_AFTER],
+    [DRAIN_BEFORE, DRAIN_AFTER],
+    [DRAIN_RESET_BEFORE, DRAIN_RESET_AFTER],
+    [DRAIN_CONFIG_BEFORE, DRAIN_CONFIG_AFTER],
+    [EOF_BEFORE, EOF_AFTER],
+    [EOF_SETTLED_BEFORE, EOF_SETTLED_AFTER],
+    [TIMELINE_BEFORE, TIMELINE_AFTER],
+    [CHAPTER_PREVIEW_BEFORE, CHAPTER_PREVIEW_AFTER],
+    [EMPTY_TIMELINE_BEFORE, EMPTY_TIMELINE_AFTER],
+    [SUBTITLE_DISCONNECT_BEFORE, SUBTITLE_DISCONNECT_AFTER],
+];
+export const NOTICE =
+    "/*! Modified by TGDrive (2026-10-20): coordinate seek resume with playable audio. See third-party/movi-player-TGDrive-patch-NOTICE.txt. */\n";
+export const digest = (source) =>
+    createHash("sha256").update(source).digest("hex");
+
+export function patchMoviSource(source, version) {
+    if (version !== VERSION)
+        throw new Error(
+            `TGDrive's seek fix requires movi-player ${VERSION}; found ${version}. Review the upstream fix before updating the pinned player.`,
+        );
+    const marked = source.startsWith(NOTICE);
+    let original = marked ? source.slice(NOTICE.length) : source;
+    for (const [before, after] of PATCHES)
+        original = original.replace(after, before);
+    if (
+        digest(original) !== ORIGINAL_SHA256 ||
+        PATCHES.some(([before]) => original.split(before).length !== 2)
+    )
+        throw new Error(
+            marked
+                ? "TGDrive's installed Movi seek patch was modified. Run npm ci and rebuild."
+                : "The pinned Movi bundle does not match TGDrive's reviewed seek fix. Run npm ci; do not apply the patch to an unknown bundle.",
+        );
+    let patched = original;
+    for (const [before, after] of PATCHES)
+        patched = patched.replace(before, after);
+    return NOTICE + patched;
+}
+
+export async function patchInstalledMovi() {
+    const root = new URL("../", import.meta.url);
+    const manifest = JSON.parse(
+        await readFile(
+            new URL("node_modules/movi-player/package.json", root),
+            "utf8",
+        ),
+    );
+    const bundle = new URL(
+        "node_modules/movi-player/dist/element.slim.js",
+        root,
+    );
+    const source = await readFile(bundle, "utf8");
+    const patched = patchMoviSource(source, manifest.version);
+    if (patched !== source) await writeFile(bundle, patched);
+    console.info(
+        `[TGDrive] Movi ${VERSION} seek, source-window and decoder-backpressure fixes verified.`,
+    );
+}
+
+if (
+    process.argv[1] &&
+    resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+    await patchInstalledMovi();
+}
diff --git a/website/scripts/patch-pdf-worker.js b/website/scripts/patch-pdf-worker.js
new file mode 100644
index 00000000..d2a408e1
--- /dev/null
+++ b/website/scripts/patch-pdf-worker.js
@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+export const VERSION = "6.4.299";
+const ORIGINAL_SHA256 =
+    "07ceb740d746e5d9012fcf9f27d5c7dea09f7d2f5e74f5c8109e5787551a2333";
+const NOTICE =
+    "// TGDrive: load shared PDF image resources only when painted.\n";
+// Some producers put every page's image in one shared resource dictionary.
+// PDF.js eagerly loads all their streams, even with disableAutoFetch. Keep
+// dictionary/header discovery, but defer image payloads until actually used.
+export const PATCHES = [
+    [
+        "  makeSubStream(start, length, dict = null) {\n    if (length) {\n      if (start + length > this.progressiveDataLength) {",
+        '  makeSubStream(start, length, dict = null) {\n    if (length) {\n      // Image payloads stay sparse until ObjectLoader loads the painted image.\n      if (start + length > this.progressiveDataLength && !isName(dict?.get("Subtype"), "Image")) {',
+    ],
+    [
+        "  constructor(dict, keys, xref) {\n    this.dict = dict;",
+        "  constructor(dict, keys, xref, deferImages = false) {\n    this.deferImages = deferImages;\n    this.dict = dict;",
+    ],
+    [
+        "      if (currentNode instanceof BaseStream) {\n        const baseStreams = currentNode.getBaseStreams();",
+        '      if (currentNode instanceof BaseStream) {\n        if (this.deferImages && isName(currentNode.dict.get("Subtype"), "Image")) continue;\n        const baseStreams = currentNode.getBaseStreams();',
+    ],
+    [
+        "  static async load(obj, keys, xref) {",
+        "  static async load(obj, keys, xref, deferImages = false) {",
+    ],
+    [
+        "    const objLoader = new ObjectLoader(obj, keys, xref);",
+        "    const objLoader = new ObjectLoader(obj, keys, xref, deferImages);",
+    ],
+    [
+        "    await ObjectLoader.load(this.resources, keys, this.xref);",
+        "    await ObjectLoader.load(this.resources, keys, this.xref, true);",
+    ],
+    [
+        "    await ObjectLoader.load(localResources, keys, this.xref);",
+        "    await ObjectLoader.load(localResources, keys, this.xref, true);",
+    ],
+    [
+        '      warn(msg);\n      return;\n    }\n    let optionalContent;\n    if (dict.has("OC")) {',
+        '      warn(msg);\n      return;\n    }\n    // Reject invalid or oversized images before requesting their payloads.\n    // Load the selected image, masks and color resources before decode.\n    if (!isInline) {\n      const selected = new Dict(this.xref);\n      selected.set("Image", image);\n      await ObjectLoader.load(selected, ["Image"], this.xref);\n    }\n    let optionalContent;\n    if (dict.has("OC")) {',
+    ],
+];
+export function patchPdfSource(source, version) {
+    if (version !== VERSION)
+        throw new Error(
+            "Review the PDF lazy-image patch before upgrading PDF.js.",
+        );
+    let original = source.startsWith(NOTICE)
+        ? source.slice(NOTICE.length)
+        : source;
+    for (const [before, after] of PATCHES)
+        original = original.replace(after, before);
+    if (
+        createHash("sha256").update(original).digest("hex") !==
+            ORIGINAL_SHA256 ||
+        PATCHES.some(([before]) => original.split(before).length !== 2)
+    ) {
+        throw new Error(
+            "The PDF worker differs from the reviewed bundle. Run npm ci; do not patch an unknown worker.",
+        );
+    }
+    for (const [before, after] of PATCHES)
+        original = original.replace(before, after);
+    return NOTICE + original;
+}
+export async function patchInstalledPdf() {
+    const root = new URL("../", import.meta.url);
+    const manifest = JSON.parse(
+        await readFile(
+            new URL("node_modules/pdfjs-dist/package.json", root),
+            "utf8",
+        ),
+    );
+    const path = new URL("node_modules/pdfjs-dist/build/pdf.worker.mjs", root);
+    const source = await readFile(path, "utf8");
+    const patched = patchPdfSource(source, manifest.version);
+    if (patched !== source) await writeFile(path, patched);
+}
+if (
+    process.argv[1] &&
+    resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+)
+    await patchInstalledPdf();
diff --git a/website/scripts/pdfjs-assets.ts b/website/scripts/pdfjs-assets.ts
new file mode 100644
index 00000000..1e490710
--- /dev/null
+++ b/website/scripts/pdfjs-assets.ts
@@ -0,0 +1,82 @@
+import { createReadStream, readFileSync, readdirSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import type { Plugin } from "vite";
+
+const RESOURCE_DIRECTORIES = ["cmaps", "standard_fonts", "wasm", "iccs"];
+const require = createRequire(import.meta.url);
+
+/** Serve the installed PDF.js rendering resources locally in development and builds. */
+export function pdfjsAssets(): Plugin {
+    const packageFile = require.resolve("pdfjs-dist/package.json");
+    const packageDirectory = dirname(packageFile);
+    const { version } = JSON.parse(readFileSync(packageFile, "utf8")) as {
+        version: string;
+    };
+    const upstreamVersion = version.replace(/-tgdrive\.\d+$/, "");
+    const base = `static/pdfjs/${upstreamVersion}/`;
+
+    return {
+        name: "tgdrive-pdfjs-assets",
+        configureServer(server) {
+            server.middlewares.use((request, response, next) => {
+                const path = new URL(request.url || "/", "http://localhost")
+                    .pathname;
+                if (!path.startsWith("/" + base)) return next();
+                const [directory, filename, extra] = path
+                    .slice(base.length + 1)
+                    .split("/");
+                if (
+                    !RESOURCE_DIRECTORIES.includes(directory) ||
+                    !filename ||
+                    !/^[A-Za-z0-9_.-]+$/.test(filename) ||
+                    filename === "." ||
+                    filename === ".." ||
+                    extra !== undefined
+                ) {
+                    response.statusCode = 404;
+                    response.end();
+                    return;
+                }
+                const file = join(packageDirectory, directory, filename);
+                try {
+                    if (!statSync(file).isFile())
+                        throw new Error("Missing PDF resource");
+                } catch {
+                    response.statusCode = 404;
+                    response.end();
+                    return;
+                }
+                response.setHeader(
+                    "Content-Type",
+                    filename.endsWith(".wasm")
+                        ? "application/wasm"
+                        : filename.endsWith(".js")
+                          ? "text/javascript; charset=utf-8"
+                          : "application/octet-stream",
+                );
+                response.setHeader("X-Content-Type-Options", "nosniff");
+                createReadStream(file).on("error", next).pipe(response);
+            });
+        },
+        generateBundle() {
+            for (const directory of RESOURCE_DIRECTORIES) {
+                for (const entry of readdirSync(
+                    join(packageDirectory, directory),
+                    {
+                        withFileTypes: true,
+                    },
+                )) {
+                    if (!entry.isFile()) continue;
+                    this.emitFile({
+                        type: "asset",
+                        fileName: `${base}${directory}/${entry.name}`,
+                        source: readFileSync(
+                            join(packageDirectory, directory, entry.name),
+                        ),
+                    });
+                }
+            }
+        },
+    };
+}
diff --git a/website/src/app/App.tsx b/website/src/app/App.tsx
new file mode 100644
index 00000000..e3d2c837
--- /dev/null
+++ b/website/src/app/App.tsx
@@ -0,0 +1,2292 @@
+import BrandLogo from "../shared/BrandLogo";
+import GitHubMark from "../shared/GitHubMark";
+import ThemeControl from "../shared/ThemeControl";
+import {
+    useCallback,
+    useEffect,
+    useLayoutEffect,
+    useRef,
+    useState,
+    useSyncExternalStore,
+    type FormEvent,
+} from "react";
+import {
+    Star,
+    FolderClosed,
+    ArrowDownUp,
+    ChartNoAxesCombined,
+    Server,
+    Database,
+    Gauge,
+    FolderPlus,
+    FolderUp,
+    HardDrive,
+    Search,
+    Trash2,
+    Upload,
+    Plus,
+    Link,
+    ChevronRight,
+    BookOpen,
+    X,
+    Plug,
+    Globe,
+    ShieldCheck,
+    ShieldAlert,
+    Menu,
+    SlidersHorizontal,
+} from "lucide-react";
+import { api, ApiError, errorMessage } from "../shared/api";
+import {
+    itemPath,
+    formatBytes,
+    setTimezone,
+    type DriveItem,
+    type Directory,
+    type View,
+} from "../shared/types";
+import { transfers, type Transfer } from "../features/transfers/transfers";
+import {
+    transferFolderDestination,
+    transferTaskId,
+} from "../features/transfers/transferTasks";
+import { needsDeviceUpload } from "../features/transfers/deviceUploadStatus";
+import {
+    createListingRefreshQueue,
+    reconcileDirectory,
+    reconcileDriveItems,
+} from "../features/files/listingUpdates";
+import { Modal, Spinner, ToastNotice as Toast } from "../shared/components";
+import Login from "./Login";
+import SharesView from "../features/shares/SharesView";
+import StorageView from "../features/settings/StorageView";
+import UploadSettings from "../features/settings/UploadSettings";
+import SettingsManagement from "../features/settings/SettingsManagement";
+import PerformanceSettings from "../features/performance/PerformanceSettings";
+import Preloads from "../features/performance/Preloads";
+import PerformancePanel from "../features/performance/PerformancePanel";
+import FileBrowser from "../features/files/FileBrowser";
+import { COMPACT_LAYOUT_QUERY } from "../shared/responsive";
+import type { FileSort } from "../features/files/SortMenu";
+import type { SortOrder } from "../features/files/fileSorting";
+import ActionDialog, {
+    type ActionDialogState,
+} from "../features/files/ActionDialog";
+import TransferPanel from "../features/transfers/TransferPanel";
+import TransferHistory from "../features/transfers/TransferHistory";
+import FolderUpload from "../features/transfers/FolderUpload";
+import DeletionNotice from "../features/transfers/DeletionNotice";
+import SidebarLogout from "./SidebarLogout";
+import ChannelBackup from "../features/backup/ChannelBackup";
+import DatabaseRestore, {
+    DatabaseRestoreResult,
+    type DatabaseRestoreState,
+} from "../features/backup/DatabaseRestore";
+import BotModeSettings from "../features/settings/BotModeSettings";
+import { useManualRefresh } from "../shared/useManualRefresh";
+function getLocation() {
+    const url = new URL(window.location.href);
+    const path = url.searchParams.get("path") || "/";
+    const requested = url.searchParams.get("view");
+    const section = url.searchParams.get("section");
+    const view: View = path.startsWith("/share_")
+        ? "files"
+        : path === "/trash"
+          ? "trash"
+          : [
+                  "activity",
+                  "starred",
+                  "shares",
+                  "connections",
+                  "storage",
+                  "settings",
+                  "preloads",
+                  "performance",
+              ].includes(requested || "")
+            ? (requested as View)
+            : "files";
+    return {
+        path,
+        auth: url.searchParams.get("auth") || "",
+        view,
+        settingsSection: ["cache", "transfers", "regional"].includes(
+            section || "",
+        )
+            ? section!
+            : "cache",
+        previewId: url.searchParams.get("preview") || "",
+        highlightId:
+            typeof window.history.state?.tgdriveHighlight === "string"
+                ? window.history.state.tgdriveHighlight
+                : "",
+    };
+}
+const TOOL_VIEWS: View[] = [
+    "performance",
+    "preloads",
+    "settings",
+    "connections",
+    "storage",
+];
+const ROOT_CRUMB = { path: "/", name: "My Files" };
+const ADMIN_SETTING_TITLES: Record<string, string> = {
+    cache: "Cache & preloading",
+    transfers: "Uploads & Telegram",
+    regional: "Regional settings",
+};
+function searchHistoryOffset() {
+    const value = window.history.state?.tgdriveSearchOffset;
+    return Number.isSafeInteger(value) && value >= 0 && value % 100 === 0
+        ? value
+        : 0;
+}
+export default function App() {
+    const [location, setLocation] = useState(getLocation);
+    const [toolsOpen, setToolsOpen] = useState(() =>
+        TOOL_VIEWS.includes(location.view),
+    );
+    useEffect(() => {
+        setToolsOpen(TOOL_VIEWS.includes(location.view));
+    }, [location.view, location.settingsSection]);
+    const [authenticated, setAuthenticated] = useState<boolean | null>(null);
+    const [databaseRestore, setDatabaseRestore] =
+        useState<DatabaseRestoreState>({ phase: "idle" });
+    const databaseRestorePhase = useRef<DatabaseRestoreState["phase"]>("idle");
+    const [admissionPaused, setAdmissionPaused] = useState(false);
+    const databaseRestoreChanged = useCallback(
+        (state: DatabaseRestoreState) => {
+            databaseRestorePhase.current = state.phase;
+            setDatabaseRestore(state);
+            if (state.phase !== "idle") setAdmissionPaused(true);
+        },
+        [],
+    );
+    useEffect(() => {
+        if (databaseRestore.phase !== "restoring") return;
+        const beforeUnload = (event: BeforeUnloadEvent) => {
+            event.preventDefault();
+            event.returnValue = "";
+        };
+        window.addEventListener("beforeunload", beforeUnload);
+        return () => window.removeEventListener("beforeunload", beforeUnload);
+    }, [databaseRestore.phase]);
+    useEffect(() => {
+        if (
+            databaseRestore.phase === "restored" ||
+            databaseRestore.phase === "restart_required"
+        )
+            document.getElementById("main-content")?.focus();
+    }, [databaseRestore.phase]);
+    const [telegramWarning, setTelegramWarning] = useState("");
+    const [config, setConfig] = useState<{
+        max_file_size: number;
+        demo_data?: boolean;
+        demo_mode?: boolean;
+        demo_read_only?: boolean;
+        demo_admin?: boolean;
+        recovery_only?: boolean;
+    }>({ max_file_size: 0 });
+    const demoReadOnly = Boolean(config.demo_read_only ?? config.demo_mode);
+    const [configLoad, setConfigLoad] = useState<"loading" | "ready" | "error">(
+        "loading",
+    );
+    const [configError, setConfigError] = useState("");
+    const [configReady, setConfigReady] = useState(false);
+    const configGeneration = useRef(0);
+    const loadConfig = useCallback(async () => {
+        const generation = ++configGeneration.current;
+        // Refreshing the same session must not unmount unsaved settings drafts.
+        setConfigLoad((current) => (current === "ready" ? current : "loading"));
+        setConfigError("");
+        try {
+            const value = await api.config();
+            if (generation !== configGeneration.current) return;
+            setConfig(value);
+            setTimezone(value.timezone || "Asia/Kolkata");
+            setConfigLoad("ready");
+            setConfigReady(true);
+        } catch (cause) {
+            if (generation !== configGeneration.current) return;
+            setConfigError(errorMessage(cause));
+            setConfigLoad("error");
+        }
+    }, []);
+    const [directory, setDirectory] = useState<Directory>({ contents: {} });
+    const [loading, setLoading] = useState(true);
+    const [loadError, setLoadError] = useState("");
+    const [refresh, setRefresh] = useState(0);
+    const [dialog, setDialog] = useState<ActionDialogState | null>(null);
+    const [demoFilesReadOnly, setDemoFilesReadOnly] = useState(false);
+    const [query, setQuery] = useState("");
+    const [scopedQuery, setScopedQuery] = useState("");
+    const [searchOffset, setSearchOffset] = useState(searchHistoryOffset);
+    const [searchSort, setSearchSort] = useState<FileSort>("name");
+    const [searchOrder, setSearchOrder] = useState<SortOrder>("asc");
+    const [searchMore, setSearchMore] = useState(false);
+    const [searchItems, setSearchItems] = useState<DriveItem[]>([]);
+    const [nextSearchOffset, setNextSearchOffset] = useState<number | null>(
+        null,
+    );
+    const searchInput = useRef<HTMLInputElement>(null);
+    const searchTrigger = useRef<HTMLButtonElement>(null);
+    const [searchExpanded, setSearchExpanded] = useState(false);
+    const requestedSearchFocus = useRef<{ select: boolean } | null>(null);
+    const revealSearch = useCallback((select = false) => {
+        setSearchExpanded(true);
+        const input = searchInput.current;
+        if (input && input.getClientRects().length) {
+            input.focus();
+            if (select) input.select();
+        } else requestedSearchFocus.current = { select };
+    }, []);
+    const searchTimer = useRef<ReturnType<typeof setTimeout> | undefined>(
+        undefined,
+    );
+    const searchComposing = useRef(false);
+    const ownSearchNavigation = useRef<string | null>(null);
+    const searchOrigin = useRef<string | null>(
+        typeof window.history.state?.tgdriveSearchOrigin === "string"
+            ? window.history.state.tgdriveSearchOrigin
+            : null,
+    );
+    const lastFolder = useRef("/");
+    const [toast, setToast] = useState<{
+        message: string;
+        error: boolean;
+    } | null>(null);
+    const [newOpen, setNewOpen] = useState(false);
+    useEffect(() => {
+        if (!newOpen) return;
+        const menu = document.getElementById("new-menu");
+        const trigger = document.activeElement;
+        const buttons = () =>
+            Array.from(
+                menu?.querySelectorAll<HTMLButtonElement>(
+                    "button:not(:disabled)",
+                ) || [],
+            );
+        buttons()[0]?.focus();
+        const keydown = (event: KeyboardEvent) => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                event.stopPropagation();
+                setNewOpen(false);
+                if (trigger instanceof HTMLElement) trigger.focus();
+                return;
+            }
+            if (!menu?.contains(event.target as Node)) return;
+            if (event.key === "Tab") {
+                setNewOpen(false);
+                if (trigger instanceof HTMLElement) trigger.focus();
+                return;
+            }
+            const actions = buttons();
+            const current = actions.indexOf(
+                document.activeElement as HTMLButtonElement,
+            );
+            let next = current;
+            if (event.key === "ArrowDown")
+                next = (current + 1) % actions.length;
+            else if (event.key === "ArrowUp")
+                next = (current + actions.length - 1) % actions.length;
+            else if (event.key === "Home") next = 0;
+            else if (event.key === "End") next = actions.length - 1;
+            else return;
+            event.preventDefault();
+            actions[next]?.focus();
+        };
+        document.addEventListener("keydown", keydown, true);
+        return () => document.removeEventListener("keydown", keydown, true);
+    }, [newOpen]);
+    const [mobileNav, setMobileNav] = useState(false);
+    useEffect(() => {
+        if (!mobileNav) return;
+        const navigation = document.getElementById("drive-navigation");
+        const opener = document.getElementById("navigation-toggle");
+        if (navigation) navigation.scrollTop = 0;
+        const controls = () =>
+            Array.from(
+                navigation?.querySelectorAll<HTMLElement>(
+                    "a[href],button:not(:disabled),summary",
+                ) || [],
+            ).filter((element) => element.getClientRects().length > 0);
+        (
+            navigation?.querySelector<HTMLElement>('[aria-current="page"]') ||
+            controls()[0]
+        )?.focus();
+        const keydown = (event: KeyboardEvent) => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                event.stopPropagation();
+                setMobileNav(false);
+            } else if (event.key === "Tab") {
+                const available = controls();
+                const first = available[0],
+                    last = available.at(-1);
+                if (
+                    event.shiftKey &&
+                    (document.activeElement === first ||
+                        !navigation?.contains(document.activeElement))
+                ) {
+                    event.preventDefault();
+                    last?.focus();
+                } else if (
+                    !event.shiftKey &&
+                    (document.activeElement === last ||
+                        !navigation?.contains(document.activeElement))
+                ) {
+                    event.preventDefault();
+                    first?.focus();
+                }
+            }
+        };
+        document.addEventListener("keydown", keydown, true);
+        return () => {
+            document.removeEventListener("keydown", keydown, true);
+            if (opener?.isConnected) opener.focus({ preventScroll: true });
+        };
+    }, [mobileNav]);
+
+    const [mobile, setMobile] = useState(
+        () => window.matchMedia(COMPACT_LAYOUT_QUERY).matches,
+    );
+    useEffect(() => {
+        const media = window.matchMedia(COMPACT_LAYOUT_QUERY);
+        const update = () => {
+            setMobile(media.matches);
+            if (!media.matches) setMobileNav(false);
+        };
+        media.addEventListener("change", update);
+        return () => media.removeEventListener("change", update);
+    }, []);
+    const [crumbs, setCrumbs] = useState([ROOT_CRUMB]);
+    const [shareRoot, setShareRoot] = useState("");
+    const fileInput = useRef<HTMLInputElement>(null);
+    const folderInput = useRef<HTMLInputElement>(null);
+    const [folderSupported] = useState(
+        () => "webkitdirectory" in document.createElement("input"),
+    );
+    const folderDestination = useRef({ path: "/", name: "My Files" });
+    const [folderSelection, setFolderSelection] = useState<{
+        files: File[];
+        destination: string;
+        name: string;
+    } | null>(null);
+    const names = useRef(new Map([["/", "My Files"]]));
+    const currentPath = location.path;
+    const isPublic = currentPath.startsWith("/share_");
+    const isSearch = currentPath.startsWith("/search_");
+    const view = location.view;
+    const searchLabel =
+        view === "files"
+            ? "Search Files and Folders"
+            : view === "trash"
+              ? "Search Trash"
+              : view === "starred"
+                ? "Search Starred"
+                : view === "activity"
+                  ? "Search Transfers"
+                  : view === "shares"
+                    ? "Search Shared Links"
+                    : view === "preloads"
+                      ? "Search cached files"
+                      : "";
+    useLayoutEffect(() => {
+        const requested = requestedSearchFocus.current;
+        const input = searchInput.current;
+        if (!requested || !input?.getClientRects().length) return;
+        requestedSearchFocus.current = null;
+        input.focus();
+        if (requested.select) input.select();
+    }, [searchExpanded, mobile, query, searchLabel]);
+    const isFiles = view === "files" || view === "trash" || view === "starred";
+    const listingKey = JSON.stringify([
+        authenticated,
+        view,
+        currentPath,
+        location.auth,
+        isSearch ? searchOffset : 0,
+        isSearch ? searchSort : "",
+        isSearch ? searchOrder : "",
+        ["trash", "starred"].includes(view) ? scopedQuery : "",
+    ]);
+    const loadedListing = useRef<string | null>(null);
+    const listingRefresh = useRef<ReturnType<
+        typeof createListingRefreshQueue
+    > | null>(null);
+    const workspace = useRef<HTMLElement>(null);
+    useLayoutEffect(() => {
+        if (workspace.current) workspace.current.scrollTop = 0;
+    }, [currentPath, view, location.settingsSection, searchOffset]);
+    const items = useSyncExternalStore(transfers.subscribe, transfers.snapshot);
+    const deletionProgress = useSyncExternalStore(
+        transfers.subscribe,
+        transfers.deletionSnapshot,
+    );
+    const activeCount = new Set(
+        items
+            .filter(
+                (item) =>
+                    !["completed", "error", "cancelled"].includes(item.state),
+            )
+            .map(transferTaskId),
+    ).size;
+    const mobileUploadIssues = items.some(
+        (item) =>
+            item.initiatedHere &&
+            ["error", "awaiting_file"].includes(item.state),
+    );
+    const deviceUploadPending =
+        authenticated === true && !isPublic && items.some(needsDeviceUpload);
+    useEffect(() => {
+        if (!deviceUploadPending) return;
+        const beforeUnload = (event: BeforeUnloadEvent) => {
+            event.preventDefault();
+            event.returnValue = "";
+        };
+        window.addEventListener("beforeunload", beforeUnload);
+        return () => window.removeEventListener("beforeunload", beforeUnload);
+    }, [deviceUploadPending]);
+    const notify = useCallback(
+        (message: string, error = false) => setToast({ message, error }),
+        [],
+    );
+    const endSession = useCallback(() => {
+        setConfig((value) => ({
+            ...value,
+            demo_read_only: Boolean(value.demo_mode),
+            demo_admin: false,
+        }));
+        setAuthenticated(false);
+        setDialog(null);
+        setFolderSelection(null);
+        setDemoFilesReadOnly(false);
+        setConfigLoad("loading");
+        setConfigReady(false);
+        void loadConfig();
+    }, [loadConfig]);
+    const listingRefreshAction = useManualRefresh(notify);
+    useEffect(() => {
+        if (
+            !deletionProgress.completed ||
+            deletionProgress.jobs.some(
+                (job) =>
+                    ![
+                        "completed",
+                        "cancelled",
+                        "error",
+                        "failed",
+                        "interrupted",
+                    ].includes(job.status),
+            )
+        )
+            return;
+        notify(
+            "Permanently deleted " +
+                deletionProgress.completed +
+                (deletionProgress.completed === 1 ? " item." : " items."),
+        );
+        // Acknowledge the result once so later polls and page changes cannot replay it.
+        transfers.dismissDeletionResult();
+    }, [deletionProgress, notify]);
+    const reload = useCallback(() => setRefresh((value) => value + 1), []);
+    const navigate = useCallback(
+        (
+            path: string,
+            view: View = "files",
+            auth = "",
+            replace = false,
+            state: Record<string, unknown> = {},
+            settingsSection = "cache",
+        ) => {
+            clearTimeout(searchTimer.current);
+            const params = new URLSearchParams();
+            if (path !== "/") params.set("path", path);
+            if (view !== "files" && view !== "trash") params.set("view", view);
+            if (view === "settings") params.set("section", settingsSection);
+            if (auth) params.set("auth", auth);
+            const target = "/" + (params.size ? "?" + params.toString() : "");
+            if (replace) window.history.replaceState(state, "", target);
+            else window.history.pushState(state, "", target);
+            setLocation(getLocation());
+            setDialog(null);
+            setNewOpen(false);
+            setMobileNav(false);
+        },
+        [],
+    );
+    useEffect(() => {
+        const pop = () => {
+            clearTimeout(searchTimer.current);
+            ownSearchNavigation.current = null;
+            searchOrigin.current =
+                typeof window.history.state?.tgdriveSearchOrigin === "string"
+                    ? window.history.state.tgdriveSearchOrigin
+                    : null;
+            setSearchOffset(searchHistoryOffset());
+            setLocation(getLocation());
+            setDialog(null);
+        };
+        window.addEventListener("popstate", pop);
+        return () => window.removeEventListener("popstate", pop);
+    }, []);
+    useEffect(() => {
+        setConfigLoad("loading");
+        setConfigReady(false);
+        void loadConfig();
+        return () => {
+            ++configGeneration.current;
+        };
+    }, [isPublic, loadConfig]);
+    useEffect(() => {
+        if (isPublic) {
+            setAuthenticated(false);
+            return;
+        }
+        void api
+            .session()
+            .then((result) => setAuthenticated(result.authenticated))
+            .catch(() => setAuthenticated(false));
+    }, [isPublic]);
+    useEffect(() => {
+        if (databaseRestore.phase !== "idle") return;
+        if (authenticated !== true || isPublic) {
+            setAdmissionPaused(false);
+            setTelegramWarning("");
+            return;
+        }
+        let disposed = false;
+        let timer: ReturnType<typeof setTimeout>;
+        const refreshAdmission = async () => {
+            try {
+                const status = await api.status();
+                if (!disposed) {
+                    setAdmissionPaused(
+                        Boolean(
+                            status.admission_paused || status.restart_required,
+                        ),
+                    );
+                    setTelegramWarning(
+                        status.telegram_issues?.[0]?.detail ||
+                            (status.telegram_ready === false &&
+                            !status.demo &&
+                            !status.recovery_only
+                                ? "No usable Telegram account is connected. Open Connections and Refresh to check bot tokens, Premium sessions and channel permissions. Existing files and saved upload progress are preserved."
+                                : ""),
+                    );
+                }
+            } catch {
+                // Keep the last known admission state until the status service recovers.
+            } finally {
+                if (!disposed) timer = setTimeout(refreshAdmission, 5000);
+            }
+        };
+        void refreshAdmission();
+        return () => {
+            disposed = true;
+            clearTimeout(timer);
+        };
+    }, [authenticated, isPublic, databaseRestore.phase]);
+    useEffect(() => {
+        const saved = (event: Event) => {
+            const detail = (
+                event as CustomEvent<{
+                    admission_paused?: boolean;
+                    restart_required?: boolean;
+                }>
+            ).detail;
+            setAdmissionPaused(
+                Boolean(detail?.admission_paused || detail?.restart_required),
+            );
+            setNewOpen(false);
+        };
+        const required = () => {
+            setAdmissionPaused(true);
+            setNewOpen(false);
+        };
+        window.addEventListener("tgdrive:settings-saved", saved);
+        window.addEventListener("tgdrive:restart-required", required);
+        return () => {
+            window.removeEventListener("tgdrive:settings-saved", saved);
+            window.removeEventListener("tgdrive:restart-required", required);
+        };
+    }, []);
+    useEffect(() => {
+        transfers.setAdmissionPaused(admissionPaused);
+    }, [admissionPaused]);
+    useEffect(() => {
+        transfers.setEnabled(
+            authenticated === true &&
+                !isPublic &&
+                !config.recovery_only &&
+                databaseRestore.phase === "idle",
+        );
+        return () => transfers.setEnabled(false);
+    }, [authenticated, isPublic, config.recovery_only, databaseRestore.phase]);
+    useEffect(() => {
+        const expired = () => {
+            // Restoring revokes sessions before its response arrives. Preserve
+            // the outcome and restart instructions instead of showing Login.
+            if (databaseRestorePhase.current !== "idle") return;
+            endSession();
+            notify("Your session expired. Log in to continue.", true);
+        };
+        window.addEventListener("tgdrive:auth-required", expired);
+        window.addEventListener("tgdrive:files-changed", reload);
+        return () => {
+            window.removeEventListener("tgdrive:auth-required", expired);
+            window.removeEventListener("tgdrive:files-changed", reload);
+        };
+    }, [endSession, notify, reload]);
+    useEffect(() => {
+        const refused = () => {
+            setDialog(null);
+            setFolderSelection(null);
+            setNewOpen(false);
+            setDemoFilesReadOnly(true);
+        };
+        window.addEventListener("tgdrive:demo-files-read-only", refused);
+        return () =>
+            window.removeEventListener("tgdrive:demo-files-read-only", refused);
+    }, []);
+    useEffect(() => {
+        if (ownSearchNavigation.current === currentPath) {
+            ownSearchNavigation.current = null;
+        } else {
+            setQuery(isSearch ? currentPath.slice(8) : "");
+            setScopedQuery("");
+            setSearchExpanded(false);
+        }
+        if (!isSearch && !isPublic && view === "files")
+            lastFolder.current = currentPath;
+    }, [isSearch, currentPath, isPublic, view]);
+    useEffect(() => {
+        if (!isSearch) return;
+        window.history.replaceState(
+            { ...window.history.state, tgdriveSearchOffset: searchOffset },
+            "",
+            window.location.href,
+        );
+    }, [isSearch, searchOffset]);
+    useEffect(() => {
+        const shortcut = (event: KeyboardEvent) => {
+            if (
+                isPublic ||
+                !searchLabel ||
+                authenticated !== true ||
+                document.querySelector("dialog[open]")
+            )
+                return;
+            const target = event.target as HTMLElement | null;
+            const editing = target?.closest(
+                "input,textarea,select,[contenteditable=true]",
+            );
+            const command =
+                (event.ctrlKey || event.metaKey) &&
+                !event.altKey &&
+                event.key.toLowerCase() === "k";
+            const slash =
+                event.key === "/" &&
+                !event.ctrlKey &&
+                !event.metaKey &&
+                !event.altKey;
+            if (
+                (!command && !slash) ||
+                (editing && !(command && target === searchInput.current))
+            )
+                return;
+            event.preventDefault();
+            revealSearch(command);
+        };
+        window.addEventListener("keydown", shortcut);
+        return () => {
+            clearTimeout(searchTimer.current);
+            window.removeEventListener("keydown", shortcut);
+        };
+    }, [authenticated, isPublic, searchLabel, revealSearch]);
+    useEffect(() => {
+        listingRefresh.current?.request();
+    }, [refresh]);
+    useEffect(() => {
+        if (
+            databaseRestore.phase !== "idle" ||
+            config.recovery_only ||
+            (!authenticated && !isPublic) ||
+            !isFiles
+        ) {
+            loadedListing.current = null;
+            setLoading(false);
+            return;
+        }
+        const controller = new AbortController();
+        // Keep the current table mounted when uploads update the same listing.
+        let retryTimer: ReturnType<typeof setTimeout> | undefined;
+        const retryNotice =
+            "Could not update your files. Retrying automatically.";
+        const queue = createListingRefreshQueue(async () => {
+            clearTimeout(retryTimer);
+            const background = loadedListing.current === listingKey;
+            if (!background) loadedListing.current = null;
+            setLoading(!background);
+            setLoadError("");
+            const resultPromise =
+                view === "starred"
+                    ? api.starred(scopedQuery, controller.signal)
+                    : view === "trash"
+                      ? api.trash(scopedQuery, controller.signal)
+                      : isSearch && !isPublic
+                        ? api
+                              .search(
+                                  currentPath.slice(8),
+                                  searchOffset,
+                                  searchSort === "modified"
+                                      ? "date"
+                                      : searchSort,
+                                  controller.signal,
+                                  searchOrder,
+                              )
+                              .then((result) => {
+                                  if (!controller.signal.aborted) {
+                                      setSearchMore(result.has_more);
+                                      setNextSearchOffset(result.next_offset);
+                                      setSearchItems((previous) =>
+                                          reconcileDriveItems(
+                                              previous,
+                                              result.items,
+                                          ),
+                                      );
+                                      if (
+                                          !result.items.length &&
+                                          searchOffset > 0
+                                      )
+                                          setSearchOffset(0);
+                                  }
+                                  return {
+                                      data: {
+                                          name: "Search Results",
+                                          contents: Object.fromEntries(
+                                              result.items.map((item) => [
+                                                  item.id,
+                                                  item,
+                                              ]),
+                                          ),
+                                      } as Directory,
+                                      auth_home_path: undefined,
+                                  };
+                              })
+                        : api.directory(
+                              currentPath,
+                              location.auth,
+                              controller.signal,
+                          );
+            return await resultPromise
+                .then((result) => {
+                    if (controller.signal.aborted) return false;
+                    loadedListing.current = listingKey;
+                    setToast((current) =>
+                        current?.message === retryNotice ? null : current,
+                    );
+                    setDirectory((previous) =>
+                        reconcileDirectory(previous, result.data),
+                    );
+                    setShareRoot(result.auth_home_path || "");
+                    if (result.data.name)
+                        names.current.set(currentPath, result.data.name);
+                    return true;
+                })
+                .catch((error) => {
+                    if (controller.signal.aborted) return false;
+                    if (error.name !== "AbortError") {
+                        if (
+                            background &&
+                            (!error.status ||
+                                error.status === 408 ||
+                                error.status === 429 ||
+                                error.status >= 500)
+                        ) {
+                            notify(retryNotice, true);
+                            retryTimer = setTimeout(reload, 3000);
+                            return false;
+                        }
+                        loadedListing.current = null;
+                        if (isSearch) {
+                            setSearchItems([]);
+                            setSearchMore(false);
+                            setNextSearchOffset(null);
+                        }
+                        setLoadError(
+                            isPublic &&
+                                (error.status === 401 || error.status === 403)
+                                ? "This link has expired, was revoked, or is not valid. Ask the owner for a new link."
+                                : errorMessage(error),
+                        );
+                        setDirectory({ contents: {} });
+                    }
+                    return false;
+                })
+                .finally(() => {
+                    if (!controller.signal.aborted) setLoading(false);
+                });
+        });
+        listingRefresh.current = queue;
+        queue.request();
+        return () => {
+            controller.abort();
+            queue.dispose();
+            if (listingRefresh.current === queue) listingRefresh.current = null;
+            clearTimeout(retryTimer);
+        };
+    }, [
+        authenticated,
+        isPublic,
+        isFiles,
+        isSearch,
+        currentPath,
+        location.auth,
+        searchOffset,
+        searchSort,
+        searchOrder,
+        scopedQuery,
+        listingKey,
+        notify,
+        config.recovery_only,
+        databaseRestore.phase,
+        reload,
+    ]);
+    useEffect(() => {
+        if (
+            config.recovery_only ||
+            databaseRestore.phase !== "idle" ||
+            !isFiles ||
+            isSearch ||
+            view === "trash" ||
+            view === "starred"
+        )
+            return;
+        let cancelled = false;
+        const realPath = isPublic
+            ? "/" + currentPath.slice(7).replace(/^\/+/, "")
+            : currentPath;
+        const segments = realPath.split("/").filter(Boolean);
+        let start = 0;
+        const base = [ROOT_CRUMB];
+        if (isPublic) {
+            const root = shareRoot || realPath;
+            start = root.split("/").filter(Boolean).length;
+            base[0] = {
+                path: "/share_" + root.replace(/^\/+/, ""),
+                name: "Shared Files",
+            };
+        }
+        const paths = segments
+            .map((_, index) => "/" + segments.slice(0, index + 1).join("/"))
+            .slice(start);
+        void Promise.all(
+            paths.map(async (path) => {
+                const navPath = isPublic ? "/share_" + path.slice(1) : path;
+                let name = names.current.get(navPath);
+                if (!name) {
+                    try {
+                        const result = await api.directory(
+                            navPath,
+                            location.auth,
+                        );
+                        name = result.data.name || "Folder";
+                        names.current.set(navPath, name);
+                    } catch {
+                        name = "Folder";
+                    }
+                }
+                return { path: navPath, name };
+            }),
+        ).then((result) => {
+            if (!cancelled) setCrumbs([...base, ...result]);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [
+        currentPath,
+        isPublic,
+        isSearch,
+        isFiles,
+        view,
+        shareRoot,
+        config.recovery_only,
+        databaseRestore.phase,
+        location.auth,
+        directory.name,
+    ]);
+    useEffect(() => {
+        if (!location.previewId || loading || view !== "files") return;
+        const item = directory.contents[location.previewId];
+        if (item?.type === "file") setDialog({ type: "preview", item });
+    }, [location.previewId, directory.contents, loading, view]);
+    const closeDialog = () => {
+        if (dialog?.type !== "preview") {
+            if (dialog?.type === "share") reload();
+            setDialog(null);
+            return;
+        }
+        setDialog(null);
+        if (window.history.state?.tgdrivePreview) {
+            window.history.back();
+        } else {
+            const url = new URL(window.location.href);
+            url.searchParams.delete("preview");
+            window.history.replaceState({}, "", url.pathname + url.search);
+            setLocation(getLocation());
+        }
+    };
+    const title =
+        view === "starred"
+            ? "Starred"
+            : view === "preloads"
+              ? "Preloads"
+              : view === "performance"
+                ? "Performance"
+                : view === "trash"
+                  ? "Trash"
+                  : view === "activity"
+                    ? "Transfers"
+                    : view === "shares"
+                      ? "Shared Links"
+                      : view === "connections"
+                        ? "Connections"
+                        : view === "storage"
+                          ? "Storage & Backups"
+                          : view === "settings"
+                            ? ADMIN_SETTING_TITLES[location.settingsSection] ||
+                              "Settings"
+                            : isSearch
+                              ? "Search Results"
+                              : isPublic
+                                ? directory.name && directory.name !== "/"
+                                    ? directory.name
+                                    : "Shared Files"
+                                : currentPath === "/"
+                                  ? "My Files"
+                                  : directory.name || "Folder";
+    useEffect(() => {
+        document.title =
+            (config.recovery_only ? "Storage recovery" : title) + " · TGDrive";
+    }, [title, config.recovery_only]);
+    const destination = isSearch || view === "trash" ? "/" : currentPath;
+    const addFiles = (files: File[]) => {
+        if (!authenticated || isPublic) return;
+        if (admissionPaused) {
+            notify(
+                "Restart TGDrive to apply the saved connection changes before uploading.",
+                true,
+            );
+            return;
+        }
+        const rejected = transfers.add(
+            files,
+            destination,
+            config.max_file_size || Number.MAX_SAFE_INTEGER,
+        );
+        if (rejected.length) notify(rejected.join("; "), true);
+        setNewOpen(false);
+    };
+    const pickFiles = () => {
+        setNewOpen(false);
+        if (admissionPaused) {
+            notify(
+                "Restart TGDrive to apply the saved connection changes before uploading.",
+                true,
+            );
+            return;
+        }
+        if (destination !== currentPath)
+            notify("Files will be uploaded to My Files.");
+        fileInput.current?.click();
+    };
+    const pickFolder = () => {
+        if (!authenticated || isPublic) return;
+        if (admissionPaused) {
+            notify(
+                "Restart TGDrive to apply the saved connection changes before uploading.",
+                true,
+            );
+            return;
+        }
+        setNewOpen(false);
+        folderDestination.current = {
+            path: destination,
+            name:
+                destination === currentPath && view === "files" && !isSearch
+                    ? title
+                    : "My Files",
+        };
+        if (!folderSupported) {
+            setFolderSelection({
+                files: [],
+                destination,
+                name: folderDestination.current.name,
+            });
+            return;
+        }
+        folderInput.current?.click();
+    };
+    const locateTransfer = async (item: Transfer, folder = false) => {
+        if (item.state !== "completed") return;
+        try {
+            const destination = folder
+                ? transferFolderDestination(item)
+                : item.destination;
+            const target = await api.transferLocation(
+                folder ? undefined : item.jobId,
+                destination,
+                !folder && item.state === "completed",
+            );
+            if (!target.available || !target.folder_path) {
+                notify(
+                    target.reason || "Location is no longer available",
+                    true,
+                );
+                return;
+            }
+            let parent = target.folder_path;
+            let highlight = target.item_id || "";
+            if (folder && parent !== "/") {
+                highlight = parent.split("/").pop() || "";
+                parent = parent.slice(0, parent.lastIndexOf("/")) || "/";
+            }
+            navigate(parent, "files", "", false, {
+                tgdriveHighlight: highlight,
+                tgdriveReveal: true,
+            });
+        } catch (cause) {
+            notify(errorMessage(cause), true);
+        }
+    };
+    const open = (item: DriveItem) => {
+        if (item.type === "folder")
+            navigate(
+                isPublic
+                    ? "/share_" + itemPath(item).replace(/^\/+/, "")
+                    : itemPath(item),
+                "files",
+                location.auth,
+            );
+        else {
+            const url = new URL(window.location.href);
+            url.searchParams.set("preview", item.id);
+            window.history.pushState(
+                { ...window.history.state, tgdrivePreview: true },
+                "",
+                url.pathname + url.search,
+            );
+            setLocation(getLocation());
+            setDialog({ type: "preview", item });
+        }
+    };
+    const action = async (
+        type: "trash" | "restore" | "delete",
+        targets: DriveItem[],
+        allowPublic = false,
+    ) => {
+        try {
+            const response = await api.bulk(
+                targets.map(itemPath),
+                type,
+                allowPublic,
+            );
+            if (type === "delete") {
+                const names = new Map(
+                    targets.map((item) => [itemPath(item), item.name]),
+                );
+                transfers.trackDeletions(
+                    (response.results || []).flatMap((result) =>
+                        result.id
+                            ? [
+                                  {
+                                      id: result.id,
+                                      name: names.get(result.path) || "Item",
+                                  },
+                              ]
+                            : [],
+                    ),
+                );
+            }
+            const failed =
+                response.results?.filter(
+                    (result) => result.error || result.status === "error",
+                ) || [];
+            if (failed.length)
+                throw new Error(
+                    failed.length +
+                        " item(s) could not be processed. " +
+                        (failed[0].error || "Refresh and try again."),
+                );
+            notify(
+                type === "trash"
+                    ? "Moved to trash. Public access has been removed."
+                    : type === "restore"
+                      ? "Restored to your drive."
+                      : "Deletion started.",
+            );
+            reload();
+        } catch (error) {
+            if (
+                type === "restore" &&
+                error instanceof ApiError &&
+                error.code.includes("PUBLIC_EXPOSURE")
+            )
+                setDialog({ type: "restore", items: targets });
+            else if (type !== "delete" && !allowPublic)
+                notify(errorMessage(error), true);
+            reload();
+            throw error;
+        }
+    };
+    const clearSearch = () => {
+        clearTimeout(searchTimer.current);
+        setQuery("");
+        setScopedQuery("");
+        setSearchOffset(0);
+        if (view === "files" && isSearch) {
+            const origin = searchOrigin.current || lastFolder.current;
+            searchOrigin.current = null;
+            ownSearchNavigation.current = null;
+            navigate(origin, "files", "", true);
+        }
+        searchInput.current?.focus();
+    };
+    const applySearch = (raw: string, commit = false) => {
+        const term = raw.trim().normalize("NFC");
+        if (!term) {
+            clearSearch();
+            return;
+        }
+        if ([...term].length > 255) {
+            notify("Search names with at most 255 characters.", true);
+            return;
+        }
+        if (view !== "files") {
+            setScopedQuery(term);
+            return;
+        }
+        const path = "/search_" + term;
+        if (path === currentPath && view === "files") return;
+        if (!isSearch)
+            searchOrigin.current =
+                view === "files" ? currentPath : lastFolder.current;
+        const origin = searchOrigin.current || "/";
+        ownSearchNavigation.current = path;
+        setSearchOffset(0);
+        navigate(path, "files", "", isSearch && !commit, {
+            tgdriveSearchOrigin: origin,
+        });
+    };
+    const changeSearch = (value: string) => {
+        setQuery(value);
+        clearTimeout(searchTimer.current);
+        if (searchComposing.current) return;
+        if (!value.trim()) {
+            clearSearch();
+            return;
+        }
+        searchTimer.current = setTimeout(() => applySearch(value), 300);
+    };
+    const onSearch = (event: FormEvent) => {
+        event.preventDefault();
+        if (searchComposing.current) return;
+        clearTimeout(searchTimer.current);
+        applySearch(query, true);
+    };
+    const navigationLink = (item: {
+        view: View;
+        label: string;
+        icon: typeof HardDrive;
+        path?: string;
+        section?: string;
+    }) => {
+        const params = new URLSearchParams();
+        if (item.view === "trash") params.set("path", "/trash");
+        else if (item.view !== "files") params.set("view", item.view);
+        if (item.section) params.set("section", item.section);
+        const current =
+            view === item.view &&
+            (item.view !== "settings" ||
+                location.settingsSection === (item.section || "cache"));
+        return (
+            <a
+                key={item.label}
+                href={"/" + (params.size ? "?" + params.toString() : "")}
+                aria-current={current ? "page" : undefined}
+                onClick={(event) => {
+                    event.preventDefault();
+                    navigate(
+                        item.path || "/",
+                        item.view,
+                        "",
+                        false,
+                        {},
+                        item.section,
+                    );
+                }}
+            >
+                <item.icon size={19} aria-hidden="true" />
+                <span>{item.label}</span>
+                {item.view === "activity" && activeCount > 0 && (
+                    <span className="nav-count">{activeCount}</span>
+                )}
+            </a>
+        );
+    };
+    const pageHeading = (
+        <div className="page-heading">
+            <div>
+                {isFiles &&
+                    !isSearch &&
+                    view !== "trash" &&
+                    view !== "starred" &&
+                    crumbs.length > 1 && (
+                        <nav className="breadcrumbs" aria-label="Breadcrumb">
+                            {crumbs.slice(0, -1).map((crumb, index) => (
+                                <span key={crumb.path}>
+                                    {index > 0 && (
+                                        <ChevronRight
+                                            size={14}
+                                            aria-hidden="true"
+                                        />
+                                    )}
+                                    <a
+                                        href={
+                                            "/?" +
+                                            new URLSearchParams({
+                                                path: crumb.path,
+                                                ...(location.auth
+                                                    ? { auth: location.auth }
+                                                    : {}),
+                                            })
+                                        }
+                                        onClick={(event) => {
+                                            event.preventDefault();
+                                            navigate(
+                                                crumb.path,
+                                                "files",
+                                                location.auth,
+                                            );
+                                        }}
+                                        aria-current={
+                                            index === crumbs.length - 1
+                                                ? "page"
+                                                : undefined
+                                        }
+                                    >
+                                        {crumb.name}
+                                    </a>
+                                </span>
+                            ))}
+                        </nav>
+                    )}
+                <div className="page-title-line">
+                    <h1>{title}</h1>
+                    {config.demo_data && (
+                        <span
+                            className="demo-marker"
+                            title="Synthetic local preview content and metrics"
+                        >
+                            Demo
+                        </span>
+                    )}
+                </div>
+                {isSearch && (
+                    <p className="page-subtitle">
+                        Files and folders matching “{currentPath.slice(8)}”
+                        across your drive
+                    </p>
+                )}
+                {view === "trash" && (
+                    <p className="page-subtitle">
+                        Trashed items cannot be opened through public links.
+                    </p>
+                )}
+            </div>
+            {!isPublic && searchLabel && mobile && (
+                <button
+                    ref={searchTrigger}
+                    type="button"
+                    className="icon-button compact-search-trigger"
+                    aria-label={searchLabel}
+                    aria-controls="page-search-form"
+                    aria-expanded={searchExpanded || Boolean(query)}
+                    onClick={() => revealSearch()}
+                >
+                    <Search size={19} aria-hidden="true" />
+                </button>
+            )}
+            {!isPublic && searchLabel && (
+                <form
+                    id="page-search-form"
+                    hidden={mobile && !searchExpanded && !query}
+                    className={
+                        "search-form" +
+                        (isSearch && loading ? " search-pending" : "")
+                    }
+                    role="search"
+                    aria-label={searchLabel}
+                    onSubmit={onSearch}
+                    onBlur={(event) => {
+                        if (
+                            mobile &&
+                            !query &&
+                            !event.currentTarget.contains(event.relatedTarget)
+                        )
+                            setSearchExpanded(false);
+                    }}
+                    aria-busy={isSearch && loading}
+                >
+                    <button
+                        type="submit"
+                        className="icon-button"
+                        aria-label="Search"
+                    >
+                        <Search size={18} aria-hidden="true" />
+                    </button>
+                    <label className="sr-only" htmlFor="file-search">
+                        {searchLabel}
+                    </label>
+                    <input
+                        id="file-search"
+                        ref={searchInput}
+                        type="search"
+                        maxLength={255}
+                        aria-describedby="search-help"
+                        value={query}
+                        onFocus={() => setSearchExpanded(true)}
+                        onChange={(event) => changeSearch(event.target.value)}
+                        onCompositionStart={() => {
+                            searchComposing.current = true;
+                            clearTimeout(searchTimer.current);
+                        }}
+                        onCompositionEnd={(event) => {
+                            searchComposing.current = false;
+                            changeSearch(event.currentTarget.value);
+                        }}
+                        onKeyDown={(event) => {
+                            if (
+                                event.key === "Escape" &&
+                                !searchComposing.current
+                            ) {
+                                event.preventDefault();
+                                clearSearch();
+                                if (mobile) {
+                                    requestedSearchFocus.current = null;
+                                    setSearchExpanded(false);
+                                    searchTrigger.current?.focus();
+                                }
+                            }
+                        }}
+                        placeholder={searchLabel}
+                    />
+                    <span id="search-help" className="sr-only">
+                        {view === "files"
+                            ? "Search names across your drive. Press Escape to return to the previous folder."
+                            : "Search this page. Press Escape to clear the search."}
+                    </span>
+                    {mobile && !query && (
+                        <button
+                            className="icon-button"
+                            type="button"
+                            aria-label="Close Search"
+                            onClick={() => {
+                                requestedSearchFocus.current = null;
+                                setSearchExpanded(false);
+                                searchTrigger.current?.focus();
+                            }}
+                        >
+                            <X size={17} aria-hidden="true" />
+                        </button>
+                    )}
+                    {query && (
+                        <button
+                            className="icon-button"
+                            type="button"
+                            aria-label="Clear Search"
+                            onClick={clearSearch}
+                        >
+                            <X size={17} />
+                        </button>
+                    )}
+                </form>
+            )}
+            {!mobile && <ThemeControl />}
+        </div>
+    );
+    const configGate = (
+        <div
+            className="deployment-config-state settings-section"
+            role={configLoad === "error" ? "alert" : "status"}
+            aria-busy={configLoad === "loading"}
+        >
+            {configLoad === "error" ? (
+                <>
+                    <p>
+                        Configuration and management are unavailable until
+                        TGDrive’s configuration can be loaded. You can continue
+                        using file features.
+                    </p>
+                    <p className="settings-help">{configError}</p>
+                    <button
+                        type="button"
+                        className="secondary-button"
+                        onClick={() => void loadConfig()}
+                    >
+                        Try Again
+                    </button>
+                </>
+            ) : (
+                <p>
+                    <Spinner /> Loading configuration…
+                </p>
+            )}
+        </div>
+    );
+    if (
+        !isPublic &&
+        (databaseRestore.phase === "restored" ||
+            databaseRestore.phase === "restart_required")
+    )
+        return (
+            <div className="channel-recovery-shell">
+                <header className="channel-recovery-topbar">
+                    <a href="/" className="brand">
+                        <BrandLogo />
+                    </a>
+                    <ThemeControl />
+                </header>
+                <main
+                    id="main-content"
+                    className="channel-recovery-main"
+                    tabIndex={-1}
+                >
+                    <h1>Storage recovery</h1>
+                    <DatabaseRestoreResult
+                        error={
+                            databaseRestore.phase === "restart_required"
+                                ? databaseRestore.message
+                                : ""
+                        }
+                    />
+                </main>
+            </div>
+        );
+    if (authenticated === null && !isPublic)
+        return (
+            <div className="startup" role="status">
+                <BrandLogo size="large" />
+                <span className="startup-status">
+                    <Spinner /> Opening TGDrive…
+                </span>
+            </div>
+        );
+    if (authenticated === false && !isPublic)
+        return (
+            <>
+                <Login
+                    onSuccess={() => {
+                        setConfigLoad("loading");
+                        setConfigReady(false);
+                        void loadConfig();
+                        setAuthenticated(true);
+                        reload();
+                        setToast(null);
+                    }}
+                />
+                {toast && <Toast toast={toast} close={() => setToast(null)} />}
+            </>
+        );
+    if (config.recovery_only && !isPublic)
+        return (
+            <div className="channel-recovery-shell">
+                <header className="channel-recovery-topbar">
+                    <a href="/" className="brand">
+                        <BrandLogo />
+                    </a>
+                    <div>
+                        <ThemeControl />
+                        <SidebarLogout onLoggedOut={endSession} />
+                    </div>
+                </header>
+                <main id="main-content" className="channel-recovery-main">
+                    <h1>Storage recovery</h1>
+                    <p className="channel-recovery-intro">
+                        Your MongoDB catalog needs recovery. File changes are
+                        paused while you restore it.
+                    </p>
+                    {configLoad === "ready" ? (
+                        <>
+                            <ChannelBackup
+                                recoveryOnly
+                                demoMode={demoReadOnly}
+                                onNotice={notify}
+                            />
+                            <DatabaseRestore
+                                demoMode={demoReadOnly}
+                                onRestoreStateChange={databaseRestoreChanged}
+                            />
+                        </>
+                    ) : (
+                        configGate
+                    )}
+                </main>
+                {toast && <Toast toast={toast} close={() => setToast(null)} />}
+            </div>
+        );
+    return (
+        <div className={"app-shell " + (isPublic ? "public-shell" : "")}>
+            <a className="skip-link" href="#main-content">
+                Skip to Files
+            </a>
+            {!isPublic && (
+                <aside
+                    id="drive-navigation"
+                    role={mobile && mobileNav ? "dialog" : undefined}
+                    aria-modal={mobile && mobileNav ? true : undefined}
+                    className={"sidebar " + (mobileNav ? "nav-open" : "")}
+                    aria-label="Drive navigation"
+                    inert={mobile && !mobileNav}
+                >
+                    <a
+                        className="brand"
+                        href="/"
+                        onClick={(event) => {
+                            event.preventDefault();
+                            navigate("/");
+                        }}
+                    >
+                        <BrandLogo />
+                    </a>
+                    {mobile && (
+                        <div className="mobile-nav-heading">
+                            <span className="mobile-drawer-brand">
+                                <BrandLogo />
+                            </span>
+                            <button
+                                className="icon-button"
+                                aria-label="Close Navigation"
+                                onClick={() => setMobileNav(false)}
+                            >
+                                <X size={20} aria-hidden="true" />
+                            </button>
+                        </div>
+                    )}
+                    <button
+                        id="new-button"
+                        disabled={admissionPaused}
+                        className="new-button"
+                        aria-expanded={newOpen}
+                        aria-controls="new-menu"
+                        onClick={() => {
+                            if (view !== "files") {
+                                navigate("/", "files");
+                                setNewOpen(true);
+                            } else setNewOpen(!newOpen);
+                        }}
+                    >
+                        <Plus size={23} /> New
+                    </button>
+                    <nav className="drive-nav">
+                        {navigationLink({
+                            view: "files",
+                            label: "My Files",
+                            icon: FolderClosed,
+                        })}
+                        {navigationLink({
+                            view: "starred",
+                            label: "Starred",
+                            icon: Star,
+                        })}
+                        {navigationLink({
+                            view: "activity",
+                            label: "Transfers",
+                            icon: ArrowDownUp,
+                        })}
+                        {navigationLink({
+                            view: "shares",
+                            label: "Shared Links",
+                            icon: Link,
+                        })}
+                        {navigationLink({
+                            view: "trash",
+                            label: "Trash",
+                            icon: Trash2,
+                            path: "/trash",
+                        })}
+                        <details
+                            className="sidebar-tools"
+                            open={toolsOpen}
+                            onToggle={(event) =>
+                                setToolsOpen(event.currentTarget.open)
+                            }
+                        >
+                            <summary
+                                id="tools-settings-summary"
+                                aria-controls="tools-settings-content"
+                            >
+                                <SlidersHorizontal
+                                    size={19}
+                                    aria-hidden="true"
+                                />
+                                <span>Tools & settings</span>
+                                <ChevronRight
+                                    className="nav-disclosure"
+                                    size={16}
+                                    aria-hidden="true"
+                                />
+                            </summary>
+                            <div
+                                className="sidebar-tools-content"
+                                id="tools-settings-content"
+                                role="group"
+                                aria-labelledby="tools-settings-summary"
+                            >
+                                <div
+                                    className="monitor-nav"
+                                    role="group"
+                                    aria-label="Monitor"
+                                >
+                                    <span className="nav-section-label">
+                                        Monitor
+                                    </span>
+                                    {navigationLink({
+                                        view: "performance",
+                                        label: "Performance",
+                                        icon: ChartNoAxesCombined,
+                                    })}
+                                    {navigationLink({
+                                        view: "preloads",
+                                        label: "Preloads",
+                                        icon: Server,
+                                    })}
+                                </div>
+                                <div
+                                    className="admin-nav"
+                                    role="group"
+                                    aria-label="Configuration"
+                                >
+                                    <span className="nav-section-label">
+                                        Configuration
+                                    </span>
+                                    {navigationLink({
+                                        view: "settings",
+                                        section: "cache",
+                                        label: "Cache settings",
+                                        icon: Database,
+                                    })}
+                                    {navigationLink({
+                                        view: "settings",
+                                        section: "transfers",
+                                        label: "Transfer limits",
+                                        icon: Gauge,
+                                    })}
+                                    {navigationLink({
+                                        view: "settings",
+                                        section: "regional",
+                                        label: "Timezone",
+                                        icon: Globe,
+                                    })}
+                                </div>
+                                <div
+                                    className="admin-nav"
+                                    role="group"
+                                    aria-label="Management"
+                                >
+                                    <span className="nav-section-label">
+                                        Management
+                                    </span>
+                                    {navigationLink({
+                                        view: "connections",
+                                        label: "Connections",
+                                        icon: Plug,
+                                    })}
+                                    {navigationLink({
+                                        view: "storage",
+                                        label: "Storage & Backups",
+                                        icon: ShieldCheck,
+                                    })}
+                                </div>
+                            </div>
+                        </details>
+                    </nav>
+                    <div className="sidebar-bottom">
+                        {config.demo_data && (
+                            <small className="demo-data-label">
+                                Local demo · sample content & metrics
+                            </small>
+                        )}
+                        <div className="sidebar-support">
+                            <a
+                                className="sidebar-help"
+                                href="https://github.com/TechShreyash/TGDrive/blob/main/docs/README.md"
+                                target="_blank"
+                                rel="noopener noreferrer"
+                            >
+                                <BookOpen size={18} aria-hidden="true" />{" "}
+                                Documentation
+                            </a>
+                            <a
+                                className="sidebar-project"
+                                href="https://github.com/TechShreyash/TGDrive"
+                                target="_blank"
+                                rel="noopener noreferrer"
+                                aria-label="TGDrive on GitHub"
+                                title="View TGDrive on GitHub"
+                            >
+                                <GitHubMark />
+                            </a>
+                        </div>
+                        <SidebarLogout
+                            onLoggedOut={() => {
+                                setMobileNav(false);
+                                setNewOpen(false);
+                                endSession();
+                                notify(
+                                    "Logged out. Server transfers continue.",
+                                );
+                            }}
+                        />
+                    </div>
+                </aside>
+            )}
+            {mobile && mobileNav && (
+                <button
+                    className="nav-dismiss"
+                    tabIndex={-1}
+                    aria-label="Close Navigation"
+                    onClick={() => setMobileNav(false)}
+                />
+            )}
+            <main
+                id="main-content"
+                className="main-content"
+                tabIndex={-1}
+                inert={mobile && mobileNav}
+                onDragOver={(event) => {
+                    if (event.dataTransfer.types.includes("Files"))
+                        event.preventDefault();
+                }}
+                onDrop={(event) => {
+                    if (!event.dataTransfer.files.length) return;
+                    event.preventDefault();
+                    if (isPublic) return;
+                    if (
+                        view !== "files" ||
+                        isSearch ||
+                        dialog ||
+                        folderSelection
+                    ) {
+                        notify(
+                            "Open a folder in My Files before dropping files.",
+                            true,
+                        );
+                        return;
+                    }
+                    if (
+                        Array.from(event.dataTransfer.items).some(
+                            (item) => item.webkitGetAsEntry?.()?.isDirectory,
+                        )
+                    ) {
+                        notify(
+                            "Use New → Upload Folder to keep the folder structure.",
+                            true,
+                        );
+                        return;
+                    }
+                    addFiles(Array.from(event.dataTransfer.files));
+                }}
+            >
+                <header className="topbar" hidden={!mobile && !isPublic}>
+                    {isPublic ? (
+                        <a href="/" className="brand">
+                            <BrandLogo />
+                        </a>
+                    ) : (
+                        <>
+                            <button
+                                id="navigation-toggle"
+                                className="icon-button mobile-menu"
+                                aria-controls="drive-navigation"
+                                aria-label="Toggle Navigation"
+                                aria-expanded={mobileNav}
+                                onClick={() => setMobileNav(!mobileNav)}
+                            >
+                                <Menu size={22} />
+                            </button>
+                        </>
+                    )}
+                    {mobile && !isPublic && (
+                        <>
+                            <a
+                                className="mobile-brand"
+                                href="/"
+                                onClick={(event) => {
+                                    event.preventDefault();
+                                    navigate("/");
+                                }}
+                            >
+                                <BrandLogo size="compact" />
+                            </a>
+                            {view === "files" && !isSearch && !dialog && (
+                                <button
+                                    id="compact-new-button"
+                                    disabled={admissionPaused}
+                                    className="mobile-new primary-button"
+                                    onClick={() => setNewOpen(!newOpen)}
+                                    aria-expanded={newOpen}
+                                    aria-controls="new-menu"
+                                >
+                                    <Plus size={18} /> New
+                                </button>
+                            )}
+                        </>
+                    )}
+                    {mobile && <ThemeControl />}
+                    {isPublic && (
+                        <span className="public-label">
+                            <Globe size={16} /> Read-Only Shared Folder
+                        </span>
+                    )}
+                </header>
+                <section
+                    ref={workspace}
+                    className={"workspace" + (isFiles ? " file-workspace" : "")}
+                    aria-label={title}
+                >
+                    {!isPublic && admissionPaused && (
+                        <div className="restart-required-banner" role="status">
+                            <ShieldAlert size={20} />
+                            <div>
+                                <strong>
+                                    Restart TGDrive to apply connection changes
+                                </strong>
+                                <p>
+                                    File changes and new uploads are paused. You
+                                    can still browse, preview and download.
+                                </p>
+                            </div>
+                            {view !== "connections" && (
+                                <button
+                                    type="button"
+                                    className="text-button"
+                                    onClick={() => navigate("/", "connections")}
+                                >
+                                    Open Connections
+                                </button>
+                            )}
+                        </div>
+                    )}
+                    {!isPublic && telegramWarning && (
+                        <div className="restart-required-banner" role="status">
+                            <ShieldAlert size={20} />
+                            <div>
+                                <strong>
+                                    A Telegram connection needs attention
+                                </strong>
+                                <p>{telegramWarning}</p>
+                            </div>
+                            {view !== "connections" && (
+                                <button
+                                    type="button"
+                                    className="text-button"
+                                    onClick={() => navigate("/", "connections")}
+                                >
+                                    Open Connections
+                                </button>
+                            )}
+                        </div>
+                    )}
+                    {!isFiles && pageHeading}
+                    {!isPublic && view === "trash" && (
+                        <DeletionNotice
+                            jobs={deletionProgress.jobs}
+                            completed={deletionProgress.completed}
+                            progressError={deletionProgress.error}
+                        />
+                    )}
+                    {isFiles ? (
+                        <FileBrowser
+                            header={pageHeading}
+                            searchQuery={
+                                ["trash", "starred"].includes(view)
+                                    ? scopedQuery
+                                    : ""
+                            }
+                            directory={directory}
+                            listingKey={listingKey}
+                            refresh={refresh}
+                            highlightId={location.highlightId}
+                            loading={loading}
+                            refreshing={listingRefreshAction.refreshing}
+                            error={loadError}
+                            isPublic={isPublic}
+                            isTrash={view === "trash"}
+                            isStarred={view === "starred"}
+                            onStar={(item) => {
+                                void api
+                                    .star(itemPath(item), !item.starred)
+                                    .then(() => {
+                                        notify(
+                                            item.starred
+                                                ? "Removed from Starred."
+                                                : "Added to Starred.",
+                                        );
+                                        reload();
+                                    })
+                                    .catch((error) =>
+                                        notify(errorMessage(error), true),
+                                    );
+                            }}
+                            isSearch={isSearch}
+                            auth={location.auth}
+                            onReload={() =>
+                                void listingRefreshAction.run(
+                                    async () =>
+                                        listingRefresh.current?.request() ??
+                                        false,
+                                    view === "trash"
+                                        ? "Trash refreshed."
+                                        : view === "starred"
+                                          ? "Starred files refreshed."
+                                          : "Files refreshed.",
+                                )
+                            }
+                            onUpload={pickFiles}
+                            onOpen={open}
+                            onDialog={setDialog}
+                            onAction={(type, targets) =>
+                                void action(type, targets).catch(() => {})
+                            }
+                            searchPagination={
+                                isSearch
+                                    ? {
+                                          offset: searchOffset,
+                                          hasMore: searchMore,
+                                          onPrevious: () =>
+                                              setSearchOffset(
+                                                  Math.max(
+                                                      0,
+                                                      searchOffset - 100,
+                                                  ),
+                                              ),
+                                          onNext: () => {
+                                              if (nextSearchOffset !== null)
+                                                  setSearchOffset(
+                                                      nextSearchOffset,
+                                                  );
+                                          },
+                                      }
+                                    : undefined
+                            }
+                            searchItems={isSearch ? searchItems : undefined}
+                            searchSort={isSearch ? searchSort : undefined}
+                            searchOrder={isSearch ? searchOrder : undefined}
+                            onSearchOrder={(value) => {
+                                setSearchOrder(value);
+                                setSearchOffset(0);
+                            }}
+                            onSearchSort={(value) => {
+                                setSearchSort(value);
+                                setSearchOffset(0);
+                            }}
+                        />
+                    ) : view === "shares" ? (
+                        <SharesView
+                            query={scopedQuery}
+                            refresh={refresh}
+                            onError={(message) => notify(message, true)}
+                            onNotice={notify}
+                            onChange={reload}
+                            onLocate={(share) =>
+                                navigate(
+                                    share.folder_path ||
+                                        share.path.slice(
+                                            0,
+                                            share.path.lastIndexOf("/"),
+                                        ) ||
+                                        "/",
+                                    "files",
+                                    "",
+                                    false,
+                                    {
+                                        tgdriveHighlight:
+                                            share.node_id ||
+                                            share.path.split("/").pop(),
+                                        tgdriveReveal: true,
+                                    },
+                                )
+                            }
+                        />
+                    ) : view === "preloads" ? (
+                        <Preloads
+                            query={scopedQuery}
+                            onError={(message) => notify(message, true)}
+                            onNotice={notify}
+                        />
+                    ) : view === "performance" ? (
+                        <PerformancePanel onNotice={notify} />
+                    ) : ["connections", "storage", "settings"].includes(
+                          view,
+                      ) ? (
+                        !configReady ? (
+                            configGate
+                        ) : (
+                            <>
+                                {configLoad !== "ready" && configGate}
+                                <fieldset
+                                    style={{ display: "contents" }}
+                                    disabled={configLoad !== "ready"}
+                                    inert={configLoad !== "ready"}
+                                >
+                                    {view === "connections" ? (
+                                        <SettingsManagement
+                                            demoMode={demoReadOnly}
+                                            onNotice={notify}
+                                        />
+                                    ) : view === "storage" ? (
+                                        <StorageView
+                                            config={config}
+                                            demoMode={demoReadOnly}
+                                            onNotice={notify}
+                                            onTransfers={() =>
+                                                navigate("/", "activity")
+                                            }
+                                            onTrash={() =>
+                                                navigate("/trash", "trash")
+                                            }
+                                            onRestoreStateChange={
+                                                databaseRestoreChanged
+                                            }
+                                        />
+                                    ) : view === "settings" ? (
+                                        <PerformanceSettings
+                                            demoMode={demoReadOnly}
+                                            onNotice={notify}
+                                            category={
+                                                location.settingsSection ===
+                                                "transfers"
+                                                    ? "transfers"
+                                                    : location.settingsSection ===
+                                                        "regional"
+                                                      ? "regional"
+                                                      : "cache"
+                                            }
+                                            uploadPreferences={
+                                                <>
+                                                    <UploadSettings
+                                                        demoMode={demoReadOnly}
+                                                        onNotice={notify}
+                                                    />
+                                                    <BotModeSettings
+                                                        demoMode={demoReadOnly}
+                                                        onNotice={notify}
+                                                    />
+                                                </>
+                                            }
+                                            onSaved={(value) => {
+                                                setTimezone(value.timezone);
+                                                void loadConfig();
+                                                notify(
+                                                    "Performance settings saved.",
+                                                );
+                                                reload();
+                                            }}
+                                        />
+                                    ) : null}
+                                </fieldset>
+                            </>
+                        )
+                    ) : (
+                        <TransferHistory
+                            onNotice={notify}
+                            query={scopedQuery}
+                            items={items}
+                            onLocate={(item, folder) =>
+                                void locateTransfer(item, folder)
+                            }
+                            onError={(message) => notify(message, true)}
+                        />
+                    )}
+                </section>
+                {mobile &&
+                    !isPublic &&
+                    view !== "activity" &&
+                    (activeCount > 0 || mobileUploadIssues) && (
+                        <button
+                            className="mobile-transfer-status"
+                            onClick={() => navigate("/", "activity")}
+                            aria-label="Open transfer progress"
+                        >
+                            <Upload size={18} aria-hidden="true" />
+                            <span>
+                                {activeCount > 0
+                                    ? activeCount +
+                                      (activeCount === 1
+                                          ? " upload in progress"
+                                          : " uploads in progress")
+                                    : "Uploads need attention"}
+                            </span>
+                            <ChevronRight size={18} aria-hidden="true" />
+                        </button>
+                    )}
+            </main>
+            {!mobile &&
+                !isPublic &&
+                ["files", "trash", "shares"].includes(view) && (
+                    <TransferPanel
+                        pageContext={view}
+                        items={items}
+                        onLocate={(item, folder) =>
+                            void locateTransfer(item, folder)
+                        }
+                        onError={(message) => notify(message, true)}
+                    />
+                )}
+            {newOpen && (
+                <>
+                    <button
+                        className="menu-dismiss"
+                        aria-label="Close New Item Menu"
+                        onClick={() => setNewOpen(false)}
+                    />
+                    <div
+                        id="new-menu"
+                        className="new-menu"
+                        role="group"
+                        aria-label="New Item Actions"
+                    >
+                        <button id="file-upload-action" onClick={pickFiles}>
+                            <Upload size={18} /> Upload Files
+                        </button>
+                        <button id="folder-upload-action" onClick={pickFolder}>
+                            <FolderUp size={18} /> Upload Folder
+                        </button>
+                        <button
+                            onClick={() => {
+                                setDialog({ type: "folder" });
+                                setNewOpen(false);
+                            }}
+                        >
+                            <FolderPlus size={18} /> New Folder
+                        </button>
+                        <button
+                            onClick={() => {
+                                setDialog({ type: "url" });
+                                setNewOpen(false);
+                            }}
+                        >
+                            <Globe size={18} /> Upload from URL
+                        </button>
+                    </div>
+                </>
+            )}
+            <input
+                id="file-input"
+                ref={fileInput}
+                type="file"
+                multiple
+                hidden
+                onChange={(event) => {
+                    addFiles(Array.from(event.target.files || []));
+                    event.target.value = "";
+                }}
+            />
+            <input
+                id="folder-input"
+                ref={(node) => {
+                    folderInput.current = node;
+                    if (node) node.webkitdirectory = true;
+                }}
+                type="file"
+                multiple
+                hidden
+                aria-label="Choose Folder to Upload"
+                onChange={(event) => {
+                    const selected = Array.from(event.target.files || []);
+                    event.target.value = "";
+                    setFolderSelection({
+                        files: selected,
+                        destination: folderDestination.current.path,
+                        name: folderDestination.current.name,
+                    });
+                }}
+            />
+            {folderSelection && !isPublic && authenticated && (
+                <FolderUpload
+                    files={folderSelection.files}
+                    destination={folderSelection.destination}
+                    destinationName={folderSelection.name}
+                    maxSize={config.max_file_size || Number.MAX_SAFE_INTEGER}
+                    supported={folderSupported}
+                    onClose={() => setFolderSelection(null)}
+                    onChanged={reload}
+                    onFilesFallback={pickFiles}
+                    onQueued={(root, count) => {
+                        setFolderSelection(null);
+                        notify(
+                            count.toLocaleString() +
+                                " files queued in “" +
+                                root.name +
+                                "”. Track each file in Transfers.",
+                        );
+                    }}
+                />
+            )}
+            {dialog && (
+                <ActionDialog
+                    key={dialog.type + ("item" in dialog ? dialog.item.id : "")}
+                    dialog={dialog}
+                    destination={destination}
+                    auth={location.auth}
+                    onClose={closeDialog}
+                    onChanged={() => {
+                        reload();
+                        if (dialog.type !== "download-link") setDialog(null);
+                    }}
+                    onNotice={notify}
+                    onDelete={(targets) => action("delete", targets)}
+                    onRestore={(targets) => action("restore", targets, true)}
+                />
+            )}
+            {demoFilesReadOnly && (
+                <Modal
+                    title="Demo Files is read-only"
+                    initialFocus="#demo-files-dismiss"
+                    onClose={() => setDemoFilesReadOnly(false)}
+                >
+                    <p>
+                        Demo Files and its contents are read-only for demo
+                        visitors. You can open, preview and download them. Open
+                        My Files to upload files, create folders and try changes
+                        outside Demo Files.
+                    </p>
+                    <div className="dialog-actions">
+                        <button
+                            id="demo-files-dismiss"
+                            type="button"
+                            className="secondary-button"
+                            onClick={() => setDemoFilesReadOnly(false)}
+                        >
+                            Close
+                        </button>
+                        <button
+                            type="button"
+                            className="primary-button"
+                            onClick={() => {
+                                setDemoFilesReadOnly(false);
+                                navigate("/");
+                            }}
+                        >
+                            Open My Files
+                        </button>
+                    </div>
+                </Modal>
+            )}
+            {toast && <Toast toast={toast} close={() => setToast(null)} />}
+        </div>
+    );
+}
diff --git a/website/src/app/Login.tsx b/website/src/app/Login.tsx
new file mode 100644
index 00000000..3ef474f5
--- /dev/null
+++ b/website/src/app/Login.tsx
@@ -0,0 +1,86 @@
+import { useState, type FormEvent } from "react";
+import { ShieldCheck } from "lucide-react";
+import BrandLogo from "../shared/BrandLogo";
+import { api, errorMessage } from "../shared/api";
+import { ErrorNotice, Spinner } from "../shared/components";
+
+export default function Login({ onSuccess }: { onSuccess: () => void }) {
+    const [password, setPassword] = useState("");
+    const [shown, setShown] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    const submit = async (event: FormEvent) => {
+        event.preventDefault();
+        setBusy(true);
+        setError("");
+        try {
+            await api.login(password);
+            setPassword("");
+            onSuccess();
+        } catch (error) {
+            setError(errorMessage(error));
+        } finally {
+            setBusy(false);
+        }
+    };
+    return (
+        <main className="login-page">
+            <a href="/" className="brand">
+                <BrandLogo size="large" />
+            </a>
+            <section
+                id="login-dialog"
+                className="login-form"
+                aria-labelledby="login-title"
+            >
+                <ShieldCheck className="login-symbol" size={36} />
+                <h1 id="login-title">Your files, your space.</h1>
+                <p>Log in to your private drive.</p>
+                <form onSubmit={(event) => void submit(event)}>
+                    <label htmlFor="owner-password">Password</label>
+                    <div className="password-field">
+                        <input
+                            id="owner-password"
+                            autoFocus
+                            type={shown ? "text" : "password"}
+                            autoComplete="current-password"
+                            required
+                            value={password}
+                            onChange={(event) =>
+                                setPassword(event.target.value)
+                            }
+                            maxLength={512}
+                        />
+                        <button
+                            type="button"
+                            className="text-button"
+                            aria-pressed={shown}
+                            onClick={() => setShown(!shown)}
+                        >
+                            {shown ? "Hide" : "Show"}
+                        </button>
+                    </div>
+                    <ErrorNotice message={error} />
+                    <button
+                        className="primary-button full-width"
+                        disabled={busy}
+                    >
+                        {busy ? (
+                            <>
+                                <Spinner /> Logging in…
+                            </>
+                        ) : (
+                            "Log in"
+                        )}
+                    </button>
+                </form>
+                <p className="login-note">
+                    Use the owner password configured for this installation.
+                </p>
+            </section>
+            <p className="login-footer">
+                Private by default. Share only what you choose.
+            </p>
+        </main>
+    );
+}
diff --git a/website/src/app/SidebarLogout.tsx b/website/src/app/SidebarLogout.tsx
new file mode 100644
index 00000000..50b323be
--- /dev/null
+++ b/website/src/app/SidebarLogout.tsx
@@ -0,0 +1,50 @@
+import { useEffect, useRef, useState } from "react";
+import { LogOut } from "lucide-react";
+import { api, errorMessage } from "../shared/api";
+import { Spinner } from "../shared/components";
+
+export default function SidebarLogout({
+    onLoggedOut,
+}: {
+    onLoggedOut: () => void;
+}) {
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    const button = useRef<HTMLButtonElement>(null);
+    useEffect(() => {
+        if (error && !busy) button.current?.focus();
+    }, [error, busy]);
+    const logout = async () => {
+        if (busy) return;
+        setBusy(true);
+        setError("");
+        try {
+            await api.logout();
+            onLoggedOut();
+        } catch (cause) {
+            setError(errorMessage(cause));
+            setBusy(false);
+        }
+    };
+    return (
+        <>
+            <button
+                ref={button}
+                type="button"
+                className="sidebar-logout"
+                disabled={busy}
+                aria-busy={busy}
+                title="Log out of this browser. Server transfers continue."
+                onClick={() => void logout()}
+            >
+                {busy ? <Spinner /> : <LogOut size={18} />}
+                {busy ? "Logging out…" : "Log Out"}
+            </button>
+            {error && (
+                <p className="sidebar-logout-error" role="alert">
+                    {error}
+                </p>
+            )}
+        </>
+    );
+}
diff --git a/website/src/app/style.css b/website/src/app/style.css
new file mode 100644
index 00000000..82848213
--- /dev/null
+++ b/website/src/app/style.css
@@ -0,0 +1,3679 @@
+@font-face {
+    font-family: InterVariable;
+    src: url("/static/fonts/InterVariable.woff2") format("woff2");
+    font-style: normal;
+    font-weight: 100 900;
+    font-display: swap;
+}
+:root {
+    font-family: InterVariable, Inter, ui-sans-serif, system-ui, sans-serif;
+    font-feature-settings:
+        "calt" 1,
+        "liga" 1;
+    color: var(--ink);
+    background: var(--canvas);
+    font-size: 14px;
+    line-height: 1.5;
+    font-synthesis: none;
+    text-rendering: optimizeLegibility;
+    --canvas: #f5f7f9;
+    --surface: #ffffff;
+    --surface-raised: #ffffff;
+    --surface-subtle: #f5f7f9;
+    --ink: #20252b;
+    --muted: #616b76;
+    --line: #dce1e6;
+    --line-subtle: #e9edf1;
+    --input-line: #b7c0ca;
+    --action: #0877b8;
+    --on-action: #ffffff;
+    --action-hover: #06669f;
+    --action-soft: #e1f0fb;
+    --action-soft-hover: #d4eafa;
+    --on-action-soft: #075e95;
+    --selected: #e6f2fb;
+    --selected-hover: #dbedf9;
+    --hover: #eff2f5;
+    --search: #eaf0f5;
+    --selection: #c8e6fa;
+    --icon: #6b7683;
+    --scrollbar: #b9c1ca;
+    --danger: #b32635;
+    --on-danger: #ffffff;
+    --danger-hover: #96202e;
+    --danger-soft: #fff0f1;
+    --danger-soft-ink: #971e30;
+    --success: #237344;
+    --success-soft: #eef7f1;
+    --warning-soft: #fff5e3;
+    --violet: #7352b6;
+    --violet-soft: #f1ecfa;
+    --warning: #815500;
+    --toast-surface: #2c3239;
+    --toast-ink: #ffffff;
+    --file-pdf: #c5423e;
+    --file-image: #25845e;
+    --file-video: #8864c0;
+    --file-document: #287bb3;
+    --menu-shadow: 0 8px 28px #20252b24;
+    --dialog-shadow: 0 18px 64px #20252b38;
+    --scrim: #18212b66;
+    color-scheme: light;
+}
+:root[data-theme="dark"] {
+    --canvas: #1c1d1f;
+    --surface: #242527;
+    --surface-raised: #2d2f32;
+    --surface-subtle: #2a2c2f;
+    --ink: #e8eaed;
+    --muted: #b0b4bc;
+    --line: #414449;
+    --line-subtle: #35373b;
+    --input-line: #71767e;
+    --action: #8acbff;
+    --on-action: #092e47;
+    --action-hover: #a8d8ff;
+    --action-soft: #293e4d;
+    --action-soft-hover: #324c5f;
+    --on-action-soft: #b0dcff;
+    --selected: #2c3e4b;
+    --selected-hover: #334957;
+    --hover: #303236;
+    --search: #303236;
+    --selection: #3e5e75;
+    --icon: #adb5bf;
+    --scrollbar: #686d74;
+    --danger: #ffabb2;
+    --on-danger: #4c111d;
+    --danger-hover: #ffc4c8;
+    --danger-soft: #48282d;
+    --danger-soft-ink: #ffc6cc;
+    --success: #8ed9aa;
+    --success-soft: #253a30;
+    --warning-soft: #3b3424;
+    --violet: #b8a4e4;
+    --violet-soft: #342e40;
+    --warning: #f0cd83;
+    --toast-surface: #e3e5e8;
+    --toast-ink: #25272b;
+    --file-pdf: #f5aaa4;
+    --file-image: #8bd0b0;
+    --file-video: #c8adf0;
+    --file-document: #8acbff;
+    --menu-shadow: 0 8px 28px #0006;
+    --dialog-shadow: 0 18px 64px #0008;
+    --scrim: #0009;
+    color-scheme: dark;
+}
+@media (prefers-color-scheme: dark) {
+    :root:not([data-theme]) {
+        --canvas: #1c1d1f;
+        --surface: #242527;
+        --surface-raised: #2d2f32;
+        --surface-subtle: #2a2c2f;
+        --ink: #e8eaed;
+        --muted: #b0b4bc;
+        --line: #414449;
+        --line-subtle: #35373b;
+        --input-line: #71767e;
+        --action: #8acbff;
+        --on-action: #092e47;
+        --action-hover: #a8d8ff;
+        --action-soft: #293e4d;
+        --action-soft-hover: #324c5f;
+        --on-action-soft: #b0dcff;
+        --selected: #2c3e4b;
+        --selected-hover: #334957;
+        --hover: #303236;
+        --search: #303236;
+        --selection: #3e5e75;
+        --icon: #adb5bf;
+        --scrollbar: #686d74;
+        --danger: #ffabb2;
+        --on-danger: #4c111d;
+        --danger-hover: #ffc4c8;
+        --danger-soft: #48282d;
+        --danger-soft-ink: #ffc6cc;
+        --success: #8ed9aa;
+        --success-soft: #253a30;
+        --warning-soft: #3b3424;
+        --violet: #b8a4e4;
+        --violet-soft: #342e40;
+        --warning: #f0cd83;
+        --toast-surface: #e3e5e8;
+        --toast-ink: #25272b;
+        --file-pdf: #f5aaa4;
+        --file-image: #8bd0b0;
+        --file-video: #c8adf0;
+        --file-document: #8acbff;
+        --menu-shadow: 0 8px 28px #0006;
+        --dialog-shadow: 0 18px 64px #0008;
+        --scrim: #0009;
+        color-scheme: dark;
+    }
+}
+* {
+    box-sizing: border-box;
+}
+html,
+body,
+#root {
+    height: 100%;
+}
+.lucide {
+    stroke-width: 2;
+}
+body {
+    font-family: InterVariable, Inter, ui-sans-serif, system-ui, sans-serif;
+    color: var(--ink);
+    background: var(--canvas);
+    margin: 0;
+    min-width: 0;
+    overflow: hidden;
+}
+button,
+input,
+select {
+    font: inherit;
+}
+button,
+a,
+input,
+select {
+    -webkit-tap-highlight-color: transparent;
+}
+button,
+a {
+    touch-action: manipulation;
+}
+button {
+    cursor: pointer;
+}
+button:disabled {
+    cursor: default;
+    opacity: 0.55;
+}
+a {
+    color: inherit;
+    text-decoration: none;
+    text-underline-offset: 4px;
+}
+button {
+    color: inherit;
+}
+button:focus-visible,
+a:focus-visible,
+input:focus-visible,
+select:focus-visible,
+summary:focus-visible {
+    outline: 2px solid var(--action);
+    outline-offset: 3px;
+}
+input,
+select {
+    accent-color: var(--action);
+    caret-color: var(--action);
+}
+::selection {
+    background: var(--selection);
+    color: var(--ink);
+}
+* {
+    scrollbar-width: thin;
+    scrollbar-color: var(--scrollbar) transparent;
+}
+[hidden] {
+    display: none !important;
+}
+h1,
+h2,
+p {
+    margin-top: 0;
+}
+h1 {
+    font-size: 24px;
+    line-height: 32px;
+    letter-spacing: -0.025em;
+    font-weight: 600;
+    margin-bottom: 0;
+}
+h2 {
+    font-size: 18px;
+    line-height: 1.4;
+    font-weight: 600;
+}
+svg {
+    flex-shrink: 0;
+    vertical-align: middle;
+}
+button {
+    border: 0;
+    background: none;
+}
+input:not([type="checkbox"]):not([type="radio"]),
+select {
+    width: 100%;
+    border: 1px solid var(--input-line);
+    border-radius: 8px;
+    padding: 10px 12px;
+    background: var(--surface);
+    color: var(--ink);
+    min-height: 42px;
+}
+input::placeholder {
+    color: var(--muted);
+    opacity: 1;
+}
+input[type="checkbox"] {
+    width: 17px;
+    height: 17px;
+    cursor: pointer;
+}
+label {
+    display: block;
+    font-weight: 500;
+    margin-bottom: 7px;
+}
+form > input,
+form > select {
+    margin-bottom: 16px;
+}
+.sr-only {
+    position: absolute !important;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+}
+.skip-link {
+    position: fixed;
+    top: 8px;
+    left: 8px;
+    padding: 12px 20px;
+    background: var(--ink);
+    color: var(--on-action);
+    z-index: 100;
+    transform: translateY(-150%);
+}
+.skip-link:focus {
+    transform: none;
+}
+.app-shell {
+    display: grid;
+    grid-template-columns: 232px minmax(0, 1fr);
+    height: 100dvh;
+    overflow: hidden;
+}
+.sidebar {
+    height: 100%;
+    padding: 0 16px 18px;
+    display: flex;
+    flex-direction: column;
+    overflow-y: auto;
+    overscroll-behavior-y: contain;
+    min-height: 0;
+}
+.brand {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    font-size: 21px;
+    line-height: 28px;
+    letter-spacing: -0.03em;
+    width: max-content;
+    flex-shrink: 0;
+}
+.sidebar > .brand {
+    height: 58px;
+    margin: 0 10px 8px;
+}
+.new-button {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 10px;
+    background: var(--action);
+    color: var(--on-action);
+    height: 44px;
+    min-width: 112px;
+    font-size: 14px;
+    font-weight: 600;
+    border-radius: 10px;
+    padding: 0 18px;
+    align-self: flex-start;
+    flex-shrink: 0;
+    margin: 0 4px 14px;
+}
+.new-button:hover {
+    background: var(--action-hover);
+}
+.new-button[aria-expanded="true"] {
+    position: relative;
+    z-index: 41;
+}
+.drive-nav {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    flex: 0 0 auto;
+}
+.drive-nav a,
+.settings-link {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    height: 40px;
+    padding: 0 13px;
+    border-radius: 8px;
+    color: var(--muted);
+    flex-shrink: 0;
+}
+.drive-nav a > svg {
+    flex-shrink: 0;
+}
+.drive-nav a > span:not(.nav-count) {
+    min-width: 0;
+    white-space: nowrap;
+}
+.drive-nav a:hover,
+.settings-link:hover {
+    background: var(--hover);
+}
+.drive-nav a[aria-current],
+.settings-link[aria-current] {
+    color: var(--on-action-soft);
+    background: var(--selected);
+    font-weight: 600;
+}
+.nav-count {
+    margin-left: auto;
+    font-size: 11px;
+    min-width: 20px;
+    text-align: center;
+    background: var(--line-subtle);
+    color: var(--muted);
+    border-radius: 10px;
+    padding: 1px 5px;
+}
+.sidebar-tools {
+    margin-top: 8px;
+    padding-top: 8px;
+    border-top: 1px solid var(--line-subtle);
+}
+.sidebar-tools > summary {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    min-height: 44px;
+    padding: 0 13px;
+    border-radius: 8px;
+    color: var(--muted);
+    cursor: pointer;
+    list-style: none;
+}
+.sidebar-tools > summary::-webkit-details-marker {
+    display: none;
+}
+.sidebar-tools > summary:hover {
+    background: var(--hover);
+    color: var(--ink);
+}
+.sidebar-tools > summary > span {
+    white-space: nowrap;
+}
+.sidebar-tools .nav-disclosure {
+    margin-inline-start: auto;
+    flex-shrink: 0;
+}
+.sidebar-tools[open] .nav-disclosure {
+    transform: rotate(90deg);
+}
+.sidebar-tools-content {
+    margin: 8px 0 4px 16px;
+    padding-inline-start: 8px;
+    border-inline-start: 1px solid var(--line);
+}
+.sidebar-tools-content > .monitor-nav,
+.sidebar-tools-content > .admin-nav {
+    border-top: 0;
+    margin-top: 16px;
+    padding-top: 0;
+}
+.sidebar-tools-content > .monitor-nav:first-child {
+    margin-top: 0;
+}
+.sidebar-tools-content a {
+    min-height: 44px;
+    height: auto;
+    gap: 8px;
+    padding: 0 8px;
+    font-size: 13px;
+}
+.sidebar-tools-content a > svg {
+    width: 16px;
+    height: 16px;
+}
+.sidebar-tools-content .nav-section-label {
+    padding: 0 8px 2px;
+    font-size: 12px;
+}
+.monitor-nav,
+.admin-nav {
+    margin-top: 8px;
+    padding-top: 8px;
+    border-top: 1px solid var(--line-subtle);
+}
+.monitor-nav,
+.admin-nav {
+    display: flex;
+    flex-direction: column;
+    flex-shrink: 0;
+    gap: 4px;
+}
+.nav-section-label {
+    display: block;
+    padding: 3px 13px 2px;
+    color: var(--muted);
+    font-size: 11px;
+    font-weight: 600;
+    line-height: 18px;
+}
+.sidebar-bottom {
+    flex-shrink: 0;
+    margin-top: 16px;
+    padding: 12px 0 0;
+    border-top: 1px solid var(--line-subtle);
+    color: var(--muted);
+}
+.sidebar-bottom p {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+    margin: 0 8px 5px;
+    font-size: 12px;
+}
+.sidebar-bottom small {
+    display: block;
+    margin: 0;
+    font-size: 11px;
+    line-height: 18px;
+}
+.sidebar-support {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-top: 8px;
+}
+.sidebar-support .sidebar-help {
+    flex: 0 1 auto;
+    width: auto;
+    min-width: 0;
+    margin: 0;
+    padding-inline: 13px;
+    gap: 12px;
+    font-size: 13px;
+    white-space: nowrap;
+}
+.sidebar-help > svg {
+    flex-shrink: 0;
+}
+.sidebar-project {
+    display: grid;
+    place-items: center;
+    flex: 0 0 44px;
+    margin-inline-start: auto;
+    height: 44px;
+    border-radius: 8px;
+    color: var(--muted);
+}
+.sidebar-project:hover {
+    color: var(--ink);
+    background: var(--hover);
+}
+.sidebar-help,
+.sidebar-logout {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    width: 100%;
+    min-height: 44px;
+    margin-top: 8px;
+    padding: 0 13px;
+    border-radius: 8px;
+    color: var(--muted);
+    text-align: start;
+}
+.sidebar-help:hover,
+.sidebar-logout:hover:not(:disabled) {
+    background: var(--hover);
+    color: var(--ink);
+}
+.sidebar-bottom .sidebar-logout-error {
+    display: block;
+    margin: 4px 8px 0;
+    color: var(--danger);
+    line-height: 1.5;
+    overflow-wrap: anywhere;
+}
+.settings-link {
+    margin-top: 16px;
+}
+.main-content {
+    min-width: 0;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+    padding: 0 16px 14px 0;
+    outline: none;
+}
+.topbar {
+    height: 54px;
+    min-height: 54px;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    padding: 0 4px 0 0;
+    position: relative;
+    z-index: 30;
+}
+.search-form {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    background: var(--search);
+    border: 1px solid transparent;
+    border-radius: 12px;
+    max-width: 640px;
+    width: 100%;
+    min-width: 0;
+    padding: 0 6px 0 10px;
+    height: 44px;
+    color: var(--muted);
+}
+.search-form input {
+    border: 0 !important;
+    box-shadow: none !important;
+    background: transparent !important;
+    padding: 0 !important;
+    margin: 0;
+    font-size: 14px;
+    line-height: 20px;
+    min-height: 40px;
+    min-width: 0;
+}
+.search-form input:focus-visible {
+    outline: none;
+}
+.search-form:focus-within {
+    background: var(--surface);
+    border-color: var(--input-line);
+}
+.search-form:has(input:focus-visible) {
+    outline: 2px solid var(--action);
+    outline-offset: 0;
+}
+.search-form .icon-button {
+    width: 32px;
+    height: 32px;
+}
+.account-button {
+    margin-left: auto;
+    color: var(--muted);
+}
+.workspace {
+    flex: 1;
+    min-height: 0;
+    min-width: 0;
+    overflow-y: auto;
+    overflow-x: hidden;
+    background: var(--surface);
+    border-radius: 16px;
+    padding: 24px 24px 88px;
+    scrollbar-gutter: stable;
+}
+.page-heading {
+    display: flex;
+    align-items: center;
+    gap: 16px;
+    min-height: 32px;
+    margin-bottom: 18px;
+}
+.page-heading > div:first-child {
+    min-width: 0;
+    flex: 1;
+}
+.page-heading > .search-form {
+    width: min(420px, 48%);
+    flex-shrink: 0;
+}
+.page-heading .search-form input {
+    width: 100%;
+}
+.page-heading h1 {
+    overflow-wrap: anywhere;
+}
+.page-subtitle {
+    margin: 8px 0 0;
+    color: var(--muted);
+    font-size: 13px;
+}
+.breadcrumbs {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px;
+    margin-bottom: 10px;
+    font-size: 12px;
+    color: var(--muted);
+}
+.breadcrumbs > span {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+    min-width: 0;
+}
+.breadcrumbs a {
+    max-width: 220px;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.breadcrumbs a:hover {
+    text-decoration: underline;
+}
+.inline-actions {
+    display: flex;
+    align-items: center;
+    gap: 9px;
+    flex-shrink: 0;
+}
+.primary-button,
+.secondary-button,
+.danger-button,
+.text-button,
+.icon-button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    white-space: nowrap;
+    border-radius: 8px;
+    font-weight: 500;
+}
+.primary-button,
+.secondary-button,
+.danger-button {
+    padding: 10px 16px;
+    min-height: 40px;
+}
+.primary-button {
+    background: var(--action);
+    color: var(--on-action);
+}
+.primary-button:hover {
+    background: var(--action-hover);
+}
+.secondary-button {
+    background: var(--surface);
+    border: 1px solid var(--line);
+}
+.secondary-button:hover {
+    background: var(--hover);
+}
+.danger-button {
+    background: var(--danger);
+    color: var(--on-danger);
+}
+.danger-button:hover {
+    background: var(--danger-hover);
+}
+.text-button {
+    padding: 8px 9px;
+    min-height: 36px;
+    color: var(--action);
+}
+.text-button:hover {
+    background: var(--hover);
+}
+.icon-button {
+    width: 40px;
+    height: 40px;
+    padding: 0;
+    color: var(--muted);
+    flex-shrink: 0;
+}
+.icon-button:hover {
+    background: var(--hover);
+}
+.danger-text {
+    color: var(--danger) !important;
+}
+.full-width {
+    width: 100%;
+}
+.file-toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: 8px;
+    min-height: 44px;
+    border-bottom: 1px solid var(--line);
+    font-size: 12px;
+    color: var(--muted);
+    padding: 0 0 8px;
+}
+.file-toolbar > span:first-child {
+    margin-inline-end: auto;
+}
+.selection-count {
+    color: var(--action);
+    font-weight: 600;
+}
+.toolbar-divider {
+    height: 20px;
+    width: 1px;
+    background: var(--line);
+    margin: 0 6px;
+}
+.file-table {
+    border-collapse: collapse;
+    width: 100%;
+    table-layout: fixed;
+}
+.file-table th {
+    text-align: left;
+    color: var(--muted);
+    font-size: 12px;
+    font-weight: 500;
+    height: 36px;
+    border-bottom: 1px solid var(--line);
+}
+.file-table td {
+    height: 48px;
+    border-bottom: 1px solid var(--line-subtle);
+    font-size: 13px;
+}
+.file-table tr:hover td {
+    background: var(--canvas);
+}
+.file-table tr.selected td {
+    background: var(--selected);
+}
+.checkbox-cell {
+    width: 40px;
+    text-align: center !important;
+}
+.checkbox-cell input {
+    vertical-align: middle;
+}
+.name-cell {
+    position: relative;
+    padding: 0 12px 0 0;
+}
+.file-icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--icon);
+    width: 32px;
+    height: 32px;
+    flex-shrink: 0;
+    vertical-align: middle;
+}
+.folder-icon {
+    color: var(--icon);
+}
+.file-name {
+    display: inline-block;
+    text-align: left;
+    font-size: 13px;
+    max-width: calc(100% - 38px);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    vertical-align: middle;
+    padding: 14px 5px;
+    color: var(--ink);
+    font-weight: 500;
+}
+.file-name:hover {
+    color: var(--ink);
+}
+.file-name:disabled {
+    opacity: 1;
+    cursor: default;
+}
+.file-name:disabled:hover {
+    text-decoration: none;
+    color: inherit;
+}
+.date-cell {
+    width: 128px;
+    color: var(--muted);
+}
+.size-cell {
+    width: 96px;
+    color: var(--muted);
+    font-variant-numeric: tabular-nums;
+}
+.actions-cell {
+    width: 40px;
+    text-align: right;
+}
+.item-actions {
+    position: relative;
+    display: inline-block;
+}
+.item-actions summary {
+    list-style: none;
+    cursor: pointer;
+}
+.item-actions summary::-webkit-details-marker {
+    display: none;
+}
+.item-actions[open] summary {
+    background: var(--selected);
+}
+.action-menu,
+.new-menu {
+    position: fixed;
+    top: 134px;
+    left: 20px;
+    z-index: 41;
+    width: 224px;
+    max-width: calc(100vw - 24px);
+    padding: 6px;
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    color: var(--ink);
+    background: var(--surface-raised);
+    box-shadow: var(--menu-shadow);
+}
+.action-menu:not([popover]) {
+    position: absolute;
+    right: 0;
+    left: auto;
+    top: 38px;
+}
+.action-menu button,
+.action-menu a,
+.new-menu button {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    width: 100%;
+    padding: 11px 12px;
+    border-radius: 6px;
+    text-align: left;
+    font-size: 13px;
+}
+.action-menu button:hover,
+.action-menu a:hover,
+.new-menu button:hover {
+    background: var(--hover);
+}
+.file-row:nth-last-child(-n + 3) .action-menu:not([popover]) {
+    top: auto;
+    bottom: 38px;
+}
+.empty-state {
+    padding: 76px 20px;
+    display: flex;
+    align-items: center;
+    flex-direction: column;
+    text-align: center;
+    color: var(--muted);
+    gap: 12px;
+}
+.empty-state > svg {
+    color: var(--icon);
+    margin-bottom: 5px;
+}
+.empty-state h2 {
+    margin: 0;
+    color: var(--ink);
+    font-size: 19px;
+}
+.empty-state p {
+    max-width: 430px;
+    margin: 0 0 10px;
+}
+.loading-state {
+    padding: 90px 20px;
+    display: flex;
+    gap: 12px;
+    justify-content: center;
+    color: var(--muted);
+}
+.pagination {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 10px;
+    font-size: 12px;
+    padding: 20px 0;
+    color: var(--muted);
+}
+.modal {
+    border: 0;
+    background: var(--surface);
+    color: var(--ink);
+    border-radius: 16px;
+    width: 480px;
+    max-width: calc(100vw - 32px);
+    max-height: calc(100dvh - 40px);
+    padding: 26px;
+    box-shadow: var(--dialog-shadow);
+    overflow: auto;
+}
+.modal::backdrop {
+    background: var(--scrim);
+}
+.modal-header {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 16px;
+    margin-bottom: 18px;
+}
+.modal-header h2 {
+    font-size: 20px;
+    margin: 5px 0;
+    overflow-wrap: anywhere;
+}
+.modal-header .icon-button {
+    margin: -4px -7px 0 0;
+}
+.modal p {
+    font-size: 13px;
+}
+.modal > p {
+    margin-bottom: 18px;
+}
+.dialog-actions {
+    display: flex;
+    justify-content: flex-end;
+    gap: 10px;
+    margin-top: 24px;
+}
+.muted {
+    color: var(--muted);
+}
+.check-field {
+    display: flex;
+    align-items: flex-start;
+    gap: 10px;
+    margin: 16px 0;
+    font-size: 13px;
+    font-weight: 400;
+}
+.check-field input {
+    margin-top: 3px;
+    flex-shrink: 0;
+}
+.check-field small {
+    display: block;
+    color: var(--muted);
+    margin-top: 4px;
+    font-size: 12px;
+}
+.error-notice {
+    background: var(--danger-soft);
+    color: var(--danger-soft-ink);
+    padding: 12px 14px;
+    border-radius: 8px;
+    margin: 14px 0;
+    overflow-wrap: anywhere;
+}
+.folder-picker {
+    min-height: 88px;
+    max-height: min(230px, 32dvh);
+    overflow: auto;
+    margin: 12px 0 20px;
+    border: 1px solid var(--line);
+    border-radius: 8px;
+    padding: 6px;
+}
+.folder-picker > button {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    width: 100%;
+    text-align: left;
+    padding: 12px;
+    border-radius: 6px;
+}
+.folder-picker > button:hover {
+    background: var(--selected);
+}
+.folder-picker > button span {
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.folder-picker > p {
+    padding: 20px 10px;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.move-breadcrumbs {
+    display: flex;
+    flex-wrap: wrap;
+    max-height: 100px;
+    overflow: auto;
+}
+.move-breadcrumbs .text-button {
+    font-size: 12px;
+    padding: 5px;
+}
+.modal-wide {
+    width: 850px;
+}
+.transfer-center {
+    position: fixed;
+    bottom: 20px;
+    right: 28px;
+    width: 408px;
+    max-width: calc(100vw - 32px);
+    background: var(--surface);
+    border-radius: 12px;
+    box-shadow: 0 6px 32px #18243b26;
+    z-index: 25;
+    overflow: hidden;
+}
+.transfer-heading {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 6px;
+    padding: 12px 12px 12px 16px;
+    background: var(--hover);
+}
+.transfer-heading h2 {
+    display: flex;
+    align-items: center;
+    gap: 9px;
+    margin: 0;
+    font-size: 13px;
+}
+.transfer-heading .inline-actions {
+    gap: 0;
+}
+.transfer-heading .text-button {
+    font-size: 11px;
+    padding: 6px;
+}
+.transfer-heading .icon-button {
+    width: 29px;
+    height: 32px;
+}
+.transfer-list {
+    max-height: 360px;
+    overflow: auto;
+}
+.transfer-item {
+    display: flex;
+    gap: 12px;
+    padding: 16px 15px;
+    border-bottom: 1px solid var(--line-subtle);
+    align-items: flex-start;
+}
+.transfer-state-icon {
+    width: 22px;
+    color: var(--action);
+    padding-top: 1px;
+}
+.transfer-copy {
+    min-width: 0;
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+}
+.transfer-item-title {
+    display: flex;
+    align-items: baseline;
+    gap: 12px;
+}
+.transfer-item-title .transfer-item-name {
+    flex: 1;
+    min-width: 0;
+}
+.transfer-item-title .transfer-batch-percent {
+    flex-shrink: 0;
+}
+.transfer-item-name {
+    font-size: 12px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-weight: 600;
+}
+.transfer-phase,
+.transfer-bytes {
+    font-size: 11px;
+    color: var(--muted);
+}
+.transfer-bytes {
+    font-variant-numeric: tabular-nums;
+}
+.transfer-error {
+    font-size: 11px;
+    color: var(--danger);
+    overflow-wrap: anywhere;
+}
+.transfer-item-actions {
+    display: flex;
+    align-items: center;
+    gap: 2px;
+}
+.transfer-item-actions .text-button {
+    font-size: 11px;
+    padding: 5px;
+    white-space: normal;
+}
+.transfer-item-actions .icon-button {
+    width: 28px;
+    height: 30px;
+}
+.transfer-footer {
+    display: flex;
+    justify-content: flex-end;
+    padding: 4px 12px;
+    border-top: 1px solid var(--line-subtle);
+}
+.transfer-footer .text-button {
+    min-height: 36px;
+    font-size: 12px;
+}
+.transfer-help {
+    margin: 0;
+    padding: 12px 16px;
+    font-size: 10px;
+    color: var(--muted);
+    background: var(--canvas);
+}
+.transfer-page {
+    position: static;
+    width: 100%;
+    max-width: none;
+    box-shadow: none;
+    border: 1px solid var(--line);
+    margin-top: 20px;
+}
+.transfer-page .transfer-list {
+    max-height: none;
+}
+.transfer-page .transfer-item-name {
+    font-size: 13px;
+}
+.transfer-page .transfer-help {
+    font-size: 12px;
+}
+.transfer-item[data-status="completed"] .transfer-state-icon {
+    color: var(--success);
+}
+.transfer-item[data-status="error"] .transfer-state-icon {
+    color: var(--danger);
+}
+progress {
+    appearance: none;
+    width: 100%;
+    height: 4px;
+    border: 0;
+    border-radius: 6px;
+    margin: 5px 0;
+    background: var(--line);
+    accent-color: var(--action);
+}
+progress::-webkit-progress-bar {
+    background: var(--line);
+    border-radius: 6px;
+}
+progress::-webkit-progress-value {
+    background: var(--action);
+    border-radius: 6px;
+}
+progress::-moz-progress-bar {
+    background: var(--action);
+    border-radius: 6px;
+}
+.section-description {
+    max-width: 650px;
+    color: var(--muted);
+    margin: 0 0 28px;
+}
+.share-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+}
+.share-list li {
+    display: flex;
+    gap: 16px;
+    align-items: center;
+    padding: 18px 4px;
+    border-bottom: 1px solid var(--line);
+}
+.share-icon {
+    color: var(--icon);
+}
+.share-list li > div {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+    flex: 1;
+}
+.share-list strong {
+    font-weight: 500;
+    overflow-wrap: anywhere;
+}
+.share-list span {
+    font-size: 12px;
+    color: var(--muted);
+}
+.login-page {
+    min-height: 100dvh;
+    display: flex;
+    align-items: center;
+    flex-direction: column;
+    padding: 48px 24px;
+    background: var(--canvas);
+}
+.login-page > .brand {
+    margin-bottom: 70px;
+}
+.login-form {
+    background: var(--surface);
+    padding: 38px 40px;
+    border-radius: 16px;
+    width: 420px;
+    max-width: 100%;
+    box-shadow: 0 8px 40px #263b6b09;
+}
+.login-symbol {
+    color: var(--action);
+    margin-bottom: 24px;
+}
+.login-form h1 {
+    font-size: 25px;
+    margin-bottom: 10px;
+}
+.login-form > p {
+    color: var(--muted);
+    margin-bottom: 28px;
+}
+.login-form form > label {
+    font-size: 12px;
+}
+.password-field {
+    position: relative;
+    margin-bottom: 18px;
+}
+.password-field input {
+    padding-right: 65px;
+}
+.password-field .text-button {
+    position: absolute;
+    right: 3px;
+    top: 3px;
+    min-height: 36px;
+    font-size: 12px;
+}
+.login-note {
+    font-size: 11px;
+    margin: 22px 0 0 !important;
+    color: var(--muted);
+}
+.login-footer {
+    margin-top: 30px;
+    font-size: 11px;
+    color: var(--muted);
+}
+.startup {
+    min-height: 100dvh;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    color: var(--muted);
+}
+.startup-status {
+    display: inline-flex;
+    align-items: center;
+    gap: 10px;
+}
+.toast {
+    position: fixed;
+    inset: auto;
+    margin: 0;
+    border: 0;
+    bottom: 24px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 100;
+    display: flex;
+    align-items: center;
+    gap: 18px;
+    background: var(--toast-surface);
+    color: var(--toast-ink);
+    border-radius: 10px;
+    padding: 10px 12px 10px 20px;
+    max-width: min(560px, calc(100vw - 32px));
+    box-shadow: 0 5px 22px #14243b22;
+    font-size: 13px;
+}
+.toast[popover]:not(:popover-open) {
+    display: none;
+}
+.toast .icon-button {
+    color: inherit;
+    flex-shrink: 0;
+}
+.toast > span {
+    min-width: 0;
+    max-height: min(240px, calc(100dvh - 96px));
+    overflow-y: auto;
+    overflow-wrap: anywhere;
+    overscroll-behavior: contain;
+}
+.toast .icon-button:hover {
+    background: #ffffff18;
+}
+.toast-error {
+    background: var(--danger);
+    color: var(--on-danger);
+}
+.new-menu {
+    position: fixed;
+    top: 128px;
+    left: 20px;
+    z-index: 41;
+}
+.menu-dismiss {
+    position: fixed;
+    inset: 0;
+    z-index: 40;
+    cursor: default;
+}
+.mobile-menu,
+.mobile-new {
+    display: none;
+}
+.public-shell {
+    grid-template-columns: minmax(0, 1fr);
+}
+.public-shell .main-content {
+    padding: 0 16px 14px;
+}
+.public-shell .topbar {
+    justify-content: space-between;
+}
+.public-label {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    color: var(--muted);
+    font-size: 12px;
+}
+.spinner {
+    animation: spin 1s linear infinite;
+}
+@keyframes spin {
+    to {
+        transform: rotate(360deg);
+    }
+}
+@media (max-width: 1050px) {
+    .app-shell {
+        grid-template-columns: 232px minmax(0, 1fr);
+    }
+    .sidebar {
+        padding-inline: 16px;
+    }
+    .workspace {
+        padding: 24px 24px 100px;
+    }
+    .main-content {
+        padding-right: 16px;
+    }
+    .date-cell {
+        width: 120px;
+    }
+    .size-cell {
+        width: 75px;
+    }
+    .desktop-action {
+        display: none;
+    }
+    .public-shell {
+        grid-template-columns: 1fr;
+    }
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .app-shell {
+        display: block;
+        height: 100dvh;
+    }
+    .sidebar {
+        position: fixed;
+        inset: 0 auto 0 0;
+        width: min(320px, calc(100vw - 40px));
+        height: 100dvh;
+        background: var(--canvas);
+        z-index: 50;
+        box-shadow: 8px 0 28px #18243b20;
+        transform: translateX(-110%);
+        padding: max(8px, env(safe-area-inset-top)) 12px
+            max(12px, env(safe-area-inset-bottom));
+        scrollbar-width: thin;
+    }
+    .sidebar.nav-open {
+        transform: none;
+    }
+    .sidebar > .brand {
+        display: none;
+    }
+    .sidebar .new-button {
+        display: none;
+    }
+    .main-content,
+    .public-shell .main-content {
+        height: 100dvh;
+        padding: 0;
+    }
+    .topbar {
+        height: auto;
+        min-height: 52px;
+        padding: env(safe-area-inset-top) 8px 0;
+        gap: 4px;
+        background: var(--surface);
+        border-bottom: 1px solid var(--line-subtle);
+    }
+    .search-form {
+        padding: 0 4px;
+        gap: 2px;
+        height: 44px;
+    }
+    .search-form input {
+        font-size: 14px;
+    }
+    .mobile-menu {
+        display: flex;
+    }
+    .account-button {
+        display: none;
+    }
+    .workspace {
+        padding: 16px 12px 24px;
+        border-radius: 0;
+        min-height: 0;
+        scrollbar-gutter: auto;
+    }
+    .page-heading {
+        gap: 8px;
+        margin-bottom: 16px;
+        align-items: center;
+    }
+    .page-heading h1 {
+        font-size: 24px;
+    }
+    .page-heading .primary-button {
+        padding: 9px 11px;
+        font-size: 12px;
+    }
+    .page-heading .primary-button svg {
+        width: 15px;
+    }
+    .page-heading .inline-actions {
+        gap: 2px;
+    }
+    .breadcrumbs {
+        font-size: 11px;
+    }
+    .breadcrumbs a {
+        max-width: 140px;
+    }
+    .file-toolbar {
+        font-size: 12px;
+        flex-wrap: wrap;
+    }
+    .file-toolbar .text-button {
+        font-size: 12px;
+        padding: 7px;
+    }
+    .file-table .date-cell {
+        display: none;
+    }
+    .file-table .size-cell {
+        width: 64px;
+        font-size: 11px;
+    }
+    .checkbox-cell {
+        width: 30px;
+    }
+    .file-table th {
+        font-size: 10px;
+    }
+    .file-table td {
+        height: 60px;
+    }
+    .name-cell {
+        padding-right: 2px;
+    }
+    .file-icon {
+        width: 32px;
+    }
+    .file-icon svg {
+        width: 20px;
+    }
+    .file-name {
+        font-size: 13px;
+        max-width: calc(100% - 36px);
+        padding: 18px 3px;
+    }
+    .actions-cell {
+        width: 32px;
+    }
+    .actions-cell .icon-button {
+        width: 30px;
+        height: 36px;
+    }
+    .mobile-new,
+    .mobile-new[aria-expanded="true"] {
+        display: inline-flex;
+        position: relative;
+        inset: auto;
+        min-height: 40px;
+        padding: 8px 12px;
+        gap: 6px;
+        border-radius: 8px;
+        flex-shrink: 0;
+    }
+    .mobile-brand {
+        flex: 1;
+        min-width: 0;
+        font-size: 17px;
+        font-weight: 600;
+        letter-spacing: -0.02em;
+        color: var(--ink);
+    }
+    .mobile-transfer-status {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        flex: 0 0 auto;
+        width: 100%;
+        min-height: 48px;
+        padding: 10px 16px max(10px, env(safe-area-inset-bottom));
+        border-top: 1px solid var(--line);
+        background: var(--surface);
+        color: var(--action);
+        text-align: start;
+        font-size: 13px;
+    }
+    .mobile-transfer-status > span {
+        flex: 1;
+        min-width: 0;
+    }
+    .new-menu {
+        top: calc(52px + env(safe-area-inset-top));
+        bottom: auto;
+        left: auto;
+        right: 8px;
+        max-width: calc(100vw - 16px);
+    }
+    .transfer-center {
+        bottom: 80px;
+        right: 14px;
+        max-width: calc(100vw - 28px);
+        width: 370px;
+    }
+    .transfer-list {
+        max-height: 240px;
+    }
+    .transfer-page {
+        width: 100%;
+        max-width: 100%;
+        margin-top: 15px;
+    }
+    .transfer-page .transfer-list {
+        max-height: none;
+    }
+    .transfer-heading {
+        padding: 10px 10px 10px 13px;
+    }
+    .transfer-heading h2 {
+        font-size: 12px;
+    }
+    .transfer-item {
+        padding: 13px 12px;
+        gap: 9px;
+    }
+    .transfer-help {
+        font-size: 10px;
+    }
+    .transfer-center .text-button {
+        min-height: 32px;
+    }
+    .public-label {
+        font-size: 10px;
+        gap: 5px;
+    }
+    .public-shell .brand {
+        font-size: 20px;
+    }
+    .modal {
+        padding: 22px;
+        max-width: calc(100vw - 24px);
+    }
+    .modal-header h2 {
+        font-size: 18px;
+    }
+    .modal .dialog-actions {
+        gap: 8px;
+    }
+    .dialog-actions .primary-button,
+    .dialog-actions .secondary-button,
+    .dialog-actions .danger-button {
+        font-size: 12px;
+        padding: 10px 12px;
+    }
+    .preview-footer {
+        align-items: flex-start;
+        flex-direction: column;
+    }
+    .login-page {
+        padding: 30px 18px;
+    }
+    .login-page > .brand {
+        margin-bottom: 48px;
+    }
+    .login-form {
+        padding: 30px 25px;
+    }
+    .login-form h1 {
+        font-size: 23px;
+    }
+    .settings-facts > div {
+        font-size: 12px;
+    }
+    .settings-section-title .text-button {
+        font-size: 11px;
+    }
+    .share-list li {
+        gap: 10px;
+    }
+    .share-list .secondary-button {
+        padding: 8px;
+        font-size: 11px;
+    }
+    .toast {
+        bottom: 22px;
+        width: max-content;
+    }
+    .toast span {
+        max-width: calc(100vw - 110px);
+    }
+    .empty-state {
+        padding: 64px 12px;
+    }
+    .empty-state p {
+        font-size: 12px;
+    }
+    .pagination {
+        font-size: 10px;
+        gap: 4px;
+    }
+    .public-shell .workspace {
+        padding-bottom: 40px;
+    }
+}
+@media (prefers-reduced-motion: reduce) {
+    .spinner {
+        animation: none;
+    }
+    html:focus-within {
+        scroll-behavior: auto;
+    }
+}
+
+.nav-dismiss {
+    position: fixed;
+    inset: 0;
+    z-index: 34;
+    background: var(--scrim);
+}
+
+.transfer-metrics {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 3px 10px;
+    color: var(--muted);
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+}
+
+/* A file is the workspace while it is open. Form dialogs remain compact. */
+.file-preview {
+    position: fixed;
+    inset: 0;
+    margin: 0;
+    width: 100vw;
+    height: 100dvh;
+    max-width: none;
+    max-height: none;
+    padding: 0;
+    border: 0;
+    border-radius: 0;
+    overflow: hidden;
+    background: #202328;
+    color: #f1f3f6;
+    color-scheme: dark;
+}
+.file-preview[open] {
+    display: flex;
+    flex-direction: column;
+}
+.file-preview::backdrop {
+    background: #15171b;
+}
+.file-preview :is(button, a, input, select):focus-visible {
+    outline-color: #b6c9ff;
+}
+.file-preview ::selection {
+    background: #385eaa;
+    color: #fff;
+}
+.preview-header {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+    gap: 14px;
+    min-height: 60px;
+    padding: 6px 16px 6px 10px;
+    border-bottom: 1px solid #373b43;
+    background: #181b20;
+}
+.preview-header .icon-button {
+    width: 44px;
+    height: 44px;
+    color: #e7eaf0;
+    border-radius: 50%;
+}
+.preview-header .icon-button:hover {
+    background: #30343c;
+}
+.preview-header > .file-icon {
+    color: #c0d1ff;
+}
+.preview-heading {
+    min-width: 0;
+    flex: 1;
+}
+.preview-heading h2 {
+    margin: 0;
+    font-size: 15px;
+    line-height: 1.4;
+    font-weight: 500;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.preview-heading > span {
+    color: #b3bbc8;
+    display: block;
+    margin-top: 3px;
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+}
+.preview-download {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 9px;
+    min-height: 42px;
+    padding: 8px 14px;
+    border-radius: 8px;
+    color: #f1f3f6;
+    font-size: 13px;
+}
+.preview-download:hover {
+    background: #30343c;
+}
+.preview-quality {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 12px;
+    min-height: 52px;
+    padding: 6px 16px;
+    border-bottom: 1px solid #373b43;
+    background: #181b20;
+    color: #c3cbd7;
+    font-size: 14px;
+}
+.preview-quality select {
+    width: auto;
+    min-width: 120px;
+    max-width: min(60vw, 300px);
+    min-height: 40px;
+    margin: 0;
+    border-color: #505b6d;
+    background: #252d39;
+    color: #eef2fa;
+    color-scheme: dark;
+    font-size: 16px;
+}
+.preview-surface {
+    flex: 1 1 auto;
+    min-height: 0;
+    min-width: 0;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    overflow: hidden;
+    background: #202328;
+}
+.preview-surface-image {
+    padding: 24px;
+}
+.preview-surface > img,
+.preview-surface > video {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
+.preview-surface-image > img {
+    width: auto;
+    height: auto;
+    max-width: 100%;
+    max-height: 100%;
+}
+.preview-surface-video {
+    background: #080a0d;
+}
+.advanced-video,
+.advanced-player-host {
+    position: relative;
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+    min-height: 0;
+}
+.advanced-player-host movi-player {
+    display: block;
+    width: 100%;
+    height: 100%;
+    max-height: none;
+}
+.preview-surface-audio {
+    padding: 24px;
+}
+.preview-surface > audio {
+    width: min(680px, 100%);
+}
+.preview-loading {
+    display: flex;
+    gap: 10px;
+    align-items: center;
+    justify-content: center;
+    color: #c0c7d3;
+    padding: 32px;
+}
+.file-preview .empty-state {
+    color: #f1f3f6;
+    max-width: 55ch;
+    padding: 32px 24px;
+}
+.file-preview .empty-state p {
+    color: #bdc5d2;
+}
+.file-preview .empty-state h3 {
+    font-size: 18px;
+    margin: 18px 0 10px;
+}
+.file-preview .empty-state .file-icon {
+    color: #c0d1ff;
+}
+.file-preview .secondary-button {
+    background: #30353e;
+    color: #f1f3f6;
+    border-color: #545c69;
+}
+.file-preview .secondary-button:hover {
+    background: #414854;
+}
+.preview-surface-text {
+    display: block;
+    background: #e7eaf0;
+}
+.text-preview {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+    min-width: 0;
+    color: #202735;
+    background: #fff;
+    color-scheme: light;
+}
+.preview-document-toolbar {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    min-height: 48px;
+    padding: 8px 24px;
+    border-bottom: 1px solid #3d424c;
+    color: #cbd2df;
+    background: #262a31;
+    font-size: 12px;
+}
+.preview-document-toolbar label {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin: 0;
+    font-weight: 400;
+}
+.text-preview pre {
+    flex: 1;
+    min-height: 0;
+    min-width: 0;
+    overflow: auto;
+    margin: 0;
+    padding: 28px max(24px, calc((100% - 1280px) / 2));
+    font:
+        14px/1.75 ui-monospace,
+        SFMono-Regular,
+        Consolas,
+        monospace;
+    tab-size: 4;
+    color: #202735;
+}
+.text-preview pre.wrap-lines {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+}
+.text-preview pre:focus-visible {
+    outline: 2px solid #4269ce;
+    outline-offset: -3px;
+}
+.preview-limit {
+    flex: 0 0 auto;
+    margin: 0;
+    padding: 9px 24px;
+    color: #d3d9e3;
+    background: #2d333d;
+    font-size: 12px;
+}
+.pdf-preview {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    width: 100%;
+    min-height: 0;
+}
+.preview-toolbar-slot {
+    flex: 0 0 auto;
+}
+.pdf-controls {
+    position: relative;
+}
+.pdf-options-toggle {
+    display: none;
+}
+.pdf-toolbar {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    color: #d3d9e3;
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+}
+.pdf-page-count {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.pdf-toolbar .inline-actions {
+    flex-wrap: nowrap;
+    gap: 3px;
+}
+.pdf-zoom {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+}
+.pdf-toolbar .icon-button,
+.pdf-fit {
+    min-width: 34px;
+    min-height: 34px;
+    color: #e4e9f2;
+    border-radius: 6px;
+}
+.pdf-toolbar .icon-button:hover,
+.pdf-fit:hover {
+    background: #3d4552;
+}
+.pdf-fit {
+    padding: 6px 10px;
+    font-size: 12px;
+}
+.pdf-scroll {
+    position: relative;
+    flex: 1;
+    min-height: 0;
+    min-width: 0;
+    overflow: auto;
+    overscroll-behavior: contain;
+    background: #25292f;
+    outline: none;
+}
+.pdf-scroll:focus-visible {
+    outline: 2px solid #b6c9ff;
+    outline-offset: -3px;
+}
+.pdf-pages {
+    position: relative;
+    min-height: 100%;
+}
+.pdf-page {
+    position: absolute;
+    left: 50%;
+    transform: translateX(-50%);
+    padding: 0;
+    max-height: none;
+    overflow: hidden;
+    color: #202735;
+    background: #fff;
+    box-shadow: 0 4px 18px #0003;
+    color-scheme: only light;
+}
+.pdf-page canvas {
+    display: block;
+    width: 100%;
+    height: 100%;
+}
+.pdf-page-loading,
+.pdf-page-error {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-direction: column;
+    gap: 12px;
+    height: 100%;
+    padding: 24px;
+    color: #59677c;
+    font-size: 13px;
+}
+.preview-pdf-error {
+    padding: 28px;
+    color: #e1e5ed;
+    text-align: center;
+}
+.file-row {
+    user-select: none;
+}
+.file-row .item-name-button {
+    font-size: 13px;
+    font-weight: 500;
+}
+.file-table tr.selected:hover td {
+    background: var(--selected-hover);
+}
+.file-icon[data-extension="pdf"] {
+    color: var(--file-pdf);
+}
+.file-icon:is(
+    [data-extension="jpg"],
+    [data-extension="png"],
+    [data-extension="webp"],
+    [data-extension="svg"],
+    [data-extension="jpeg"]
+) {
+    color: var(--file-image);
+}
+.file-icon:is(
+    [data-extension="mp4"],
+    [data-extension="mkv"],
+    [data-extension="webm"]
+) {
+    color: var(--file-video);
+}
+.file-icon:is(
+    [data-extension="doc"],
+    [data-extension="docx"],
+    [data-extension="txt"],
+    [data-extension="md"]
+) {
+    color: var(--file-document);
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .preview-header {
+        gap: 8px;
+        min-height: 64px;
+        padding: max(8px, env(safe-area-inset-top)) 10px 8px;
+    }
+    .preview-header > .file-icon,
+    .preview-download > span {
+        display: none;
+    }
+    .preview-heading h2 {
+        font-size: 14px;
+    }
+    .preview-heading > span {
+        font-size: 10px;
+    }
+    .preview-download {
+        width: 44px;
+        height: 44px;
+        padding: 0;
+    }
+    .preview-surface-image,
+    .preview-surface-audio {
+        padding: 12px;
+    }
+    .preview-document-toolbar {
+        padding: 8px 12px;
+        gap: 10px;
+    }
+    .pdf-options-toggle {
+        display: inline-flex;
+    }
+    .preview-header-pdf .preview-heading > span {
+        display: none;
+    }
+    .pdf-controls .pdf-toolbar {
+        display: none;
+        position: absolute;
+        top: calc(100% + 8px);
+        right: -52px;
+        z-index: 5;
+        width: max-content;
+        max-width: calc(100vw - 24px);
+        padding: 8px 12px;
+        gap: 10px;
+        border: 1px solid #454b55;
+        border-radius: 10px;
+        background: #25292f;
+        box-shadow: 0 6px 20px #0005;
+    }
+    .pdf-controls[data-open="true"] .pdf-toolbar {
+        display: flex;
+    }
+    .pdf-toolbar .inline-actions {
+        flex-shrink: 0;
+    }
+    .pdf-fit-label {
+        display: none;
+    }
+    .pdf-toolbar .pdf-fit {
+        width: 44px;
+        height: 44px;
+        padding: 0;
+        justify-content: center;
+    }
+    .pdf-zoom {
+        gap: 2px;
+    }
+    .text-preview pre {
+        padding: 18px 14px;
+        font-size: 13px;
+    }
+    .transfer-metrics {
+        font-size: 11px;
+    }
+}
+
+/* Unpreviewable files keep their list context and lead with the next action. */
+.file-preview.file-details {
+    margin: auto;
+    width: min(480px, calc(100vw - 32px));
+    height: fit-content;
+    max-height: calc(100dvh - 32px);
+    overflow: auto;
+    border-radius: 16px;
+    background: var(--surface);
+    color: var(--ink);
+    color-scheme: inherit;
+    box-shadow: var(--dialog-shadow);
+}
+.file-preview.file-details[open] {
+    display: block;
+}
+.file-details::backdrop {
+    background: var(--scrim);
+}
+.file-details .preview-header {
+    position: relative;
+    min-height: 0;
+    height: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+}
+.file-details .preview-close {
+    position: absolute;
+    top: 12px;
+    right: 12px;
+    color: var(--muted);
+}
+.file-details .preview-close:hover {
+    color: var(--ink);
+    background: var(--canvas);
+}
+.file-details-body {
+    padding: 42px 32px 20px;
+    text-align: center;
+}
+.file-details-icon {
+    display: flex;
+    justify-content: center;
+    margin-bottom: 18px;
+    color: var(--muted);
+}
+.file-details-icon .file-icon {
+    width: 52px;
+    height: 52px;
+}
+.file-details-icon svg {
+    width: 48px;
+    height: 48px;
+    stroke-width: 1.4;
+}
+.file-details-body h2 {
+    margin: 0;
+    font-size: 19px;
+    font-weight: 600;
+    line-height: 1.5;
+    overflow-wrap: anywhere;
+}
+.file-details-body > p {
+    max-width: 38ch;
+    margin: 10px auto 24px;
+    color: var(--muted);
+    font-size: 14px;
+    line-height: 1.65;
+    overflow-wrap: anywhere;
+}
+.file-details-checking {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+}
+.file-details-metadata {
+    margin: 0 0 24px;
+    padding: 18px 0;
+    border-top: 1px solid var(--line);
+    border-bottom: 1px solid var(--line);
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    font-size: 13px;
+}
+.file-details-metadata > div {
+    display: flex;
+    justify-content: space-between;
+    gap: 20px;
+}
+.file-details-metadata dt {
+    color: var(--muted);
+}
+.file-details-metadata dd {
+    margin: 0;
+    color: var(--ink);
+    text-align: right;
+    overflow-wrap: anywhere;
+}
+.file-details-download {
+    width: 100%;
+    min-height: 48px;
+}
+.file-details :is(button, a):focus-visible {
+    outline-color: var(--action);
+}
+.file-details ::selection {
+    background: var(--selected);
+    color: var(--ink);
+}
+@media (max-width: 480px) {
+    .file-details-body {
+        padding: 40px 22px 16px;
+    }
+    .file-details-body h2 {
+        font-size: 18px;
+    }
+}
+
+.transfer-batch + .transfer-batch {
+    border-top: 1px solid var(--line);
+}
+.transfer-batch-summary {
+    padding: 16px;
+}
+.transfer-batch-title {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+.transfer-batch-title .transfer-state-icon {
+    display: flex;
+    flex-shrink: 0;
+    padding: 0;
+}
+.transfer-batch-name {
+    flex: 1;
+    min-width: 0;
+    font-size: 13px;
+    font-weight: 600;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.transfer-batch-percent {
+    color: var(--muted);
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+}
+.transfer-batch-status {
+    margin: 8px 0 10px;
+    color: var(--muted);
+    font-size: 12px;
+    line-height: 1.6;
+}
+.transfer-batch-summary > progress {
+    display: block;
+    width: 100%;
+    margin: 0 0 10px;
+    height: 6px;
+}
+.transfer-batch-metrics {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 3px 12px;
+    color: var(--muted);
+    font-size: 11px;
+    line-height: 1.6;
+    font-variant-numeric: tabular-nums;
+}
+.transfer-batch-actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 2px 12px;
+    margin-top: 8px;
+}
+.transfer-batch-actions .text-button {
+    min-height: 40px;
+    padding: 6px 0;
+    font-size: 12px;
+}
+.transfer-batch-toggle {
+    margin-inline-end: auto;
+}
+.transfer-batch-files {
+    border-top: 1px solid var(--line);
+}
+.transfer-files-toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    padding: 10px 16px;
+    background: var(--canvas);
+    color: var(--muted);
+    font-size: 11px;
+}
+.transfer-filters {
+    display: flex;
+    flex: 1;
+    align-items: center;
+    gap: 4px;
+    min-width: 0;
+    max-width: 100%;
+    overflow-x: auto;
+    overscroll-behavior-inline: contain;
+    scrollbar-width: none;
+}
+.transfer-filters button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 6px;
+    flex-shrink: 0;
+    min-height: 40px;
+    padding: 8px 10px;
+    border-radius: 7px;
+    color: var(--muted);
+    font-size: 12px;
+    white-space: nowrap;
+}
+.transfer-filters button:hover {
+    color: var(--ink);
+    background: var(--hover);
+}
+.transfer-filters button[aria-pressed="true"] {
+    color: var(--on-action-soft);
+    background: var(--action-soft);
+}
+.transfer-filters button span {
+    font-variant-numeric: tabular-nums;
+    opacity: 0.85;
+}
+.transfer-relative-path {
+    color: var(--muted);
+    font-size: 11px;
+    overflow-wrap: anywhere;
+}
+.transfer-no-files {
+    margin: 0;
+    padding: 20px 16px;
+    color: var(--muted);
+    font-size: 12px;
+}
+.transfer-show-more {
+    width: 100%;
+    min-height: 44px;
+    padding: 10px 16px;
+    font-size: 12px;
+}
+.transfer-notice {
+    margin: 0;
+    padding: 12px 16px;
+    color: var(--ink);
+    background: var(--selected);
+    font-size: 12px;
+    line-height: 1.6;
+}
+.transfer-storage-warning {
+    display: block;
+    margin-top: 8px;
+    color: var(--danger);
+}
+.transfer-batch[data-status="attention"]
+    > .transfer-batch-summary
+    .transfer-state-icon {
+    color: var(--danger);
+}
+.transfer-batch[data-status="finished"]
+    > .transfer-batch-summary
+    .transfer-state-icon {
+    color: var(--success);
+}
+.transfer-page .transfer-batch-summary {
+    padding: 20px;
+}
+.transfer-page .transfer-batch-name {
+    font-size: 15px;
+}
+.transfer-page .transfer-batch-status,
+.transfer-page .transfer-batch-metrics {
+    font-size: 13px;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .transfer-heading .icon-button {
+        width: 40px;
+        height: 40px;
+    }
+    .transfer-heading .text-button {
+        min-height: 40px;
+    }
+    .transfer-batch-summary,
+    .transfer-page .transfer-batch-summary {
+        padding: 14px;
+    }
+    .transfer-batch-actions .text-button {
+        min-height: 44px;
+    }
+    .transfer-item-actions .icon-button {
+        min-width: 40px;
+        min-height: 40px;
+    }
+}
+
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .page-heading {
+        flex-direction: column;
+        align-items: stretch;
+    }
+    .page-heading > div:first-child {
+        width: 100%;
+    }
+    .page-heading > .search-form {
+        width: 100%;
+    }
+    .page-heading > .inline-actions {
+        width: 100%;
+        flex-wrap: wrap;
+        flex-shrink: 1;
+        justify-content: flex-start;
+    }
+}
+
+.drive-backup-state {
+    display: flex;
+    align-items: center;
+    gap: 9px;
+    font-weight: 500;
+}
+.drive-recovery-help {
+    margin-top: 20px;
+    color: var(--muted);
+    font-size: 13px;
+}
+.drive-recovery-help summary {
+    cursor: pointer;
+    color: var(--ink);
+    font-weight: 500;
+}
+.drive-recovery-help pre {
+    padding: 14px;
+    background: var(--canvas);
+    color: var(--ink);
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    border-radius: 8px;
+}
+.drive-recovery-help p {
+    line-height: 1.7;
+}
+
+.toast {
+    color: var(--toast-ink);
+}
+.toast.toast-error {
+    background: var(--danger);
+    color: var(--on-danger);
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .topbar {
+        gap: 8px;
+    }
+    .transfer-filters button {
+        min-height: 44px;
+    }
+}
+
+/* Keep navigation and file controls from becoming a text document on Ctrl+A. */
+.app-shell,
+.login-page,
+.startup {
+    user-select: none;
+}
+input,
+textarea,
+[contenteditable]:not([contenteditable="false"]),
+.text-preview pre,
+.pdf-text-layer,
+.pdf-text-layer *,
+.settings-facts dd,
+.connection-api-summary dd,
+.storage-catalog dd,
+.recovery-command code,
+.error-notice,
+[role="alert"],
+.transfer-error,
+.drive-recovery-help pre,
+.management-pending code,
+.file-details-metadata dd,
+.file-details-body h2,
+.preview-heading h2 {
+    user-select: text;
+}
+.search-form[aria-busy="true"] > .spinner {
+    flex-shrink: 0;
+    width: 16px;
+    height: 16px;
+}
+
+.transfer-history-filters {
+    margin-top: 20px;
+    flex-wrap: wrap;
+    overflow: visible;
+    max-width: 100%;
+}
+.transfer-history-loading {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    padding: 40px 0;
+    color: var(--muted);
+}
+.transfer-history-time {
+    color: var(--muted);
+    font-size: 11px;
+}
+.transfer-history-more {
+    display: flex;
+    justify-content: center;
+    margin-top: 16px;
+}
+
+@media (max-width: 480px) {
+    .transfer-history-filters {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+}
+
+/* Transfer overview: compact rows, separated by the work that needs attention. */
+.transfer-center.transfer-page {
+    border: 0;
+    border-radius: 0;
+    background: transparent;
+    margin-top: 12px;
+    overflow: visible;
+}
+.transfer-page > .transfer-heading {
+    justify-content: flex-end;
+    background: transparent;
+    padding: 0 0 8px;
+}
+.transfer-heading[hidden] {
+    display: none;
+}
+.transfer-page > .transfer-heading .text-button {
+    font-size: 12px;
+}
+.transfer-category + .transfer-category {
+    margin-top: 16px;
+}
+.transfer-category-title {
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+    margin: 0;
+    padding: 10px 16px 8px;
+    color: var(--muted);
+    font-size: 12px;
+    font-weight: 500;
+}
+.transfer-category-title > span {
+    font-variant-numeric: tabular-nums;
+}
+.transfer-page .transfer-category-title {
+    padding: 12px 8px 8px;
+    color: var(--ink);
+    font-size: 13px;
+}
+.transfer-page .transfer-category-title > span {
+    color: var(--muted);
+    font-size: 12px;
+}
+.transfer-page .transfer-category > [role="list"] {
+    border-top: 1px solid var(--line-subtle);
+}
+.transfer-center .transfer-item {
+    gap: 10px;
+    padding: 12px 16px;
+}
+.transfer-page .transfer-item {
+    padding: 12px 8px;
+    align-items: flex-start;
+}
+.transfer-center .transfer-copy {
+    gap: 4px;
+}
+.transfer-center .transfer-item-name {
+    font-weight: 500;
+}
+.transfer-location {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 11px;
+    color: var(--muted);
+}
+.transfer-row-details {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 4px 14px;
+}
+.transfer-row-details .transfer-metrics {
+    display: contents;
+}
+.transfer-center .transfer-copy > progress {
+    height: 4px;
+    margin: 3px 0;
+}
+.transfer-center .transfer-item[data-status="cancelled"] .transfer-state-icon {
+    color: var(--muted);
+}
+.transfer-center .transfer-batch-summary {
+    padding: 12px 16px;
+}
+.transfer-page .transfer-batch-summary {
+    padding: 12px 8px;
+}
+.transfer-center .transfer-batch-status,
+.transfer-center .transfer-batch-metrics {
+    margin-block: 5px;
+}
+.transfer-center .transfer-batch-summary > progress {
+    height: 4px;
+    margin-block: 6px;
+}
+.transfer-center .transfer-batch-actions {
+    margin-top: 6px;
+}
+.transfer-category .transfer-item:last-child,
+.transfer-category .transfer-batch:last-child {
+    border-bottom: 0;
+}
+.transfer-page .transfer-item:hover {
+    background: var(--hover);
+}
+.transfer-page .transfer-item-name {
+    font-size: 13px;
+}
+.transfer-page .transfer-location,
+.transfer-page .transfer-bytes,
+.transfer-page .transfer-history-time,
+.transfer-page .transfer-phase {
+    font-size: 12px;
+}
+.transfer-page .transfer-category + .transfer-category {
+    margin-top: 22px;
+}
+@media (max-width: 480px) {
+    .transfer-row-details {
+        gap: 4px 10px;
+    }
+    .transfer-page .transfer-item {
+        gap: 8px;
+    }
+    .transfer-page .transfer-item-actions {
+        flex-wrap: wrap;
+        max-width: 68px;
+    }
+}
+
+.transfer-category-title[hidden] {
+    display: none;
+}
+
+/* Use the transfer area's width, including inside expanded upload batches. */
+.transfer-page {
+    container-type: inline-size;
+}
+.transfer-page .transfer-relative-path,
+.transfer-page .transfer-history-time {
+    min-width: 0;
+}
+@container (min-width: 600px) {
+    .transfer-page .transfer-copy {
+        display: grid;
+        grid-template-columns: minmax(0, 1.5fr) minmax(0, 1fr);
+        align-items: center;
+        column-gap: 20px;
+        row-gap: 4px;
+    }
+    .transfer-page .transfer-item-title {
+        grid-column: 1;
+        grid-row: 1;
+        min-width: 0;
+    }
+    .transfer-page .transfer-location {
+        grid-column: 2;
+        grid-row: 1;
+        min-width: 0;
+    }
+    .transfer-page
+        .transfer-copy:not(:has(.transfer-location))
+        > .transfer-item-title {
+        grid-column: 1 / -1;
+    }
+    .transfer-page .transfer-row-details,
+    .transfer-page .transfer-phase,
+    .transfer-page .transfer-copy > progress,
+    .transfer-page .transfer-error,
+    .transfer-page .transfer-relative-path {
+        grid-column: 1 / -1;
+        min-width: 0;
+    }
+    .transfer-page .transfer-row-details {
+        margin-top: 0;
+    }
+}
+@container (min-width: 900px) {
+    .transfer-page .transfer-item {
+        display: grid;
+        grid-template-columns: 20px minmax(0, 1fr) 96px;
+        align-items: start;
+        column-gap: 12px;
+        padding-block: 10px;
+        min-height: 48px;
+    }
+    .transfer-page .transfer-state-icon {
+        padding-top: 4px;
+    }
+    .transfer-page .transfer-copy {
+        grid-template-columns: minmax(0, 1.6fr) minmax(0, 1fr) 110px 160px;
+        min-height: 28px;
+    }
+    .transfer-page
+        .transfer-copy:not(:has(.transfer-location))
+        > .transfer-item-title {
+        grid-column: 1 / 3;
+    }
+    .transfer-page .transfer-row-details {
+        display: contents;
+    }
+    .transfer-page .transfer-row-details > .transfer-bytes {
+        grid-column: 3;
+        grid-row: 1;
+        text-align: end;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+    }
+    .transfer-page .transfer-history-time {
+        grid-column: 4;
+        grid-row: 1;
+        text-align: end;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+    }
+    .transfer-page .transfer-phase {
+        grid-column: 1;
+        grid-row: 2;
+    }
+    .transfer-page .transfer-row-details .transfer-metrics {
+        display: flex;
+        grid-column: 2 / -1;
+        grid-row: 2;
+        flex-wrap: wrap;
+        min-width: 0;
+    }
+    .transfer-page .transfer-copy > progress {
+        grid-row: 3;
+    }
+    .transfer-page .transfer-item-actions {
+        width: auto;
+        max-width: none;
+        flex-wrap: wrap;
+        justify-content: flex-end;
+    }
+}
+
+.transfer-recovery {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 8px 14px;
+    min-width: 0;
+    padding-block: 3px;
+}
+.transfer-recovery-message {
+    color: var(--muted);
+    font-size: 12px;
+    overflow-wrap: anywhere;
+}
+.transfer-recovery .transfer-recovery-button {
+    display: inline-flex;
+    align-items: center;
+    gap: 7px;
+    flex-shrink: 0;
+    min-height: 34px;
+    padding: 6px 11px;
+    font-size: 12px;
+    line-height: 18px;
+    border-radius: 8px;
+    white-space: nowrap;
+}
+@container (min-width: 600px) {
+    .transfer-page .transfer-recovery {
+        grid-column: 1 / -1;
+    }
+}
+@container (min-width: 900px) {
+    .transfer-page .transfer-recovery {
+        grid-row: 2;
+    }
+}
+
+.transfer-verification {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+}
+.transfer-verification .spinner {
+    width: 13px;
+    height: 13px;
+    flex-shrink: 0;
+}
+
+/* Batch headers use the same compact rhythm as individual transfers. */
+.transfer-center .transfer-batch-summary {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) auto;
+    align-items: center;
+    column-gap: 12px;
+    row-gap: 4px;
+    min-width: 0;
+}
+.transfer-batch-title {
+    grid-column: 1;
+    grid-row: 1;
+    min-width: 0;
+    gap: 8px;
+}
+.transfer-center .transfer-batch-toggle {
+    display: inline-flex;
+    align-items: center;
+    justify-content: flex-start;
+    flex: 1;
+    min-width: 0;
+    min-height: 28px;
+    gap: 6px;
+    padding: 0;
+    margin: 0;
+    text-align: start;
+}
+.transfer-batch-toggle > svg {
+    flex-shrink: 0;
+    color: var(--muted);
+}
+.transfer-center .transfer-batch-name {
+    font-size: 13px;
+    font-weight: 500;
+    line-height: 20px;
+}
+.transfer-batch-count {
+    flex-shrink: 0;
+    white-space: nowrap;
+    color: var(--muted);
+    font-size: 11px;
+}
+.transfer-batch-location {
+    grid-column: 1 / -1;
+    grid-row: 2;
+    padding-inline-start: 30px;
+    min-width: 0;
+    color: var(--muted);
+    font-size: 11px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.transfer-center .transfer-batch-metrics {
+    grid-column: 1;
+    grid-row: 3;
+    min-width: 0;
+    padding-inline-start: 30px;
+    margin: 0;
+}
+.transfer-batch-throughput {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px 12px;
+    min-width: 0;
+}
+.transfer-batch-size {
+    font-variant-numeric: tabular-nums;
+}
+.transfer-batch-time {
+    grid-column: 2;
+    grid-row: 3;
+    min-width: 0;
+    color: var(--muted);
+    font-size: 11px;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    text-align: end;
+}
+.transfer-center .transfer-batch-status {
+    grid-column: 1 / -1;
+    grid-row: 4;
+    margin: 0;
+    padding-inline-start: 30px;
+    font-size: 11px;
+    line-height: 1.5;
+}
+.transfer-center .transfer-batch-summary > progress {
+    grid-column: 1 / -1;
+    grid-row: 5;
+    margin: 3px 0 3px 30px;
+    width: calc(100% - 30px);
+}
+.transfer-center .transfer-batch-actions {
+    grid-column: 1 / -1;
+    grid-row: 6;
+    margin: 0;
+    padding-inline-start: 30px;
+}
+.transfer-batch-locate,
+.transfer-batch-cancel {
+    grid-column: 2;
+    grid-row: 1;
+    justify-self: end;
+}
+.transfer-batch[data-cancelled="true"]
+    > .transfer-batch-summary
+    .transfer-state-icon {
+    color: var(--muted);
+}
+.transfer-batch-files {
+    margin: 0 0 8px 22px;
+    border-top: 0;
+    border-inline-start: 1px solid var(--line-subtle);
+}
+.transfer-files-toolbar {
+    background: transparent;
+    padding-block: 6px;
+}
+.transfer-batch + .transfer-batch {
+    border-top-color: var(--line-subtle);
+}
+.transfer-page .transfer-batch {
+    border-bottom: 1px solid var(--line-subtle);
+}
+.transfer-page .transfer-batch + .transfer-batch {
+    border-top: 0;
+}
+@container (min-width: 900px) {
+    .transfer-page .transfer-batch-summary {
+        grid-template-columns: minmax(0, 1.6fr) minmax(0, 1fr) 110px 160px 96px;
+        padding-block: 10px;
+        column-gap: 20px;
+        min-height: 48px;
+    }
+    .transfer-page .transfer-batch-location {
+        grid-column: 2;
+        grid-row: 1;
+        padding: 0;
+        font-size: 12px;
+    }
+    .transfer-page .transfer-batch-metrics {
+        display: contents;
+    }
+    .transfer-page .transfer-batch-size {
+        grid-column: 3;
+        grid-row: 1;
+        font-size: 12px;
+        text-align: end;
+        white-space: nowrap;
+    }
+    .transfer-page .transfer-batch-time {
+        grid-column: 4;
+        grid-row: 1;
+        font-size: 12px;
+    }
+    .transfer-page .transfer-batch-locate,
+    .transfer-page .transfer-batch-cancel {
+        grid-column: 5;
+        grid-row: 1;
+    }
+    .transfer-page .transfer-batch-status {
+        grid-column: 1;
+        grid-row: 2;
+        padding-inline-start: 30px;
+        font-size: 12px;
+    }
+    .transfer-page .transfer-batch-throughput {
+        grid-column: 2 / 5;
+        grid-row: 2;
+        font-size: 12px;
+    }
+    .transfer-page .transfer-batch-actions {
+        grid-row: 3;
+    }
+    .transfer-page .transfer-batch-summary > progress {
+        grid-row: 4;
+    }
+}
+@media (max-width: 480px) {
+    .transfer-batch-files {
+        margin-inline-start: 12px;
+    }
+    .transfer-center .transfer-batch-summary {
+        column-gap: 8px;
+    }
+    .transfer-batch-time {
+        white-space: normal;
+        overflow-wrap: anywhere;
+        max-width: 150px;
+    }
+}
+
+@container (min-width: 900px) {
+    .transfer-page
+        .transfer-batch:not([data-status="finished"])
+        .transfer-batch-size {
+        grid-column: 3 / 5;
+        white-space: normal;
+        overflow-wrap: anywhere;
+    }
+}
+
+.share-expiry-options {
+    border: 0;
+    padding: 0;
+    margin: 20px 0;
+    min-width: 0;
+}
+.share-expiry-options legend {
+    padding: 0;
+    margin-bottom: 10px;
+    font-weight: 500;
+}
+.share-expiry-options > div {
+    display: grid;
+    grid-template-columns: repeat(4, minmax(0, 1fr));
+    gap: 6px;
+}
+.share-expiry-options button {
+    padding: 9px 4px;
+    border: 1px solid var(--line);
+    background: var(--surface);
+    color: var(--ink);
+    border-radius: 8px;
+    font: inherit;
+    font-size: 13px;
+    cursor: pointer;
+}
+.share-expiry-options button:hover {
+    background: var(--hover);
+}
+.share-expiry-options button[aria-pressed="true"] {
+    border-color: var(--action);
+    background: var(--selected);
+    color: var(--on-action-soft);
+}
+
+/* Shared compact choice fields use the same themed, explicit controls. */
+.dialog-choice-options {
+    border: 0;
+    padding: 0;
+    margin: 20px 0;
+    min-width: 0;
+}
+.dialog-choice-options legend {
+    padding: 0;
+    margin-bottom: 10px;
+    font-weight: 500;
+}
+.dialog-choice-options > div {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 8px;
+}
+.dialog-choice-options button {
+    min-height: 42px;
+    padding: 9px 12px;
+    border: 1px solid var(--line);
+    background: var(--surface);
+    color: var(--ink);
+    border-radius: 8px;
+    font: inherit;
+    cursor: pointer;
+}
+.dialog-choice-options button:hover {
+    background: var(--hover);
+}
+.dialog-choice-options button[aria-pressed="true"] {
+    border-color: var(--action);
+    background: var(--selected);
+    color: var(--on-action-soft);
+}
+.dialog-choice-options p {
+    margin: 8px 0 0;
+    font-size: 12px;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .icon-button,
+    .actions-cell .icon-button,
+    .transfer-item-actions .icon-button,
+    .transfer-batch-locate,
+    .transfer-batch-cancel {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .managed-client-row .text-button {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .transfer-item-actions {
+        flex-wrap: wrap;
+        justify-content: flex-end;
+        max-width: 88px;
+    }
+    .transfer-center .text-button {
+        min-height: 44px;
+    }
+    .share-row-actions .secondary-button {
+        min-height: 44px;
+    }
+    .file-table .size-cell {
+        width: 76px;
+    }
+    .share-row-actions {
+        flex-wrap: wrap;
+    }
+}
+
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    /* Keep action clearance inside the scrolling content, without an outer gap. */
+    .app-shell:has(#compact-new-button) .workspace {
+        max-height: none;
+    }
+}
+
+/* Disclosure is one stable target; navigation is a separate row action. */
+.transfer-center .transfer-batch-toggle {
+    border: 0;
+    background: transparent;
+    color: var(--ink);
+    border-radius: 6px;
+    font: inherit;
+    cursor: pointer;
+    padding: 4px 0;
+    min-height: 36px;
+    gap: 8px;
+}
+.transfer-batch-toggle:focus-visible {
+    outline: 2px solid var(--action);
+    outline-offset: 3px;
+}
+.transfer-batch-toggle .transfer-batch-name {
+    flex: 0 1 auto;
+    color: var(--ink);
+}
+.transfer-group-icon {
+    display: inline-flex;
+    flex-shrink: 0;
+    color: var(--icon);
+}
+.transfer-center .transfer-batch-summary:has(.transfer-batch-toggle:hover) {
+    background: var(--hover);
+}
+.transfer-batch[data-expanded="true"] > .transfer-batch-summary {
+    background: var(--surface-subtle);
+}
+.transfer-batch-files {
+    margin-inline-start: 28px;
+}
+.transfer-center .transfer-child {
+    padding-block: 8px;
+}
+@container (min-width:600px) {
+    .transfer-page .transfer-child .transfer-copy {
+        grid-template-columns: minmax(0, 1fr) 110px;
+    }
+    .transfer-page .transfer-child .transfer-item-title,
+    .transfer-page
+        .transfer-child
+        .transfer-copy:not(:has(.transfer-location))
+        > .transfer-item-title {
+        grid-column: 1;
+        grid-row: 1;
+    }
+    .transfer-page .transfer-child .transfer-location {
+        grid-column: 1;
+        grid-row: 2;
+    }
+    .transfer-page .transfer-child .transfer-phase {
+        grid-column: 1;
+        grid-row: 2;
+    }
+    .transfer-page
+        .transfer-child
+        .transfer-copy:has(.transfer-phase)
+        .transfer-location {
+        grid-row: 3;
+    }
+    .transfer-page .transfer-child .transfer-row-details {
+        display: contents;
+    }
+    .transfer-page .transfer-child .transfer-row-details > .transfer-bytes {
+        grid-column: 2;
+        grid-row: 1;
+        text-align: end;
+    }
+    .transfer-page .transfer-child .transfer-row-details .transfer-metrics {
+        display: flex;
+        grid-column: 1 / -1;
+        grid-row: 4;
+    }
+    .transfer-page .transfer-child .transfer-copy > progress {
+        grid-column: 1 / -1;
+        grid-row: 5;
+    }
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .transfer-center .transfer-batch-toggle {
+        min-height: 44px;
+    }
+    .transfer-batch-files {
+        margin-inline-start: 14px;
+    }
+}
+
+/* Audit fixes shared by owner pages, menus and narrow layouts. */
+.mobile-nav-heading {
+    display: flex;
+    flex: 0 0 auto;
+    min-height: 44px;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    margin-bottom: 12px;
+}
+.mobile-nav-heading strong {
+    font-size: 18px;
+    letter-spacing: -0.02em;
+}
+.page-load-error {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    gap: 12px;
+    margin-block: 16px;
+}
+.page-load-error .error-notice {
+    flex: 1 1 240px;
+    margin: 0;
+}
+.file-checkbox-target {
+    margin: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .text-button,
+    .primary-button,
+    .secondary-button,
+    .danger-button,
+    .file-sort-trigger,
+    .file-sort-menu button,
+    .theme-menu button,
+    .inline-link {
+        min-height: 44px;
+    }
+    .column-sort-button {
+        min-width: 44px;
+    }
+    .storage-count-link {
+        min-width: 44px;
+        min-height: 44px;
+        text-align: start;
+    }
+    .file-selection-slot:has(input) {
+        flex-basis: 44px;
+        width: 44px;
+        height: 44px;
+    }
+    .file-checkbox-target {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .search-form input {
+        font-size: 16px;
+    }
+    input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not(
+            [type="file"]
+        ),
+    .app-shell select,
+    .app-shell textarea,
+    .modal select,
+    .modal textarea {
+        font-size: 16px;
+    }
+    .topbar {
+        padding-inline: max(8px, env(safe-area-inset-left))
+            max(8px, env(safe-area-inset-right));
+    }
+    .public-shell .topbar {
+        flex-wrap: wrap;
+    }
+    .public-shell .topbar > .brand {
+        flex: 1;
+        min-width: 0;
+    }
+    .public-label {
+        flex: 1 0 100%;
+        padding: 0 4px 8px;
+    }
+}
+
+.theme-control {
+    position: relative;
+    flex-shrink: 0;
+}
+.theme-trigger {
+    color: var(--muted);
+}
+.theme-menu {
+    position: absolute;
+    right: 0;
+    top: calc(100% + 6px);
+    width: 168px;
+    padding: 6px;
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    background: var(--surface-raised);
+    box-shadow: var(--menu-shadow);
+    z-index: 50;
+}
+.theme-menu button {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    width: 100%;
+    padding: 10px;
+    background: transparent;
+    border: 0;
+    border-radius: 6px;
+    text-align: left;
+}
+.theme-menu button span {
+    flex: 1;
+}
+.theme-menu button:hover {
+    background: var(--hover);
+}
+.theme-menu button[aria-checked="true"] {
+    color: var(--action);
+    background: var(--action-soft);
+}
+.page-heading > .theme-control {
+    margin-inline-start: auto;
+}
+.file-toolbar > .page-heading > .theme-control {
+    order: 4;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .page-heading > .theme-control {
+        display: none;
+    }
+    .topbar > .theme-control {
+        margin-inline-start: auto;
+    }
+}
+
+.page-title-line {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    min-width: 0;
+}
+.page-title-line h1 {
+    margin-bottom: 0;
+}
+.demo-marker {
+    font-size: 12px;
+    font-weight: 400;
+    color: var(--muted);
+}
+
+.preview-fullscreen-surface {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-width: 0;
+    min-height: 0;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    background: #202328;
+}
+.preview-fullscreen-surface:fullscreen {
+    position: relative;
+    width: 100vw;
+    height: 100dvh;
+}
+.preview-header[hidden],
+.preview-quality[hidden] {
+    display: none;
+}
+.preview-toolbar-toggle {
+    position: absolute;
+    z-index: 10;
+    /* Keep one stable target clear of the browser's fullscreen exit control. */
+    top: max(8px, env(safe-area-inset-top));
+    right: max(12px, env(safe-area-inset-right));
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 44px;
+    height: 44px;
+    padding: 0;
+    border: 1px solid #535963;
+    border-radius: 8px;
+    background: #181b20;
+    color: #f1f3f6;
+    cursor: pointer;
+}
+.preview-toolbar-toggle:hover {
+    background: #30343c;
+}
+.preview-toolbar-toggle:focus-visible {
+    outline: 2px solid #f1f3f6;
+    outline-offset: -4px;
+}
+.file-preview .preview-fullscreen-surface:fullscreen .preview-header {
+    /* Reserve space for the toggle in the expanded toolbar too. */
+    padding-right: calc(max(12px, env(safe-area-inset-right)) + 56px);
+}
+.file-details .preview-fullscreen-surface {
+    display: contents;
+}
+.preview-header .preview-fullscreen {
+    flex: 0 0 44px;
+}
+
+.brand-mark {
+    display: block;
+    flex-shrink: 0;
+    object-fit: contain;
+}
+.brand-logo {
+    display: inline-block;
+    flex: 0 0 auto;
+    width: 160px;
+    aspect-ratio: 2010 / 401;
+    vertical-align: middle;
+}
+.brand-logo-compact {
+    width: 160px;
+}
+.brand-logo-large {
+    width: 192px;
+}
+.brand-logo img {
+    display: block;
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
+.brand-logo .brand-logo-dark,
+.brand-logo .brand-logo-icon {
+    display: none;
+}
+:root[data-theme="dark"] .brand-logo .brand-logo-light {
+    display: none;
+}
+:root[data-theme="dark"] .brand-logo .brand-logo-dark {
+    display: block;
+}
+@media (prefers-color-scheme: dark) {
+    :root:not([data-theme]) .brand-logo .brand-logo-light {
+        display: none;
+    }
+    :root:not([data-theme]) .brand-logo .brand-logo-dark {
+        display: block;
+    }
+}
+.mobile-drawer-brand,
+.mobile-brand {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.mobile-brand {
+    min-height: 44px;
+}
+.mobile-brand .brand-logo {
+    flex-shrink: 1;
+    width: 100%;
+    max-width: 160px;
+}
+@media (max-width: 374px) {
+    .mobile-brand .brand-logo {
+        flex: 0 0 32px;
+        width: 32px;
+        aspect-ratio: 1;
+    }
+    :root .mobile-brand .brand-logo .brand-logo-light,
+    :root .mobile-brand .brand-logo .brand-logo-dark {
+        display: none;
+    }
+    .mobile-brand .brand-logo .brand-logo-icon {
+        display: block;
+    }
+}
+.file-star-indicator {
+    flex: 0 0 auto;
+    color: var(--action);
+}
+.file-tile-format {
+    color: var(--muted);
+    font-size: 12px;
+    font-weight: 500;
+    letter-spacing: 0.02em;
+}
+.file-tile-preview:has(.file-tile-format) {
+    flex-direction: column;
+    gap: 8px;
+}
diff --git a/website/src/features/backup/ChannelBackup.css b/website/src/features/backup/ChannelBackup.css
new file mode 100644
index 00000000..b1acc400
--- /dev/null
+++ b/website/src/features/backup/ChannelBackup.css
@@ -0,0 +1,295 @@
+.channel-backup {
+    min-width: 0;
+}
+.channel-backup-heading {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 16px;
+}
+.channel-backup-heading > div {
+    min-width: 0;
+}
+.channel-backup-heading h2 {
+    margin: 0 0 8px;
+}
+.channel-backup-heading p {
+    margin: 0;
+    max-width: 70ch;
+    color: var(--muted);
+    line-height: 1.6;
+}
+.channel-backup .icon-button {
+    flex: 0 0 auto;
+}
+.channel-backup-loading,
+.channel-backup-phase {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin: 20px 0 16px;
+}
+.channel-backup-channels,
+.channel-backup-candidate dl {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 16px 36px;
+    margin: 16px 0;
+}
+.channel-backup-channels div,
+.channel-backup-candidate dl div {
+    display: grid;
+    gap: 6px;
+    min-width: 0;
+}
+.channel-backup dt {
+    color: var(--muted);
+    font-size: 13px;
+}
+.channel-backup dd {
+    margin: 0;
+    overflow-wrap: anywhere;
+    font-variant-numeric: tabular-nums;
+}
+.channel-backup-confirmation p,
+.channel-backup-key-help {
+    margin: 10px 0;
+    color: var(--muted);
+    font-size: 13px;
+    line-height: 1.6;
+    max-width: 75ch;
+}
+.channel-backup-progress {
+    margin-block: 20px;
+}
+.channel-backup-progress-label {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: 8px 16px;
+    color: var(--muted);
+    font-size: 13px;
+    font-variant-numeric: tabular-nums;
+}
+.channel-backup progress {
+    display: block;
+    width: 100%;
+    height: 6px;
+    margin: 12px 0;
+    accent-color: var(--action);
+}
+.channel-backup-file {
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    margin-bottom: 12px;
+}
+.channel-backup-progress-detail {
+    font-variant-numeric: tabular-nums;
+}
+.channel-backup-progress > p:not(.channel-backup-file),
+.channel-backup-feedback p {
+    color: var(--muted);
+    line-height: 1.6;
+    font-size: 13px;
+}
+.channel-backup-actions {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 8px 12px;
+    margin-block: 16px;
+}
+.channel-backup-actions button,
+.channel-backup-actions a,
+.channel-backup-form > button {
+    gap: 8px;
+}
+.channel-backup-feedback {
+    margin-block: 16px;
+}
+.channel-backup-feedback p {
+    margin-block: 8px;
+}
+.channel-backup-form {
+    margin-block: 20px;
+    display: grid;
+    gap: 16px;
+}
+.channel-backup-form h3,
+.channel-backup-candidate h3 {
+    margin: 0;
+    font-size: 16px;
+    font-weight: 600;
+}
+.channel-backup-form > p,
+.channel-backup-details > p,
+.channel-backup-candidate p {
+    margin: 0;
+    color: var(--muted);
+    line-height: 1.6;
+    max-width: 75ch;
+}
+.channel-backup-fields {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 16px;
+}
+.channel-backup label:not(.channel-backup-checkbox) {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    min-width: 0;
+    line-height: 1.5;
+}
+.channel-backup input:not([type="checkbox"]) {
+    width: 100%;
+    min-width: 0;
+    box-sizing: border-box;
+}
+.channel-backup-optional {
+    color: var(--muted);
+    font-size: 13px;
+}
+.channel-backup-checkbox {
+    display: flex;
+    align-items: flex-start;
+    gap: 10px;
+    max-width: 75ch;
+    line-height: 1.6;
+    cursor: pointer;
+}
+.channel-backup-checkbox input {
+    flex: 0 0 auto;
+    margin-top: 4px;
+    width: 18px;
+    height: 18px;
+    accent-color: var(--action);
+}
+.channel-backup-details {
+    margin-top: 20px;
+    padding-top: 16px;
+    border-top: 1px solid var(--line);
+}
+.channel-backup-details > summary {
+    cursor: pointer;
+    font-weight: 600;
+    padding-block: 8px;
+}
+.channel-backup-details[open] > summary {
+    margin-bottom: 12px;
+}
+.channel-backup-candidate {
+    margin-top: 20px;
+}
+.channel-backup-report {
+    padding: 0;
+    margin: 16px 0;
+    list-style: none;
+    max-height: 320px;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+}
+.channel-backup-report li {
+    display: grid;
+    grid-template-columns: minmax(100px, 190px) minmax(0, 1fr);
+    gap: 8px 16px;
+    padding-block: 10px;
+    border-bottom: 1px solid var(--line-subtle);
+    font-size: 13px;
+    line-height: 1.6;
+}
+.channel-backup-report time {
+    color: var(--muted);
+}
+.channel-backup-report span {
+    overflow-wrap: anywhere;
+}
+.channel-backup-guide {
+    display: inline-block;
+    margin-top: 20px;
+}
+@media (max-width: 720px) {
+    .channel-backup-fields {
+        grid-template-columns: minmax(0, 1fr);
+    }
+    .channel-backup-actions {
+        gap: 8px;
+    }
+    .channel-backup button,
+    .channel-backup .text-button,
+    .channel-backup summary {
+        min-height: 44px;
+    }
+    .channel-backup-actions > .primary-button,
+    .channel-backup-form > .primary-button {
+        width: 100%;
+        justify-content: center;
+    }
+    .channel-backup-report li {
+        grid-template-columns: minmax(0, 1fr);
+        gap: 4px;
+    }
+    .channel-backup-channels,
+    .channel-backup-candidate dl {
+        gap: 16px 24px;
+    }
+}
+
+.channel-recovery-shell {
+    height: 100dvh;
+    display: flex;
+    flex-direction: column;
+    background: var(--surface);
+}
+.channel-recovery-topbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    min-height: 64px;
+    padding: 8px 24px;
+    border-bottom: 1px solid var(--line);
+}
+.channel-recovery-topbar > div {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+}
+.channel-recovery-topbar .sidebar-logout {
+    width: auto;
+    padding-inline: 12px;
+}
+.channel-recovery-main {
+    flex: 1;
+    min-height: 0;
+    overflow-y: auto;
+    width: 100%;
+    max-width: 1100px;
+    margin: 0 auto;
+    padding: 24px;
+}
+.channel-recovery-main > h1 {
+    font-size: 24px;
+    margin: 0 0 12px;
+}
+.channel-recovery-intro {
+    color: var(--muted);
+    margin: 0 0 24px;
+    max-width: 75ch;
+    line-height: 1.6;
+}
+@media (max-width: 720px) {
+    .channel-recovery-topbar {
+        flex-wrap: wrap;
+        gap: 4px 12px;
+        padding: max(8px, env(safe-area-inset-top)) 12px 8px;
+    }
+    .channel-recovery-topbar > div {
+        gap: 4px;
+        margin-inline-start: auto;
+    }
+    .channel-recovery-main {
+        padding: 20px 12px max(20px, env(safe-area-inset-bottom));
+    }
+}
diff --git a/website/src/features/backup/ChannelBackup.test.ts b/website/src/features/backup/ChannelBackup.test.ts
new file mode 100644
index 00000000..b074b4a9
--- /dev/null
+++ b/website/src/features/backup/ChannelBackup.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import {
+    parseChannelId,
+    retryTime,
+    validateBackupToken,
+} from "./ChannelBackup";
+
+describe("channel identifiers stay exact before a backup destination is sent", () => {
+    it("accepts a Telegram channel ID and surrounding copied whitespace", () => {
+        expect(parseChannelId(" -1001234567890 ")).toBe(-1001234567890);
+    });
+    it.each([
+        "",
+        "0",
+        "-0",
+        "123456",
+        "-1e12",
+        "-100.5",
+        "-9007199254740992",
+        "--100123",
+        "-100 123",
+    ])("rejects ambiguous, positive or imprecise destination %s", (value) => {
+        expect(() => parseChannelId(value)).toThrow(
+            "negative numeric channel ID",
+        );
+    });
+});
+describe("backup bot credentials", () => {
+    it("accepts a complete token copied with surrounding whitespace", () => {
+        const token = "123456789:" + "a".repeat(35);
+        expect(validateBackupToken(" " + token + " ")).toBe(token);
+    });
+    it.each([
+        "",
+        "123456789",
+        "123456789:short",
+        "123456789:" + "a".repeat(20) + " injected",
+    ])(
+        "rejects incomplete or internally spaced tokens without echoing them",
+        (value) => {
+            expect(() => validateBackupToken(value)).toThrow(
+                "Enter the full bot token from BotFather.",
+            );
+        },
+    );
+});
+
+describe("Telegram retry deadlines", () => {
+    it("uses Unix seconds once and accepts persisted ISO deadlines", () => {
+        const seconds = Date.parse("2026-10-22T05:00:00Z") / 1000;
+        expect(retryTime(seconds)).toContain("2026");
+        expect(retryTime(seconds)).toBe(retryTime("2026-10-22T05:00:00Z"));
+        expect(retryTime(null)).toBe("");
+    });
+});
diff --git a/website/src/features/backup/ChannelBackup.tsx b/website/src/features/backup/ChannelBackup.tsx
new file mode 100644
index 00000000..f8af0a06
--- /dev/null
+++ b/website/src/features/backup/ChannelBackup.tsx
@@ -0,0 +1,1288 @@
+import {
+    useCallback,
+    useEffect,
+    useRef,
+    useState,
+    type FormEvent,
+} from "react";
+import { Download, Pause, Play, RefreshCw, ShieldCheck } from "lucide-react";
+import { errorMessage, request } from "../../shared/api";
+import { useManualRefresh } from "../../shared/useManualRefresh";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import {
+    currentRate,
+    formatDuration,
+    sampleProgress,
+    type ProgressSample,
+} from "../transfers/progress";
+import { formatBytes, formatTimestamp } from "../../shared/types";
+import "./ChannelBackup.css";
+import DemoModeNotice from "../../shared/DemoModeNotice";
+
+export type ReplicaPhase =
+    | "disabled"
+    | "idle"
+    | "syncing"
+    | "paused"
+    | "waiting"
+    | "error"
+    | "protected"
+    | "recovering"
+    | "ready_to_activate"
+    | "restart_required";
+export interface ReplicaState {
+    enabled: boolean;
+    configured: boolean;
+    recovery_only: boolean;
+    phase: ReplicaPhase;
+    source_channel?: number | null;
+    backup_channel?: number | null;
+    revision: number;
+    protected_revision: number;
+    pending_revision?: number;
+    last_success_at?: string | null;
+    current_file?: string | null;
+    total_files: number;
+    done_files: number;
+    total_parts: number;
+    done_parts: number;
+    total_bytes: number;
+    done_bytes: number;
+    error?: {
+        code: string;
+        detail: string;
+        action: string;
+        retry_at?: number | string | null;
+    } | null;
+    report: { at: string; level: string; message: string }[];
+    recovery_candidate?: {
+        revision: number;
+        files: number;
+        bytes: number;
+        channel: number;
+        complete: boolean;
+    } | null;
+}
+
+type ReplicaAction = "sync" | "pause" | "resume" | "retry" | "disable";
+const ACTIVE = new Set<ReplicaPhase>(["syncing", "recovering", "waiting"]);
+const PHASE_LABEL: Record<ReplicaPhase, string> = {
+    disabled: "Not enabled",
+    idle: "Ready to sync",
+    syncing: "Copying to the backup channel",
+    paused: "Paused",
+    waiting: "Waiting for Telegram",
+    error: "Needs attention",
+    protected: "Backup confirmed",
+    recovering: "Preparing the recovered drive",
+    ready_to_activate: "Recovered drive ready to activate",
+    restart_required: "Restart required",
+};
+
+export function parseChannelId(value: string): number {
+    const raw = value.trim();
+    const id = Number(raw);
+    if (!/^-[1-9]\d*$/.test(raw) || !Number.isSafeInteger(id))
+        throw new Error(
+            "Enter a negative numeric channel ID, such as -1001234567890.",
+        );
+    return id;
+}
+export function validateBackupToken(value: string): string {
+    const token = value.trim();
+    if (!/^[1-9][0-9]{4,14}:[A-Za-z0-9_-]{20,}$/.test(token))
+        throw new Error("Enter the full bot token from BotFather.");
+    return token;
+}
+export function retryTime(value: number | string | null | undefined): string {
+    if (!value) return "";
+    return formatTimestamp(value);
+}
+
+export default function ChannelBackup({
+    recoveryOnly = false,
+    demoMode = false,
+    onRestartRequired,
+    onNotice,
+}: {
+    recoveryOnly?: boolean;
+    demoMode?: boolean;
+    onRestartRequired?: () => void;
+    onNotice?: (message: string, error?: boolean) => void;
+}) {
+    const [state, setState] = useState<ReplicaState | null>(null);
+    const [loadError, setLoadError] = useState("");
+    const [actionError, setActionError] = useState("");
+    const [busy, setBusy] = useState("");
+    const [configureOpen, setConfigureOpen] = useState(false);
+    const [channel, setChannel] = useState("");
+    const [token, setToken] = useState("");
+    const [independent, setIndependent] = useState(false);
+    const [disableConfirm, setDisableConfirm] = useState(false);
+    const [recoveryOpen, setRecoveryOpen] = useState(recoveryOnly);
+    const [source, setSource] = useState("");
+    const [sourceToken, setSourceToken] = useState("");
+    const [key, setKey] = useState("");
+    const [messageId, setMessageId] = useState("");
+    const [target, setTarget] = useState("");
+    const [targetToken, setTargetToken] = useState("");
+    const [catalogOnly, setCatalogOnly] = useState(false);
+    const [confirmation, setConfirmation] = useState("");
+    const [activationConfirmation, setActivationConfirmation] = useState("");
+    const [observedAt, setObservedAt] = useState(Date.now());
+    const mounted = useRef(true);
+    const generation = useRef(0);
+    const manualPending = useRef(false);
+    const { refreshing, run } = useManualRefresh(onNotice);
+    const progress = useRef<ProgressSample | undefined>(undefined);
+    const restartNotified = useRef(false);
+    const surface = useRef<HTMLElement>(null);
+    const focusResult = useRef<"status" | "candidate" | null>(null);
+    const restartCallback = useRef(onRestartRequired);
+    restartCallback.current = onRestartRequired;
+
+    const load = useCallback(async (signal?: AbortSignal, manual = false) => {
+        if (manualPending.current && !manual) return false;
+        const revision = ++generation.current;
+        try {
+            const result = await request<ReplicaState>(
+                "/api/v1/replica",
+                undefined,
+                {
+                    signal,
+                    timeoutMs: 20000,
+                },
+            );
+            if (
+                !mounted.current ||
+                signal?.aborted ||
+                revision !== generation.current
+            )
+                return false;
+            const now = Date.now();
+            progress.current = sampleProgress(
+                progress.current,
+                result.phase,
+                result.done_bytes || 0,
+                now,
+            );
+            setObservedAt(now);
+            setState(result);
+            setLoadError("");
+            return true;
+        } catch (cause) {
+            if (
+                mounted.current &&
+                !signal?.aborted &&
+                revision === generation.current
+            )
+                setLoadError(errorMessage(cause));
+            if (manual) throw cause;
+            return false;
+        }
+    }, []);
+    const refreshStatus = () =>
+        run(
+            async (signal) => {
+                manualPending.current = true;
+                try {
+                    return await load(signal, true);
+                } finally {
+                    manualPending.current = false;
+                }
+            },
+            recoveryOnly
+                ? "Recovery status refreshed."
+                : "Backup status refreshed.",
+        );
+
+    useEffect(() => {
+        mounted.current = true;
+        const controller = new AbortController();
+        void load(controller.signal);
+        const visible = () => {
+            if (document.visibilityState === "visible")
+                void load(controller.signal);
+        };
+        document.addEventListener("visibilitychange", visible);
+        return () => {
+            mounted.current = false;
+            ++generation.current;
+            controller.abort();
+            document.removeEventListener("visibilitychange", visible);
+        };
+    }, [load]);
+    useEffect(() => {
+        if (!state || state.phase === "restart_required") return;
+        const active = ACTIVE.has(state.phase);
+        if (!active && (!state.configured || !state.enabled)) return;
+        const controller = new AbortController();
+        const interval = active
+            ? recoveryOnly || state.phase === "recovering"
+                ? 3000
+                : 5000
+            : 15000;
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            if (document.visibilityState === "visible")
+                await load(controller.signal);
+            // Slow responses still update the page before another poll starts.
+            if (!controller.signal.aborted) timer = setTimeout(poll, interval);
+        };
+        timer = setTimeout(poll, interval);
+        return () => {
+            clearTimeout(timer);
+            controller.abort();
+        };
+    }, [state?.phase, state?.configured, state?.enabled, recoveryOnly, load]);
+    useEffect(() => {
+        if (state?.phase === "restart_required" && !restartNotified.current) {
+            restartNotified.current = true;
+            restartCallback.current?.();
+        }
+    }, [state?.phase]);
+
+    useEffect(() => {
+        if (busy || !focusResult.current) return;
+        const selector =
+            focusResult.current === "candidate"
+                ? ".channel-backup-candidate h3"
+                : ".channel-backup-heading h2";
+        const target = surface.current?.querySelector<HTMLElement>(selector);
+        if (!target) return;
+        focusResult.current = null;
+        target.focus({ preventScroll: true });
+        target.scrollIntoView({ block: "start" });
+    }, [state, busy]);
+
+    const mutate = async (
+        label: string,
+        url: string,
+        payload: unknown,
+        done?: () => void,
+    ) => {
+        if (demoMode) return;
+        setBusy(label);
+        setActionError("");
+        try {
+            await request(url, payload, {
+                timeoutMs: 120000,
+            });
+            if (mounted.current) {
+                if (
+                    [
+                        "configure",
+                        "inspect",
+                        "recover",
+                        "activate",
+                        "pause",
+                        "resume",
+                        "retry",
+                        "disable",
+                        "sync",
+                    ].includes(label)
+                )
+                    focusResult.current =
+                        label === "inspect" ? "candidate" : "status";
+                done?.();
+                await load();
+            }
+        } catch (cause) {
+            if (mounted.current) setActionError(errorMessage(cause));
+        } finally {
+            if (mounted.current) setBusy("");
+        }
+    };
+    const action = (value: ReplicaAction) =>
+        void mutate(value, "/api/v1/replica/action", { action: value }, () =>
+            setDisableConfirm(false),
+        );
+    const configure = (event: FormEvent) => {
+        event.preventDefault();
+        if (demoMode) return;
+        setActionError("");
+        try {
+            const channelId = parseChannelId(channel);
+            if (channelId === state?.source_channel)
+                throw new Error(
+                    "Choose a different channel from the main channel.",
+                );
+            if (!independent)
+                throw new Error(
+                    "Confirm that you created the backup with a separate Telegram account.",
+                );
+            const botToken = validateBackupToken(token);
+            void mutate(
+                "configure",
+                "/api/v1/replica/configure",
+                {
+                    channel_id: channelId,
+                    bot_token: botToken,
+                    independent_accounts: true,
+                },
+                () => {
+                    setToken("");
+                    setConfigureOpen(false);
+                    setIndependent(false);
+                },
+            );
+        } catch (cause) {
+            setActionError(errorMessage(cause));
+        }
+    };
+    const recover = (event: FormEvent, copy: boolean) => {
+        event.preventDefault();
+        if (demoMode) return;
+        setActionError("");
+        try {
+            const sourceChannel =
+                copy && state?.recovery_candidate
+                    ? state.recovery_candidate.channel
+                    : parseChannelId(source);
+            const useSavedCopy = copy && !!state?.recovery_candidate;
+            const credential =
+                !useSavedCopy || sourceToken.trim()
+                    ? validateBackupToken(sourceToken)
+                    : undefined;
+            const recoveryKey = key.trim();
+            if (recoveryKey && !/^[0-9a-fA-F]{64}$/.test(recoveryKey))
+                throw new Error(
+                    "Enter the 64-character hexadecimal key value from the saved recovery-key JSON.",
+                );
+            let checkpoint: number | undefined;
+            if (messageId.trim() && !useSavedCopy) {
+                checkpoint = Number(messageId.trim());
+                if (
+                    !/^[1-9]\d*$/.test(messageId.trim()) ||
+                    !Number.isSafeInteger(checkpoint)
+                )
+                    throw new Error(
+                        "The checkpoint message ID must be a positive whole number.",
+                    );
+            }
+            const mainBot = copy ? validateBackupToken(targetToken) : undefined;
+            const destination = copy
+                ? catalogOnly
+                    ? sourceChannel
+                    : parseChannelId(target)
+                : undefined;
+            if (copy && !catalogOnly && destination === sourceChannel)
+                throw new Error(
+                    "Recovery needs a different empty destination channel.",
+                );
+            if (copy && confirmation.trim() !== String(destination))
+                throw new Error(
+                    "Type the destination channel ID exactly to confirm recovery.",
+                );
+            void mutate(
+                copy ? "recover" : "inspect",
+                "/api/v1/replica/recover",
+                {
+                    source_channel: sourceChannel,
+                    ...(credential ? { bot_token: credential } : {}),
+                    ...(recoveryKey ? { key: recoveryKey } : {}),
+                    ...(checkpoint ? { message_id: checkpoint } : {}),
+                    ...(copy
+                        ? {
+                              target_channel: destination,
+                              target_bot_token: mainBot,
+                              catalog_only: catalogOnly,
+                              confirm_channel: confirmation.trim(),
+                          }
+                        : {}),
+                },
+                () => {
+                    setSourceToken("");
+                    setKey("");
+                    if (copy) setTargetToken("");
+                },
+            );
+        } catch (cause) {
+            setActionError(errorMessage(cause));
+        }
+    };
+    const activate = () => {
+        if (
+            demoMode ||
+            activationConfirmation.trim() !==
+                String(state?.recovery_candidate?.channel)
+        )
+            return;
+        void mutate(
+            "activate",
+            "/api/v1/replica/recover",
+            {
+                activate: true,
+                confirm_channel: activationConfirmation.trim(),
+            },
+            () => {
+                setSourceToken("");
+                setKey("");
+                setActivationConfirmation("");
+            },
+        );
+    };
+
+    const phase = state?.phase || "disabled";
+    const active = ACTIVE.has(phase);
+    const blocked =
+        demoMode || Boolean(busy) || active || phase === "restart_required";
+    const candidate = state?.recovery_candidate;
+    const pending = !!state && state.revision > state.protected_revision;
+    const showProgress =
+        !!state &&
+        (active ||
+            phase === "paused" ||
+            phase === "ready_to_activate" ||
+            (phase === "error" && state.total_files > 0));
+    const rate =
+        active && !state?.error && !loadError
+            ? currentRate(progress.current, observedAt)
+            : undefined;
+    const remaining = state
+        ? Math.max(0, state.total_bytes - state.done_bytes)
+        : 0;
+    const report = (state?.report || []).slice(-30).reverse();
+    const recoveryKeyAction = demoMode ? (
+        <button type="button" className="text-button" disabled>
+            <Download size={16} />
+            Save recovery key
+        </button>
+    ) : (
+        <a className="text-button" href="/api/v1/replica/key" download>
+            <Download size={16} />
+            Save recovery key
+        </a>
+    );
+
+    return (
+        <section
+            className="settings-section channel-backup"
+            aria-labelledby="channel-backup-title"
+            aria-busy={!!busy || refreshing}
+            ref={surface}
+        >
+            {demoMode && recoveryOnly && <DemoModeNotice />}
+            <div className="channel-backup-heading">
+                <div>
+                    <h2 id="channel-backup-title" tabIndex={-1}>
+                        {recoveryOnly
+                            ? "Recover your drive"
+                            : "Independent backup channel"}
+                    </h2>
+                    <p>
+                        {recoveryOnly
+                            ? "Use a surviving channel and your saved recovery key to recover completed files and the catalog."
+                            : "Keep a second copy of completed files and the catalog in another private channel."}
+                    </p>
+                </div>
+                <button
+                    type="button"
+                    className="icon-button"
+                    aria-label="Refresh channel backup status"
+                    disabled={!!busy || refreshing}
+                    onClick={() => void refreshStatus()}
+                >
+                    {refreshing ? <Spinner /> : <RefreshCw size={18} />}
+                </button>
+            </div>
+            {!state && !loadError && (
+                <p className="channel-backup-loading" role="status">
+                    <Spinner /> Checking channel backup…
+                </p>
+            )}
+            {loadError && (
+                <div className="channel-backup-feedback">
+                    <ErrorNotice message={loadError} />
+                    <button
+                        type="button"
+                        className="text-button"
+                        disabled={refreshing}
+                        onClick={() => void refreshStatus()}
+                    >
+                        {refreshing && <Spinner />} Try again
+                    </button>
+                </div>
+            )}
+            {state && (
+                <>
+                    <p className="channel-backup-phase" role="status">
+                        {active ? (
+                            <Spinner />
+                        ) : phase === "protected" ? (
+                            <ShieldCheck size={18} aria-hidden="true" />
+                        ) : null}
+                        <strong>
+                            {recoveryOnly && phase === "disabled"
+                                ? "Choose a surviving recovery copy"
+                                : PHASE_LABEL[phase]}
+                        </strong>
+                    </p>
+                    {!recoveryOnly && state.configured && (
+                        <dl className="channel-backup-channels">
+                            <div>
+                                <dt>Main channel</dt>
+                                <dd>{state.source_channel ?? "Unavailable"}</dd>
+                            </div>
+                            <div>
+                                <dt>Backup channel</dt>
+                                <dd>{state.backup_channel ?? "Unavailable"}</dd>
+                            </div>
+                        </dl>
+                    )}
+                    {!recoveryOnly && state.configured && (
+                        <div className="channel-backup-confirmation">
+                            <p>
+                                Last confirmed restore point:{" "}
+                                <strong>
+                                    {state.last_success_at
+                                        ? formatTimestamp(state.last_success_at)
+                                        : "Not confirmed yet"}
+                                </strong>
+                                {state.protected_revision > 0
+                                    ? ` · catalog revision ${state.protected_revision}`
+                                    : ""}
+                            </p>
+                            {pending && (
+                                <p>
+                                    Catalog revision {state.revision} is waiting
+                                    to be protected. Files not yet confirmed in
+                                    the backup may still depend on the main
+                                    channel.
+                                </p>
+                            )}
+                        </div>
+                    )}
+                    {showProgress && (
+                        <div className="channel-backup-progress">
+                            {state.current_file && (
+                                <p
+                                    className="channel-backup-file"
+                                    title={state.current_file}
+                                >
+                                    {state.current_file}
+                                </p>
+                            )}
+                            <div className="channel-backup-progress-label">
+                                <span>
+                                    {state.done_files.toLocaleString()} /{" "}
+                                    {state.total_files.toLocaleString()} files
+                                </span>
+                                <span>
+                                    {formatBytes(state.done_bytes)} /{" "}
+                                    {formatBytes(state.total_bytes)}
+                                </span>
+                            </div>
+                            <progress
+                                aria-label="Channel copy progress"
+                                max={Math.max(1, state.total_bytes)}
+                                value={
+                                    state.total_bytes > 0
+                                        ? Math.min(
+                                              state.done_bytes,
+                                              state.total_bytes,
+                                          )
+                                        : undefined
+                                }
+                            />
+                            <p className="channel-backup-progress-detail">
+                                {state.done_parts.toLocaleString()} /{" "}
+                                {state.total_parts.toLocaleString()} parts
+                                confirmed
+                                {rate ? ` · ${formatBytes(rate)}/s` : ""}
+                                {rate && remaining > 0
+                                    ? ` · About ${formatDuration(remaining / rate)} remaining at this rate`
+                                    : ""}
+                            </p>
+                            {phase === "paused" && (
+                                <p>
+                                    The saved checkpoint will be used when you
+                                    resume.
+                                </p>
+                            )}
+                            {active && (
+                                <p>
+                                    You can leave this page. Progress is saved
+                                    on the server.
+                                </p>
+                            )}
+                        </div>
+                    )}
+                    {state.error && (
+                        <div className="channel-backup-feedback">
+                            <ErrorNotice message={state.error.detail} />
+                            {state.error.action && <p>{state.error.action}</p>}
+                            {state.error.retry_at && (
+                                <p>
+                                    Next retry:{" "}
+                                    {retryTime(state.error.retry_at)}
+                                </p>
+                            )}
+                        </div>
+                    )}
+                    {phase === "restart_required" && (
+                        <p className="channel-backup-feedback">
+                            The recovered configuration is saved. Restart
+                            TGDrive to open it. Keep the surviving channel and
+                            your recovery key.
+                        </p>
+                    )}
+                    {!recoveryOnly && (
+                        <div className="channel-backup-actions">
+                            {!state.configured && (
+                                <button
+                                    type="button"
+                                    className="primary-button"
+                                    disabled={blocked}
+                                    onClick={() => {
+                                        setConfigureOpen(true);
+                                        setActionError("");
+                                    }}
+                                >
+                                    Set up backup channel
+                                </button>
+                            )}
+                            {state.configured &&
+                                !state.enabled &&
+                                phase === "disabled" && (
+                                    <button
+                                        type="button"
+                                        className="secondary-button"
+                                        disabled={demoMode || !!busy}
+                                        onClick={() => action("resume")}
+                                    >
+                                        <Play size={16} />
+                                        {busy === "resume"
+                                            ? "Enabling…"
+                                            : "Enable backup"}
+                                    </button>
+                                )}
+                            {state.configured &&
+                                state.enabled &&
+                                !active &&
+                                ![
+                                    "ready_to_activate",
+                                    "restart_required",
+                                    "paused",
+                                    "error",
+                                ].includes(phase) && (
+                                    <button
+                                        type="button"
+                                        className="secondary-button"
+                                        disabled={
+                                            demoMode || !!busy || !state.enabled
+                                        }
+                                        onClick={() => action("sync")}
+                                    >
+                                        <RefreshCw size={16} />
+                                        Sync now
+                                    </button>
+                                )}
+                            {active && (
+                                <button
+                                    type="button"
+                                    className="secondary-button"
+                                    disabled={demoMode || !!busy}
+                                    onClick={() => action("pause")}
+                                >
+                                    <Pause size={16} />
+                                    {busy === "pause" ? "Pausing…" : "Pause"}
+                                </button>
+                            )}
+                            {phase === "paused" && (
+                                <button
+                                    type="button"
+                                    className="secondary-button"
+                                    disabled={demoMode || !!busy}
+                                    onClick={() => action("resume")}
+                                >
+                                    <Play size={16} />
+                                    {busy === "resume" ? "Resuming…" : "Resume"}
+                                </button>
+                            )}
+                            {phase === "error" && (
+                                <button
+                                    type="button"
+                                    className="secondary-button"
+                                    disabled={demoMode || !!busy}
+                                    onClick={() => action("retry")}
+                                >
+                                    <RefreshCw size={16} />
+                                    {busy === "retry" ? "Retrying…" : "Retry"}
+                                </button>
+                            )}
+                            {state.configured && recoveryKeyAction}
+                        </div>
+                    )}
+                    {recoveryOnly &&
+                        ["paused", "error", "waiting", "recovering"].includes(
+                            phase,
+                        ) && (
+                            <div className="channel-backup-actions">
+                                {active ? (
+                                    <button
+                                        type="button"
+                                        className="secondary-button"
+                                        disabled={demoMode || !!busy}
+                                        onClick={() => action("pause")}
+                                    >
+                                        <Pause size={16} />
+                                        Pause recovery
+                                    </button>
+                                ) : (
+                                    <button
+                                        type="button"
+                                        className="secondary-button"
+                                        disabled={demoMode || !!busy}
+                                        onClick={() =>
+                                            action(
+                                                phase === "error"
+                                                    ? "retry"
+                                                    : "resume",
+                                            )
+                                        }
+                                    >
+                                        <Play size={16} />
+                                        {phase === "error"
+                                            ? "Retry recovery"
+                                            : "Resume recovery"}
+                                    </button>
+                                )}
+                            </div>
+                        )}
+                    {recoveryOnly && candidate && (
+                        <div className="channel-backup-actions">
+                            {recoveryKeyAction}
+                        </div>
+                    )}
+                    {!recoveryOnly && state.configured && (
+                        <p className="channel-backup-key-help">
+                            Save the recovery key outside Telegram. It is needed
+                            if this installation is lost. A second channel
+                            reduces risk; it cannot guarantee Telegram access.
+                        </p>
+                    )}
+                </>
+            )}
+            {!recoveryOnly && configureOpen && (
+                <form className="channel-backup-form" onSubmit={configure}>
+                    <h3>
+                        {state?.configured
+                            ? "Replace backup channel"
+                            : "Set up a private backup"}
+                    </h3>
+                    <p>
+                        Create a private channel from a separate Telegram
+                        account. Create a backup bot with that account and add
+                        it to both channels as an administrator with access to
+                        messages, posting, deletion and pinning. Keep both
+                        channels private and let TGDrive manage their messages.
+                    </p>
+                    <div className="channel-backup-fields">
+                        <label>
+                            Backup channel ID
+                            <input
+                                inputMode="numeric"
+                                autoComplete="off"
+                                value={channel}
+                                onChange={(event) =>
+                                    setChannel(event.target.value)
+                                }
+                                placeholder="-1001234567890"
+                                required
+                                disabled={demoMode || !!busy}
+                            />
+                        </label>
+                        <label>
+                            Backup bot token
+                            <input
+                                type="password"
+                                autoComplete="new-password"
+                                value={token}
+                                onChange={(event) =>
+                                    setToken(event.target.value)
+                                }
+                                spellCheck={false}
+                                maxLength={512}
+                                required
+                                disabled={demoMode || !!busy}
+                            />
+                        </label>
+                    </div>
+                    <label className="channel-backup-checkbox">
+                        <input
+                            type="checkbox"
+                            checked={independent}
+                            onChange={(event) =>
+                                setIndependent(event.target.checked)
+                            }
+                            disabled={demoMode || !!busy}
+                        />
+                        <span>
+                            I created the backup channel and bot with a
+                            different Telegram account from the main channel.
+                            TGDrive cannot verify account ownership.
+                        </span>
+                    </label>
+                    <div className="channel-backup-actions">
+                        <button
+                            type="submit"
+                            className="primary-button"
+                            disabled={
+                                blocked ||
+                                !channel.trim() ||
+                                !token.trim() ||
+                                !independent
+                            }
+                        >
+                            {busy === "configure" ? (
+                                <Spinner />
+                            ) : (
+                                <ShieldCheck size={16} />
+                            )}
+                            {busy === "configure"
+                                ? "Verifying…"
+                                : "Verify and start backup"}
+                        </button>
+                        <button
+                            type="button"
+                            className="text-button"
+                            disabled={demoMode || !!busy}
+                            onClick={() => {
+                                setConfigureOpen(false);
+                                setToken("");
+                                setIndependent(false);
+                            }}
+                        >
+                            Cancel
+                        </button>
+                    </div>
+                    <p>
+                        Existing files are copied first. Protection is confirmed
+                        only after their file parts and catalog are saved in the
+                        backup.
+                    </p>
+                </form>
+            )}
+            {!recoveryOnly && !!state?.configured && (
+                <details className="channel-backup-details">
+                    <summary>Backup settings</summary>
+                    <div className="channel-backup-actions">
+                        <button
+                            type="button"
+                            className="secondary-button"
+                            disabled={blocked}
+                            onClick={() => {
+                                setConfigureOpen(true);
+                                setChannel("");
+                                setToken("");
+                                setIndependent(false);
+                            }}
+                        >
+                            Replace backup channel
+                        </button>
+                        <button
+                            type="button"
+                            className="text-button"
+                            disabled={blocked}
+                            onClick={() => setDisableConfirm(true)}
+                        >
+                            Disable automatic backup
+                        </button>
+                    </div>
+                    {disableConfirm && (
+                        <div className="channel-backup-feedback">
+                            <p>
+                                New changes will stop being copied. Keep the
+                                existing channels and recovery key; disabling
+                                does not replace a recovery plan.
+                            </p>
+                            <div className="channel-backup-actions">
+                                <button
+                                    type="button"
+                                    className="secondary-button"
+                                    disabled={demoMode || !!busy}
+                                    onClick={() => action("disable")}
+                                >
+                                    Confirm disable
+                                </button>
+                                <button
+                                    type="button"
+                                    className="text-button"
+                                    disabled={demoMode || !!busy}
+                                    onClick={() => setDisableConfirm(false)}
+                                >
+                                    Keep enabled
+                                </button>
+                            </div>
+                        </div>
+                    )}
+                </details>
+            )}
+            <details
+                className="channel-backup-details"
+                open={recoveryOpen}
+                onToggle={(event) => setRecoveryOpen(event.currentTarget.open)}
+            >
+                <summary>
+                    {recoveryOnly
+                        ? "Recover from a surviving channel"
+                        : "Recover a channel or catalog"}
+                </summary>
+                <p>
+                    {recoveryOnly
+                        ? "Start with a surviving private channel. Keep it unchanged until recovery is verified."
+                        : "If the backup channel is lost while the main channel still works, replace it in Backup settings. To rebuild a lost main channel, inspect a surviving recovery copy below."}
+                </p>
+                {!candidate?.complete &&
+                    !active &&
+                    phase !== "restart_required" && (
+                        <form
+                            className="channel-backup-form"
+                            onSubmit={(event) => recover(event, false)}
+                        >
+                            <div className="channel-backup-fields">
+                                <label>
+                                    Surviving channel ID
+                                    <input
+                                        inputMode="numeric"
+                                        autoComplete="off"
+                                        value={source}
+                                        onChange={(event) =>
+                                            setSource(event.target.value)
+                                        }
+                                        placeholder="-1001234567890"
+                                        required
+                                        disabled={demoMode || !!busy}
+                                    />
+                                </label>
+                                <label>
+                                    Bot token with access to the surviving
+                                    channel
+                                    <input
+                                        type="password"
+                                        autoComplete="new-password"
+                                        value={sourceToken}
+                                        onChange={(event) =>
+                                            setSourceToken(event.target.value)
+                                        }
+                                        spellCheck={false}
+                                        maxLength={512}
+                                        required
+                                        disabled={demoMode || !!busy}
+                                    />
+                                </label>
+                                <label>
+                                    Saved recovery key
+                                    <input
+                                        type="password"
+                                        autoComplete="new-password"
+                                        value={key}
+                                        onChange={(event) =>
+                                            setKey(event.target.value)
+                                        }
+                                        spellCheck={false}
+                                        maxLength={64}
+                                        disabled={demoMode || !!busy}
+                                        aria-describedby="channel-recovery-key-help"
+                                    />
+                                </label>
+                                <label>
+                                    <span>
+                                        Checkpoint message ID{" "}
+                                        <span className="channel-backup-optional">
+                                            (optional)
+                                        </span>
+                                    </span>
+                                    <input
+                                        inputMode="numeric"
+                                        autoComplete="off"
+                                        value={messageId}
+                                        onChange={(event) =>
+                                            setMessageId(event.target.value)
+                                        }
+                                        disabled={demoMode || !!busy}
+                                        aria-describedby="checkpoint-id-help"
+                                    />
+                                </label>
+                            </div>
+                            <p id="channel-recovery-key-help">
+                                Encrypted copies need the 64-character key value
+                                from your saved recovery-key JSON. Leave this
+                                empty only for a verified plain catalog
+                                checkpoint.
+                            </p>
+                            <p id="checkpoint-id-help">
+                                Leave the message ID empty to inspect the latest
+                                pinned recovery copy. Inspecting does not
+                                activate or overwrite a drive.
+                            </p>
+                            <button
+                                type="submit"
+                                className="secondary-button"
+                                disabled={
+                                    demoMode ||
+                                    !!busy ||
+                                    !source.trim() ||
+                                    !sourceToken.trim()
+                                }
+                            >
+                                {busy === "inspect" ? (
+                                    <Spinner />
+                                ) : (
+                                    <RefreshCw size={16} />
+                                )}
+                                {busy === "inspect"
+                                    ? "Inspecting…"
+                                    : "Inspect recovery copy"}
+                            </button>
+                        </form>
+                    )}
+                {candidate && (
+                    <div className="channel-backup-candidate">
+                        <h3 tabIndex={-1}>
+                            {candidate.complete
+                                ? "Recovered drive verified"
+                                : "Recovery copy found"}
+                        </h3>
+                        <dl>
+                            <div>
+                                <dt>Catalog revision</dt>
+                                <dd>{candidate.revision}</dd>
+                            </div>
+                            <div>
+                                <dt>Completed files</dt>
+                                <dd>
+                                    {candidate.files.toLocaleString()} ·{" "}
+                                    {formatBytes(candidate.bytes)}
+                                </dd>
+                            </div>
+                            <div>
+                                <dt>
+                                    {candidate.complete
+                                        ? "Recovered channel"
+                                        : "Source channel"}
+                                </dt>
+                                <dd>{candidate.channel}</dd>
+                            </div>
+                        </dl>
+                        {!candidate.complete &&
+                            !active &&
+                            phase !== "restart_required" && (
+                                <form
+                                    className="channel-backup-form"
+                                    onSubmit={(event) => recover(event, true)}
+                                >
+                                    <label className="channel-backup-checkbox">
+                                        <input
+                                            type="checkbox"
+                                            checked={catalogOnly}
+                                            onChange={(event) => {
+                                                setCatalogOnly(
+                                                    event.target.checked,
+                                                );
+                                                setConfirmation("");
+                                            }}
+                                            disabled={demoMode || !!busy}
+                                        />
+                                        <span>
+                                            Restore the database only on this
+                                            surviving channel
+                                        </span>
+                                    </label>
+                                    <p>
+                                        {catalogOnly
+                                            ? "Files stay in this surviving channel. Add a main bot as an administrator; it must be different from the surviving backup bot. TGDrive checks every stored part before the catalog can be activated."
+                                            : "Create a new, empty private main channel in Telegram. Add the surviving backup bot and a new main bot as administrators. The main bot must be different from the surviving bot. TGDrive verifies both before copying; the source stays unchanged."}
+                                    </p>
+                                    <div className="channel-backup-fields">
+                                        {!catalogOnly && (
+                                            <label>
+                                                New main channel ID
+                                                <input
+                                                    inputMode="numeric"
+                                                    autoComplete="off"
+                                                    value={target}
+                                                    onChange={(event) =>
+                                                        setTarget(
+                                                            event.target.value,
+                                                        )
+                                                    }
+                                                    required
+                                                    disabled={
+                                                        demoMode || !!busy
+                                                    }
+                                                />
+                                            </label>
+                                        )}{" "}
+                                        <label>
+                                            {catalogOnly
+                                                ? "Main bot token for this channel"
+                                                : "New main bot token"}
+                                            <input
+                                                type="password"
+                                                autoComplete="new-password"
+                                                value={targetToken}
+                                                onChange={(event) =>
+                                                    setTargetToken(
+                                                        event.target.value,
+                                                    )
+                                                }
+                                                spellCheck={false}
+                                                maxLength={512}
+                                                required
+                                                disabled={demoMode || !!busy}
+                                            />
+                                        </label>
+                                        <label>
+                                            Type{" "}
+                                            {catalogOnly
+                                                ? candidate.channel
+                                                : "the new main channel ID"}{" "}
+                                            to confirm
+                                            <input
+                                                inputMode="numeric"
+                                                autoComplete="off"
+                                                value={confirmation}
+                                                onChange={(event) =>
+                                                    setConfirmation(
+                                                        event.target.value,
+                                                    )
+                                                }
+                                                required
+                                                disabled={demoMode || !!busy}
+                                            />
+                                        </label>
+                                    </div>
+                                    <p>
+                                        {catalogOnly
+                                            ? "After activation this channel becomes the main channel. Set up an independent backup again afterwards."
+                                            : "Copying can take time."}{" "}
+                                        File changes are paused for recovery.
+                                        Your existing local database and
+                                        configuration are preserved until
+                                        activation.
+                                    </p>
+                                    <button
+                                        type="submit"
+                                        className="primary-button"
+                                        disabled={
+                                            blocked ||
+                                            (!catalogOnly && !target.trim()) ||
+                                            !targetToken.trim() ||
+                                            (catalogOnly
+                                                ? String(candidate.channel)
+                                                : target.trim()) !==
+                                                confirmation.trim()
+                                        }
+                                    >
+                                        {busy === "recover" ? (
+                                            <Spinner />
+                                        ) : (
+                                            <RefreshCw size={16} />
+                                        )}
+                                        {busy === "recover"
+                                            ? "Starting recovery…"
+                                            : catalogOnly
+                                              ? "Verify catalog on this channel"
+                                              : "Copy to new main channel"}
+                                    </button>
+                                </form>
+                            )}
+                        {candidate.complete &&
+                            phase === "ready_to_activate" && (
+                                <div className="channel-backup-form">
+                                    <p>
+                                        All required parts and the recovered
+                                        catalog are confirmed. Activation
+                                        switches TGDrive to this main channel; a
+                                        service restart is required.
+                                    </p>
+                                    <label>
+                                        Type {candidate.channel} to activate
+                                        this recovered drive
+                                        <input
+                                            inputMode="numeric"
+                                            autoComplete="off"
+                                            value={activationConfirmation}
+                                            onChange={(event) =>
+                                                setActivationConfirmation(
+                                                    event.target.value,
+                                                )
+                                            }
+                                            disabled={demoMode || !!busy}
+                                        />
+                                    </label>
+                                    <button
+                                        type="button"
+                                        className="primary-button"
+                                        disabled={
+                                            demoMode ||
+                                            !!busy ||
+                                            activationConfirmation.trim() !==
+                                                String(candidate.channel)
+                                        }
+                                        onClick={activate}
+                                    >
+                                        {busy === "activate" ? (
+                                            <Spinner />
+                                        ) : (
+                                            <ShieldCheck size={16} />
+                                        )}
+                                        {busy === "activate"
+                                            ? "Activating…"
+                                            : "Activate recovered drive"}
+                                    </button>
+                                </div>
+                            )}
+                    </div>
+                )}
+            </details>
+            <ErrorNotice message={actionError} />
+            {state &&
+                (report.length > 0 ||
+                    state.configured ||
+                    state.recovery_candidate) && (
+                    <details className="channel-backup-details">
+                        <summary>Activity and report</summary>
+                        {report.length > 0 ? (
+                            <ol className="channel-backup-report">
+                                {report.map((entry, index) => (
+                                    <li key={entry.at + ":" + index}>
+                                        <time>{formatTimestamp(entry.at)}</time>
+                                        <span
+                                            className={
+                                                entry.level === "error"
+                                                    ? "danger-text"
+                                                    : ""
+                                            }
+                                        >
+                                            {entry.message}
+                                        </span>
+                                    </li>
+                                ))}
+                            </ol>
+                        ) : (
+                            <p>No activity reported yet.</p>
+                        )}
+                        <a
+                            className="text-button"
+                            href="/api/v1/replica/report"
+                            download
+                        >
+                            <Download size={16} />
+                            Download report
+                        </a>
+                    </details>
+                )}
+            <a
+                className="inline-link channel-backup-guide"
+                href="https://github.com/TechShreyash/TGDrive/blob/main/docs/backup-recovery.md"
+                target="_blank"
+                rel="noopener noreferrer"
+            >
+                Backup channel setup and recovery guide
+            </a>
+        </section>
+    );
+}
diff --git a/website/src/features/backup/DatabaseRestore.css b/website/src/features/backup/DatabaseRestore.css
new file mode 100644
index 00000000..a962b08c
--- /dev/null
+++ b/website/src/features/backup/DatabaseRestore.css
@@ -0,0 +1,58 @@
+.database-restore {
+    min-width: 0;
+    margin-block: 24px;
+}
+.database-restore h2 {
+    margin: 0 0 12px;
+    font-size: 16px;
+    font-weight: 600;
+}
+.database-restore > p,
+.database-restore li {
+    max-width: 75ch;
+    color: var(--muted);
+    line-height: 1.6;
+    overflow-wrap: anywhere;
+}
+.database-restore-form {
+    display: grid;
+    gap: 12px;
+    margin-top: 20px;
+    max-width: 640px;
+}
+.database-restore-form label {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    min-width: 0;
+    line-height: 1.5;
+}
+.database-restore-form input {
+    width: 100%;
+    min-width: 0;
+    box-sizing: border-box;
+}
+.database-restore-form > p,
+.database-restore-progress p {
+    margin: 0;
+    color: var(--muted);
+    font-size: 13px;
+    line-height: 1.6;
+}
+.database-restore-form > button,
+.database-restore-result > button {
+    justify-self: start;
+    gap: 8px;
+}
+.database-restore-progress {
+    display: grid;
+    gap: 8px;
+}
+.database-restore progress {
+    width: 100%;
+    height: 6px;
+    accent-color: var(--action);
+}
+.database-restore-result li + li {
+    margin-top: 8px;
+}
diff --git a/website/src/features/backup/DatabaseRestore.test.ts b/website/src/features/backup/DatabaseRestore.test.ts
new file mode 100644
index 00000000..18ae46d1
--- /dev/null
+++ b/website/src/features/backup/DatabaseRestore.test.ts
@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+    MAX_DATABASE_ARCHIVE_BYTES,
+    databaseRecoveryKey,
+    uploadDatabaseArchive,
+    validateDatabaseArchive,
+} from "./DatabaseRestore";
+
+class MockXHR {
+    static latest: MockXHR;
+    upload = {
+        onprogress: null as ((event: { loaded: number }) => void) | null,
+        onload: null as (() => void) | null,
+    };
+    onload: (() => void) | null = null;
+    onerror: (() => void) | null = null;
+    onabort: (() => void) | null = null;
+    status = 200;
+    responseText = JSON.stringify({ restart_required: true });
+    withCredentials = false;
+    timeout = 60000;
+    open = vi.fn();
+    setRequestHeader = vi.fn();
+    send = vi.fn();
+    constructor() {
+        MockXHR.latest = this;
+    }
+}
+
+beforeEach(() => vi.stubGlobal("XMLHttpRequest", MockXHR));
+afterEach(() => vi.unstubAllGlobals());
+
+describe("database archive input", () => {
+    it.each([
+        { name: "checkpoint.json", size: 100 },
+        { name: "backup.tgdb", size: 0 },
+        { name: "backup.tgdb", size: MAX_DATABASE_ARCHIVE_BYTES + 1 },
+    ])("rejects an unusable archive %j", (file) => {
+        expect(() => validateDatabaseArchive(file)).toThrow();
+    });
+    it("accepts an encrypted archive at the documented upload limit", () => {
+        expect(() =>
+            validateDatabaseArchive({
+                name: "BACKUP.TGDB",
+                size: MAX_DATABASE_ARCHIVE_BYTES,
+            }),
+        ).not.toThrow();
+    });
+    it("trims a copied key and rejects invalid keys without echoing them", () => {
+        const key = "a".repeat(64);
+        expect(databaseRecoveryKey(` ${key}\n`)).toBe(key);
+        const invalid = "private-recovery-key-that-must-not-be-echoed";
+        expect(() => databaseRecoveryKey(invalid)).toThrow(
+            "64-character hexadecimal",
+        );
+        try {
+            databaseRecoveryKey(invalid);
+        } catch (error) {
+            expect(String(error)).not.toContain(invalid);
+        }
+    });
+});
+
+describe("database restore transport", () => {
+    const archive = new File(["encrypted archive"], "backup.tgdb");
+    const key = "b".repeat(64);
+
+    it("sends the file once with the private key in a header and waits for confirmation", async () => {
+        const progress = vi.fn();
+        const result = uploadDatabaseArchive(archive, key, progress);
+        const xhr = MockXHR.latest;
+        expect(xhr.open).toHaveBeenCalledWith("POST", "/api/v1/backup/restore");
+        expect(xhr.setRequestHeader).toHaveBeenCalledWith(
+            "X-TGDrive-Recovery-Key",
+            key,
+        );
+        expect(xhr.setRequestHeader).toHaveBeenCalledWith(
+            "X-TGDrive-Confirm",
+            "RESTORE",
+        );
+        expect(xhr.setRequestHeader).toHaveBeenCalledWith(
+            "Content-Type",
+            "application/octet-stream",
+        );
+        expect(xhr.withCredentials).toBe(true);
+        expect(xhr.timeout).toBe(0);
+        expect(xhr.send).toHaveBeenCalledOnce();
+        expect(xhr.send).toHaveBeenCalledWith(archive);
+        xhr.upload.onprogress?.({ loaded: 3 });
+        xhr.upload.onload?.();
+        expect(progress.mock.calls.map(([bytes]) => bytes)).toEqual([
+            3,
+            archive.size,
+        ]);
+        xhr.onload?.();
+        await expect(result).resolves.toBeUndefined();
+        expect(xhr.send).toHaveBeenCalledOnce();
+    });
+
+    it("preserves a validation failure as a correctable form error", async () => {
+        const result = uploadDatabaseArchive(archive, key, vi.fn());
+        const rejection = expect(result).rejects.toMatchObject({
+            message: "Archive authentication failed. Check its matching key.",
+            status: 422,
+            restartRequired: false,
+        });
+        const xhr = MockXHR.latest;
+        xhr.status = 422;
+        xhr.responseText = JSON.stringify({
+            detail: "Archive authentication failed. Check its matching key.",
+        });
+        xhr.onload?.();
+        await rejection;
+        expect(xhr.send).toHaveBeenCalledOnce();
+    });
+
+    it("keeps a known pre-restore storage failure retryable without a restart", async () => {
+        const result = uploadDatabaseArchive(archive, key, vi.fn());
+        const rejection = expect(result).rejects.toMatchObject({
+            status: 507,
+            restartRequired: false,
+        });
+        const xhr = MockXHR.latest;
+        xhr.status = 507;
+        xhr.responseText = JSON.stringify({
+            detail: "Check temporary storage before retrying.",
+            restart_required: false,
+        });
+        xhr.onload?.();
+        await rejection;
+    });
+
+    it.each(["server", "network", "unreadable-success"])(
+        "requires restart and inspection after an uncertain %s outcome without replaying",
+        async (failure) => {
+            const result = uploadDatabaseArchive(archive, key, vi.fn());
+            const rejection = expect(result).rejects.toMatchObject({
+                restartRequired: true,
+            });
+            const xhr = MockXHR.latest;
+            if (failure === "network") xhr.onerror?.();
+            else {
+                xhr.status = failure === "server" ? 503 : 200;
+                xhr.responseText =
+                    failure === "server"
+                        ? JSON.stringify({
+                              detail: "Restart TGDrive and inspect the restore.",
+                          })
+                        : "Connection interrupted";
+                xhr.onload?.();
+            }
+            await rejection;
+            expect(xhr.send).toHaveBeenCalledOnce();
+        },
+    );
+});
diff --git a/website/src/features/backup/DatabaseRestore.tsx b/website/src/features/backup/DatabaseRestore.tsx
new file mode 100644
index 00000000..ad5bf627
--- /dev/null
+++ b/website/src/features/backup/DatabaseRestore.tsx
@@ -0,0 +1,401 @@
+import { useEffect, useId, useRef, useState, type FormEvent } from "react";
+import { Upload } from "lucide-react";
+import { ApiError, errorMessage } from "../../shared/api";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import { formatBytes } from "../../shared/types";
+import "./DatabaseRestore.css";
+
+export const MAX_DATABASE_ARCHIVE_BYTES = 1024 ** 3;
+export type DatabaseRestoreState =
+    | { phase: "idle" | "restoring" }
+    | { phase: "restored" }
+    | { phase: "restart_required"; message: string };
+
+class DatabaseRestoreError extends ApiError {
+    constructor(
+        message: string,
+        status: number,
+        public restartRequired = false,
+    ) {
+        super(message, status);
+    }
+}
+
+export function validateDatabaseArchive(file: Pick<File, "name" | "size">) {
+    if (!file.name.toLowerCase().endsWith(".tgdb"))
+        throw new Error(
+            "Choose the encrypted .tgdb database archive from your private channel.",
+        );
+    if (file.size === 0 || file.size > MAX_DATABASE_ARCHIVE_BYTES)
+        throw new Error(
+            "Choose a nonempty database archive no larger than 1 GiB.",
+        );
+}
+
+export function databaseRecoveryKey(value: string) {
+    const key = value.trim();
+    if (!/^[a-fA-F0-9]{64}$/.test(key))
+        throw new Error(
+            "Enter the 64-character hexadecimal MONGODB_BACKUP_KEY saved with this archive.",
+        );
+    return key;
+}
+
+/** One attempt only: a lost response can hide an already committed restore. */
+export function uploadDatabaseArchive(
+    file: File,
+    key: string,
+    progress: (bytes: number) => void,
+): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        let settled = false;
+        const cleanup = () => {
+            xhr.upload.onprogress = null;
+            xhr.upload.onload = null;
+            xhr.onload = null;
+            xhr.onerror = null;
+            xhr.onabort = null;
+        };
+        const fail = (error: DatabaseRestoreError) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        xhr.open("POST", "/api/v1/backup/restore");
+        xhr.withCredentials = true;
+        // Verification and the database transaction can outlast the normal API
+        // timeout. Only the final response confirms whether the restore finished.
+        xhr.timeout = 0;
+        xhr.setRequestHeader("Accept", "application/json");
+        xhr.setRequestHeader("Content-Type", "application/octet-stream");
+        xhr.setRequestHeader("X-TGDrive-Recovery-Key", key);
+        xhr.setRequestHeader("X-TGDrive-Confirm", "RESTORE");
+        xhr.upload.onprogress = (event) => {
+            if (!settled && Number.isFinite(event.loaded))
+                progress(Math.min(file.size, Math.max(0, event.loaded)));
+        };
+        xhr.upload.onload = () => {
+            if (!settled) progress(file.size);
+        };
+        xhr.onload = () => {
+            if (settled) return;
+            let data: Record<string, unknown> = {};
+            try {
+                const parsed: unknown = JSON.parse(xhr.responseText);
+                if (
+                    parsed &&
+                    typeof parsed === "object" &&
+                    !Array.isArray(parsed)
+                )
+                    data = parsed as Record<string, unknown>;
+            } catch {
+                // A proxy can return HTML, including after the restore committed.
+            }
+            if (
+                xhr.status >= 200 &&
+                xhr.status < 300 &&
+                data.restart_required === true
+            ) {
+                settled = true;
+                cleanup();
+                resolve();
+                return;
+            }
+            const detail =
+                typeof data.detail === "string"
+                    ? data.detail
+                    : typeof data.error === "string"
+                      ? data.error
+                      : xhr.status === 401
+                        ? "Your session expired. Sign in again before restoring the database."
+                        : "TGDrive could not confirm this restore. Check the deployment logs and the database before trying again.";
+            fail(
+                new DatabaseRestoreError(
+                    detail,
+                    xhr.status,
+                    typeof data.restart_required === "boolean"
+                        ? data.restart_required
+                        : xhr.status === 0 ||
+                              xhr.status >= 500 ||
+                              (xhr.status >= 200 && xhr.status < 300),
+                ),
+            );
+        };
+        const disconnected = () =>
+            fail(
+                new DatabaseRestoreError(
+                    "The restore response was interrupted. The database may already have been restored. Restart TGDrive and check Storage & Backups before trying again.",
+                    0,
+                    true,
+                ),
+            );
+        xhr.onerror = disconnected;
+        xhr.onabort = disconnected;
+        try {
+            xhr.send(file);
+        } catch {
+            fail(
+                new DatabaseRestoreError(
+                    "The archive could not be sent. Check your connection and choose the file again.",
+                    0,
+                ),
+            );
+        }
+    });
+}
+
+export function DatabaseRestoreResult({ error = "" }: { error?: string }) {
+    return (
+        <section
+            className="database-restore database-restore-result"
+            aria-live="polite"
+        >
+            <h2>
+                {error
+                    ? "Database restore needs a restart"
+                    : "Database restored"}
+            </h2>
+            <ErrorNotice message={error} />
+            <p>
+                {error
+                    ? "Restart TGDrive, then check which drive opens before trying the restore again."
+                    : "Restart TGDrive to open the restored drive. Existing browser sessions have been signed out."}
+            </p>
+            <ol>
+                <li>
+                    Use the Restart action for the app in Docker Desktop or
+                    Coolify.
+                </li>
+                <li>
+                    Reload this page. A restored drive uses the owner password
+                    saved in the archive; credentials explicitly configured in
+                    the deployment environment take precedence.
+                </li>
+                <li>
+                    Review files, Connections and shared links before uploading.
+                    Older backups can restore previously removed records and
+                    revoked shares.
+                </li>
+            </ol>
+            <button
+                type="button"
+                className="secondary-button"
+                onClick={() => window.location.reload()}
+            >
+                Reload after restart
+            </button>
+        </section>
+    );
+}
+
+export default function DatabaseRestore({
+    demoMode = false,
+    onRestoreStateChange,
+}: {
+    demoMode?: boolean;
+    onRestoreStateChange?: (state: DatabaseRestoreState) => void;
+}) {
+    const id = useId();
+    const [file, setFile] = useState<File | null>(null);
+    const [key, setKey] = useState("");
+    const [confirmation, setConfirmation] = useState("");
+    const [busy, setBusy] = useState(false);
+    const [sent, setSent] = useState(0);
+    const [error, setError] = useState("");
+    const [result, setResult] = useState<{ error?: string } | null>(null);
+    const errorSummary = useRef<HTMLDivElement>(null);
+    const pending = useRef(false);
+    const mounted = useRef(true);
+    const stateCallback = useRef(onRestoreStateChange);
+    stateCallback.current = onRestoreStateChange;
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    useEffect(() => {
+        if (error) errorSummary.current?.focus();
+    }, [error]);
+
+    const restore = async (event: FormEvent<HTMLFormElement>) => {
+        event.preventDefault();
+        if (demoMode || pending.current) return;
+        setError("");
+        let recoveryKey: string;
+        try {
+            if (!file)
+                throw new Error("Choose an encrypted .tgdb database archive.");
+            validateDatabaseArchive(file);
+            recoveryKey = databaseRecoveryKey(key);
+            if (confirmation.trim() !== "RESTORE")
+                throw new Error(
+                    "Type RESTORE to confirm restoring this database archive.",
+                );
+        } catch (cause) {
+            setError(errorMessage(cause));
+            return;
+        }
+        pending.current = true;
+        setBusy(true);
+        setSent(0);
+        stateCallback.current?.({ phase: "restoring" });
+        try {
+            await uploadDatabaseArchive(file!, recoveryKey, (bytes) => {
+                if (mounted.current) setSent(bytes);
+            });
+            if (mounted.current) {
+                setKey("");
+                setFile(null);
+                setResult({});
+            }
+            stateCallback.current?.({ phase: "restored" });
+        } catch (cause) {
+            const message = errorMessage(cause);
+            if (
+                cause instanceof DatabaseRestoreError &&
+                cause.restartRequired
+            ) {
+                if (mounted.current) {
+                    setKey("");
+                    setResult({ error: message });
+                }
+                stateCallback.current?.({ phase: "restart_required", message });
+            } else {
+                if (mounted.current) setError(message);
+                stateCallback.current?.({ phase: "idle" });
+            }
+        } finally {
+            pending.current = false;
+            if (mounted.current) setBusy(false);
+        }
+    };
+    if (result) return <DatabaseRestoreResult error={result.error} />;
+    return (
+        <section className="database-restore" aria-labelledby={`${id}-heading`}>
+            <h2 id={`${id}-heading`}>Restore a database archive</h2>
+            <p>
+                Download the full encrypted .tgdb database archive from your
+                private Telegram channel. Only an empty, unused drive can
+                receive it; TGDrive refuses to replace existing files or work.
+                Channel recovery capsules use the separate channel recovery
+                form.
+            </p>
+            <p>
+                Keep the archive’s matching recovery key. Local unfinished
+                upload bytes are not included. Older archives can restore
+                removed records and previously revoked shares.
+            </p>
+            <form
+                className="database-restore-form"
+                onSubmit={restore}
+                aria-busy={busy}
+            >
+                {error && (
+                    <div ref={errorSummary} tabIndex={-1}>
+                        <ErrorNotice message={error} />
+                    </div>
+                )}
+                <label htmlFor={`${id}-file`}>
+                    Database archive (required)
+                    <input
+                        id={`${id}-file`}
+                        type="file"
+                        accept=".tgdb"
+                        required
+                        disabled={demoMode || busy}
+                        aria-describedby={`${id}-file-help`}
+                        onChange={(event) => {
+                            setFile(event.target.files?.[0] || null);
+                            setError("");
+                        }}
+                    />
+                </label>
+                <p id={`${id}-file-help`} className="settings-help">
+                    Encrypted .tgdb file, up to 1 GiB.
+                </p>
+                <label htmlFor={`${id}-key`}>
+                    Archive recovery key (required)
+                    <input
+                        id={`${id}-key`}
+                        type="password"
+                        autoComplete="off"
+                        spellCheck={false}
+                        maxLength={128}
+                        required
+                        value={key}
+                        disabled={demoMode || busy}
+                        aria-describedby={`${id}-key-help`}
+                        onChange={(event) => setKey(event.target.value)}
+                    />
+                </label>
+                <p id={`${id}-key-help`} className="settings-help">
+                    Enter the 64-character MONGODB_BACKUP_KEY value from the
+                    saved database recovery key. The independent channel
+                    recovery key is different.
+                </p>
+                <label htmlFor={`${id}-confirmation`}>
+                    Type RESTORE to confirm (required)
+                    <input
+                        id={`${id}-confirmation`}
+                        autoComplete="off"
+                        spellCheck={false}
+                        required
+                        value={confirmation}
+                        disabled={demoMode || busy}
+                        onChange={(event) =>
+                            setConfirmation(event.target.value)
+                        }
+                    />
+                </label>
+                {busy && (
+                    <div
+                        className="database-restore-progress"
+                        role="status"
+                        aria-live="polite"
+                    >
+                        <p>
+                            {file && sent < file.size
+                                ? `Sending archive: ${formatBytes(sent)} of ${formatBytes(file.size)}`
+                                : "Archive sent. Waiting for TGDrive to verify and restore the database…"}
+                        </p>
+                        <progress
+                            aria-label="Database archive upload"
+                            value={sent}
+                            max={file?.size || 1}
+                        />
+                        <p>
+                            Keep this page open until the result appears. Do not
+                            submit another restore while this one is processing.
+                        </p>
+                    </div>
+                )}
+                <button
+                    type="submit"
+                    className="secondary-button"
+                    disabled={
+                        demoMode ||
+                        busy ||
+                        !file ||
+                        !key ||
+                        confirmation.trim() !== "RESTORE"
+                    }
+                >
+                    {busy ? (
+                        <Spinner />
+                    ) : (
+                        <Upload size={16} aria-hidden="true" />
+                    )}
+                    {busy ? "Restoring database…" : "Restore database archive"}
+                </button>
+                {demoMode && (
+                    <p className="settings-help">
+                        Database restore is unavailable in the read-only demo.
+                    </p>
+                )}
+            </form>
+        </section>
+    );
+}
diff --git a/website/src/features/files/ActionDialog.css b/website/src/features/files/ActionDialog.css
new file mode 100644
index 00000000..791de939
--- /dev/null
+++ b/website/src/features/files/ActionDialog.css
@@ -0,0 +1,19 @@
+.item-name-field {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-bottom: 16px;
+}
+.item-name-field input {
+    flex: 1;
+    min-width: 0;
+}
+.rename-extension {
+    max-width: 50%;
+    overflow-wrap: anywhere;
+    color: var(--muted);
+}
+#item-name-hint {
+    margin-top: -8px;
+    overflow-wrap: anywhere;
+}
diff --git a/website/src/features/files/ActionDialog.tsx b/website/src/features/files/ActionDialog.tsx
new file mode 100644
index 00000000..ac1fd942
--- /dev/null
+++ b/website/src/features/files/ActionDialog.tsx
@@ -0,0 +1,787 @@
+import Preview from "../previews/Preview";
+import { useEffect, useState } from "react";
+import {
+    Folder,
+    ChevronRight,
+    RefreshCw,
+    Move,
+    Link,
+    Copy,
+    Download,
+    AlertCircle,
+} from "lucide-react";
+import { api, request, ApiError, errorMessage } from "../../shared/api";
+import { performanceApi } from "../performance/performanceApi";
+import { itemPath, formatTimestamp, type DriveItem } from "../../shared/types";
+import { transfers } from "../transfers/transfers";
+import { Modal, ErrorNotice, Spinner } from "../../shared/components";
+import "./ActionDialog.css";
+export type ActionDialogState =
+    | { type: "folder" }
+    | { type: "rename"; item: DriveItem }
+    | { type: "url" }
+    | { type: "share"; item: DriveItem }
+    | { type: "move"; items: DriveItem[] }
+    | { type: "delete"; items: DriveItem[] }
+    | { type: "restore"; items: DriveItem[] }
+    | { type: "preview"; item: DriveItem }
+    | { type: "download-link"; item: DriveItem }
+    | { type: "prepare"; item: DriveItem };
+export default function ActionDialog({
+    dialog,
+    destination,
+    auth,
+    onClose,
+    onChanged,
+    onNotice,
+    onDelete,
+    onRestore,
+}: {
+    dialog: ActionDialogState;
+    destination: string;
+    auth: string;
+    onClose: () => void;
+    onChanged: () => void;
+    onNotice: (message: string, error?: boolean) => void;
+    onDelete: (items: DriveItem[]) => Promise<void>;
+    onRestore: (items: DriveItem[]) => Promise<void>;
+}) {
+    const originalName = dialog.type === "rename" ? dialog.item.name : "";
+    const extensionStart = originalName.lastIndexOf(".");
+    const extension =
+        dialog.type === "rename" &&
+        dialog.item.type === "file" &&
+        extensionStart > 0 &&
+        extensionStart < originalName.length - 1
+            ? originalName.slice(extensionStart)
+            : "";
+    const [name, setName] = useState(
+        extension ? originalName.slice(0, -extension.length) : originalName,
+    );
+    const [url, setUrl] = useState("");
+    const [compat, setCompat] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    const [expires, setExpires] = useState("7");
+    const [shareLabel, setShareLabel] = useState("");
+    const [customExpiry, setCustomExpiry] = useState("");
+    const [link, setLink] = useState("");
+    const [expiry, setExpiry] = useState<string | null>(null);
+    const [requestId, setRequestId] = useState(() =>
+        crypto.randomUUID().replaceAll("-", "_"),
+    );
+    const close = () => {
+        if (!busy) onClose();
+    };
+    const run = async (task: () => Promise<void>) => {
+        setBusy(true);
+        setError("");
+        try {
+            await task();
+        } catch (error) {
+            setError(errorMessage(error));
+        } finally {
+            setBusy(false);
+        }
+    };
+    if (dialog.type === "download-link" || dialog.type === "prepare")
+        return (
+            <Modal
+                title={
+                    dialog.type === "prepare"
+                        ? "Preload file"
+                        : "Copy Download Link"
+                }
+                onClose={close}
+            >
+                <p>{dialog.item.name}</p>
+                <p>
+                    {dialog.type === "prepare"
+                        ? "Cache the whole file on the server for faster later streaming and downloads. This uses the shared cache budget and runs behind active streams and downloads. Cached bytes may be removed when space is needed."
+                        : "Anyone with this link can download the file without logging in. An active link is reused, or a new one-day link is created. Revoke it in Shared Links."}
+                </p>
+                {dialog.type === "prepare" && (
+                    <>
+                        <p>
+                            Opening or streaming fetches requested chunks with
+                            adaptive, bounded read-ahead. Automatic preloading
+                            can warm additional upcoming playback chunks.
+                            Downloads fetch their requested ranges. Use this
+                            action to preload the entire file in advance. Your
+                            device still needs an internet connection to access
+                            the server copy.
+                        </p>
+                        <p>
+                            View progress and manage cached files in{" "}
+                            <a className="inline-link" href="/?view=preloads">
+                                Preloads
+                            </a>
+                            .
+                        </p>
+                    </>
+                )}
+                {link && (
+                    <label>
+                        Download link
+                        <input
+                            readOnly
+                            value={link}
+                            onFocus={(e) => e.currentTarget.select()}
+                        />
+                    </label>
+                )}
+                {link && (
+                    <p className="muted">
+                        {expiry
+                            ? "Expires " + formatTimestamp(expiry)
+                            : "No expiry. Revoke access in Shared Links."}
+                    </p>
+                )}
+                <ErrorNotice message={error} />
+                <div className="dialog-actions">
+                    <button
+                        className="secondary-button"
+                        onClick={close}
+                        disabled={busy}
+                    >
+                        Close
+                    </button>
+                    <button
+                        className="primary-button"
+                        disabled={busy}
+                        onClick={() =>
+                            void run(async () => {
+                                if (dialog.type === "prepare") {
+                                    const job = await performanceApi.prepare(
+                                        itemPath(dialog.item),
+                                    );
+                                    onNotice(
+                                        job.state === "ready"
+                                            ? "File is already fully cached on the server. View it in Preloads."
+                                            : job.state === "preparing"
+                                              ? "File is preloading on the server. View progress in Preloads."
+                                              : "Preload queued. View progress in Preloads.",
+                                    );
+                                    onClose();
+                                } else {
+                                    const result = await request<{
+                                        url: string;
+                                        expires_at: string | null;
+                                    }>("/api/v1/download-links", {
+                                        path: itemPath(dialog.item),
+                                    });
+                                    setLink(result.url);
+                                    setExpiry(result.expires_at);
+                                    onChanged();
+                                    await navigator.clipboard.writeText(
+                                        result.url,
+                                    );
+                                    onNotice("Download link copied.");
+                                }
+                            })
+                        }
+                    >
+                        {busy ? <Spinner /> : null}
+                        {dialog.type === "prepare"
+                            ? "Preload file"
+                            : "Create or Copy Link"}
+                    </button>
+                </div>
+            </Modal>
+        );
+    if (dialog.type === "move")
+        return (
+            <MoveDialog
+                items={dialog.items}
+                onClose={onClose}
+                onChanged={onChanged}
+            />
+        );
+    if (dialog.type === "preview")
+        return <Preview item={dialog.item} auth={auth} onClose={onClose} />;
+    if (dialog.type === "restore")
+        return (
+            <Modal title="Restore to a Shared Folder?" onClose={close}>
+                <p>
+                    The destination has an active public folder link. Restoring
+                    these items will make them accessible to anyone with that
+                    link. Previously revoked item links stay revoked.
+                </p>
+                <ErrorNotice message={error} />
+                <div className="dialog-actions">
+                    <button
+                        className="secondary-button"
+                        onClick={close}
+                        disabled={busy}
+                    >
+                        Cancel
+                    </button>
+                    <button
+                        className="primary-button"
+                        disabled={busy}
+                        onClick={() =>
+                            void run(async () => {
+                                await onRestore(dialog.items);
+                                onChanged();
+                            })
+                        }
+                    >
+                        {busy ? <Spinner /> : null} Restore and Allow Public
+                        Access
+                    </button>
+                </div>
+            </Modal>
+        );
+    if (dialog.type === "delete")
+        return (
+            <Modal title="Delete Permanently?" onClose={close}>
+                <p>
+                    This will remove{" "}
+                    {dialog.items.length === 1
+                        ? "“" + dialog.items[0].name + "”"
+                        : dialog.items.length + " selected items"}{" "}
+                    and all files inside from TGDrive’s database. The original
+                    files will remain in Telegram.
+                </p>
+                <p className="muted">
+                    You cannot restore these items from Trash after deletion. If
+                    deletion fails, the item stays in Trash so you can try
+                    again.
+                </p>
+                <ErrorNotice message={error} />
+                <div className="dialog-actions">
+                    <button
+                        className="secondary-button"
+                        disabled={busy}
+                        onClick={onClose}
+                    >
+                        Keep in Trash
+                    </button>
+                    <button
+                        className="danger-button"
+                        disabled={busy}
+                        onClick={() =>
+                            void run(async () => {
+                                await onDelete(dialog.items);
+                                onChanged();
+                            })
+                        }
+                    >
+                        {busy ? (
+                            <>
+                                <Spinner /> Deleting…
+                            </>
+                        ) : (
+                            "Delete Permanently"
+                        )}
+                    </button>
+                </div>
+            </Modal>
+        );
+    if (dialog.type === "share")
+        return (
+            <Modal title={"Share “" + dialog.item.name + "”"} onClose={close}>
+                <p>
+                    Anyone with the link can{" "}
+                    {dialog.item.type === "folder"
+                        ? "view and download this folder’s current and future contents"
+                        : "download this file"}
+                    . They cannot edit your drive.
+                </p>
+                {!link && (
+                    <p className="muted">
+                        Each link has its own expiry. Existing links keep
+                        working.
+                    </p>
+                )}
+                {!link ? (
+                    <form
+                        onSubmit={(event) => {
+                            event.preventDefault();
+                            void run(async () => {
+                                const result = await api.share(
+                                    itemPath(dialog.item),
+                                    expires === "never" || expires === "custom"
+                                        ? null
+                                        : Number(expires),
+                                    shareLabel,
+                                    expires === "custom"
+                                        ? new Date(customExpiry).toISOString()
+                                        : undefined,
+                                );
+                                const params = new URLSearchParams({
+                                    path:
+                                        dialog.item.type === "folder"
+                                            ? "/share_" + dialog.item.id
+                                            : itemPath(dialog.item),
+                                    auth: result.auth,
+                                });
+                                setLink(
+                                    window.location.origin +
+                                        (dialog.item.type === "folder"
+                                            ? "/"
+                                            : "/file") +
+                                        "?" +
+                                        params,
+                                );
+                                setExpiry(result.expires_at);
+                            });
+                        }}
+                    >
+                        <label htmlFor="share-label">
+                            Link label (optional)
+                        </label>
+                        <input
+                            id="share-label"
+                            maxLength={80}
+                            value={shareLabel}
+                            placeholder="For example, Alex or project review"
+                            onChange={(event) =>
+                                setShareLabel(event.target.value)
+                            }
+                        />
+                        <fieldset className="share-expiry-options">
+                            <legend>Link Expires</legend>
+                            <div>
+                                {[
+                                    ["1", "1 day"],
+                                    ["7", "7 days"],
+                                    ["30", "30 days"],
+                                    ["never", "Never"],
+                                    ["custom", "Custom"],
+                                ].map(([value, label]) => (
+                                    <button
+                                        type="button"
+                                        key={value}
+                                        aria-pressed={expires === value}
+                                        onClick={() => setExpires(value)}
+                                    >
+                                        {label}
+                                    </button>
+                                ))}
+                            </div>
+                        </fieldset>
+                        {expires === "custom" && (
+                            <>
+                                <label htmlFor="share-custom-expiry">
+                                    Expiry date and time
+                                </label>
+                                <input
+                                    id="share-custom-expiry"
+                                    type="datetime-local"
+                                    required
+                                    value={customExpiry}
+                                    onChange={(event) =>
+                                        setCustomExpiry(event.target.value)
+                                    }
+                                />
+                            </>
+                        )}
+                        <ErrorNotice message={error} />
+                        <div className="dialog-actions">
+                            <button
+                                className="secondary-button"
+                                type="button"
+                                onClick={close}
+                            >
+                                Cancel
+                            </button>
+                            <button className="primary-button" disabled={busy}>
+                                {busy ? <Spinner /> : <Link size={16} />} Create
+                                Share Link
+                            </button>
+                        </div>
+                    </form>
+                ) : (
+                    <>
+                        <label htmlFor="share-link">Share Link</label>
+                        <input
+                            id="share-link"
+                            value={link}
+                            readOnly
+                            onFocus={(event) => event.target.select()}
+                        />
+                        <p className="muted">
+                            {expiry
+                                ? "Expires " + formatTimestamp(expiry) + "."
+                                : "This link does not expire."}{" "}
+                            Revoke access from Shared Links.
+                        </p>
+                        <ErrorNotice message={error} />
+                        <div className="dialog-actions">
+                            <button
+                                className="secondary-button"
+                                onClick={close}
+                            >
+                                Done
+                            </button>
+                            <button
+                                className="primary-button"
+                                onClick={() =>
+                                    void run(async () => {
+                                        if (!navigator.clipboard)
+                                            throw new Error(
+                                                "Clipboard access is unavailable. Select and copy the link above.",
+                                            );
+                                        await navigator.clipboard.writeText(
+                                            link,
+                                        );
+                                        onNotice("Share Link copied.");
+                                    })
+                                }
+                            >
+                                <Copy size={16} /> Copy Link
+                            </button>
+                        </div>
+                    </>
+                )}
+            </Modal>
+        );
+    const isFolder = dialog.type === "folder";
+    const isRename = dialog.type === "rename";
+    return (
+        <Modal
+            title={
+                isFolder
+                    ? "New Folder"
+                    : isRename
+                      ? "Rename"
+                      : "Upload from URL"
+            }
+            onClose={close}
+        >
+            <form
+                onSubmit={(event) => {
+                    event.preventDefault();
+                    void run(async () => {
+                        if (isFolder) {
+                            await api.folder(destination, name);
+                            onNotice("Folder created.");
+                            onChanged();
+                        } else if (isRename) {
+                            await api.rename(
+                                itemPath(dialog.item),
+                                name + extension,
+                            );
+                            onNotice("Name updated.");
+                            onChanged();
+                        } else {
+                            transfers.startRemote(
+                                url,
+                                destination,
+                                compat,
+                                requestId,
+                            );
+                            onNotice(
+                                "Starting URL import. Follow progress in Transfers.",
+                            );
+                            onClose();
+                        }
+                    });
+                }}
+            >
+                {isFolder || isRename ? (
+                    <>
+                        <label htmlFor="item-name">
+                            {isFolder ? "Folder Name" : "Name"}
+                        </label>
+                        <div className="item-name-field">
+                            <input
+                                id="item-name"
+                                required
+                                maxLength={255 - extension.length}
+                                value={name}
+                                aria-describedby={
+                                    extension ? "item-name-hint" : undefined
+                                }
+                                onChange={(event) =>
+                                    setName(event.target.value)
+                                }
+                            />
+                            {extension && (
+                                <span
+                                    className="rename-extension"
+                                    aria-hidden="true"
+                                >
+                                    {extension}
+                                </span>
+                            )}
+                        </div>
+                        {extension && (
+                            <p id="item-name-hint" className="muted">
+                                The {extension} extension will stay the same.
+                            </p>
+                        )}
+                    </>
+                ) : (
+                    <>
+                        <p className="muted">
+                            Import a direct HTTP or HTTPS file link. The server
+                            downloads it and uploads the original bytes to
+                            Telegram.
+                        </p>
+                        <label htmlFor="remote-url">Direct File URL</label>
+                        <input
+                            id="remote-url"
+                            type="url"
+                            required
+                            placeholder="https://example.com/file.zip"
+                            value={url}
+                            onChange={(event) => {
+                                setUrl(event.target.value);
+                                setRequestId(
+                                    crypto.randomUUID().replaceAll("-", "_"),
+                                );
+                            }}
+                        />
+                        <label className="check-field">
+                            <input
+                                type="checkbox"
+                                checked={compat}
+                                onChange={(event) =>
+                                    setCompat(event.target.checked)
+                                }
+                            />
+                            <span>
+                                Compatibility Mode
+                                <small>
+                                    Use one connection. Unsupported sources fall
+                                    back automatically.
+                                </small>
+                            </span>
+                        </label>
+                    </>
+                )}
+                <ErrorNotice message={error} />
+                <div className="dialog-actions">
+                    <button
+                        className="secondary-button"
+                        type="button"
+                        disabled={busy}
+                        onClick={onClose}
+                    >
+                        Cancel
+                    </button>
+                    <button className="primary-button" disabled={busy}>
+                        {busy ? <Spinner /> : null}
+                        {isFolder
+                            ? "Create Folder"
+                            : isRename
+                              ? "Save Name"
+                              : "Start Import"}
+                    </button>
+                </div>
+            </form>
+        </Modal>
+    );
+}
+function MoveDialog({
+    items,
+    onClose,
+    onChanged,
+}: {
+    items: DriveItem[];
+    onClose: () => void;
+    onChanged: () => void;
+}) {
+    const [path, setPath] = useState("/");
+    const [folders, setFolders] = useState<DriveItem[]>([]);
+    const [trail, setTrail] = useState([{ path: "/", name: "My Files" }]);
+    const [loading, setLoading] = useState(true);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    const [conflict, setConflict] = useState("keep_both");
+    const [exposure, setExposure] = useState(false);
+    const [allow, setAllow] = useState(false);
+    useEffect(() => {
+        let ignore = false;
+        setLoading(true);
+        setFolders([]);
+        setError("");
+        setExposure(false);
+        setAllow(false);
+        void api
+            .directory(path)
+            .then((result) => {
+                if (!ignore) {
+                    setError("");
+                    setFolders(
+                        Object.values(result.data.contents).filter(
+                            (item) =>
+                                item.type === "folder" &&
+                                !items.some(
+                                    (selected) =>
+                                        itemPath(item) === itemPath(selected) ||
+                                        itemPath(item).startsWith(
+                                            itemPath(selected) + "/",
+                                        ),
+                                ),
+                        ),
+                    );
+                }
+            })
+            .catch((error) => {
+                if (!ignore) setError(errorMessage(error));
+            })
+            .finally(() => {
+                if (!ignore) setLoading(false);
+            });
+        return () => {
+            ignore = true;
+        };
+    }, [path, items]);
+    const move = async () => {
+        setBusy(true);
+        setError("");
+        try {
+            const result = await api.move(
+                items.map(itemPath),
+                path,
+                conflict,
+                allow,
+            );
+            const failed = result.results?.filter(
+                (result) => result.error || result.status === "error",
+            );
+            if (failed?.length)
+                throw new Error(
+                    failed.length +
+                        " item(s) could not be moved. " +
+                        (failed[0].error || "Refresh and try again."),
+                );
+            onChanged();
+        } catch (error) {
+            if (
+                error instanceof ApiError &&
+                error.code.includes("PUBLIC_EXPOSURE")
+            ) {
+                setExposure(true);
+                setError(
+                    "This move would make some files accessible through a public folder link. Confirm below to continue.",
+                );
+            } else setError(errorMessage(error));
+        } finally {
+            setBusy(false);
+        }
+    };
+    return (
+        <Modal
+            title={
+                "Move " +
+                (items.length === 1
+                    ? "“" + items[0].name + "”"
+                    : items.length + " items")
+            }
+            onClose={() => {
+                if (!busy) onClose();
+            }}
+        >
+            <p className="muted">
+                Choose a different destination folder. Existing files are never
+                overwritten.
+            </p>
+            <nav
+                className="move-breadcrumbs"
+                aria-label="Destination breadcrumb"
+            >
+                {trail.map((crumb, index) => (
+                    <button
+                        key={crumb.path}
+                        className="text-button"
+                        onClick={() => {
+                            setPath(crumb.path);
+                            setTrail(trail.slice(0, index + 1));
+                        }}
+                    >
+                        {index > 0 && <ChevronRight size={13} />} {crumb.name}
+                    </button>
+                ))}
+            </nav>
+            <div className="folder-picker" aria-busy={loading}>
+                {loading ? (
+                    <p>
+                        <Spinner /> Loading folders…
+                    </p>
+                ) : folders.length ? (
+                    folders.map((folder) => (
+                        <button
+                            key={folder.id}
+                            onClick={() => {
+                                const next = itemPath(folder);
+                                setPath(next);
+                                setTrail([
+                                    ...trail,
+                                    { path: next, name: folder.name },
+                                ]);
+                            }}
+                        >
+                            <Folder size={19} />
+                            <span>{folder.name}</span>
+                            <ChevronRight size={17} />
+                        </button>
+                    ))
+                ) : (
+                    <p className="muted">No folders inside this destination.</p>
+                )}
+            </div>
+            <fieldset className="dialog-choice-options">
+                <legend>Name Conflicts</legend>
+                <div>
+                    <button
+                        type="button"
+                        aria-pressed={conflict === "keep_both"}
+                        onClick={() => setConflict("keep_both")}
+                    >
+                        Keep Both
+                    </button>
+                    <button
+                        type="button"
+                        aria-pressed={conflict === "skip"}
+                        onClick={() => setConflict("skip")}
+                    >
+                        Skip Existing
+                    </button>
+                </div>
+                <p className="muted">
+                    {conflict === "keep_both"
+                        ? "Add a number to the moved item if its name is already used."
+                        : "Leave items with matching names in their original location."}
+                </p>
+            </fieldset>
+            <ErrorNotice message={error} />
+            {exposure && (
+                <label className="check-field">
+                    <input
+                        type="checkbox"
+                        checked={allow}
+                        onChange={(event) => setAllow(event.target.checked)}
+                    />
+                    <span>
+                        I understand that files moved here may become public.
+                    </span>
+                </label>
+            )}
+            <div className="dialog-actions">
+                <button
+                    className="secondary-button"
+                    onClick={onClose}
+                    disabled={busy}
+                >
+                    Cancel
+                </button>
+                <button
+                    className="primary-button"
+                    disabled={
+                        busy ||
+                        loading ||
+                        items.every((item) => (item.path || "/") === path) ||
+                        (exposure && !allow)
+                    }
+                    onClick={() => void move()}
+                >
+                    {busy ? <Spinner /> : <Move size={16} />} Move Here
+                </button>
+            </div>
+        </Modal>
+    );
+}
diff --git a/website/src/features/files/FileBrowser.css b/website/src/features/files/FileBrowser.css
new file mode 100644
index 00000000..0ccd6e35
--- /dev/null
+++ b/website/src/features/files/FileBrowser.css
@@ -0,0 +1,698 @@
+.workspace.file-workspace {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    padding-bottom: 0;
+}
+.file-workspace > :not(.file-browser) {
+    flex-shrink: 0;
+}
+.file-browser {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-height: 0;
+    min-width: 0;
+}
+.file-browser > .file-toolbar {
+    flex-shrink: 0;
+    flex-wrap: wrap;
+    column-gap: 20px;
+    row-gap: 8px;
+    padding-bottom: 10px;
+    min-height: 54px;
+}
+.file-toolbar > .page-heading {
+    display: contents;
+}
+.file-toolbar .page-heading > div:first-child {
+    flex: 1 1 140px;
+    min-width: 0;
+}
+.file-toolbar h1 {
+    font-size: 24px;
+    line-height: 1.3;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.file-toolbar .breadcrumbs {
+    flex-wrap: nowrap;
+    overflow: hidden;
+    margin-bottom: 4px;
+    white-space: nowrap;
+}
+.file-toolbar .breadcrumbs > span {
+    display: inline-flex;
+    min-width: 0;
+}
+.file-toolbar .breadcrumbs a {
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.file-toolbar .search-form {
+    flex: 1 1 220px;
+    max-width: 380px;
+}
+.file-toolbar-controls {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    gap: 8px;
+    flex: 0 0 auto;
+    min-height: 44px;
+}
+.file-toolbar-controls > span:first-child {
+    white-space: nowrap;
+    margin-inline-end: 8px;
+}
+.file-list-scroll {
+    flex: 1;
+    min-height: 0;
+    overflow: auto;
+    overscroll-behavior-y: contain;
+    scrollbar-gutter: stable;
+    padding-bottom: 88px;
+}
+.file-list-scroll:focus-visible {
+    outline: 2px solid var(--action);
+    outline-offset: -2px;
+}
+.file-list-scroll .file-table th {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    background: var(--surface);
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .file-browser > .file-toolbar {
+        gap: 8px;
+    }
+    .file-toolbar .page-heading > div:first-child {
+        flex: 1 1 80px;
+    }
+    .file-toolbar h1 {
+        font-size: 21px;
+    }
+    .file-toolbar .page-heading .search-form {
+        flex-basis: 100%;
+        order: 2;
+        max-width: none;
+    }
+    .file-toolbar-controls {
+        margin-inline-start: auto;
+        gap: 2px;
+    }
+    .file-toolbar-actions {
+        gap: 0;
+    }
+    .file-toolbar-controls > span:first-child {
+        font-size: 11px;
+        margin-inline-end: 2px;
+    }
+    .file-toolbar .page-subtitle {
+        display: none;
+    }
+    .workspace.file-workspace,
+    .app-shell:has(#compact-new-button) .workspace.file-workspace {
+        overflow-y: auto;
+        padding: 12px 12px max(12px, env(safe-area-inset-bottom));
+        scrollbar-gutter: auto;
+        border-radius: 0;
+    }
+    .file-workspace .file-browser {
+        flex: 0 0 auto;
+    }
+    .file-list-scroll {
+        flex: 0 0 auto;
+        overflow: visible;
+        padding-bottom: 0;
+        scrollbar-gutter: auto;
+    }
+    .file-list-scroll .file-table th {
+        position: static;
+    }
+}
+
+.file-table .name-cell {
+    padding-inline-start: 12px;
+}
+.name-cell-content,
+.name-header-content {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+    min-width: 0;
+}
+.name-cell-content {
+    min-height: 48px;
+}
+.file-selection-slot {
+    width: 32px;
+    height: 32px;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex: 0 0 32px;
+}
+.file-name-details {
+    flex: 1;
+    min-width: 0;
+}
+.file-icon-spacer {
+    width: 32px;
+    flex: 0 0 32px;
+}
+.file-size-mobile {
+    display: none;
+}
+.file-name-details .file-name {
+    display: block;
+    max-width: 100%;
+}
+.search-result-location {
+    display: block;
+    margin-top: -8px;
+    padding: 0 5px 8px;
+    color: var(--muted);
+    font-size: 11px;
+    line-height: 1.5;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+.file-toolbar-actions {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .name-cell-content {
+        min-height: 60px;
+    }
+    .file-table .name-cell {
+        padding-inline-start: 0;
+    }
+    .search-result-location {
+        font-size: 11px;
+    }
+}
+
+.action-menu[popover] {
+    position: fixed;
+    inset: auto;
+    margin: 0;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+}
+
+/* Keep filenames uninterrupted; optional state is separate, quiet metadata. */
+.file-title-line {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+    min-width: 0;
+}
+.file-title-line .file-name {
+    flex: 1 1 auto;
+    min-width: 0;
+}
+.file-item-status {
+    display: inline-flex;
+    align-items: center;
+    flex: 0 0 auto;
+    gap: 10px;
+    padding-inline-start: 12px;
+    color: var(--muted);
+    font-size: 12px;
+    font-weight: 400;
+    line-height: 18px;
+    white-space: nowrap;
+}
+.file-status-label + .file-status-label {
+    border-inline-start: 1px solid var(--line);
+    padding-inline-start: 10px;
+}
+.file-table th:first-child {
+    padding-inline-start: 12px;
+}
+.column-sort-button {
+    min-height: 32px;
+    padding-block: 6px;
+}
+.file-row {
+    touch-action: manipulation;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .file-table th:first-child {
+        padding-inline-start: 0;
+    }
+    .column-sort-button {
+        min-height: 44px;
+    }
+    .actions-cell {
+        width: 44px;
+    }
+    .file-table .item-actions > summary {
+        width: 44px;
+        height: 44px;
+    }
+}
+
+/* The same row baseline is shared by Files, Trash and Shared Links. */
+:root {
+    --list-row-min-height: 56px;
+    --list-row-padding: 8px;
+}
+.file-table:not(.file-grid) td {
+    height: var(--list-row-min-height);
+}
+.name-cell-content {
+    min-height: var(--list-row-min-height);
+}
+.file-toolbar-controls {
+    flex-wrap: wrap;
+    row-gap: 4px;
+}
+.file-view-toggle {
+    display: inline-flex;
+    flex: 0 0 auto;
+    border: 1px solid var(--line);
+    border-radius: 6px;
+    padding: 2px;
+}
+.file-view-toggle .icon-button {
+    width: 36px;
+    height: 36px;
+    border-radius: 4px;
+}
+.file-view-toggle button[aria-pressed="true"] {
+    background: var(--selected);
+    color: var(--on-action-soft);
+}
+.file-grid {
+    display: block;
+    padding: 12px 0;
+}
+.file-grid > ul {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(168px, 1fr));
+    gap: 12px;
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+.file-grid .file-row {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) 44px;
+    align-content: stretch;
+    grid-template-rows: 1fr auto;
+    position: relative;
+    min-width: 0;
+    overflow: visible;
+    border: 1px solid var(--line-subtle);
+    border-radius: 8px;
+    background: var(--surface);
+}
+.file-grid .file-row:hover {
+    background: var(--hover);
+    border-color: var(--line);
+}
+.file-grid .file-row.selected {
+    background: var(--selected);
+    border-color: var(--action);
+}
+.file-grid .name-cell {
+    grid-column: 1 / -1;
+    padding: 0;
+    min-width: 0;
+}
+.file-tile-preview {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    aspect-ratio: 16 / 10;
+    overflow: hidden;
+    background: var(--canvas);
+    border-radius: 7px 7px 0 0;
+}
+.file-tile-preview img {
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+}
+.file-tile-preview .file-icon {
+    width: 48px;
+    height: 48px;
+}
+.file-tile-preview .file-icon svg {
+    width: 40px;
+    height: 40px;
+}
+.file-grid .name-cell-content {
+    padding: 8px 10px 0;
+    min-height: 0;
+    gap: 0;
+}
+.file-grid .file-selection-slot {
+    display: none;
+}
+.file-grid:has(input[type="checkbox"]) .file-selection-slot {
+    display: inline-flex;
+    position: absolute;
+    top: 6px;
+    left: 6px;
+    background: var(--surface);
+    border-radius: 4px;
+}
+.file-grid .file-name {
+    white-space: normal;
+    overflow-wrap: anywhere;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    line-height: 20px;
+    padding: 2px 0;
+    min-height: 24px;
+    max-width: 100%;
+}
+.file-grid .file-title-line {
+    align-items: flex-start;
+    flex-direction: column;
+    gap: 2px;
+}
+.file-grid .file-item-status {
+    padding: 0;
+}
+.file-grid .search-result-location {
+    padding: 0;
+    margin-top: 4px;
+}
+.file-grid .date-cell {
+    display: none;
+}
+.file-grid .size-cell {
+    display: flex;
+    align-items: center;
+    grid-column: 1;
+    width: auto;
+    padding: 4px 10px 8px;
+    font-size: 12px;
+}
+.file-grid .actions-cell {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+    grid-column: 2;
+    width: 44px;
+    padding: 0 4px 4px 0;
+}
+.file-grid .item-actions > summary {
+    width: 36px;
+    height: 36px;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .file-view-toggle .icon-button {
+        width: 40px;
+        height: 40px;
+        min-height: 44px;
+    }
+    .file-grid > ul {
+        grid-template-columns: repeat(auto-fill, minmax(132px, 1fr));
+        gap: 10px;
+    }
+    .file-grid .item-actions > summary {
+        width: 44px;
+        height: 44px;
+    }
+    .file-grid .actions-cell {
+        padding-inline-end: 0;
+    }
+    .file-grid .size-cell {
+        font-size: 11px;
+    }
+}
+
+.grid-select-all {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    min-height: 44px;
+    padding-inline: 8px;
+    font-size: 12px;
+}
+
+.file-table.file-grid .size-cell {
+    width: auto;
+    white-space: nowrap;
+    font-size: 12px;
+}
+
+.file-toolbar .file-selection-toggle {
+    border: 1px solid var(--line);
+    border-radius: 6px;
+    background: var(--surface);
+    min-height: 36px;
+    padding: 8px 12px;
+    gap: 8px;
+    font-weight: 500;
+}
+.file-selection-toggle > svg {
+    display: block;
+    flex-shrink: 0;
+}
+.file-selection-toggle:hover {
+    background: var(--hover);
+    border-color: var(--input-line);
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .page-heading:has(> .compact-search-trigger) {
+        flex-direction: row;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 8px;
+    }
+    .page-heading:has(> .compact-search-trigger) > div:first-child {
+        width: auto;
+        flex: 1 1 0;
+        min-width: 0;
+    }
+    .page-heading > .compact-search-trigger {
+        width: 44px;
+        height: 44px;
+        flex: 0 0 44px;
+    }
+    .page-heading > .search-form {
+        flex: 1 0 100%;
+        order: 3;
+        margin: 0;
+        max-width: none;
+    }
+    .page-heading .search-form .icon-button {
+        width: 44px;
+        height: 44px;
+        flex: 0 0 44px;
+    }
+    .page-heading .search-form {
+        padding-inline: 0;
+        gap: 0;
+    }
+    .file-browser > .file-toolbar {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto auto;
+        column-gap: 4px;
+        row-gap: 8px;
+        min-height: 52px;
+        padding-bottom: 8px;
+    }
+    .file-toolbar .page-heading > div:first-child {
+        grid-column: 1;
+        grid-row: 1;
+        min-width: 0;
+    }
+    .file-toolbar .page-title-line {
+        gap: 6px;
+    }
+    .file-toolbar .page-title-line h1 {
+        font-size: 18px;
+        line-height: 24px;
+        min-width: 0;
+    }
+    .file-toolbar .demo-marker {
+        display: none;
+    }
+    .file-toolbar .breadcrumbs {
+        font-size: 11px;
+        line-height: 16px;
+        margin-bottom: 0;
+    }
+    .file-toolbar .compact-search-trigger {
+        grid-column: 2;
+        grid-row: 1;
+    }
+    .file-toolbar .file-toolbar-controls {
+        grid-column: 3;
+        grid-row: 1;
+        flex-wrap: nowrap;
+        gap: 0;
+        margin: 0;
+    }
+    .file-toolbar .file-item-count,
+    .file-toolbar .file-view-toggle {
+        display: none;
+    }
+    .file-toolbar .file-selection-toggle {
+        width: 44px;
+        min-width: 44px;
+        min-height: 44px;
+        padding: 0;
+        justify-content: center;
+    }
+    .file-toolbar .file-selection-toggle > svg {
+        display: block;
+    }
+    .file-toolbar .file-selection-toggle > span {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+    }
+    .file-toolbar .file-selection-toggle[aria-pressed="true"] {
+        background: var(--selected);
+        color: var(--on-action-soft);
+    }
+    .file-toolbar .page-heading .search-form {
+        grid-column: 1 / -1;
+        grid-row: 2;
+        width: 100%;
+        max-width: none;
+        min-width: 0;
+    }
+    .file-toolbar[data-selection="true"] .file-toolbar-controls {
+        grid-column: 1 / -1;
+        grid-row: 1;
+        flex-wrap: nowrap;
+        justify-content: flex-start;
+        z-index: 1;
+        background: var(--surface);
+        gap: 4px;
+    }
+    .file-toolbar[data-selection="true"] .page-heading > div:first-child,
+    .file-toolbar[data-selection="true"] .compact-search-trigger {
+        visibility: hidden;
+        pointer-events: none;
+    }
+    .file-toolbar[data-selection="true"] .selection-count {
+        font-size: 13px;
+        margin-inline-end: auto;
+    }
+    .file-toolbar[data-selection="true"] .toolbar-divider,
+    .file-toolbar[data-selection="true"] .file-view-toggle {
+        display: none;
+    }
+    .file-toolbar .file-bulk-action {
+        min-width: 44px;
+        flex-shrink: 0;
+        justify-content: center;
+    }
+    .file-selection-slot {
+        width: 44px;
+        height: 44px;
+        flex-basis: 44px;
+    }
+    .file-toolbar .grid-select-all {
+        padding: 0;
+        flex-shrink: 0;
+    }
+    .file-toolbar[data-selection="true"]:has(.grid-select-all)
+        .file-bulk-action
+        > span {
+        display: none;
+    }
+    .file-list-scroll .file-name {
+        min-height: 44px;
+        width: 100%;
+        align-content: center;
+    }
+    .file-table:not(.file-grid) .size-cell {
+        display: none;
+    }
+    .file-table:not(.file-grid) .file-name-details {
+        display: grid;
+        grid-template-columns: max-content minmax(0, 1fr);
+        column-gap: 8px;
+        padding-bottom: 8px;
+    }
+    .file-table:not(.file-grid) .file-title-line {
+        display: contents;
+    }
+    .file-table:not(.file-grid) .file-name {
+        grid-column: 1 / -1;
+        grid-row: 1;
+        padding-block: 0;
+    }
+    .file-table:not(.file-grid) .file-size-mobile {
+        display: block;
+        grid-column: 1;
+        grid-row: 2;
+        font-size: 12px;
+        line-height: 18px;
+        color: var(--muted);
+    }
+    .file-table:not(.file-grid) .file-item-status {
+        grid-column: 2;
+        grid-row: 2;
+        padding: 0;
+        gap: 6px;
+        font-size: 11px;
+        min-width: 0;
+    }
+    .file-table:not(.file-grid) .file-status-label + .file-status-label {
+        padding-inline-start: 6px;
+    }
+    .file-table:not(.file-grid) .search-result-location {
+        grid-column: 1 / -1;
+        grid-row: 3;
+        padding: 0;
+        margin: 0;
+    }
+    .workspace.file-workspace,
+    .app-shell:has(#compact-new-button) .workspace.file-workspace {
+        padding-inline: max(12px, env(safe-area-inset-left))
+            max(12px, env(safe-area-inset-right));
+    }
+}
+
+@media (max-width: 400px) {
+    .file-toolbar .file-bulk-action > span {
+        display: none;
+    }
+}
+
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .file-title-line:has(.file-item-status) {
+        flex-direction: column;
+        align-items: flex-start;
+        gap: 0;
+    }
+    .file-title-line:has(.file-item-status) .file-name {
+        padding-block: 3px;
+    }
+    .file-title-line .file-item-status {
+        padding: 0 5px 3px;
+    }
+    .file-grid .file-title-line .file-item-status {
+        padding: 0;
+    }
+}
diff --git a/website/src/features/files/FileBrowser.tsx b/website/src/features/files/FileBrowser.tsx
new file mode 100644
index 00000000..cffa497f
--- /dev/null
+++ b/website/src/features/files/FileBrowser.tsx
@@ -0,0 +1,1496 @@
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import {
+    Star,
+    AlertCircle,
+    Folder,
+    Upload,
+    Move,
+    Trash2,
+    RefreshCw,
+    Download,
+    Server,
+    ChevronRight,
+    ChevronLeft,
+    MoreHorizontal,
+    Pencil,
+    Eye,
+    Link,
+    List,
+    LayoutGrid,
+    ArrowUp,
+    ArrowDown,
+    SquareCheck,
+} from "lucide-react";
+import type { ActionDialogState } from "./ActionDialog";
+import {
+    itemPath,
+    fileUrl,
+    formatBytes,
+    formatDate,
+    type DriveItem,
+    type Directory,
+    type Share,
+} from "../../shared/types";
+import { api } from "../../shared/api";
+import { shareExpired } from "../shares/SharesView";
+import { FileIcon, Spinner } from "../../shared/components";
+import SortMenu, { type FileSort } from "./SortMenu";
+import "./FileBrowser.css";
+import FileThumbnail from "./FileThumbnail";
+import { COMPACT_LAYOUT_QUERY } from "../../shared/responsive";
+import {
+    defaultSortOrder,
+    sortDriveItems,
+    type SortOrder,
+} from "./fileSorting";
+
+function positionItemMenu(details: HTMLDetailsElement) {
+    const panel = details.querySelector<HTMLElement>(".action-menu");
+    const trigger = details.querySelector("summary");
+    if (!panel || !trigger || !panel.showPopover) return;
+    if (!details.open) {
+        if (panel.matches(":popover-open")) panel.hidePopover();
+        return;
+    }
+    panel.style.maxHeight = Math.max(96, window.innerHeight - 24) + "px";
+    panel.showPopover();
+    const bounds = trigger.getBoundingClientRect();
+    const menu = panel.getBoundingClientRect();
+    const roomBelow = window.innerHeight - bounds.bottom - 18;
+    panel.style.left =
+        Math.max(
+            12,
+            Math.min(
+                bounds.right - menu.width,
+                window.innerWidth - menu.width - 12,
+            ),
+        ) + "px";
+    panel.style.top =
+        Math.max(
+            12,
+            roomBelow >= menu.height
+                ? bounds.bottom + 6
+                : bounds.top - menu.height - 6,
+        ) + "px";
+}
+
+function hideItemMenus() {
+    document
+        .querySelectorAll<HTMLDetailsElement>(".item-actions[open]")
+        .forEach((menu) => {
+            menu.open = false;
+            positionItemMenu(menu);
+        });
+}
+export default function FileBrowser({
+    directory,
+    listingKey,
+    refresh = 0,
+    highlightId = "",
+    loading,
+    refreshing = false,
+    error,
+    isPublic,
+    isTrash,
+    isStarred = false,
+    onStar,
+    isSearch,
+    auth,
+    onReload,
+    onUpload,
+    onOpen,
+    onDialog,
+    onAction,
+    searchPagination,
+    searchSort,
+    onSearchSort,
+    searchOrder,
+    onSearchOrder,
+    searchItems,
+    header,
+    searchQuery = "",
+}: {
+    directory: Directory;
+    listingKey: string;
+    refresh?: number;
+    highlightId?: string;
+    loading: boolean;
+    refreshing?: boolean;
+    error: string;
+    isPublic: boolean;
+    isTrash: boolean;
+    isStarred?: boolean;
+    onStar?: (item: DriveItem) => void;
+    isSearch: boolean;
+    auth: string;
+    onReload: () => void;
+    onUpload: () => void;
+    onOpen: (item: DriveItem) => void;
+    onDialog: (dialog: ActionDialogState) => void;
+    onAction: (action: "trash" | "restore", items: DriveItem[]) => void;
+    searchPagination?: {
+        offset: number;
+        hasMore: boolean;
+        onPrevious: () => void;
+        onNext: () => void;
+    };
+    searchSort?: FileSort;
+    onSearchSort?: (value: FileSort) => void;
+    searchOrder?: SortOrder;
+    onSearchOrder?: (value: SortOrder) => void;
+    searchItems?: DriveItem[];
+    header?: ReactNode;
+    searchQuery?: string;
+}) {
+    const [activeShares, setActiveShares] = useState<Share[]>([]);
+    useEffect(() => {
+        let ignore = false;
+        if (isPublic || isTrash) {
+            setActiveShares([]);
+            return;
+        }
+        void api
+            .shares()
+            .then((result) => {
+                if (!ignore) setActiveShares(result.shares);
+            })
+            .catch(() => {
+                if (!ignore) setActiveShares([]);
+            });
+        return () => {
+            ignore = true;
+        };
+    }, [directory, refresh, isPublic, isTrash]);
+    const [shareTick, tickShares] = useState(0);
+    useEffect(() => {
+        if (!activeShares.length) return;
+        const timer = setInterval(() => tickShares((n) => n + 1), 30000);
+        return () => clearInterval(timer);
+    }, [activeShares]);
+    const shareIndex = useMemo(() => {
+        const active = activeShares.filter((share) => !shareExpired(share));
+        return {
+            ids: new Set(active.map((share) => share.node_id)),
+            paths: new Set(
+                active.map((share) => share.path.replace(/\/+$/, "")),
+            ),
+        };
+    }, [activeShares, shareTick]);
+    const sharing = (item: DriveItem) => {
+        let path = itemPath(item);
+        if (shareIndex.ids.has(item.id) || shareIndex.paths.has(path))
+            return "Shared by Link";
+        while (path.includes("/")) {
+            path = path.slice(0, path.lastIndexOf("/"));
+            if (shareIndex.paths.has(path))
+                return "Shared Through Parent Folder";
+        }
+        return "";
+    };
+    const [selected, setSelected] = useState<Set<string>>(new Set());
+    const [selectionMode, setSelectionMode] = useState(false);
+    const pointerKind = useRef("");
+    const selectionActive = useRef(false);
+    selectionActive.current = selectionMode || selected.size > 0;
+    const [localSort, setLocalSort] = useState<FileSort>("name");
+    const [localOrder, setLocalOrder] = useState<SortOrder>("asc");
+    const [layout, setLayout] = useState<"list" | "grid">(() => {
+        try {
+            return localStorage.getItem("tgdrive.file-view") === "grid"
+                ? "grid"
+                : "list";
+        } catch {
+            return "list";
+        }
+    });
+    const sort = searchSort || localSort;
+    const order = searchOrder || localOrder;
+    const setOrder = (value: SortOrder) => {
+        if (searchPagination) onSearchOrder?.(value);
+        else setLocalOrder(value);
+        setPage(0);
+    };
+    const setSort = (value: FileSort, toggle = false) => {
+        const direction =
+            toggle && value === sort
+                ? order === "asc"
+                    ? "desc"
+                    : "asc"
+                : value === sort
+                  ? order
+                  : defaultSortOrder(value);
+        if (searchPagination) {
+            onSearchSort?.(value);
+            onSearchOrder?.(direction);
+        } else {
+            setLocalSort(value);
+            setLocalOrder(direction);
+        }
+        setPage(0);
+    };
+    const setView = (value: "list" | "grid") => {
+        setLayout(value);
+        try {
+            localStorage.setItem("tgdrive.file-view", value);
+        } catch {}
+        hideItemMenus();
+    };
+    const [page, setPage] = useState(0);
+    useEffect(() => {
+        setSelected(new Set());
+        setSelectionMode(false);
+        setPage(0);
+    }, [listingKey]);
+    useEffect(() => {
+        const escape = (event: KeyboardEvent) => {
+            if (
+                event.key !== "Escape" ||
+                document.querySelector("dialog[open]") ||
+                (event.target as HTMLElement).closest(
+                    "input:not([type=checkbox]),textarea,[role=menu]",
+                )
+            )
+                return;
+            const openMenu = document.querySelector<HTMLDetailsElement>(
+                ".item-actions[open]",
+            );
+            if (openMenu) {
+                event.preventDefault();
+                hideItemMenus();
+                openMenu.querySelector("summary")?.focus();
+                return;
+            }
+            if (!selectionActive.current) return;
+            event.preventDefault();
+            const row =
+                (event.target as HTMLElement).closest<HTMLElement>(
+                    ".file-row",
+                ) || document.querySelector<HTMLElement>(".file-row.selected");
+            const item =
+                row?.querySelector<HTMLButtonElement>(".item-name-button");
+            setSelected(new Set());
+            setSelectionMode(false);
+            // Selection checkboxes disappear on Escape. Return keyboard focus to a
+            // surviving control instead of letting the browser focus the whole scroller.
+            requestAnimationFrame(() => {
+                const target = item?.isConnected
+                    ? item
+                    : document.querySelector<HTMLButtonElement>(
+                          ".file-selection-toggle",
+                      );
+                target?.focus({ preventScroll: true });
+            });
+        };
+        document.addEventListener("keydown", escape);
+        return () => document.removeEventListener("keydown", escape);
+    }, []);
+    const allItems = useMemo(() => {
+        const items = (
+            searchItems || Object.values(directory.contents || {})
+        ).slice();
+        return searchPagination ? items : sortDriveItems(items, sort, order);
+    }, [directory.contents, searchItems, searchPagination, sort, order]);
+    useEffect(() => {
+        // Retain browsing state on refresh, dropping only selections that disappeared.
+        const ids = new Set(allItems.map((item) => item.id));
+        setSelected((current) => {
+            const next = new Set([...current].filter((id) => ids.has(id)));
+            return next.size === current.size ? current : next;
+        });
+        setPage((current) =>
+            Math.min(
+                current,
+                Math.max(0, Math.ceil(allItems.length / 100) - 1),
+            ),
+        );
+    }, [allItems]);
+    useEffect(() => {
+        const list = document.querySelector<HTMLElement>(".file-list-scroll");
+        const scroller = window.matchMedia(COMPACT_LAYOUT_QUERY).matches
+            ? list?.closest(".workspace")
+            : list;
+        scroller?.scrollTo({ top: 0 });
+    }, [page, listingKey, layout]);
+    const highlighted = useRef("");
+    useEffect(() => {
+        if (loading || !highlightId) return;
+        const target = JSON.stringify([
+            listingKey,
+            highlightId,
+            sort,
+            order,
+            layout,
+        ]);
+        if (highlighted.current === target) return;
+        const index = allItems.findIndex((item) => item.id === highlightId);
+        if (index < 0) return;
+        setPage(Math.floor(index / 100));
+        setSelected(new Set([highlightId]));
+        setSelectionMode(false);
+        let frame = requestAnimationFrame(() => {
+            frame = requestAnimationFrame(() => {
+                highlighted.current = target;
+                const row = document.querySelector<HTMLElement>(
+                    '[data-item-id="' + CSS.escape(highlightId) + '"]',
+                );
+                row?.scrollIntoView({ block: "center" });
+                row?.querySelector<HTMLButtonElement>(
+                    ".item-name-button",
+                )?.focus({ preventScroll: true });
+            });
+        });
+        return () => cancelAnimationFrame(frame);
+    }, [allItems, listingKey, highlightId, loading, sort, order, layout]);
+    const visibleItems = allItems.slice(page * 100, (page + 1) * 100);
+    const chosen = allItems.filter((item) => selected.has(item.id));
+    const closeItemMenus = () => {
+        const trigger = document.activeElement
+            ?.closest(".item-actions")
+            ?.querySelector("summary");
+        hideItemMenus();
+        trigger?.focus();
+    };
+    const showDialog = (dialog: ActionDialogState) => {
+        closeItemMenus();
+        onDialog(dialog);
+    };
+    const openPrimary = (
+        item: DriveItem,
+        keyboard = false,
+        doubleClick = false,
+    ) => {
+        // Opening never enters selection mode. Explicit selection has the same
+        // behavior for touch, mouse and keyboard, without double-tap timing.
+        if (!isPublic && selectionMode) {
+            setSelected((current) => {
+                const next = new Set(current);
+                if (next.has(item.id)) next.delete(item.id);
+                else next.add(item.id);
+                return next;
+            });
+        } else if (
+            !isTrash &&
+            (pointerKind.current !== "mouse" || keyboard || doubleClick)
+        ) {
+            setSelected(new Set());
+            onOpen(item);
+        }
+    };
+    useEffect(() => {
+        const close = (event: MouseEvent) => {
+            if (!(event.target as Element).closest(".item-actions"))
+                hideItemMenus();
+        };
+        const reposition = (event: Event) => {
+            if ((event.target as Element)?.closest?.(".action-menu")) return;
+            document
+                .querySelectorAll<HTMLDetailsElement>(".item-actions[open]")
+                .forEach((details) => {
+                    const bounds = details
+                        .querySelector("summary")
+                        ?.getBoundingClientRect();
+                    if (
+                        !bounds ||
+                        bounds.bottom < 0 ||
+                        bounds.top > window.innerHeight
+                    ) {
+                        details.open = false;
+                    }
+                    positionItemMenu(details);
+                });
+        };
+        document.addEventListener("click", close);
+        window.addEventListener("resize", hideItemMenus);
+        window.addEventListener("scroll", reposition, true);
+        return () => {
+            document.removeEventListener("click", close);
+            window.removeEventListener("resize", hideItemMenus);
+            window.removeEventListener("scroll", reposition, true);
+            hideItemMenus();
+        };
+    }, []);
+    const toggle = (id: string) =>
+        setSelected((prev) => {
+            const next = new Set(prev);
+            if (next.has(id)) next.delete(id);
+            else next.add(id);
+            return next;
+        });
+    const Collection = layout === "grid" ? "div" : "table";
+    const CollectionBody = layout === "grid" ? "ul" : "tbody";
+    const Row = layout === "grid" ? "li" : "tr";
+    const Cell = layout === "grid" ? "div" : "td";
+    return (
+        <div
+            className="file-browser"
+            onPointerDownCapture={(event) => {
+                pointerKind.current = event.pointerType;
+            }}
+        >
+            <div
+                className="file-toolbar"
+                data-selection={selectionMode && !isPublic ? "true" : undefined}
+            >
+                {header}
+                <div className="file-toolbar-controls">
+                    {selectionMode && !isPublic ? (
+                        <>
+                            {layout === "grid" && (
+                                <label className="grid-select-all file-checkbox-target">
+                                    <input
+                                        type="checkbox"
+                                        aria-label="Select All Files on This Page"
+                                        checked={
+                                            visibleItems.length > 0 &&
+                                            visibleItems.every((item) =>
+                                                selected.has(item.id),
+                                            )
+                                        }
+                                        ref={(input) => {
+                                            if (input) {
+                                                const count =
+                                                    visibleItems.filter(
+                                                        (item) =>
+                                                            selected.has(
+                                                                item.id,
+                                                            ),
+                                                    ).length;
+                                                input.indeterminate =
+                                                    count > 0 &&
+                                                    count < visibleItems.length;
+                                            }
+                                        }}
+                                        onChange={(event) => {
+                                            const next = new Set(selected);
+                                            for (const item of visibleItems)
+                                                event.target.checked
+                                                    ? next.add(item.id)
+                                                    : next.delete(item.id);
+                                            setSelected(next);
+                                        }}
+                                    />
+                                </label>
+                            )}
+                            <span className="selection-count" role="status">
+                                {chosen.length} selected
+                            </span>
+                            <button
+                                className="text-button"
+                                onClick={() => {
+                                    setSelected(new Set());
+                                    setSelectionMode(false);
+                                    requestAnimationFrame(() => {
+                                        document
+                                            .querySelector<HTMLButtonElement>(
+                                                ".file-selection-toggle",
+                                            )
+                                            ?.focus({ preventScroll: true });
+                                    });
+                                }}
+                            >
+                                Done
+                            </button>
+                            <div className="toolbar-divider" />
+                            {isTrash ? (
+                                <>
+                                    <button
+                                        className="text-button file-bulk-action"
+                                        disabled={!chosen.length}
+                                        aria-label="Restore"
+                                        title="Restore"
+                                        onClick={() =>
+                                            onAction("restore", chosen)
+                                        }
+                                    >
+                                        <RefreshCw size={16} />{" "}
+                                        <span>Restore</span>
+                                    </button>
+                                    <button
+                                        className="text-button danger-text file-bulk-action"
+                                        disabled={!chosen.length}
+                                        aria-label="Delete Permanently"
+                                        title="Delete Permanently"
+                                        onClick={() =>
+                                            showDialog({
+                                                type: "delete",
+                                                items: chosen,
+                                            })
+                                        }
+                                    >
+                                        <Trash2 size={16} />{" "}
+                                        <span>Delete Permanently</span>
+                                    </button>
+                                </>
+                            ) : (
+                                <>
+                                    <button
+                                        className="text-button file-bulk-action"
+                                        disabled={!chosen.length}
+                                        aria-label="Move"
+                                        title="Move"
+                                        onClick={() =>
+                                            showDialog({
+                                                type: "move",
+                                                items: chosen,
+                                            })
+                                        }
+                                    >
+                                        <Move size={16} /> <span>Move</span>
+                                    </button>
+                                    <button
+                                        className="text-button file-bulk-action"
+                                        disabled={!chosen.length}
+                                        aria-label="Trash"
+                                        title="Trash"
+                                        onClick={() =>
+                                            onAction("trash", chosen)
+                                        }
+                                    >
+                                        <Trash2 size={16} /> <span>Trash</span>
+                                    </button>
+                                </>
+                            )}
+                        </>
+                    ) : (
+                        <>
+                            <span className="file-item-count">
+                                {searchPagination
+                                    ? allItems.length
+                                        ? "Showing " +
+                                          (searchPagination.offset + 1) +
+                                          "–" +
+                                          (searchPagination.offset +
+                                              allItems.length) +
+                                          (searchPagination.hasMore
+                                              ? " · More available"
+                                              : "")
+                                        : "No Results"
+                                    : allItems.length +
+                                      (allItems.length === 1
+                                          ? " item"
+                                          : " items")}
+                                {isPublic ? " · Read-only" : ""}
+                            </span>
+                            <div className="file-toolbar-actions">
+                                {!isPublic && (
+                                    <button
+                                        type="button"
+                                        className="text-button file-selection-toggle"
+                                        title="Select files and folders"
+                                        aria-pressed={selectionMode}
+                                        onClick={() => {
+                                            setSelectionMode(!selectionMode);
+                                            setSelected(new Set());
+                                        }}
+                                    >
+                                        <SquareCheck
+                                            size={18}
+                                            aria-hidden="true"
+                                        />
+                                        <span>
+                                            {selectionMode ? "Done" : "Select"}
+                                        </span>
+                                    </button>
+                                )}
+                                <SortMenu
+                                    value={sort}
+                                    order={order}
+                                    onChange={(value) => setSort(value)}
+                                    onOrderChange={setOrder}
+                                    view={layout}
+                                    onViewChange={setView}
+                                />
+                            </div>
+                        </>
+                    )}
+                    <div
+                        className="file-view-toggle"
+                        role="group"
+                        aria-label="File view"
+                    >
+                        <button
+                            type="button"
+                            className="icon-button"
+                            aria-label="List view"
+                            title="List view"
+                            aria-pressed={layout === "list"}
+                            onClick={() => setView("list")}
+                        >
+                            <List size={18} />
+                        </button>
+                        <button
+                            type="button"
+                            className="icon-button"
+                            aria-label="Grid view"
+                            title="Grid view"
+                            aria-pressed={layout === "grid"}
+                            onClick={() => setView("grid")}
+                        >
+                            <LayoutGrid size={18} />
+                        </button>
+                    </div>
+                </div>
+            </div>
+            {!isPublic && directory.read_only && (
+                <p
+                    className="settings-help demo-files-read-only-note"
+                    role="note"
+                >
+                    Demo Files is read-only. You can open, preview and download
+                    these files. Use My Files to upload files, create folders
+                    and try changes.
+                </p>
+            )}
+            <div
+                className={
+                    "file-list-scroll" +
+                    (layout === "grid" ? " file-grid-scroll" : "")
+                }
+                tabIndex={0}
+                aria-label="File list"
+            >
+                {error ? (
+                    <div className="empty-state">
+                        <AlertCircle size={38} />
+                        <h2>
+                            {isPublic
+                                ? "Shared Folder Unavailable"
+                                : "Could Not Load Your Files"}
+                        </h2>
+                        <p role="alert">{error}</p>
+                        <button
+                            className="secondary-button"
+                            disabled={loading || refreshing}
+                            onClick={onReload}
+                        >
+                            {refreshing && <Spinner />}
+                            {refreshing ? "Refreshing…" : "Try Again"}
+                        </button>
+                    </div>
+                ) : loading ? (
+                    <div className="loading-state" role="status">
+                        <Spinner /> Loading files…
+                    </div>
+                ) : allItems.length === 0 ? (
+                    <div className="empty-state">
+                        <Folder size={46} />
+                        <h2>
+                            {isStarred
+                                ? searchQuery
+                                    ? "No Matching Starred Items"
+                                    : "No Starred Items Yet"
+                                : isTrash && searchQuery
+                                  ? "No Matching Trashed Items"
+                                  : isTrash
+                                    ? "Trash Is Empty"
+                                    : isSearch
+                                      ? "No Matching Files or Folders"
+                                      : "Nothing Here Yet"}
+                        </h2>
+                        <p>
+                            {isStarred
+                                ? "Star a file or folder from its actions menu to find it here."
+                                : isTrash && searchQuery
+                                  ? "Try another name or clear the search. This search stays in Trash."
+                                  : isTrash
+                                    ? "Items you trash stay here until you restore or permanently delete them."
+                                    : isSearch
+                                      ? "Try another file or folder name."
+                                      : isPublic
+                                        ? "The owner has not added any files to this folder."
+                                        : "Upload your first file or create a folder to get started."}
+                        </p>
+                        {!isPublic && !isTrash && !isSearch && !isStarred && (
+                            <button
+                                className="primary-button"
+                                onClick={onUpload}
+                            >
+                                <Upload size={17} /> Upload Files
+                            </button>
+                        )}
+                    </div>
+                ) : (
+                    <>
+                        <div className="file-table-wrap">
+                            <Collection
+                                className={
+                                    "file-table" +
+                                    (layout === "grid" ? " file-grid" : "")
+                                }
+                            >
+                                {layout === "list" && (
+                                    <thead>
+                                        <tr>
+                                            <th
+                                                scope="col"
+                                                aria-sort={
+                                                    sort === "name"
+                                                        ? order === "asc"
+                                                            ? "ascending"
+                                                            : "descending"
+                                                        : undefined
+                                                }
+                                            >
+                                                <div className="name-header-content">
+                                                    {!isPublic &&
+                                                        selectionMode && (
+                                                            <span className="file-selection-slot">
+                                                                {selectionMode && (
+                                                                    <label className="file-checkbox-target">
+                                                                        <input
+                                                                            type="checkbox"
+                                                                            aria-label="Select All Files on This Page"
+                                                                            ref={(
+                                                                                input,
+                                                                            ) => {
+                                                                                if (
+                                                                                    input
+                                                                                ) {
+                                                                                    const count =
+                                                                                        visibleItems.filter(
+                                                                                            (
+                                                                                                item,
+                                                                                            ) =>
+                                                                                                selected.has(
+                                                                                                    item.id,
+                                                                                                ),
+                                                                                        ).length;
+                                                                                    input.indeterminate =
+                                                                                        count >
+                                                                                            0 &&
+                                                                                        count <
+                                                                                            visibleItems.length;
+                                                                                }
+                                                                            }}
+                                                                            checked={
+                                                                                visibleItems.length >
+                                                                                    0 &&
+                                                                                visibleItems.every(
+                                                                                    (
+                                                                                        item,
+                                                                                    ) =>
+                                                                                        selected.has(
+                                                                                            item.id,
+                                                                                        ),
+                                                                                )
+                                                                            }
+                                                                            onChange={(
+                                                                                event,
+                                                                            ) => {
+                                                                                const next =
+                                                                                    new Set(
+                                                                                        selected,
+                                                                                    );
+                                                                                for (const item of visibleItems)
+                                                                                    event
+                                                                                        .target
+                                                                                        .checked
+                                                                                        ? next.add(
+                                                                                              item.id,
+                                                                                          )
+                                                                                        : next.delete(
+                                                                                              item.id,
+                                                                                          );
+                                                                                setSelected(
+                                                                                    next,
+                                                                                );
+                                                                            }}
+                                                                        />
+                                                                    </label>
+                                                                )}
+                                                            </span>
+                                                        )}
+                                                    <span
+                                                        className="file-icon-spacer"
+                                                        aria-hidden="true"
+                                                    />
+                                                    <button
+                                                        type="button"
+                                                        className="column-sort-button"
+                                                        aria-label="Sort by Name"
+                                                        onClick={() => {
+                                                            setSort(
+                                                                "name",
+                                                                true,
+                                                            );
+                                                            setPage(0);
+                                                        }}
+                                                    >
+                                                        Name{" "}
+                                                        {sort === "name" &&
+                                                            (order === "asc" ? (
+                                                                <ArrowUp
+                                                                    size={12}
+                                                                    aria-hidden="true"
+                                                                />
+                                                            ) : (
+                                                                <ArrowDown
+                                                                    size={12}
+                                                                    aria-hidden="true"
+                                                                />
+                                                            ))}
+                                                    </button>
+                                                </div>
+                                            </th>
+                                            <th
+                                                scope="col"
+                                                className="date-cell"
+                                                aria-sort={
+                                                    sort === "modified"
+                                                        ? order === "asc"
+                                                            ? "ascending"
+                                                            : "descending"
+                                                        : undefined
+                                                }
+                                            >
+                                                <button
+                                                    type="button"
+                                                    className="column-sort-button"
+                                                    aria-label="Sort by Date Added"
+                                                    onClick={() => {
+                                                        setSort(
+                                                            "modified",
+                                                            true,
+                                                        );
+                                                        setPage(0);
+                                                    }}
+                                                >
+                                                    Added
+                                                </button>
+                                            </th>
+                                            <th
+                                                scope="col"
+                                                className="size-cell"
+                                                aria-sort={
+                                                    sort === "size"
+                                                        ? order === "asc"
+                                                            ? "ascending"
+                                                            : "descending"
+                                                        : undefined
+                                                }
+                                            >
+                                                <button
+                                                    type="button"
+                                                    className="column-sort-button"
+                                                    aria-label="Sort by File Size"
+                                                    onClick={() => {
+                                                        setSort("size", true);
+                                                        setPage(0);
+                                                    }}
+                                                >
+                                                    Size
+                                                </button>
+                                            </th>
+                                            <th
+                                                scope="col"
+                                                className="actions-cell"
+                                            >
+                                                <span className="sr-only">
+                                                    Actions
+                                                </span>
+                                            </th>
+                                        </tr>
+                                    </thead>
+                                )}
+                                <CollectionBody
+                                    aria-label={
+                                        layout === "grid"
+                                            ? "Files and folders"
+                                            : undefined
+                                    }
+                                >
+                                    {visibleItems.map((item) => (
+                                        <Row
+                                            key={item.id}
+                                            className={
+                                                "file-row " +
+                                                (selected.has(item.id)
+                                                    ? "selected"
+                                                    : "")
+                                            }
+                                            data-item-id={item.id}
+                                            onClick={(event) => {
+                                                if (
+                                                    (event.detail > 1 &&
+                                                        pointerKind.current ===
+                                                            "mouse" &&
+                                                        !selectionMode) ||
+                                                    (
+                                                        event.target as Element
+                                                    ).closest(
+                                                        "button,a,input,label,summary,details",
+                                                    )
+                                                )
+                                                    return;
+                                                openPrimary(item);
+                                            }}
+                                            onDoubleClick={(event) => {
+                                                if (
+                                                    selectionMode ||
+                                                    pointerKind.current !==
+                                                        "mouse" ||
+                                                    (
+                                                        event.target as Element
+                                                    ).closest(
+                                                        "a,input,label,summary,details,button:not(.item-name-button)",
+                                                    )
+                                                )
+                                                    return;
+                                                openPrimary(item, false, true);
+                                            }}
+                                        >
+                                            <Cell className="name-cell">
+                                                {layout === "grid" && (
+                                                    <FileThumbnail
+                                                        item={item}
+                                                        auth={auth}
+                                                        disabled={isTrash}
+                                                    />
+                                                )}
+                                                <div className="name-cell-content">
+                                                    {!isPublic &&
+                                                        selectionMode && (
+                                                            <span className="file-selection-slot">
+                                                                {selectionMode && (
+                                                                    <label className="file-checkbox-target">
+                                                                        <input
+                                                                            type="checkbox"
+                                                                            aria-label={
+                                                                                "Select " +
+                                                                                item.name
+                                                                            }
+                                                                            checked={selected.has(
+                                                                                item.id,
+                                                                            )}
+                                                                            onChange={() =>
+                                                                                toggle(
+                                                                                    item.id,
+                                                                                )
+                                                                            }
+                                                                        />
+                                                                    </label>
+                                                                )}
+                                                            </span>
+                                                        )}
+                                                    {layout === "list" && (
+                                                        <FileIcon
+                                                            name={item.name}
+                                                            folder={
+                                                                item.type ===
+                                                                "folder"
+                                                            }
+                                                        />
+                                                    )}
+                                                    <div className="file-name-details">
+                                                        <div className="file-title-line">
+                                                            <button
+                                                                className="file-name item-name-button"
+                                                                title={
+                                                                    item.name
+                                                                }
+                                                                onClick={(
+                                                                    event,
+                                                                ) => {
+                                                                    if (
+                                                                        event.detail >
+                                                                            1 &&
+                                                                        pointerKind.current ===
+                                                                            "mouse" &&
+                                                                        !selectionMode
+                                                                    )
+                                                                        return;
+                                                                    openPrimary(
+                                                                        item,
+                                                                        event.detail ===
+                                                                            0,
+                                                                    );
+                                                                }}
+                                                            >
+                                                                {item.name}
+                                                            </button>
+                                                            {!isPublic &&
+                                                                ((!isStarred &&
+                                                                    item.starred) ||
+                                                                    (!isTrash &&
+                                                                        sharing(
+                                                                            item,
+                                                                        )) ||
+                                                                    item.read_only) && (
+                                                                    <span className="file-item-status">
+                                                                        {item.read_only && (
+                                                                            <span
+                                                                                className="file-status-label demo-files-read-only-label"
+                                                                                title="Read-only in the public demo"
+                                                                            >
+                                                                                Read-only
+                                                                            </span>
+                                                                        )}
+                                                                        {!isStarred &&
+                                                                            item.starred && (
+                                                                                <span className="file-status-label">
+                                                                                    Starred
+                                                                                </span>
+                                                                            )}
+                                                                        {!isTrash &&
+                                                                            sharing(
+                                                                                item,
+                                                                            ) && (
+                                                                                <span
+                                                                                    className="file-status-label"
+                                                                                    title={sharing(
+                                                                                        item,
+                                                                                    )}
+                                                                                    aria-label={sharing(
+                                                                                        item,
+                                                                                    )}
+                                                                                >
+                                                                                    Shared
+                                                                                </span>
+                                                                            )}
+                                                                    </span>
+                                                                )}
+                                                        </div>
+                                                        <span className="file-size-mobile">
+                                                            {item.type ===
+                                                            "folder"
+                                                                ? "Folder"
+                                                                : formatBytes(
+                                                                      item.size,
+                                                                  )}
+                                                        </span>
+                                                        {(isSearch ||
+                                                            isTrash ||
+                                                            isStarred) && (
+                                                            <span
+                                                                className="search-result-location"
+                                                                title={[
+                                                                    "My Files",
+                                                                    ...(item.parent_names ||
+                                                                        []),
+                                                                ].join(" / ")}
+                                                            >
+                                                                {isTrash
+                                                                    ? "Deleted from: "
+                                                                    : ""}
+                                                                {[
+                                                                    "My Files",
+                                                                    ...(item.parent_names ||
+                                                                        []),
+                                                                ].join(" / ")}
+                                                            </span>
+                                                        )}
+                                                    </div>
+                                                    {item.type === "folder" &&
+                                                        layout !== "grid" && (
+                                                            <span className="sr-only">
+                                                                Folder
+                                                            </span>
+                                                        )}
+                                                </div>
+                                            </Cell>
+                                            <Cell className="date-cell">
+                                                {formatDate(item.upload_date)}
+                                            </Cell>
+                                            <Cell className="size-cell">
+                                                {item.type === "folder"
+                                                    ? layout === "grid"
+                                                        ? "Folder"
+                                                        : "—"
+                                                    : formatBytes(item.size)}
+                                            </Cell>
+                                            <Cell className="actions-cell">
+                                                {isPublic ? (
+                                                    <a
+                                                        className="icon-button"
+                                                        href={
+                                                            item.type === "file"
+                                                                ? fileUrl(
+                                                                      itemPath(
+                                                                          item,
+                                                                      ),
+                                                                      auth,
+                                                                      true,
+                                                                  )
+                                                                : "/?" +
+                                                                  new URLSearchParams(
+                                                                      {
+                                                                          path:
+                                                                              "/share_" +
+                                                                              itemPath(
+                                                                                  item,
+                                                                              ).slice(
+                                                                                  1,
+                                                                              ),
+                                                                          auth,
+                                                                      },
+                                                                  )
+                                                        }
+                                                        download={
+                                                            item.type === "file"
+                                                                ? item.name
+                                                                : undefined
+                                                        }
+                                                        aria-label={
+                                                            (item.type ===
+                                                            "file"
+                                                                ? "Download "
+                                                                : "Open ") +
+                                                            item.name
+                                                        }
+                                                        onClick={
+                                                            item.type ===
+                                                            "folder"
+                                                                ? (event) => {
+                                                                      event.preventDefault();
+                                                                      onOpen(
+                                                                          item,
+                                                                      );
+                                                                  }
+                                                                : undefined
+                                                        }
+                                                    >
+                                                        {item.type ===
+                                                        "file" ? (
+                                                            <Download
+                                                                size={18}
+                                                            />
+                                                        ) : (
+                                                            <ChevronRight
+                                                                size={18}
+                                                            />
+                                                        )}
+                                                    </a>
+                                                ) : (
+                                                    <details
+                                                        className="item-actions"
+                                                        name="file-actions"
+                                                        onToggle={(event) => {
+                                                            if (
+                                                                event.target ===
+                                                                event.currentTarget
+                                                            )
+                                                                positionItemMenu(
+                                                                    event.currentTarget,
+                                                                );
+                                                        }}
+                                                    >
+                                                        <summary
+                                                            className="icon-button"
+                                                            aria-label={
+                                                                "Actions for " +
+                                                                item.name
+                                                            }
+                                                        >
+                                                            <MoreHorizontal
+                                                                size={20}
+                                                            />
+                                                        </summary>
+                                                        <div
+                                                            className="action-menu"
+                                                            popover="manual"
+                                                        >
+                                                            {isTrash ? (
+                                                                <>
+                                                                    <button
+                                                                        onClick={() => {
+                                                                            closeItemMenus();
+                                                                            onAction(
+                                                                                "restore",
+                                                                                [
+                                                                                    item,
+                                                                                ],
+                                                                            );
+                                                                        }}
+                                                                    >
+                                                                        <RefreshCw
+                                                                            size={
+                                                                                16
+                                                                            }
+                                                                        />{" "}
+                                                                        Restore
+                                                                    </button>
+                                                                    <button
+                                                                        className="danger-text"
+                                                                        onClick={() =>
+                                                                            showDialog(
+                                                                                {
+                                                                                    type: "delete",
+                                                                                    items: [
+                                                                                        item,
+                                                                                    ],
+                                                                                },
+                                                                            )
+                                                                        }
+                                                                    >
+                                                                        <Trash2
+                                                                            size={
+                                                                                16
+                                                                            }
+                                                                        />{" "}
+                                                                        Delete
+                                                                        Permanently
+                                                                    </button>
+                                                                </>
+                                                            ) : (
+                                                                <>
+                                                                    <button
+                                                                        onClick={() => {
+                                                                            closeItemMenus();
+                                                                            onOpen(
+                                                                                item,
+                                                                            );
+                                                                        }}
+                                                                    >
+                                                                        <Eye
+                                                                            size={
+                                                                                16
+                                                                            }
+                                                                        />{" "}
+                                                                        Open
+                                                                    </button>
+                                                                    {item.type ===
+                                                                        "file" && (
+                                                                        <>
+                                                                            <a
+                                                                                href={fileUrl(
+                                                                                    itemPath(
+                                                                                        item,
+                                                                                    ),
+                                                                                    "",
+                                                                                    true,
+                                                                                )}
+                                                                                download={
+                                                                                    item.name
+                                                                                }
+                                                                                onClick={
+                                                                                    closeItemMenus
+                                                                                }
+                                                                            >
+                                                                                <Download
+                                                                                    size={
+                                                                                        16
+                                                                                    }
+                                                                                />{" "}
+                                                                                Download
+                                                                            </a>
+                                                                            <button
+                                                                                role="menuitem"
+                                                                                onClick={() =>
+                                                                                    showDialog(
+                                                                                        {
+                                                                                            type: "download-link",
+                                                                                            item,
+                                                                                        },
+                                                                                    )
+                                                                                }
+                                                                            >
+                                                                                <Link
+                                                                                    size={
+                                                                                        16
+                                                                                    }
+                                                                                />{" "}
+                                                                                Copy
+                                                                                Download
+                                                                                Link
+                                                                            </button>
+                                                                            <button
+                                                                                role="menuitem"
+                                                                                title="Cache the whole file on the server for faster streaming and downloads"
+                                                                                onClick={() =>
+                                                                                    showDialog(
+                                                                                        {
+                                                                                            type: "prepare",
+                                                                                            item,
+                                                                                        },
+                                                                                    )
+                                                                                }
+                                                                            >
+                                                                                <Server
+                                                                                    size={
+                                                                                        16
+                                                                                    }
+                                                                                    aria-hidden="true"
+                                                                                />{" "}
+                                                                                Preload
+                                                                                file
+                                                                            </button>
+                                                                        </>
+                                                                    )}
+                                                                    {onStar && (
+                                                                        <button
+                                                                            onClick={() => {
+                                                                                closeItemMenus();
+                                                                                onStar(
+                                                                                    item,
+                                                                                );
+                                                                            }}
+                                                                        >
+                                                                            <Star
+                                                                                size={
+                                                                                    16
+                                                                                }
+                                                                                fill={
+                                                                                    item.starred
+                                                                                        ? "currentColor"
+                                                                                        : "none"
+                                                                                }
+                                                                            />
+                                                                            {item.starred
+                                                                                ? "Remove from Starred"
+                                                                                : "Add to Starred"}
+                                                                        </button>
+                                                                    )}
+                                                                    <button
+                                                                        onClick={() =>
+                                                                            showDialog(
+                                                                                {
+                                                                                    type: "rename",
+                                                                                    item,
+                                                                                },
+                                                                            )
+                                                                        }
+                                                                    >
+                                                                        <Pencil
+                                                                            size={
+                                                                                16
+                                                                            }
+                                                                        />{" "}
+                                                                        Rename
+                                                                    </button>
+                                                                    <button
+                                                                        onClick={() =>
+                                                                            showDialog(
+                                                                                {
+                                                                                    type: "move",
+                                                                                    items: [
+                                                                                        item,
+                                                                                    ],
+                                                                                },
+                                                                            )
+                                                                        }
+                                                                    >
+                                                                        <Move
+                                                                            size={
+                                                                                16
+                                                                            }
+                                                                        />{" "}
+                                                                        Move
+                                                                    </button>
+                                                                    <button
+                                                                        onClick={() =>
+                                                                            showDialog(
+                                                                                {
+                                                                                    type: "share",
+                                                                                    item,
+                                                                                },
+                                                                            )
+                                                                        }
+                                                                    >
+                                                                        <Link
+                                                                            size={
+                                                                                16
+                                                                            }
+                                                                        />{" "}
+                                                                        Share
+                                                                        Link
+                                                                    </button>
+                                                                    <button
+                                                                        className="danger-text"
+                                                                        onClick={() => {
+                                                                            closeItemMenus();
+                                                                            onAction(
+                                                                                "trash",
+                                                                                [
+                                                                                    item,
+                                                                                ],
+                                                                            );
+                                                                        }}
+                                                                    >
+                                                                        <Trash2
+                                                                            size={
+                                                                                16
+                                                                            }
+                                                                        />{" "}
+                                                                        Move to
+                                                                        Trash
+                                                                    </button>
+                                                                </>
+                                                            )}
+                                                        </div>
+                                                    </details>
+                                                )}
+                                            </Cell>
+                                        </Row>
+                                    ))}
+                                </CollectionBody>
+                            </Collection>
+                        </div>
+                        {searchPagination &&
+                            (searchPagination.offset > 0 ||
+                                searchPagination.hasMore) && (
+                                <div className="pagination">
+                                    <span>
+                                        Results {searchPagination.offset + 1}–
+                                        {searchPagination.offset +
+                                            allItems.length}
+                                    </span>
+                                    <button
+                                        type="button"
+                                        className="secondary-button"
+                                        disabled={!searchPagination.offset}
+                                        onClick={searchPagination.onPrevious}
+                                    >
+                                        Previous Results
+                                    </button>
+                                    <button
+                                        type="button"
+                                        className="secondary-button"
+                                        disabled={!searchPagination.hasMore}
+                                        onClick={searchPagination.onNext}
+                                    >
+                                        Next Results
+                                    </button>
+                                </div>
+                            )}
+                        {!searchPagination && allItems.length > 100 && (
+                            <div className="pagination">
+                                <span>
+                                    Showing {page * 100 + 1}–
+                                    {Math.min(
+                                        (page + 1) * 100,
+                                        allItems.length,
+                                    )}{" "}
+                                    of {allItems.length}
+                                </span>
+                                <button
+                                    className="icon-button"
+                                    disabled={!page}
+                                    aria-label="Previous Page"
+                                    onClick={() => {
+                                        setPage(page - 1);
+                                        setSelected(new Set());
+                                    }}
+                                >
+                                    <ChevronLeft size={18} />
+                                </button>
+                                <button
+                                    className="icon-button"
+                                    disabled={
+                                        (page + 1) * 100 >= allItems.length
+                                    }
+                                    aria-label="Next Page"
+                                    onClick={() => {
+                                        setPage(page + 1);
+                                        setSelected(new Set());
+                                    }}
+                                >
+                                    <ChevronRight size={18} />
+                                </button>
+                            </div>
+                        )}
+                    </>
+                )}
+            </div>
+        </div>
+    );
+}
diff --git a/website/src/features/files/FileThumbnail.tsx b/website/src/features/files/FileThumbnail.tsx
new file mode 100644
index 00000000..874ca6b0
--- /dev/null
+++ b/website/src/features/files/FileThumbnail.tsx
@@ -0,0 +1,109 @@
+import { useEffect, useRef, useState } from "react";
+import { FileIcon } from "../../shared/components";
+import type { DriveItem } from "../../shared/types";
+import { fetchThumbnail, thumbnailCandidate, thumbnailUrl } from "./thumbnails";
+
+export default function FileThumbnail({
+    item,
+    auth,
+    disabled = false,
+}: {
+    item: DriveItem;
+    auth: string;
+    disabled?: boolean;
+}) {
+    const target = useRef<HTMLDivElement>(null);
+    const [source, setSource] = useState<string | null>(null);
+    const [loading, setLoading] = useState(false);
+    useEffect(() => {
+        setSource(null);
+        setLoading(false);
+        const connection = (
+            navigator as Navigator & { connection?: { saveData?: boolean } }
+        ).connection;
+        if (disabled || !thumbnailCandidate(item) || connection?.saveData)
+            return;
+        const element = target.current!;
+        let controller: AbortController | null = null;
+        let visible = false;
+        const load = () => {
+            if (controller || !visible) return;
+            const work = new AbortController();
+            controller = work;
+            setLoading(true);
+            void fetchThumbnail(thumbnailUrl(item, auth), work.signal)
+                .then((url) => {
+                    if (!work.signal.aborted && visible) setSource(url);
+                })
+                .catch(() => {})
+                .finally(() => {
+                    if (controller === work) {
+                        controller = null;
+                        setLoading(false);
+                    }
+                });
+        };
+        const observer = new IntersectionObserver(
+            (entries) => {
+                const entry = entries.find((value) => value.target === element);
+                if (!entry) return;
+                visible = entry.isIntersecting;
+                if (visible) load();
+                else {
+                    controller?.abort();
+                    controller = null;
+                    setLoading(false);
+                    setSource(null);
+                }
+            },
+            { rootMargin: "120px" },
+        );
+        observer.observe(element);
+        return () => {
+            visible = false;
+            observer.disconnect();
+            controller?.abort();
+            controller = null;
+        };
+    }, [
+        item.id,
+        item.path,
+        item.name,
+        item.size,
+        item.upload_date,
+        auth,
+        disabled,
+    ]);
+    return (
+        <div
+            ref={target}
+            className={
+                "file-tile-preview" + (loading ? " thumbnail-loading" : "")
+            }
+            aria-hidden="true"
+        >
+            {source ? (
+                <img
+                    src={source}
+                    alt=""
+                    decoding="async"
+                    onError={() => setSource(null)}
+                />
+            ) : (
+                <>
+                    <FileIcon
+                        name={item.name}
+                        folder={item.type === "folder"}
+                    />
+                    {item.type !== "folder" && (
+                        <span className="file-tile-format">
+                            {(item.name.split(".").at(-1) || "File")
+                                .slice(0, 8)
+                                .toUpperCase()}
+                        </span>
+                    )}
+                </>
+            )}
+        </div>
+    );
+}
diff --git a/website/src/features/files/SortMenu.css b/website/src/features/files/SortMenu.css
new file mode 100644
index 00000000..de88327d
--- /dev/null
+++ b/website/src/features/files/SortMenu.css
@@ -0,0 +1,100 @@
+.file-sort-trigger {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 10px;
+    border-radius: 6px;
+    color: var(--muted);
+    min-height: 36px;
+    font-size: 13px;
+}
+.file-sort-trigger:hover,
+.file-sort-trigger[aria-expanded="true"] {
+    background: var(--canvas);
+    color: var(--ink);
+}
+.file-sort-menu {
+    position: fixed;
+    z-index: 120;
+    padding: 5px;
+    border: 1px solid var(--line);
+    border-radius: 8px;
+    background: var(--surface);
+    color: var(--ink);
+    max-height: calc(100dvh - 24px);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+}
+.file-sort-menu button {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    padding: 10px 12px;
+    min-height: 40px;
+    width: 100%;
+    border-radius: 4px;
+    text-align: start;
+    font-size: 13px;
+}
+.file-sort-menu button:hover,
+.file-sort-menu button:focus-visible {
+    background: var(--selected);
+}
+.file-sort-menu button:focus-visible {
+    outline-offset: -2px;
+}
+.sort-check-hidden {
+    visibility: hidden;
+}
+.file-table th .column-sort-button {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 0;
+    color: inherit;
+    font-size: inherit;
+    font-weight: inherit;
+}
+.column-sort-button:hover {
+    color: var(--action);
+}
+
+.sort-direction-group {
+    margin-top: 4px;
+    padding-top: 4px;
+    border-top: 1px solid var(--line);
+}
+.sort-direction-group small {
+    display: inline;
+    margin-inline-start: 8px;
+    color: var(--muted);
+    font-size: 11px;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .file-sort-trigger,
+    .file-sort-menu button {
+        min-height: 44px;
+    }
+}
+
+.sort-view-group {
+    margin-bottom: 4px;
+    padding-bottom: 4px;
+    border-bottom: 1px solid var(--line);
+}
+.sort-view-option {
+    display: inline-flex;
+    align-items: center;
+    gap: 10px;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .file-toolbar .file-sort-trigger {
+        width: 44px;
+        height: 44px;
+        justify-content: center;
+        padding: 0;
+    }
+}
diff --git a/website/src/features/files/SortMenu.tsx b/website/src/features/files/SortMenu.tsx
new file mode 100644
index 00000000..f9f92bb0
--- /dev/null
+++ b/website/src/features/files/SortMenu.tsx
@@ -0,0 +1,324 @@
+import {
+    useEffect,
+    useId,
+    useLayoutEffect,
+    useRef,
+    useState,
+    type KeyboardEvent,
+} from "react";
+import { createPortal } from "react-dom";
+import {
+    ArrowUp,
+    ArrowDown,
+    Check,
+    ChevronDown,
+    List,
+    LayoutGrid,
+    SlidersHorizontal,
+} from "lucide-react";
+import "./SortMenu.css";
+import type { SortOrder } from "./fileSorting";
+import { COMPACT_LAYOUT_QUERY } from "../../shared/responsive";
+
+export const SORT_OPTIONS = [
+    { value: "name", label: "Name" },
+    { value: "modified", label: "Date Added" },
+    { value: "size", label: "File Size" },
+] as const;
+export type FileSort = (typeof SORT_OPTIONS)[number]["value"];
+
+export default function SortMenu({
+    value,
+    onChange,
+    order,
+    onOrderChange,
+    view,
+    onViewChange,
+}: {
+    value: FileSort;
+    onChange: (value: FileSort) => void;
+    order: SortOrder;
+    onOrderChange: (value: SortOrder) => void;
+    view?: "list" | "grid";
+    onViewChange?: (value: "list" | "grid") => void;
+}) {
+    const [open, setOpen] = useState(false);
+    const [mobile, setMobile] = useState(
+        () => window.matchMedia(COMPACT_LAYOUT_QUERY).matches,
+    );
+    useEffect(() => {
+        const media = window.matchMedia(COMPACT_LAYOUT_QUERY);
+        const update = () => setMobile(media.matches);
+        media.addEventListener("change", update);
+        return () => media.removeEventListener("change", update);
+    }, []);
+    const combined = mobile && Boolean(onViewChange);
+    const [position, setPosition] = useState({ top: 0, left: 0, width: 224 });
+    const trigger = useRef<HTMLButtonElement>(null);
+    const menu = useRef<HTMLDivElement>(null);
+    const id = useId();
+    const label = SORT_OPTIONS.find((option) => option.value === value)!.label;
+    const close = (returnFocus = true) => {
+        setOpen(false);
+        if (returnFocus) trigger.current?.focus();
+    };
+    const show = () => {
+        const rect = trigger.current!.getBoundingClientRect();
+        const width = Math.min(224, window.innerWidth - 24);
+        setPosition({
+            top: Math.max(
+                12,
+                Math.min(rect.bottom + 6, window.innerHeight - 260),
+            ),
+            left: Math.max(
+                12,
+                Math.min(rect.right - width, window.innerWidth - width - 12),
+            ),
+            width,
+        });
+        setOpen(true);
+    };
+    useLayoutEffect(() => {
+        if (!open || !menu.current || !trigger.current) return;
+        const height = menu.current.getBoundingClientRect().height;
+        const anchor = trigger.current.getBoundingClientRect();
+        setPosition((current) => ({
+            ...current,
+            top: Math.max(
+                12,
+                Math.min(anchor.bottom + 6, window.innerHeight - height - 12),
+            ),
+        }));
+        Array.from(
+            menu.current.querySelectorAll<HTMLElement>('[aria-checked="true"]'),
+        )
+            .find((option) => option.getClientRects().length > 0)
+            ?.focus();
+    }, [open]);
+    useEffect(() => {
+        if (!open) return;
+        const outside = (event: PointerEvent) => {
+            if (
+                !menu.current?.contains(event.target as Node) &&
+                !trigger.current?.contains(event.target as Node)
+            )
+                setOpen(false);
+        };
+        const reposition = (event: Event) => {
+            if (
+                !(event.target instanceof Node) ||
+                !menu.current?.contains(event.target)
+            )
+                setOpen(false);
+        };
+        document.addEventListener("pointerdown", outside);
+        window.addEventListener("resize", reposition);
+        window.addEventListener("scroll", reposition, true);
+        return () => {
+            document.removeEventListener("pointerdown", outside);
+            window.removeEventListener("resize", reposition);
+            window.removeEventListener("scroll", reposition, true);
+        };
+    }, [open]);
+    const keydown = (event: KeyboardEvent<HTMLDivElement>) => {
+        const options = [
+            ...menu.current!.querySelectorAll<HTMLButtonElement>(
+                '[role="menuitemradio"]',
+            ),
+        ].filter((option) => option.getClientRects().length > 0);
+        const current = options.indexOf(
+            document.activeElement as HTMLButtonElement,
+        );
+        let next = current;
+        if (event.key === "ArrowDown") next = (current + 1) % options.length;
+        else if (event.key === "ArrowUp")
+            next = (current + options.length - 1) % options.length;
+        else if (event.key === "Home") next = 0;
+        else if (event.key === "End") next = options.length - 1;
+        else if (event.key === "Escape") {
+            event.preventDefault();
+            event.stopPropagation();
+            close();
+            return;
+        } else if (event.key === "Tab") {
+            close();
+            return;
+        } else return;
+        event.preventDefault();
+        options[next]?.focus();
+    };
+    return (
+        <>
+            <button
+                ref={trigger}
+                className="file-sort-trigger"
+                type="button"
+                aria-haspopup="menu"
+                aria-expanded={open}
+                aria-controls={open ? id : undefined}
+                aria-label={combined ? "View and sort" : "Sort Files: " + label}
+                aria-description={order === "asc" ? "Ascending" : "Descending"}
+                onClick={() => (open ? close() : show())}
+                onKeyDown={(event) => {
+                    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                        event.preventDefault();
+                        show();
+                    }
+                }}
+            >
+                {combined ? (
+                    <SlidersHorizontal size={19} aria-hidden="true" />
+                ) : (
+                    <>
+                        {order === "asc" ? (
+                            <ArrowUp size={15} />
+                        ) : (
+                            <ArrowDown size={15} />
+                        )}
+                        <span>{label}</span>
+                        <ChevronDown size={14} />
+                    </>
+                )}
+            </button>
+            {open &&
+                createPortal(
+                    <div
+                        ref={menu}
+                        id={id}
+                        className="file-sort-menu"
+                        role="menu"
+                        aria-label={combined ? "View and sort" : "Sort Files"}
+                        style={position}
+                        onKeyDown={keydown}
+                    >
+                        {combined && (
+                            <div
+                                className="sort-view-group"
+                                role="group"
+                                aria-label="File view"
+                            >
+                                {(["list", "grid"] as const).map((layout) => (
+                                    <button
+                                        key={layout}
+                                        type="button"
+                                        role="menuitemradio"
+                                        tabIndex={-1}
+                                        aria-checked={view === layout}
+                                        onClick={() => {
+                                            onViewChange?.(layout);
+                                            close();
+                                        }}
+                                    >
+                                        <span className="sort-view-option">
+                                            {layout === "list" ? (
+                                                <List
+                                                    size={18}
+                                                    aria-hidden="true"
+                                                />
+                                            ) : (
+                                                <LayoutGrid
+                                                    size={18}
+                                                    aria-hidden="true"
+                                                />
+                                            )}
+                                            {layout === "list"
+                                                ? "List view"
+                                                : "Grid view"}
+                                        </span>
+                                        <Check
+                                            size={16}
+                                            aria-hidden="true"
+                                            className={
+                                                view === layout
+                                                    ? ""
+                                                    : "sort-check-hidden"
+                                            }
+                                        />
+                                    </button>
+                                ))}
+                            </div>
+                        )}
+                        <div role="group" aria-label="Sort field">
+                            {SORT_OPTIONS.map((option) => (
+                                <button
+                                    key={option.value}
+                                    type="button"
+                                    role="menuitemradio"
+                                    tabIndex={-1}
+                                    aria-checked={value === option.value}
+                                    onClick={() => {
+                                        onChange(option.value);
+                                        close();
+                                    }}
+                                >
+                                    <span>{option.label}</span>
+                                    <Check
+                                        size={16}
+                                        aria-hidden="true"
+                                        className={
+                                            value === option.value
+                                                ? ""
+                                                : "sort-check-hidden"
+                                        }
+                                    />
+                                </button>
+                            ))}
+                        </div>
+                        <div
+                            className="sort-direction-group"
+                            role="group"
+                            aria-label="Sort direction"
+                        >
+                            {(["asc", "desc"] as const).map((direction) => (
+                                <button
+                                    key={direction}
+                                    type="button"
+                                    role="menuitemradio"
+                                    tabIndex={-1}
+                                    aria-checked={order === direction}
+                                    aria-label={
+                                        direction === "asc"
+                                            ? "Ascending"
+                                            : "Descending"
+                                    }
+                                    onClick={() => {
+                                        onOrderChange(direction);
+                                        close();
+                                    }}
+                                >
+                                    <span>
+                                        {direction === "asc"
+                                            ? "Ascending"
+                                            : "Descending"}
+                                        <small>
+                                            {value === "name"
+                                                ? direction === "asc"
+                                                    ? "A–Z"
+                                                    : "Z–A"
+                                                : value === "size"
+                                                  ? direction === "asc"
+                                                      ? "Smallest first"
+                                                      : "Largest first"
+                                                  : direction === "asc"
+                                                    ? "Oldest first"
+                                                    : "Newest first"}
+                                        </small>
+                                    </span>
+                                    <Check
+                                        size={16}
+                                        aria-hidden="true"
+                                        className={
+                                            order === direction
+                                                ? ""
+                                                : "sort-check-hidden"
+                                        }
+                                    />
+                                </button>
+                            ))}
+                        </div>
+                    </div>,
+                    document.body,
+                )}
+        </>
+    );
+}
diff --git a/website/src/features/files/fileSorting.test.ts b/website/src/features/files/fileSorting.test.ts
new file mode 100644
index 00000000..5567fc66
--- /dev/null
+++ b/website/src/features/files/fileSorting.test.ts
@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import { defaultSortOrder, sortDriveItems } from "./fileSorting";
+import type { DriveItem } from "../../shared/types";
+const items: DriveItem[] = [
+    {
+        id: "b",
+        name: "Beta",
+        type: "file",
+        path: "/",
+        size: 10,
+        upload_date: "2026-10-20",
+    },
+    {
+        id: "a",
+        name: "Alpha",
+        type: "file",
+        path: "/",
+        size: 20,
+        upload_date: "2026-10-19",
+    },
+    { id: "folder", name: "Zulu", type: "folder", path: "/" },
+    {
+        id: "c",
+        name: "Gamma",
+        type: "file",
+        path: "/",
+        size: 10,
+        upload_date: "2026-10-18",
+    },
+];
+describe("file sorting", () => {
+    it.each([
+        ["name", "asc", ["folder", "a", "b", "c"]],
+        ["name", "desc", ["folder", "c", "b", "a"]],
+        ["size", "asc", ["folder", "b", "c", "a"]],
+        ["size", "desc", ["folder", "a", "b", "c"]],
+        ["modified", "asc", ["folder", "c", "a", "b"]],
+        ["modified", "desc", ["folder", "b", "a", "c"]],
+    ] as const)(
+        "sorts %s %s with folders first and stable ties",
+        (field, order, ids) => {
+            expect(
+                sortDriveItems(items, field, order).map((item) => item.id),
+            ).toEqual(ids);
+            expect(items[0].id).toBe("b");
+        },
+    );
+    it("uses ID as a final tie breaker and keeps natural names", () => {
+        const values = ["10", "2", "1"].map((id) => ({
+            id,
+            name: "File " + id,
+            type: "file" as const,
+            path: "/",
+        }));
+        expect(sortDriveItems(values, "name", "asc").map((x) => x.id)).toEqual([
+            "1",
+            "2",
+            "10",
+        ]);
+        expect(
+            sortDriveItems(
+                [
+                    { ...values[0], id: "b", name: "Same" },
+                    { ...values[0], id: "a", name: "Same" },
+                ],
+                "size",
+                "desc",
+            ).map((x) => x.id),
+        ).toEqual(["a", "b"]);
+    });
+    it("preserves established defaults", () => {
+        expect(defaultSortOrder("name")).toBe("asc");
+        expect(defaultSortOrder("size")).toBe("desc");
+        expect(defaultSortOrder("modified")).toBe("desc");
+    });
+});
diff --git a/website/src/features/files/fileSorting.ts b/website/src/features/files/fileSorting.ts
new file mode 100644
index 00000000..758926db
--- /dev/null
+++ b/website/src/features/files/fileSorting.ts
@@ -0,0 +1,28 @@
+import type { DriveItem } from "../../shared/types";
+import type { FileSort } from "./SortMenu";
+
+export type SortOrder = "asc" | "desc";
+export const defaultSortOrder = (sort: FileSort): SortOrder =>
+    sort === "name" ? "asc" : "desc";
+export function sortDriveItems(
+    items: DriveItem[],
+    sort: FileSort,
+    order: SortOrder,
+): DriveItem[] {
+    const direction = order === "asc" ? 1 : -1;
+    return items.slice().sort((a, b) => {
+        if (a.type !== b.type) return a.type === "folder" ? -1 : 1;
+        const name = a.name.localeCompare(b.name, undefined, {
+            numeric: true,
+            sensitivity: "base",
+        });
+        const value =
+            sort === "size"
+                ? (a.size || 0) - (b.size || 0)
+                : sort === "modified"
+                  ? (Date.parse(a.upload_date || "") || 0) -
+                    (Date.parse(b.upload_date || "") || 0)
+                  : name;
+        return value * direction || name || a.id.localeCompare(b.id);
+    });
+}
diff --git a/website/src/features/files/listingUpdates.test.ts b/website/src/features/files/listingUpdates.test.ts
new file mode 100644
index 00000000..622158ed
--- /dev/null
+++ b/website/src/features/files/listingUpdates.test.ts
@@ -0,0 +1,200 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+    createListingRefreshQueue,
+    reconcileDirectory,
+    reconcileDriveItems,
+} from "./listingUpdates";
+import type { Directory, DriveItem } from "../../shared/types";
+
+function deferred() {
+    let resolve!: () => void;
+    let reject!: (reason: unknown) => void;
+    const promise = new Promise<void>((success, failure) => {
+        resolve = success;
+        reject = failure;
+    });
+    return { promise, resolve, reject };
+}
+
+describe("upload-driven listing refreshes", () => {
+    it("acknowledges an explicit refresh only after its trailing fresh load", async () => {
+        const first = deferred();
+        const second = deferred();
+        const load = vi
+            .fn<() => Promise<void>>()
+            .mockReturnValueOnce(first.promise)
+            .mockReturnValueOnce(second.promise);
+        const queue = createListingRefreshQueue(load);
+        const initial = queue.request();
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+        const acknowledge = vi.fn();
+        const manual = queue.request().then(acknowledge);
+        first.resolve();
+        await expect(initial).resolves.toBe(true);
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(2));
+        expect(acknowledge).not.toHaveBeenCalled();
+        second.resolve();
+        await manual;
+        expect(acknowledge).toHaveBeenCalledWith(true);
+        queue.dispose();
+    });
+
+    it("does not report refresh success after failure or navigation", async () => {
+        const queue = createListingRefreshQueue(async () => false);
+        await expect(queue.request()).resolves.toBe(false);
+        queue.dispose();
+        const waiting = deferred();
+        const other = createListingRefreshQueue(() => waiting.promise);
+        const current = other.request();
+        const trailing = other.request();
+        other.dispose();
+        await expect(current).resolves.toBe(false);
+        await expect(trailing).resolves.toBe(false);
+        waiting.resolve();
+    });
+
+    it("lets a slow listing finish and coalesces a completion burst into one trailing request", async () => {
+        const first = deferred();
+        const second = deferred();
+        const load = vi
+            .fn<() => Promise<void>>()
+            .mockReturnValueOnce(first.promise)
+            .mockReturnValueOnce(second.promise)
+            .mockResolvedValue(undefined);
+        const queue = createListingRefreshQueue(load);
+        queue.request();
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+        for (let index = 0; index < 100; index++) queue.request();
+        expect(load).toHaveBeenCalledTimes(1);
+        first.resolve();
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(2));
+        second.resolve();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(load).toHaveBeenCalledTimes(2);
+        queue.request();
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(3));
+        queue.dispose();
+    });
+
+    it("retries a queued invalidation after a failed request", async () => {
+        const first = deferred();
+        const load = vi
+            .fn<() => Promise<void>>()
+            .mockReturnValueOnce(first.promise)
+            .mockResolvedValue(undefined);
+        const queue = createListingRefreshQueue(load);
+        queue.request();
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+        queue.request();
+        first.reject(new Error("Network interrupted"));
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(2));
+        queue.dispose();
+    });
+
+    it("drops stale queued refreshes when navigating to another directory", async () => {
+        const first = deferred();
+        const load = vi.fn(() => first.promise);
+        const queue = createListingRefreshQueue(load);
+        queue.request();
+        await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(1));
+        queue.request();
+        queue.dispose();
+        first.resolve();
+        queue.request();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        expect(load).toHaveBeenCalledTimes(1);
+        const untouched = vi.fn(async () => {});
+        const cancelled = createListingRefreshQueue(untouched);
+        cancelled.request();
+        cancelled.dispose();
+        await Promise.resolve();
+        expect(untouched).not.toHaveBeenCalled();
+    });
+});
+
+const file: DriveItem = {
+    id: "file",
+    name: "File.txt",
+    path: "/folder",
+    type: "file",
+    size: 30,
+    parent_names: ["Folder"],
+};
+const folder: DriveItem = {
+    id: "folder",
+    name: "Folder",
+    path: "/folder",
+    type: "folder",
+};
+
+describe("incremental directory updates", () => {
+    it("updates a directory's read-only state even when its rows are unchanged", () => {
+        const previous: Directory = { contents: {}, read_only: false };
+        const restricted = reconcileDirectory(previous, {
+            contents: {},
+            read_only: true,
+        });
+        expect(restricted.read_only).toBe(true);
+        expect(restricted).not.toBe(previous);
+        expect(restricted.contents).toBe(previous.contents);
+        expect(
+            reconcileDirectory(restricted, { contents: {}, read_only: false })
+                .read_only,
+        ).toBe(false);
+    });
+    it("reuses an unchanged listing and rows across fresh JSON responses", () => {
+        const previous: Directory = {
+            name: "Folder",
+            contents: { file, folder },
+        };
+        const next = JSON.parse(JSON.stringify(previous)) as Directory;
+        expect(reconcileDirectory(previous, next)).toBe(previous);
+    });
+
+    it("inserts new uploads while preserving existing rows and accepts later removals", () => {
+        const previous: Directory = { contents: { file, folder } };
+        const uploaded = { ...file, id: "new-file", name: "Uploaded.txt" };
+        const result = reconcileDirectory(previous, {
+            contents: {
+                file: { ...file },
+                folder: { ...folder },
+                "new-file": uploaded,
+            },
+        });
+        expect(result).not.toBe(previous);
+        expect(result.contents.file).toBe(file);
+        expect(result.contents.folder).toBe(folder);
+        expect(result.contents["new-file"]).toBe(uploaded);
+        const removed = reconcileDirectory(result, { contents: { folder } });
+        expect(removed.contents).toEqual({ folder });
+    });
+
+    it("applies changed metadata and folder names without replacing untouched rows", () => {
+        const previous: Directory = {
+            name: "Before",
+            contents: { file, folder },
+        };
+        const changed = { ...file, size: 50, parent_names: ["Renamed Folder"] };
+        const result = reconcileDirectory(previous, {
+            name: "After",
+            contents: { file: changed, folder: { ...folder } },
+        });
+        expect(result.name).toBe("After");
+        expect(result.contents.file).toBe(changed);
+        expect(result.contents.folder).toBe(folder);
+    });
+
+    it("preserves unchanged search results and follows server ordering after an upload", () => {
+        const previous = [file, folder];
+        expect(
+            reconcileDriveItems(previous, [{ ...file }, { ...folder }]),
+        ).toBe(previous);
+        const reordered = reconcileDriveItems(previous, [
+            { ...folder },
+            { ...file },
+        ]);
+        expect(reordered).toEqual([folder, file]);
+        expect(reordered[0]).toBe(folder);
+        expect(reordered[1]).toBe(file);
+    });
+});
diff --git a/website/src/features/files/listingUpdates.ts b/website/src/features/files/listingUpdates.ts
new file mode 100644
index 00000000..550275b3
--- /dev/null
+++ b/website/src/features/files/listingUpdates.ts
@@ -0,0 +1,101 @@
+import type { Directory, DriveItem } from "../../shared/types";
+
+/** Coalesce invalidations without cancelling a listing that is still loading. */
+export function createListingRefreshQueue(load: () => Promise<void | boolean>) {
+    let running = false;
+    let disposed = false;
+    let current: ((success: boolean) => void)[] = [];
+    let queued: ((success: boolean) => void)[] = [];
+    const start = () => {
+        running = true;
+        current = queued;
+        queued = [];
+        const finish = (success: boolean) => {
+            for (const resolve of current) resolve(success && !disposed);
+            current = [];
+            running = false;
+            if (queued.length && !disposed) start();
+        };
+        // The caller presents load errors. A failed request must still release the
+        // queue so a later upload notification can retry the listing.
+        void Promise.resolve()
+            .then(() => {
+                return disposed ? false : load();
+            })
+            .then(
+                (result) => finish(result !== false),
+                () => finish(false),
+            );
+    };
+    const request = (): Promise<boolean> => {
+        if (disposed) return Promise.resolve(false);
+        return new Promise((resolve) => {
+            queued.push(resolve);
+            if (!running) start();
+        });
+    };
+    return {
+        request,
+        dispose() {
+            disposed = true;
+            for (const resolve of [...current, ...queued]) resolve(false);
+            current = [];
+            queued = [];
+        },
+    };
+}
+
+function sameItem(previous: DriveItem, next: DriveItem): boolean {
+    const keys = Object.keys(next) as (keyof DriveItem)[];
+    if (Object.keys(previous).length !== keys.length) return false;
+    return keys.every((key) => {
+        const before = previous[key];
+        const after = next[key];
+        return (
+            before === after ||
+            (Array.isArray(before) &&
+                Array.isArray(after) &&
+                before.length === after.length &&
+                before.every((value, index) => value === after[index]))
+        );
+    });
+}
+
+export function reconcileDriveItems(
+    previous: DriveItem[],
+    next: DriveItem[],
+): DriveItem[] {
+    const byId = new Map(previous.map((item) => [item.id, item]));
+    const reconciled = next.map((item) => {
+        const before = byId.get(item.id);
+        return before && sameItem(before, item) ? before : item;
+    });
+    return previous.length === reconciled.length &&
+        reconciled.every((item, index) => previous[index] === item)
+        ? previous
+        : reconciled;
+}
+
+/** Preserve unchanged rows so background refreshes do not churn their UI. */
+export function reconcileDirectory(
+    previous: Directory,
+    next: Directory,
+): Directory {
+    const entries = Object.entries(next.contents).map(([id, item]) => {
+        const before = previous.contents[id];
+        return [id, before && sameItem(before, item) ? before : item] as const;
+    });
+    const unchanged =
+        Object.keys(previous.contents).length === entries.length &&
+        entries.every(([id, item]) => previous.contents[id] === item);
+    if (
+        unchanged &&
+        previous.name === next.name &&
+        previous.read_only === next.read_only
+    )
+        return previous;
+    return {
+        ...next,
+        contents: unchanged ? previous.contents : Object.fromEntries(entries),
+    };
+}
diff --git a/website/src/features/files/thumbnails.test.ts b/website/src/features/files/thumbnails.test.ts
new file mode 100644
index 00000000..c651a545
--- /dev/null
+++ b/website/src/features/files/thumbnails.test.ts
@@ -0,0 +1,160 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+    fetchThumbnail,
+    thumbnailCandidate,
+    thumbnailUrl,
+    MAX_THUMBNAIL_BYTES,
+} from "./thumbnails";
+const item = {
+    id: "id",
+    name: "Photo.JPG",
+    type: "file" as const,
+    path: "/folder",
+    size: 1024,
+};
+afterEach(() => vi.unstubAllGlobals());
+describe("bounded provider thumbnails", () => {
+    it("requests only likely thumbnail formats, never the original endpoint", () => {
+        expect(thumbnailCandidate(item)).toBe(true);
+        expect(thumbnailCandidate({ ...item, name: "Manual.pdf" })).toBe(true);
+        expect(thumbnailCandidate({ ...item, name: "Archive.zip" })).toBe(
+            false,
+        );
+        expect(thumbnailCandidate({ ...item, type: "folder" })).toBe(false);
+        const url = new URL(
+            thumbnailUrl(item, "private-token"),
+            "https://drive.test",
+        );
+        expect(url.pathname).toBe("/api/v1/thumbnail");
+        expect(url.searchParams.get("auth")).toBe("private-token");
+        expect(url.searchParams.get("path")).toBe("/folder/id");
+    });
+    it("loads a small data image under the existing CSP with permission revalidation", async () => {
+        const request = vi.fn(
+            async () =>
+                new Response(new Uint8Array([1, 2, 3]), {
+                    headers: { "Content-Type": "image/png" },
+                }),
+        );
+        vi.stubGlobal("fetch", request);
+        expect(
+            await fetchThumbnail(
+                "/api/v1/thumbnail?path=/a",
+                new AbortController().signal,
+            ),
+        ).toBe("data:image/png;base64,AQID");
+        expect(request).toHaveBeenCalledWith(
+            expect.any(String),
+            expect.objectContaining({
+                credentials: "same-origin",
+                cache: "no-cache",
+            }),
+        );
+    });
+    it.each([204, 401, 403, 404, 503])(
+        "leaves an icon fallback for HTTP %s",
+        async (status) => {
+            vi.stubGlobal(
+                "fetch",
+                vi.fn(
+                    async () =>
+                        new Response(status === 204 ? null : "unavailable", {
+                            status,
+                        }),
+                ),
+            );
+            expect(
+                await fetchThumbnail(
+                    "/api/v1/thumbnail",
+                    new AbortController().signal,
+                ),
+            ).toBeNull();
+        },
+    );
+    it("rejects declared/actual oversized images and non-image responses", async () => {
+        for (const response of [
+            new Response("small", {
+                headers: {
+                    "content-type": "image/png",
+                    "content-length": String(MAX_THUMBNAIL_BYTES + 1),
+                },
+            }),
+            new Response(new Uint8Array(MAX_THUMBNAIL_BYTES + 1), {
+                headers: { "content-type": "image/png" },
+            }),
+            new Response("<svg></svg>", {
+                headers: { "content-type": "image/svg+xml" },
+            }),
+        ]) {
+            vi.stubGlobal(
+                "fetch",
+                vi.fn(async () => response),
+            );
+            expect(
+                await fetchThumbnail(
+                    "/api/v1/thumbnail",
+                    new AbortController().signal,
+                ),
+            ).toBeNull();
+        }
+    });
+    it("bounds pending work while a fast scroll outruns the network", async () => {
+        const releases: (() => void)[] = [];
+        const request = vi.fn(
+            () =>
+                new Promise<Response>((resolve) =>
+                    releases.push(() =>
+                        resolve(
+                            new Response(new Uint8Array([1]), {
+                                headers: { "content-type": "image/png" },
+                            }),
+                        ),
+                    ),
+                ),
+        );
+        vi.stubGlobal("fetch", request);
+        const controllers = Array.from(
+            { length: 35 },
+            () => new AbortController(),
+        );
+        const pending = controllers.map((controller, i) =>
+            fetchThumbnail("/thumb/" + i, controller.signal),
+        );
+        const results = Promise.allSettled(pending);
+        expect(request).toHaveBeenCalledTimes(2);
+        controllers.slice(2).forEach((controller) => controller.abort());
+        releases.forEach((release) => release());
+        const settled = await results;
+        expect(settled[34]).toMatchObject({
+            status: "rejected",
+            reason: { name: "QuotaExceededError" },
+        });
+        expect(request).toHaveBeenCalledTimes(2);
+    });
+    it("limits concurrency and cancels queued work before it sends anything", async () => {
+        const releases: (() => void)[] = [];
+        const request = vi.fn(
+            () =>
+                new Promise<Response>((resolve) =>
+                    releases.push(() =>
+                        resolve(
+                            new Response(new Uint8Array([1]), {
+                                headers: { "content-type": "image/png" },
+                            }),
+                        ),
+                    ),
+                ),
+        );
+        vi.stubGlobal("fetch", request);
+        const first = fetchThumbnail("/one", new AbortController().signal);
+        const second = fetchThumbnail("/two", new AbortController().signal);
+        const controller = new AbortController();
+        const third = fetchThumbnail("/three", controller.signal);
+        expect(request).toHaveBeenCalledTimes(2);
+        controller.abort();
+        await expect(third).rejects.toMatchObject({ name: "AbortError" });
+        releases.forEach((release) => release());
+        await Promise.all([first, second]);
+        expect(request).toHaveBeenCalledTimes(2);
+    });
+});
diff --git a/website/src/features/files/thumbnails.ts b/website/src/features/files/thumbnails.ts
new file mode 100644
index 00000000..ae3f73f9
--- /dev/null
+++ b/website/src/features/files/thumbnails.ts
@@ -0,0 +1,155 @@
+import { itemPath, type DriveItem } from "../../shared/types";
+
+export const MAX_THUMBNAIL_BYTES = 128 * 1024;
+export const THUMBNAIL_CONCURRENCY = 2;
+export const THUMBNAIL_PENDING = 32;
+const candidates = new Set([
+    "cbr",
+    "docx",
+    "pptx",
+    "xlsx",
+    "odt",
+    "odp",
+    "ods",
+    "mp3",
+    "flac",
+    "m4a",
+    "ogg",
+    "opus",
+    "wav",
+    "aac",
+    "epub",
+    "cbz",
+    "jpg",
+    "jpeg",
+    "png",
+    "webp",
+    "gif",
+    "avif",
+    "heic",
+    "heif",
+    "bmp",
+    "tif",
+    "tiff",
+    "svg",
+    "mp4",
+    "mkv",
+    "webm",
+    "mov",
+    "avi",
+    "wmv",
+    "m4v",
+    "mpeg",
+    "mpg",
+    "pdf",
+]);
+export function thumbnailCandidate(item: DriveItem): boolean {
+    return (
+        item.type === "file" &&
+        candidates.has(item.name.split(".").at(-1)?.toLowerCase() || "")
+    );
+}
+export function thumbnailUrl(item: DriveItem, auth: string): string {
+    return (
+        "/api/v1/thumbnail?" +
+        new URLSearchParams({ path: itemPath(item), ...(auth ? { auth } : {}) })
+    );
+}
+let active = 0;
+const queue: (() => void)[] = [];
+function drain() {
+    while (active < THUMBNAIL_CONCURRENCY && queue.length) queue.shift()!();
+}
+function limited<T>(signal: AbortSignal, task: () => Promise<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+        const cancelled = () => {
+            const index = queue.indexOf(start);
+            if (index >= 0) queue.splice(index, 1);
+            reject(new DOMException("Thumbnail cancelled", "AbortError"));
+        };
+        const start = () => {
+            signal.removeEventListener("abort", cancelled);
+            if (signal.aborted) {
+                cancelled();
+                return;
+            }
+            active++;
+            void task()
+                .then(resolve, reject)
+                .finally(() => {
+                    active--;
+                    drain();
+                });
+        };
+        if (signal.aborted) {
+            cancelled();
+            return;
+        }
+        if (queue.length >= THUMBNAIL_PENDING) {
+            reject(
+                new DOMException(
+                    "Thumbnail queue is busy",
+                    "QuotaExceededError",
+                ),
+            );
+            return;
+        }
+        signal.addEventListener("abort", cancelled, { once: true });
+        queue.push(start);
+        drain();
+    });
+}
+export async function fetchThumbnail(
+    url: string,
+    signal: AbortSignal,
+): Promise<string | null> {
+    return limited(signal, async () => {
+        const response = await fetch(url, {
+            credentials: "same-origin",
+            headers: { Accept: "image/jpeg, image/png, image/webp" },
+            signal: AbortSignal.any([signal, AbortSignal.timeout(10000)]),
+            // Each mount revalidates permission; HTTP ETags can reuse the small body.
+            cache: "no-cache",
+        });
+        const mime = response.headers.get("content-type")?.split(";")[0].trim();
+        if (
+            !response.ok ||
+            !["image/jpeg", "image/png", "image/webp"].includes(mime || "")
+        ) {
+            await response.body?.cancel();
+            return null;
+        }
+        if (
+            Number(response.headers.get("content-length") || 0) >
+            MAX_THUMBNAIL_BYTES
+        ) {
+            await response.body?.cancel();
+            return null;
+        }
+        const reader = response.body?.getReader();
+        if (!reader) return null;
+        let length = 0;
+        const parts: Uint8Array[] = [];
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done) break;
+                length += chunk.value.byteLength;
+                if (length > MAX_THUMBNAIL_BYTES) {
+                    await reader.cancel();
+                    return null;
+                }
+                parts.push(chunk.value);
+            }
+        } finally {
+            reader.releaseLock();
+        }
+        if (!length || signal.aborted) return null;
+        // The existing image CSP permits data URLs. Never expand it for grid previews.
+        let binary = "";
+        for (const part of parts)
+            for (let i = 0; i < part.length; i += 8192)
+                binary += String.fromCharCode(...part.subarray(i, i + 8192));
+        return `data:${mime};base64,${btoa(binary)}`;
+    });
+}
diff --git a/website/src/features/performance/Performance.css b/website/src/features/performance/Performance.css
new file mode 100644
index 00000000..3a94aa38
--- /dev/null
+++ b/website/src/features/performance/Performance.css
@@ -0,0 +1,1314 @@
+.performance-settings {
+    max-width: 1040px;
+}
+.performance-setting-group {
+    border: 0;
+    padding: 0;
+    margin: 28px 0 0;
+    min-width: 0;
+}
+.performance-setting-group legend {
+    padding: 0;
+    font-size: 16px;
+    font-weight: 600;
+    margin-bottom: 6px;
+}
+.performance-setting-group > .settings-help {
+    margin: 0 0 4px;
+    max-width: 70ch;
+}
+.performance-setting-group .performance-field:last-child {
+    border-bottom: 0;
+}
+.performance-section-heading {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 20px;
+}
+.performance-section-heading > div {
+    min-width: 0;
+}
+.performance-section-heading > :is(button, a) {
+    flex-shrink: 0;
+}
+.performance-section-heading h2,
+.performance-section-heading h3 {
+    margin-top: 0;
+}
+.performance-section-heading p {
+    margin-top: 6px;
+    max-width: 68ch;
+    color: var(--muted);
+    line-height: 1.6;
+}
+.performance-loading {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    color: var(--muted);
+    padding-block: 18px;
+}
+.performance-field {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(145px, 230px);
+    align-items: center;
+    gap: 28px;
+    padding-block: 18px;
+    border-bottom: 1px solid var(--line);
+}
+.performance-field label {
+    font-weight: 500;
+}
+.performance-field p {
+    margin: 5px 0 0;
+    color: var(--muted);
+    font-size: 14px;
+    line-height: 1.6;
+    max-width: 62ch;
+}
+.performance-field input {
+    min-width: 0;
+    margin: 0;
+    font-size: 16px;
+    font-variant-numeric: tabular-nums;
+}
+.performance-auto-preload {
+    align-items: flex-start;
+    margin-block: 22px;
+}
+.performance-auto-preload small {
+    display: block;
+    max-width: 68ch;
+    margin-top: 5px;
+    color: var(--muted);
+    font-size: 14px;
+    line-height: 1.6;
+}
+.performance-advanced {
+    margin-block: 20px;
+}
+.performance-advanced > summary {
+    width: fit-content;
+    min-height: 44px;
+    padding-block: 12px;
+    cursor: pointer;
+    font-weight: 500;
+}
+.performance-advanced > p {
+    color: var(--muted);
+    font-size: 14px;
+    line-height: 1.6;
+    max-width: 68ch;
+}
+.performance-actions {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 12px;
+    margin-block: 24px 0;
+    padding-block: 16px;
+    border-top: 1px solid var(--line);
+    background: var(--surface);
+}
+.performance-save-state {
+    margin-right: auto;
+    color: var(--muted);
+    font-size: 13px;
+}
+.preloads-page,
+.performance-page {
+    max-width: 1280px;
+}
+.performance-facts {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: 20px 32px;
+    margin-block: 24px;
+    padding-block: 18px;
+    border-block: 1px solid var(--line);
+}
+.performance-facts > div {
+    min-width: 0;
+}
+.performance-facts dt {
+    color: var(--muted);
+    font-size: 13px;
+    margin-bottom: 9px;
+}
+.performance-facts dd {
+    margin: 0;
+    color: var(--ink);
+    font-size: 16px;
+    font-weight: 500;
+    font-variant-numeric: tabular-nums;
+    overflow-wrap: anywhere;
+}
+.performance-facts small {
+    display: block;
+    margin-top: 7px;
+    color: var(--muted);
+    font-size: 12px;
+    line-height: 1.6;
+}
+.performance-section {
+    margin-top: 28px;
+}
+.performance-section h3 {
+    font-size: 16px;
+    margin-bottom: 14px;
+}
+.performance-empty {
+    color: var(--muted);
+    font-size: 14px;
+    line-height: 1.7;
+    max-width: 68ch;
+    padding: 24px 0;
+    margin: 0;
+}
+.performance-count {
+    display: inline-block;
+    color: var(--muted);
+    font-size: 13px;
+    font-weight: 400;
+    margin-left: 8px;
+    font-variant-numeric: tabular-nums;
+}
+.performance-filters {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px;
+}
+.performance-filters button {
+    display: inline-flex;
+    align-items: center;
+    gap: 9px;
+    min-height: 40px;
+    padding: 8px 14px;
+    border: 0;
+    border-radius: 6px;
+    color: var(--muted);
+    background: transparent;
+    font-weight: 500;
+    cursor: pointer;
+}
+.performance-filters button:hover {
+    background: var(--hover);
+    color: var(--ink);
+}
+.performance-filters button:is([aria-pressed="true"], [aria-selected="true"]) {
+    background: var(--action-soft);
+    color: var(--on-action-soft);
+}
+.performance-filters button span {
+    font-variant-numeric: tabular-nums;
+    font-size: 12px;
+    opacity: 0.85;
+}
+.performance-view-tabs {
+    margin-top: 28px;
+    padding-bottom: 12px;
+    border-bottom: 1px solid var(--line);
+}
+.performance-overview-grid:not([hidden]) {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 32px;
+}
+.performance-overview-grid .performance-facts {
+    grid-template-columns: 1fr;
+    gap: 16px;
+    margin-block: 16px;
+    border: 0;
+    padding: 0;
+}
+.performance-overview-grid .performance-facts > div {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: 4px 12px;
+}
+.performance-overview-grid .performance-facts dt {
+    margin: 0;
+}
+.performance-overview-grid .performance-facts dd {
+    font-size: 14px;
+}
+.performance-overview-grid .performance-facts small {
+    grid-column: 1 / -1;
+    margin: 0;
+}
+.cache-inventory-toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    padding-block: 8px 16px;
+    border-bottom: 1px solid var(--line);
+}
+.cache-search {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    max-width: 320px;
+    min-width: 0;
+    flex: 1;
+    background: var(--surface-subtle);
+    border-radius: 8px;
+    padding-left: 12px;
+    color: var(--muted);
+}
+.cache-search svg {
+    flex-shrink: 0;
+}
+.preloads-page .cache-search input[type="search"] {
+    width: 100%;
+    min-width: 0;
+    margin: 0;
+    border: 0;
+    background: transparent;
+    padding: 10px 12px 10px 0;
+    color: var(--ink);
+}
+.cache-budget-summary progress {
+    display: block;
+    width: 100%;
+    height: 5px;
+    margin-top: 12px;
+    accent-color: var(--action);
+}
+.performance-detail-note {
+    font-size: 13px;
+    color: var(--muted);
+}
+.performance-detail-note > summary {
+    width: fit-content;
+    padding-block: 8px;
+    cursor: pointer;
+}
+.performance-detail-note .performance-facts {
+    border: 0;
+    padding: 0;
+    margin-block: 12px;
+}
+.cached-file-title {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 12px;
+}
+.cached-file-title > strong {
+    min-width: 0;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.cache-ready-state {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    flex-shrink: 0;
+    font-size: 12px;
+    color: var(--muted);
+}
+.cache-ready-state[data-complete="true"] {
+    color: var(--success);
+}
+.cache-clear-help {
+    margin-top: 16px;
+}
+.cache-diagnostics {
+    margin-top: 24px;
+    border-top: 1px solid var(--line);
+    padding-top: 12px;
+}
+.cache-budget-summary {
+    padding-block: 14px;
+    margin-block: 16px;
+}
+.preloads-page .performance-section {
+    margin-top: 20px;
+}
+.cached-file > .file-icon {
+    margin-top: 1px;
+}
+.performance-resource-summary {
+    grid-column: 1 / -1;
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 20px 32px;
+}
+.performance-resource-summary h3 {
+    grid-column: 1 / -1;
+    margin-bottom: 0;
+}
+.performance-usage > div {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 16px;
+}
+.performance-usage > div > span {
+    color: var(--muted);
+    font-size: 13px;
+}
+.performance-usage strong {
+    font-size: 14px;
+    font-variant-numeric: tabular-nums;
+    font-weight: 500;
+}
+.performance-usage progress {
+    display: block;
+    width: 100%;
+    height: 6px;
+    margin-block: 8px;
+    accent-color: var(--action);
+}
+.performance-usage small {
+    color: var(--muted);
+    font-size: 12px;
+    line-height: 1.5;
+}
+.performance-cache-summary {
+    grid-column: 1 / -1;
+    border-block: 1px solid var(--line);
+    padding-block: 18px;
+}
+.performance-cache-summary p {
+    margin-bottom: 8px;
+}
+.performance-page .performance-network-help {
+    max-width: 80ch;
+    margin: 12px 0 0;
+    color: var(--muted);
+    font-size: 13px;
+    line-height: 1.6;
+}
+.performance-metric-chart {
+    min-width: 0;
+    padding-block: 24px 8px;
+}
+.performance-history-controls,
+.performance-history-controls > label {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+.performance-history-controls > label {
+    color: var(--muted);
+    font-size: 12px;
+    white-space: nowrap;
+}
+.performance-history-controls select {
+    min-height: 44px;
+    padding: 8px 30px 8px 12px;
+    width: auto;
+    font-size: 13px;
+}
+.performance-history-availability {
+    margin: 14px 0 0;
+    color: var(--muted);
+    font-size: 12px;
+    line-height: 1.5;
+}
+.performance-custom-range {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: end;
+    gap: 12px;
+    padding-block: 16px;
+    border-bottom: 1px solid var(--line);
+}
+.performance-custom-range > label {
+    display: grid;
+    gap: 6px;
+    color: var(--muted);
+    font-size: 12px;
+    flex: 1 1 200px;
+}
+.performance-custom-range input {
+    width: 100%;
+    min-width: 0;
+}
+.performance-custom-range > p {
+    flex-basis: 100%;
+    margin: 0;
+}
+.performance-history-status,
+.performance-history-error {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin-block: 12px;
+    font-size: 13px;
+    color: var(--muted);
+}
+.performance-chart-now {
+    margin-inline-start: 8px;
+    color: var(--muted);
+    font-size: 11px;
+    font-weight: 400;
+    white-space: nowrap;
+}
+.performance-chart-times > span {
+    flex: 1;
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.performance-chart-times > span:last-child {
+    text-align: end;
+}
+.performance-all-time {
+    grid-column: 1 / -1;
+    padding-block: 20px 0;
+    margin-top: 12px;
+    border-top: 1px solid var(--line);
+}
+.performance-all-time h3 {
+    margin-bottom: 8px;
+}
+.performance-chart-legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px 20px;
+    margin: 0 0 12px;
+    font-size: 12px;
+    color: var(--muted);
+}
+.performance-chart-legend > span::before {
+    width: 20px;
+    height: 0;
+    border-radius: 0;
+    background: transparent;
+    border-top: 2px solid var(--action);
+}
+.performance-chart-legend > .chart-series-secondary::before {
+    background: transparent;
+    border-top: 2px dashed var(--muted);
+}
+.performance-chart-plot {
+    position: relative;
+}
+.performance-chart-plot > svg {
+    cursor: crosshair;
+}
+.performance-chart-tooltip {
+    position: absolute;
+    display: grid;
+    gap: 3px;
+    width: 280px;
+    max-width: calc(100% - 16px);
+    padding: 8px 10px;
+    border: 1px solid var(--line);
+    border-radius: 6px;
+    background: var(--surface);
+    color: var(--ink);
+    font-size: 11px;
+    line-height: 1.5;
+    box-shadow: 0 2px 8px #00000015;
+    pointer-events: none;
+    font-variant-numeric: tabular-nums;
+}
+@media (max-width: 620px) {
+    .performance-history-controls {
+        flex-wrap: wrap;
+        width: 100%;
+        justify-content: space-between;
+    }
+}
+.performance-network-chart {
+    grid-column: 1 / -1;
+}
+.performance-chart-heading {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 12px;
+    flex-wrap: wrap;
+    margin-bottom: 16px;
+}
+.performance-chart-heading h3 {
+    margin: 0;
+    font-size: 16px;
+    font-weight: 600;
+}
+.performance-chart-heading > strong {
+    font-size: 15px;
+    font-weight: 500;
+    font-variant-numeric: tabular-nums;
+}
+.performance-chart-plot {
+    display: grid;
+    grid-template-columns: 5.5em minmax(0, 1fr);
+    gap: 10px;
+    height: 170px;
+}
+.performance-network-chart .performance-chart-plot {
+    height: 210px;
+}
+.performance-chart-plot.is-idle {
+    height: 96px;
+}
+.performance-chart-axis {
+    position: relative;
+    font-size: 11px;
+    color: var(--muted);
+    text-align: right;
+    font-variant-numeric: tabular-nums;
+}
+.performance-chart-axis > span {
+    position: absolute;
+    right: 0;
+    transform: translateY(-50%);
+}
+.performance-chart-axis > span:first-child {
+    top: 9.23%;
+}
+.performance-chart-axis > span:nth-child(2) {
+    top: 47.69%;
+}
+.performance-chart-axis > span:last-child {
+    top: 86.15%;
+}
+.performance-chart-plot > svg {
+    display: block;
+    height: 100%;
+    width: 100%;
+    overflow: visible;
+}
+.performance-chart-plot polyline {
+    fill: none;
+    stroke-width: 2;
+    vector-effect: non-scaling-stroke;
+    stroke-linejoin: round;
+    stroke-linecap: round;
+}
+.performance-chart-grid {
+    fill: none;
+    stroke: var(--line-subtle);
+    stroke-width: 1;
+    vector-effect: non-scaling-stroke;
+}
+.performance-chart-cursor {
+    stroke: var(--muted);
+    stroke-width: 1;
+    stroke-dasharray: 2 4;
+    vector-effect: non-scaling-stroke;
+}
+.performance-chart-point {
+    fill: var(--action);
+}
+.performance-chart-point-secondary {
+    fill: var(--muted);
+}
+.performance-chart-times {
+    display: flex;
+    justify-content: space-between;
+    gap: 10px;
+    margin-left: calc(5.5em + 10px);
+    color: var(--muted);
+    font-size: 11px;
+    font-variant-numeric: tabular-nums;
+}
+.performance-chart .performance-chart-scrubber {
+    display: block;
+}
+.performance-metric-chart .performance-chart-scrubber input[type="range"] {
+    appearance: none;
+    width: 100%;
+    border: 0;
+    padding: 0;
+    background: transparent;
+    min-height: 28px;
+    margin: 6px 0 0;
+    accent-color: var(--action);
+    cursor: pointer;
+}
+.performance-chart-scrubber input[type="range"]::-webkit-slider-runnable-track {
+    height: 2px;
+    background: var(--line);
+}
+.performance-chart-scrubber input[type="range"]::-webkit-slider-thumb {
+    appearance: none;
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    background: var(--muted);
+    margin-top: -5px;
+}
+.performance-chart-scrubber input[type="range"]::-moz-range-track {
+    height: 2px;
+    background: var(--line);
+}
+.performance-chart-scrubber input[type="range"]::-moz-range-progress {
+    height: 2px;
+    background: var(--line);
+}
+.performance-chart-scrubber input[type="range"]::-moz-range-thumb {
+    width: 12px;
+    height: 12px;
+    border: 0;
+    border-radius: 50%;
+    background: var(--muted);
+}
+.performance-chart-readout {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 8px 16px;
+    color: var(--muted);
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+}
+.performance-chart-readout strong {
+    color: var(--ink);
+    font-weight: 500;
+    margin-left: 5px;
+}
+.performance-chart-readout .text-button {
+    min-height: 32px;
+    padding: 4px 8px;
+}
+.chart-series-primary::before,
+.chart-series-secondary::before {
+    content: "";
+    display: inline-block;
+    width: 16px;
+    border-top: 2px solid var(--action);
+    margin-right: 6px;
+    vertical-align: middle;
+}
+.chart-series-secondary::before {
+    border-color: var(--muted);
+    border-top-style: dashed;
+}
+.performance-chart-note {
+    color: var(--muted);
+    font-size: 12px;
+    line-height: 1.6;
+    margin: 10px 0 0;
+    max-width: 90ch;
+}
+.performance-chart-collecting {
+    min-height: 80px;
+    display: flex;
+    align-items: center;
+    color: var(--muted);
+    font-size: 13px;
+    margin: 0;
+}
+.performance-overview-status {
+    grid-column: 1 / -1;
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 12px 28px;
+    padding-block: 18px;
+    border-block: 1px solid var(--line);
+    font-size: 13px;
+    color: var(--muted);
+}
+.performance-overview-status strong {
+    color: var(--ink);
+    font-weight: 500;
+    font-variant-numeric: tabular-nums;
+}
+.performance-overview-status > a {
+    margin-left: auto;
+}
+@media (max-width: 720px) {
+    .performance-chart-plot {
+        height: 150px;
+        grid-template-columns: 4.5em minmax(0, 1fr);
+    }
+    .performance-network-chart .performance-chart-plot {
+        height: 170px;
+    }
+    .performance-chart-plot.is-idle {
+        height: 96px;
+    }
+    .performance-chart-times {
+        margin-left: calc(4.5em + 10px);
+    }
+    .performance-overview-status {
+        gap: 10px 18px;
+    }
+    .performance-overview-status > a {
+        width: 100%;
+        margin-left: 0;
+    }
+}
+.preload-jobs,
+.cached-file-list,
+.cached-ranges {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+}
+.preload-job,
+.cached-file {
+    display: flex;
+    align-items: flex-start;
+    gap: 16px;
+    padding-block: 18px;
+    border-bottom: 1px solid var(--line);
+}
+.preload-job-copy,
+.cached-file-copy {
+    flex: 1;
+    min-width: 0;
+}
+.preload-job strong,
+.cached-file strong {
+    display: block;
+    font-size: 14px;
+    font-weight: 500;
+    overflow-wrap: anywhere;
+    line-height: 1.6;
+}
+.preload-job-copy > span {
+    display: block;
+    margin-top: 5px;
+    color: var(--muted);
+    font-size: 13px;
+}
+.preload-job progress {
+    display: block;
+    width: 100%;
+    height: 6px;
+    margin-block: 12px 8px;
+    accent-color: var(--action);
+}
+.preload-job-error {
+    display: flex;
+    align-items: flex-start;
+    gap: 8px;
+    color: var(--danger);
+    font-size: 14px;
+    line-height: 1.6;
+    overflow-wrap: anywhere;
+}
+.preload-job-error svg {
+    flex-shrink: 0;
+    margin-top: 3px;
+}
+.cached-file > svg {
+    flex-shrink: 0;
+    margin-top: 3px;
+    color: var(--muted);
+}
+.cached-file > button {
+    flex-shrink: 0;
+}
+.cache-coverage svg {
+    display: block;
+    width: 100%;
+    height: 6px;
+    margin-block: 12px 7px;
+    border-radius: 3px;
+}
+.cache-coverage-track {
+    fill: var(--line);
+}
+.cache-coverage-ready {
+    fill: var(--action);
+}
+.cache-coverage > span {
+    display: block;
+    color: var(--muted);
+    font-size: 13px;
+    font-variant-numeric: tabular-nums;
+}
+.cached-file details {
+    margin-top: 9px;
+    font-size: 13px;
+    color: var(--muted);
+}
+.cached-file summary {
+    width: fit-content;
+    min-height: 36px;
+    padding-block: 8px;
+    cursor: pointer;
+}
+.cached-ranges {
+    max-height: 180px;
+    overflow-y: auto;
+    padding-block: 8px;
+    font-variant-numeric: tabular-nums;
+}
+.cached-ranges li {
+    padding-block: 5px;
+}
+.performance-notice {
+    color: var(--muted);
+    font-size: 14px;
+    line-height: 1.6;
+}
+.performance-table-wrap {
+    overflow-x: auto;
+    border-block: 1px solid var(--line);
+}
+.performance-table {
+    width: 100%;
+    border-collapse: collapse;
+    text-align: start;
+    font-size: 14px;
+    font-variant-numeric: tabular-nums;
+}
+.performance-table :is(th, td) {
+    padding: 14px 16px;
+    border-bottom: 1px solid var(--line);
+    vertical-align: top;
+    text-align: start;
+    line-height: 1.5;
+}
+.performance-table thead th {
+    color: var(--muted);
+    font-size: 12px;
+    font-weight: 500;
+    background: var(--surface-subtle);
+}
+.performance-table tbody tr:hover {
+    background: var(--hover);
+}
+.performance-table tbody th {
+    font-weight: 500;
+    max-width: 240px;
+    overflow-wrap: anywhere;
+}
+.performance-table small {
+    display: block;
+    color: var(--muted);
+    font-size: 12px;
+    font-weight: 400;
+    margin-top: 5px;
+}
+.performance-table tr:last-child > :is(td, th) {
+    border-bottom: 0;
+}
+.performance-load-plot {
+    display: block;
+    width: 100%;
+    height: 170px;
+    margin-top: 14px;
+}
+.performance-load-plot polyline {
+    fill: none;
+    stroke-width: 2;
+    vector-effect: non-scaling-stroke;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+}
+.performance-plot-axis {
+    stroke: var(--line);
+    stroke-width: 1;
+}
+.performance-plot-active {
+    stroke: var(--action);
+}
+.performance-plot-queued {
+    stroke: var(--muted);
+    stroke-dasharray: 5 4;
+}
+.performance-plot-legend {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 22px;
+    color: var(--muted);
+    font-size: 13px;
+}
+.performance-plot-legend > span {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+}
+.performance-plot-legend > span::before {
+    content: "";
+    width: 20px;
+    border-top: 2px solid var(--action);
+}
+.performance-plot-legend > span + span::before {
+    border-color: var(--muted);
+    border-top-style: dashed;
+}
+.performance-settings :focus-visible,
+.preloads-page :focus-visible,
+.performance-page :focus-visible {
+    outline: 2px solid var(--action);
+    outline-offset: 3px;
+}
+@media (max-width: 720px) {
+    .performance-resource-summary {
+        grid-template-columns: 1fr;
+    }
+    .preloads-page .cache-budget-summary {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 16px;
+    }
+    .preloads-page .cache-budget-summary > div {
+        display: block;
+    }
+    .preloads-page .cache-budget-summary dd {
+        text-align: start;
+        margin-block: 5px;
+    }
+    .preloads-page .cache-budget-summary > div + div {
+        border-top: 0;
+        padding-top: 0;
+    }
+    .preloads-page .cache-budget-summary > div:last-child {
+        display: flex;
+        grid-column: 1 / -1;
+        align-items: baseline;
+        gap: 8px;
+    }
+    .preloads-page .cache-budget-summary > div:last-child dt {
+        display: none;
+    }
+    .preloads-page .cache-budget-summary > div:last-child small {
+        margin-left: auto;
+    }
+    :is(.preloads-page, .performance-page) > .performance-section-heading {
+        flex-wrap: nowrap;
+        align-items: center;
+    }
+    :is(.preloads-page, .performance-page)
+        > .performance-section-heading
+        > button {
+        width: 44px;
+        height: 44px;
+        padding: 0;
+    }
+    :is(.preloads-page, .performance-page)
+        > .performance-section-heading
+        > button
+        span {
+        display: none;
+    }
+    .performance-page > .performance-section-heading {
+        flex-wrap: wrap;
+        gap: 12px;
+        align-items: flex-start;
+    }
+    .performance-page > .performance-section-heading > div:first-child {
+        flex-basis: 100%;
+    }
+    .performance-page .performance-history-controls {
+        flex-wrap: nowrap;
+        align-items: flex-end;
+        width: 100%;
+    }
+    .performance-page .performance-history-controls > label {
+        display: grid;
+        flex: 1;
+        min-width: 0;
+        gap: 6px;
+    }
+    .performance-page .performance-history-controls select {
+        width: 100%;
+        min-width: 0;
+    }
+    .performance-page .performance-history-controls > button {
+        width: 44px;
+        height: 44px;
+        padding: 0;
+        flex: 0 0 44px;
+    }
+    .performance-page .performance-history-controls > button span {
+        display: none;
+    }
+    .performance-overview-grid:not([hidden]) {
+        grid-template-columns: 1fr;
+        gap: 0;
+    }
+    .performance-view-tabs {
+        gap: 0;
+    }
+    .performance-view-tabs button {
+        padding-inline: 10px;
+    }
+    .cache-inventory-toolbar {
+        align-items: stretch;
+        flex-direction: column;
+        gap: 12px;
+    }
+    .cache-search {
+        max-width: none;
+        flex: auto;
+    }
+    .cached-file-title {
+        flex-wrap: wrap;
+        gap: 2px 12px;
+    }
+    .cache-budget-summary progress {
+        grid-column: 1 / -1;
+        margin: 4px 0;
+    }
+    .performance-save-state {
+        width: 100%;
+    }
+    .performance-actions {
+        gap: 10px;
+        padding-block: 12px;
+    }
+    .performance-actions > button {
+        flex: 1 1 160px;
+    }
+    .performance-field {
+        grid-template-columns: 1fr;
+        gap: 12px;
+    }
+    .performance-field input {
+        width: 100%;
+        max-width: 100%;
+    }
+    .performance-facts {
+        grid-template-columns: 1fr;
+        gap: 14px;
+        padding-block: 14px;
+    }
+    .performance-facts > div {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+        align-items: start;
+        gap: 6px 12px;
+    }
+    .performance-facts dt {
+        margin-bottom: 0;
+    }
+    .performance-facts dd {
+        text-align: end;
+        font-size: 14px;
+    }
+    .performance-facts small {
+        grid-column: 1 / -1;
+        margin-top: 0;
+    }
+    .performance-facts > div + div {
+        border-top: 1px solid var(--line);
+        padding-top: 14px;
+    }
+    .performance-section-heading {
+        gap: 12px;
+        flex-wrap: wrap;
+    }
+    .performance-table {
+        min-width: 620px;
+    }
+    .performance-table :is(td, th) {
+        padding: 12px;
+    }
+    .preload-job {
+        gap: 10px;
+    }
+    .preload-job > button {
+        padding-inline: 10px;
+    }
+    .cached-file {
+        gap: 10px;
+    }
+    .cached-file > svg {
+        display: none;
+    }
+    .performance-actions > button {
+        min-height: 44px;
+    }
+}
+
+/* Each performance metric has one home; the shared toolbar scopes history. */
+.performance-toolbar {
+    align-items: center;
+    padding-bottom: 16px;
+    margin-block-end: 16px;
+    border-bottom: 1px solid var(--line);
+}
+.performance-toolbar .performance-view-tabs {
+    margin: 0;
+    padding: 0;
+    border: 0;
+}
+.performance-toolbar .performance-history-controls {
+    margin-inline-start: auto;
+}
+.performance-section-title {
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+}
+.performance-section-title h3 {
+    margin-bottom: 12px;
+}
+.performance-live-traffic {
+    grid-column: 1 / -1;
+    border-top: 1px solid var(--line);
+    padding-top: 24px;
+    margin-top: 0;
+}
+.performance-overview-grid .performance-live-traffic .performance-facts {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 20px 36px;
+}
+.performance-totals-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 13px;
+    font-variant-numeric: tabular-nums;
+}
+.performance-totals-table :is(th, td) {
+    text-align: end;
+    padding: 12px 0 12px 16px;
+    border-bottom: 1px solid var(--line-subtle);
+    font-weight: 400;
+}
+.performance-totals-table th:first-child {
+    text-align: start;
+    padding-left: 0;
+}
+.performance-totals-table thead th {
+    color: var(--muted);
+    font-size: 12px;
+}
+.performance-all-time > .settings-help:last-child {
+    margin-block: 12px 0;
+}
+.performance-resource-charts .performance-metric-chart {
+    padding-top: 8px;
+}
+.performance-resource-summary {
+    margin-block: 12px 20px;
+}
+.performance-cache-link {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px 16px;
+    align-items: baseline;
+    padding-bottom: 24px;
+    border-bottom: 1px solid var(--line);
+    margin-bottom: 24px;
+    font-size: 13px;
+}
+.performance-cache-link > span {
+    color: var(--muted);
+}
+.performance-memory-details {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+}
+@media (max-width: 720px) {
+    .performance-page > .performance-toolbar {
+        gap: 12px;
+    }
+    .performance-page > .performance-toolbar .performance-view-tabs {
+        flex-basis: auto;
+    }
+    .performance-toolbar[data-view="telegram"] .performance-history-controls {
+        width: auto;
+    }
+    .performance-toolbar[data-view="telegram"] .performance-view-tabs {
+        flex: 1;
+    }
+    .performance-overview-grid .performance-live-traffic .performance-facts {
+        grid-template-columns: 1fr;
+        gap: 14px;
+    }
+    .performance-memory-details {
+        grid-template-columns: 1fr;
+    }
+    .performance-totals-table :is(th, td) {
+        padding-left: 10px;
+    }
+    .performance-totals-table th:first-child {
+        padding-left: 0;
+    }
+}
+
+@media (max-width: 720px) {
+    .performance-page
+        > .performance-toolbar[data-view="telegram"]
+        > .performance-view-tabs {
+        flex: 1 1 auto;
+    }
+}
+
+.performance-history-availability {
+    margin: 0 0 16px;
+    line-height: 1.6;
+}
+.performance-chart-readout {
+    margin-top: 16px;
+    row-gap: 8px;
+}
+.performance-metric-chart .performance-chart-note {
+    margin-top: 14px;
+}
+.transfer-history
+    .transfer-category[data-category="finished"]:has(> .empty-state) {
+    border-bottom: 0;
+}
+
+.performance-accounts-grid:not([hidden]) {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 20px;
+    align-items: start;
+}
+.performance-account-section {
+    padding: 18px;
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    background: var(--surface-subtle);
+    margin: 0;
+    min-width: 0;
+}
+.performance-account-section:first-child {
+    grid-column: 1 / -1;
+}
+.performance-account-heading {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    margin-bottom: 10px;
+}
+.performance-account-heading h3 {
+    margin: 0;
+}
+.performance-account-section .performance-overview-status {
+    background: transparent;
+    border: 0;
+    padding: 0;
+    margin: 0;
+    color: var(--muted);
+    font-size: 12px;
+    gap: 14px;
+}
+.performance-overview-status strong {
+    color: var(--ink);
+}
+.performance-account-section > .settings-help {
+    margin: 8px 0 16px;
+}
+.performance-account-section .performance-empty {
+    padding: 18px 0;
+    margin: 0;
+}
+.performance-account-section .performance-table-wrap {
+    border: 0;
+    border-radius: 8px;
+}
+.performance-account-section .performance-table td,
+.performance-account-section .performance-table th {
+    padding: 12px;
+}
+.performance-chart-plot .performance-chart-tooltip {
+    z-index: 2;
+}
+.demo-data-label {
+    color: var(--warning);
+    margin-bottom: 10px;
+}
+@media (max-width: 960px) {
+    .performance-accounts-grid:not([hidden]) {
+        grid-template-columns: 1fr;
+    }
+}
diff --git a/website/src/features/performance/PerformancePanel.tsx b/website/src/features/performance/PerformancePanel.tsx
new file mode 100644
index 00000000..94a0b63a
--- /dev/null
+++ b/website/src/features/performance/PerformancePanel.tsx
@@ -0,0 +1,1758 @@
+import { Tabs, Paper } from "@mantine/core";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { RefreshCw } from "lucide-react";
+import { errorMessage } from "../../shared/api";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import { formatBytes, formatTimestamp, getTimezone } from "../../shared/types";
+import StreamMemoryFact from "./StreamMemoryFact";
+import { cachedFileComplete } from "./Preloads";
+import { useManualRefresh } from "../../shared/useManualRefresh";
+import {
+    performanceApi,
+    type LoadSample,
+    type PerformanceSnapshot,
+    type TrafficSample,
+    type ResourceSample,
+    type PerformanceHistory,
+} from "./performanceApi";
+import "./Performance.css";
+
+type MetricKey =
+    | "cpu_percent"
+    | "memory_bytes"
+    | "received_bytes_per_second"
+    | "sent_bytes_per_second";
+type MetricSeries = { key: MetricKey; label: string; secondary?: boolean };
+export function metricSegments(
+    samples: ResourceSample[],
+    key: MetricKey,
+    maximum: number,
+    scope?: "cpu_scope" | "network_interface",
+    maxGapSeconds = 30,
+): string[] {
+    const first = samples[0]?.at || 0,
+        last = samples.at(-1)?.at || first;
+    const segments: string[] = [];
+    let current: string[] = [],
+        previous: ResourceSample | undefined;
+    const flush = () => {
+        if (current.length) segments.push(current.join(" "));
+        current = [];
+        previous = undefined;
+    };
+    for (const sample of samples) {
+        const value = sample[key];
+        if (
+            value === null ||
+            !Number.isFinite(value) ||
+            value < 0 ||
+            !Number.isFinite(sample.at)
+        ) {
+            flush();
+            continue;
+        }
+        if (
+            previous &&
+            (sample.at <= previous.at ||
+                sample.at - previous.at > maxGapSeconds ||
+                (scope && sample[scope] !== previous[scope]))
+        )
+            flush();
+        current.push(
+            (last === first ? 1 : (sample.at - first) / (last - first)) * 600 +
+                "," +
+                (112 - Math.min(1, value / Math.max(1, maximum)) * 100),
+        );
+        previous = sample;
+    }
+    flush();
+    return segments;
+}
+export function metricCeiling(value: number): number {
+    if (!Number.isFinite(value) || value <= 0) return 0;
+    const unit =
+        1024 ** Math.max(0, Math.floor(Math.log(value) / Math.log(1024)));
+    return (
+        ([1, 2, 5, 10, 20, 50, 100, 200, 500, 1024].find(
+            (step) => step * unit >= value,
+        ) || 1024) * unit
+    );
+}
+function metricTime(at: number) {
+    return formatTimestamp(at);
+}
+function MetricChart({
+    title,
+    samples,
+    series,
+    maximum,
+    format,
+    scope,
+    current,
+    note,
+    windowSeconds,
+    bucketSeconds = 3,
+    historical = false,
+}: {
+    title: string;
+    samples: ResourceSample[];
+    series: MetricSeries[];
+    maximum: number;
+    format: (value: number) => string;
+    scope?: "cpu_scope" | "network_interface";
+    current: string;
+    note: string;
+    windowSeconds: number;
+    bucketSeconds?: number;
+    historical?: boolean;
+}) {
+    const [selectedAt, setSelectedAt] = useState<number | null>(null);
+    const [hoverAt, setHoverAt] = useState<number | null>(null);
+    const [hoverPosition, setHoverPosition] = useState({ left: 8, top: 8 });
+    const tooltip = useRef<HTMLDivElement>(null);
+    useEffect(() => setHoverAt(null), [windowSeconds]);
+    const inspectedAt = hoverAt ?? selectedAt;
+    const found =
+        inspectedAt === null
+            ? -1
+            : samples.findIndex((sample) => sample.at >= inspectedAt);
+    const index = found < 0 ? samples.length - 1 : found;
+    const selected = samples[index];
+    const available = samples.some((sample) =>
+        series.some(({ key }) => typeof sample[key] === "number"),
+    );
+    const quiet =
+        available &&
+        samples.every((sample) =>
+            series.every(
+                ({ key }) => sample[key] === null || sample[key] === 0,
+            ),
+        );
+    const first = samples[0]?.at || 0,
+        last = samples.at(-1)?.at || first;
+    const x =
+        selected && last > first
+            ? ((selected.at - first) / (last - first)) * 600
+            : 600;
+    return (
+        <Paper
+            component="section"
+            className={
+                "performance-metric-chart" +
+                (series.length > 1 ? " performance-network-chart" : "")
+            }
+            aria-label={title}
+            data-metric={series[0]?.key}
+        >
+            <div className="performance-chart-heading">
+                <h3>{title}</h3>
+                <strong title="Current reading">
+                    {current}
+                    <small className="performance-chart-now">Now</small>
+                </strong>
+            </div>
+            {series.length > 1 && (
+                <div className="performance-chart-legend">
+                    {series.map(({ key, label, secondary }) => (
+                        <span
+                            key={key}
+                            className={
+                                secondary
+                                    ? "chart-series-secondary"
+                                    : "chart-series-primary"
+                            }
+                        >
+                            {label}
+                        </span>
+                    ))}
+                </div>
+            )}
+            {(samples.length >= 2 || (historical && samples.length === 1)) &&
+            available ? (
+                <>
+                    <div
+                        className={
+                            "performance-chart-plot" + (quiet ? " is-idle" : "")
+                        }
+                    >
+                        <div
+                            className="performance-chart-axis"
+                            aria-hidden="true"
+                        >
+                            {maximum > 0 && (
+                                <>
+                                    <span>{format(maximum)}</span>
+                                    <span>{format(maximum / 2)}</span>
+                                </>
+                            )}
+                            <span>{format(0)}</span>
+                        </div>
+                        <svg
+                            viewBox="0 0 600 130"
+                            preserveAspectRatio="none"
+                            role="img"
+                            aria-label={title + " over time"}
+                            onPointerMove={(event) => {
+                                if (event.pointerType !== "mouse") return;
+                                const bounds =
+                                    event.currentTarget.getBoundingClientRect();
+                                const position = Math.max(
+                                    0,
+                                    Math.min(
+                                        1,
+                                        (event.clientX - bounds.left) /
+                                            bounds.width,
+                                    ),
+                                );
+                                const target =
+                                    first + position * (last - first);
+                                const nearest = nearestSampleAt(
+                                    samples,
+                                    target,
+                                );
+                                const plot =
+                                    event.currentTarget.parentElement!.getBoundingClientRect();
+                                const width =
+                                    tooltip.current?.offsetWidth ??
+                                    Math.min(280, plot.width - 16);
+                                const height =
+                                    tooltip.current?.offsetHeight ?? 90;
+                                const pointerX = event.clientX - plot.left;
+                                const pointerY = event.clientY - plot.top;
+                                setHoverPosition({
+                                    left: Math.max(
+                                        8,
+                                        Math.min(
+                                            plot.width - width - 8,
+                                            pointerX + width + 16 < plot.width
+                                                ? pointerX + 14
+                                                : pointerX - width - 14,
+                                        ),
+                                    ),
+                                    top: Math.max(
+                                        8,
+                                        Math.min(
+                                            plot.height - height - 8,
+                                            pointerY + 16,
+                                        ),
+                                    ),
+                                });
+                                setHoverAt(nearest);
+                            }}
+                            onPointerLeave={() => setHoverAt(null)}
+                        >
+                            <desc>
+                                {note +
+                                    " Missing readings and interruptions are left as gaps."}
+                            </desc>
+                            <path
+                                d="M0 12H600 M0 62H600 M0 112H600"
+                                className="performance-chart-grid"
+                            />
+                            {series.flatMap(({ key, secondary }) =>
+                                metricSegments(
+                                    samples,
+                                    key,
+                                    maximum,
+                                    scope,
+                                    Math.max(30, bucketSeconds * 1.5),
+                                ).map((points, part) => (
+                                    <polyline
+                                        key={key + part}
+                                        points={points}
+                                        className={
+                                            secondary
+                                                ? "performance-plot-queued"
+                                                : "performance-plot-active"
+                                        }
+                                    />
+                                )),
+                            )}
+                            {series.flatMap(({ key, secondary }) =>
+                                samples.flatMap((sample, sampleIndex) => {
+                                    const value = sample[key];
+                                    return value === null ||
+                                        !Number.isFinite(value) ||
+                                        value < 0
+                                        ? []
+                                        : [
+                                              <circle
+                                                  key={key + ":" + sampleIndex}
+                                                  cx={
+                                                      (last === first
+                                                          ? 1
+                                                          : (sample.at -
+                                                                first) /
+                                                            (last - first)) *
+                                                      600
+                                                  }
+                                                  cy={
+                                                      112 -
+                                                      Math.min(
+                                                          1,
+                                                          value /
+                                                              Math.max(
+                                                                  1,
+                                                                  maximum,
+                                                              ),
+                                                      ) *
+                                                          100
+                                                  }
+                                                  r={2}
+                                                  className={
+                                                      secondary
+                                                          ? "performance-chart-point-secondary"
+                                                          : "performance-chart-point"
+                                                  }
+                                              />,
+                                          ];
+                                }),
+                            )}
+                            {selected && (
+                                <path
+                                    d={"M" + x + " 8V116"}
+                                    className="performance-chart-cursor"
+                                />
+                            )}
+                        </svg>
+                        {hoverAt !== null && selected && (
+                            <div
+                                ref={tooltip}
+                                className="performance-chart-tooltip"
+                                aria-hidden="true"
+                                style={hoverPosition}
+                            >
+                                <time>{metricTime(selected.at)}</time>
+                                {series.map(({ key, label }) => (
+                                    <span key={key}>
+                                        {label}:{" "}
+                                        {selected[key] === null
+                                            ? "No reading"
+                                            : format(selected[key])}
+                                    </span>
+                                ))}
+                            </div>
+                        )}
+                    </div>
+                    <div className="performance-chart-times">
+                        <span>
+                            {historical
+                                ? metricTime(first)
+                                : historyDuration(last - first) + " ago"}
+                        </span>
+                        <span>
+                            {historical ? metricTime(last) : "Latest reading"}
+                        </span>
+                    </div>
+                    <label className="performance-chart-scrubber">
+                        <span className="sr-only">
+                            {"Inspect " + title + " samples"}
+                        </span>
+                        <input
+                            type="range"
+                            disabled={samples.length < 2}
+                            min={0}
+                            max={samples.length - 1}
+                            value={Math.max(0, index)}
+                            onChange={(event) => {
+                                setHoverAt(null);
+                                setSelectedAt(
+                                    samples[Number(event.target.value)].at,
+                                );
+                            }}
+                            aria-valuetext={
+                                selected
+                                    ? metricTime(selected.at) +
+                                      ": " +
+                                      series
+                                          .map(
+                                              ({ key, label }) =>
+                                                  label +
+                                                  " " +
+                                                  (selected[key] === null
+                                                      ? "no reading"
+                                                      : format(selected[key])),
+                                          )
+                                          .join(", ")
+                                    : "No reading"
+                            }
+                        />
+                    </label>
+                    <div className="performance-chart-readout">
+                        <time
+                            dateTime={
+                                selected
+                                    ? new Date(selected.at * 1000).toISOString()
+                                    : undefined
+                            }
+                        >
+                            {selected ? metricTime(selected.at) : ""}
+                        </time>
+                        {scope && selected?.[scope] && (
+                            <span>
+                                {scope === "cpu_scope"
+                                    ? selected.cpu_scope === "cgroup"
+                                        ? "Container reading"
+                                        : "Host reading"
+                                    : "Interface " + selected.network_interface}
+                            </span>
+                        )}
+                        {series.map(({ key, label, secondary }) => (
+                            <span
+                                key={key}
+                                className={
+                                    secondary
+                                        ? "chart-series-secondary"
+                                        : "chart-series-primary"
+                                }
+                            >
+                                {label}{" "}
+                                <strong>
+                                    {selected && selected[key] !== null
+                                        ? format(selected[key])
+                                        : "No reading"}
+                                </strong>
+                            </span>
+                        ))}
+                        {selectedAt !== null && (
+                            <button
+                                type="button"
+                                className="text-button"
+                                onClick={() => setSelectedAt(null)}
+                            >
+                                Live
+                            </button>
+                        )}
+                    </div>
+                </>
+            ) : (
+                <p className="performance-chart-collecting">
+                    {historical
+                        ? "No recorded readings in this range."
+                        : available
+                          ? "Collecting the next reading…"
+                          : "No history yet. Readings appear as the server samples activity."}
+                </p>
+            )}
+            <p className="performance-chart-note">
+                {quiet ? "Idle during this observed window. " : ""}
+                {note}
+            </p>
+        </Paper>
+    );
+}
+
+const HISTORY_WINDOW_KEY = "tgdrive-performance-range";
+type HistoryRange = "live" | "hour" | "day" | "week" | "month" | "custom";
+const HISTORY_RANGES = {
+    live: 300,
+    hour: 3600,
+    day: 86400,
+    week: 7 * 86400,
+    month: 30 * 86400,
+    custom: 31 * 86400,
+};
+export function historyDuration(seconds: number): string {
+    const rounded = Math.max(0, Math.floor(seconds));
+    for (const [unit, suffix, nextUnit, nextSuffix] of [
+        [86400, "day", 3600, "hr"],
+        [3600, "hr", 60, "min"],
+        [60, "min", 1, "sec"],
+    ] as const) {
+        if (rounded >= unit) {
+            const count = Math.floor(rounded / unit),
+                rest = Math.floor((rounded % unit) / nextUnit);
+            return (
+                count +
+                " " +
+                suffix +
+                (suffix === "day" && count !== 1 ? "s" : "") +
+                (rest ? " " + rest + " " + nextSuffix : "")
+            );
+        }
+    }
+    return rounded + " sec";
+}
+export function samplesInWindow<T extends { at: number }>(
+    samples: T[],
+    seconds: number,
+): T[] {
+    const end = samples.at(-1)?.at;
+    if (end === undefined || !Number.isFinite(end)) return [];
+    return samples.filter(
+        (sample) =>
+            Number.isFinite(sample.at) &&
+            sample.at >= end - seconds &&
+            sample.at <= end,
+    );
+}
+export function nearestSampleAt<T extends { at: number }>(
+    samples: T[],
+    target: number,
+): number | null {
+    return samples.reduce<number | null>(
+        (nearest, sample) =>
+            Number.isFinite(sample.at) &&
+            (nearest === null ||
+                Math.abs(sample.at - target) < Math.abs(nearest - target))
+                ? sample.at
+                : nearest,
+        null,
+    );
+}
+export function customHistoryBounds(
+    startText: string,
+    endText: string,
+    now = Date.now() / 1000,
+) {
+    const parse = (text: string) => {
+        const value = Date.parse(text + "Z") / 1000;
+        if (
+            !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(text) ||
+            !Number.isFinite(value) ||
+            new Date(value * 1000).toISOString().slice(0, 16) !== text
+        )
+            throw new Error("Choose valid start and end dates in UTC.");
+        return value;
+    };
+    const start = parse(startText),
+        end = parse(endText);
+    if (end <= start) throw new Error("End must be after start.");
+    if (end - start > 31 * 86400)
+        throw new Error("Choose a range of at most 31 days.");
+    if (end > now + 60) throw new Error("End cannot be in the future.");
+    if (start < now - 31 * 86400)
+        throw new Error(
+            "Recorded history is retained for 31 days. Choose a more recent start.",
+        );
+    return { start, end };
+}
+function savedHistoryRange(): HistoryRange {
+    try {
+        const value = window.localStorage.getItem(HISTORY_WINDOW_KEY);
+        if (value && ["live", "hour", "day", "week", "month"].includes(value))
+            return value as HistoryRange;
+    } catch {
+        /* Browser storage can be unavailable. */
+    }
+    return "live";
+}
+
+/** Charts show a recent continuous window, never a line across a polling gap. */
+export function recentSamples<T extends { at: number }>(
+    samples: T[],
+    seconds = 300,
+): T[] {
+    const end = samples.at(-1)?.at;
+    if (end === undefined || !Number.isFinite(end)) return [];
+    let start = samples.length - 1;
+    while (start > 0) {
+        const gap = samples[start].at - samples[start - 1].at;
+        if (
+            !Number.isFinite(gap) ||
+            gap <= 0 ||
+            gap > 30 ||
+            end - samples[start - 1].at > seconds
+        )
+            break;
+        start--;
+    }
+    return samples.slice(start);
+}
+
+export function UsageMeter({
+    label,
+    used,
+    total,
+    detail,
+    percent = false,
+    unavailableLabel = "Unavailable",
+}: {
+    label: string;
+    used: number;
+    total: number;
+    detail?: string;
+    percent?: boolean;
+    unavailableLabel?: string;
+}) {
+    const valid = Number.isFinite(used) && Number.isFinite(total) && total > 0;
+    const bounded = valid ? Math.min(total, Math.max(0, used)) : 0;
+    return (
+        <div className="performance-usage">
+            <div>
+                <span>{label}</span>
+                <strong>
+                    {valid
+                        ? percent
+                            ? Math.max(0, used).toFixed(1) + "%"
+                            : formatBytes(Math.max(0, used)) +
+                              " / " +
+                              formatBytes(total)
+                        : total === 0 && used === 0
+                          ? "Disabled"
+                          : unavailableLabel}
+                </strong>
+            </div>
+            {valid && (
+                <progress aria-label={label} value={bounded} max={total} />
+            )}
+            {detail && <small>{detail}</small>}
+        </div>
+    );
+}
+
+export function queueWait(seconds: number | null | undefined): string {
+    if (seconds === null || seconds === undefined || !Number.isFinite(seconds))
+        return "Estimating…";
+    if (seconds < 1) return "Less than 1s";
+    if (seconds < 60) return "About " + Math.ceil(seconds) + "s";
+    return "About " + Math.ceil(seconds / 60) + "m";
+}
+export function httpRates(history: TrafficSample[]): LoadSample[] {
+    const rates: LoadSample[] = [];
+    for (let index = 1; index < history.length; index++) {
+        const previous = history[index - 1],
+            current = history[index];
+        const seconds = current.at - previous.at;
+        if (
+            seconds <= 0 ||
+            seconds > 30 ||
+            !Number.isFinite(seconds) ||
+            current.download_bytes < previous.download_bytes ||
+            current.upload_bytes < previous.upload_bytes
+        )
+            continue;
+        rates.push({
+            at: current.at,
+            active:
+                (current.download_bytes - previous.download_bytes) / seconds,
+            queued: (current.upload_bytes - previous.upload_bytes) / seconds,
+        });
+    }
+    return rates;
+}
+export function loadPoints(
+    samples: LoadSample[],
+    key: "active" | "queued",
+    max: number,
+): string {
+    const valid = samples.filter(
+        (sample) => Number.isFinite(sample[key]) && Number.isFinite(sample.at),
+    );
+    if (!valid.length) return "";
+    const first = valid[0].at;
+    const duration = valid[valid.length - 1].at - first;
+    return valid
+        .map(
+            (sample) =>
+                (duration <= 0 ? 0 : ((sample.at - first) / duration) * 600) +
+                "," +
+                (120 - (Math.max(0, sample[key]) / Math.max(1, max)) * 110),
+        )
+        .join(" ");
+}
+export default function PerformancePanel({
+    onNotice,
+}: {
+    onNotice?: (message: string, error?: boolean) => void;
+} = {}) {
+    const [snapshot, setSnapshot] = useState<PerformanceSnapshot | null>(null);
+    const [error, setError] = useState("");
+    const [loading, setLoading] = useState(true);
+    const [range, setRange] = useState<HistoryRange>(savedHistoryRange);
+    const [customStart, setCustomStart] = useState(() =>
+        new Date(Date.now() - 86400000).toISOString().slice(0, 16),
+    );
+    const [customEnd, setCustomEnd] = useState(() =>
+        new Date().toISOString().slice(0, 16),
+    );
+    const [customBounds, setCustomBounds] = useState<{
+        start: number;
+        end: number;
+    } | null>(null);
+    const [customError, setCustomError] = useState("");
+    const [recorded, setRecorded] = useState<PerformanceHistory | null>(null);
+    const [historyLoading, setHistoryLoading] = useState(false);
+    const [historyError, setHistoryError] = useState("");
+    const [loadedRange, setLoadedRange] = useState("");
+    const rangeKey = range === "custom" ? JSON.stringify(customBounds) : range;
+    const windowSeconds =
+        range === "custom" && customBounds
+            ? customBounds.end - customBounds.start
+            : HISTORY_RANGES[range];
+    const historical = range !== "live";
+    const [view, setView] = useState<"overview" | "telegram" | "server">(
+        "overview",
+    );
+    const latestSnapshot = useRef(0);
+    const latestHistory = useRef(0);
+    const manualLoading = useRef(false);
+    const { refreshing, run } = useManualRefresh(onNotice);
+    const loadSnapshot = useCallback(
+        async (signal: AbortSignal, manual = false) => {
+            if (!manual && manualLoading.current) return false;
+            const request = ++latestSnapshot.current;
+            try {
+                const value = await performanceApi.snapshot(signal);
+                if (signal.aborted || request !== latestSnapshot.current)
+                    return false;
+                setSnapshot(value);
+                setError("");
+                return true;
+            } catch (cause) {
+                if (!signal.aborted && request === latestSnapshot.current)
+                    setError(errorMessage(cause));
+                if (manual) throw cause;
+                return false;
+            } finally {
+                if (!signal.aborted && request === latestSnapshot.current)
+                    setLoading(false);
+            }
+        },
+        [],
+    );
+    const loadHistory = useCallback(
+        async (signal: AbortSignal, manual = false) => {
+            if (!manual && manualLoading.current) return false;
+            const request = ++latestHistory.current;
+            if (range === "custom" && !customBounds) {
+                setHistoryError("");
+                setHistoryLoading(false);
+                return true;
+            }
+            setHistoryLoading(true);
+            if (!manual) setHistoryError("");
+            const end =
+                range === "custom"
+                    ? customBounds!.end
+                    : Math.floor(Date.now() / 1000);
+            const start =
+                range === "custom"
+                    ? customBounds!.start
+                    : end - HISTORY_RANGES[range];
+            try {
+                const data = await performanceApi.history(start, end, signal);
+                if (signal.aborted || request !== latestHistory.current)
+                    return false;
+                setRecorded(data);
+                setLoadedRange(rangeKey);
+                setHistoryError("");
+                return true;
+            } catch (cause) {
+                if (!signal.aborted && request === latestHistory.current)
+                    setHistoryError(errorMessage(cause));
+                if (manual) throw cause;
+                return false;
+            } finally {
+                if (!signal.aborted && request === latestHistory.current)
+                    setHistoryLoading(false);
+            }
+        },
+        [range, customBounds, rangeKey],
+    );
+    const refreshPerformance = () =>
+        void run(async (signal) => {
+            manualLoading.current = true;
+            try {
+                const results = await Promise.allSettled([
+                    loadSnapshot(signal, true),
+                    loadHistory(signal, true),
+                ]);
+                for (const result of results)
+                    if (result.status === "rejected") throw result.reason;
+                return results.every(
+                    (result) => result.status === "fulfilled" && result.value,
+                );
+            } finally {
+                manualLoading.current = false;
+            }
+        }, "Performance refreshed.");
+    useEffect(() => {
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            await loadSnapshot(controller.signal);
+            if (!controller.signal.aborted)
+                timer = setTimeout(poll, document.hidden ? 15000 : 3000);
+        };
+        void poll();
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [loadSnapshot]);
+    useEffect(() => {
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            await loadHistory(controller.signal);
+            if (!controller.signal.aborted && range !== "custom")
+                timer = setTimeout(poll, 60000);
+        };
+        void poll();
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [range, loadHistory]);
+    const telegram = snapshot?.telegram;
+    const history = recentSamples(telegram?.history || [], 300);
+    const ceiling = Math.max(
+        1,
+        ...history.flatMap((sample) => [sample.active, sample.queued]),
+    );
+    const traffic = snapshot?.traffic;
+    const rates = httpRates(
+        recentSamples(traffic?.history || [], windowSeconds),
+    );
+    const latestRate = rates.at(-1);
+    const rateFresh =
+        latestRate && Math.abs(Date.now() / 1000 - latestRate.at) <= 30;
+    const sendRate =
+        traffic?.download_bytes_per_second ??
+        (rateFresh ? latestRate.active : null);
+    const receiveRate =
+        traffic?.upload_bytes_per_second ??
+        (rateFresh ? latestRate.queued : null);
+    const downloads =
+        telegram?.accounts.reduce(
+            (sum, account) => sum + account.downloads,
+            0,
+        ) || 0;
+    const uploads =
+        telegram?.accounts.reduce((sum, account) => sum + account.uploads, 0) ||
+        0;
+    const hasTelegramActivity = history.some(
+        (sample) => sample.active > 0 || sample.queued > 0,
+    );
+    const memory = snapshot?.server.memory;
+    const memoryUsed = memory?.cgroup_current ?? NaN;
+    const network = snapshot?.server.network;
+    const cpu = snapshot?.server.cpu;
+    const resourceHistory = historical
+        ? range === "custom" && !customBounds
+            ? []
+            : recorded?.samples || []
+        : samplesInWindow(snapshot?.server.history || [], 300);
+    const networkCeiling = metricCeiling(
+        Math.max(
+            0,
+            ...resourceHistory.flatMap((sample) => [
+                sample.received_bytes_per_second || 0,
+                sample.sent_bytes_per_second || 0,
+            ]),
+        ),
+    );
+    const memoryLimit = memory?.cgroup_limit || 0;
+    const memoryCeiling =
+        memoryLimit > 0
+            ? Math.max(
+                  memoryLimit,
+                  ...resourceHistory.map(
+                      (sample) => sample.memory_limit_bytes || 0,
+                  ),
+                  ...resourceHistory.map((sample) => sample.memory_bytes || 0),
+              )
+            : metricCeiling(
+                  Math.max(
+                      0,
+                      ...resourceHistory.map(
+                          (sample) => sample.memory_bytes || 0,
+                      ),
+                  ),
+              );
+    const networkRate = (value: number | null | undefined) =>
+        typeof value === "number" ? formatBytes(value) + "/s" : "Measuring…";
+    return (
+        <Tabs
+            className="performance-page page-body"
+            id="performance"
+            value={view}
+            onChange={(value) => {
+                if (
+                    value === "overview" ||
+                    value === "telegram" ||
+                    value === "server"
+                )
+                    setView(value);
+            }}
+        >
+            <div
+                className="performance-section-heading performance-toolbar"
+                data-view={view}
+            >
+                <Tabs.List
+                    className="performance-view-tabs"
+                    aria-label="Performance views"
+                >
+                    <Tabs.Tab value="overview">Overview</Tabs.Tab>
+                    <Tabs.Tab value="telegram">Accounts</Tabs.Tab>
+                    <Tabs.Tab value="server">Resources</Tabs.Tab>
+                </Tabs.List>
+                <div className="performance-history-controls">
+                    <label hidden={view === "telegram"}>
+                        Time range
+                        <select
+                            aria-label="Time range"
+                            disabled={refreshing}
+                            value={range}
+                            onChange={(event) => {
+                                const value = event.target
+                                    .value as HistoryRange;
+                                setRange(value);
+                                setCustomError("");
+                                try {
+                                    if (value !== "custom")
+                                        window.localStorage.setItem(
+                                            HISTORY_WINDOW_KEY,
+                                            value,
+                                        );
+                                } catch {
+                                    /* Keep working without storage. */
+                                }
+                            }}
+                        >
+                            <option value="live">Live (5 min)</option>
+                            <option value="hour">Last hour</option>
+                            <option value="day">Last 24 hours</option>
+                            <option value="week">Last 7 days</option>
+                            <option value="month">Last month (30 days)</option>
+                            <option value="custom">Custom range</option>
+                        </select>
+                    </label>
+                    <button
+                        className="secondary-button"
+                        disabled={refreshing}
+                        aria-busy={refreshing}
+                        onClick={refreshPerformance}
+                        aria-label="Refresh Performance"
+                    >
+                        {refreshing ? <Spinner /> : <RefreshCw size={16} />}
+                        <span>{refreshing ? "Refreshing…" : "Refresh"}</span>
+                    </button>
+                </div>
+            </div>
+            {range === "custom" && (
+                <form
+                    className="performance-custom-range"
+                    hidden={view === "telegram"}
+                    onSubmit={(event) => {
+                        event.preventDefault();
+                        try {
+                            setCustomBounds(
+                                customHistoryBounds(customStart, customEnd),
+                            );
+                            setCustomError("");
+                        } catch (cause) {
+                            setCustomError(errorMessage(cause));
+                        }
+                    }}
+                >
+                    <label>
+                        Start (UTC)
+                        <input
+                            type="datetime-local"
+                            required
+                            value={customStart}
+                            onChange={(event) =>
+                                setCustomStart(event.target.value)
+                            }
+                        />
+                    </label>
+                    <label>
+                        End (UTC)
+                        <input
+                            type="datetime-local"
+                            required
+                            value={customEnd}
+                            onChange={(event) =>
+                                setCustomEnd(event.target.value)
+                            }
+                        />
+                    </label>
+                    <button
+                        className="secondary-button"
+                        type="submit"
+                        disabled={refreshing}
+                    >
+                        Apply Range
+                    </button>
+                    <p className="settings-help">
+                        Enter UTC times. Chart timestamps use {getTimezone()}.
+                        Up to 31 days; gaps mean no readings were recorded.
+                    </p>
+                    {customBounds && (
+                        <p className="settings-help">
+                            Applied: {formatTimestamp(customBounds.start)} –{" "}
+                            {formatTimestamp(customBounds.end)} ({getTimezone()}
+                            )
+                        </p>
+                    )}
+                    <ErrorNotice message={customError} />
+                </form>
+            )}
+            {view !== "telegram" && historyLoading && historical && (
+                <p className="performance-history-status" role="status">
+                    <Spinner /> Loading selected history…
+                    {recorded && loadedRange !== rangeKey
+                        ? " Previous range remains visible until it is ready."
+                        : ""}
+                </p>
+            )}
+            {view !== "telegram" && historyError && (
+                <div className="performance-history-error">
+                    <ErrorNotice
+                        message={
+                            (historical && recorded
+                                ? "Showing previously loaded history. "
+                                : "") + historyError
+                        }
+                    />
+                    <button
+                        type="button"
+                        className="text-button"
+                        disabled={refreshing}
+                        aria-busy={refreshing}
+                        onClick={refreshPerformance}
+                    >
+                        {refreshing && <Spinner />}
+                        {refreshing ? "Refreshing…" : "Retry History"}
+                    </button>
+                </div>
+            )}
+            {loading && (
+                <p className="performance-loading" role="status">
+                    <Spinner /> Loading server performance…
+                </p>
+            )}
+            <ErrorNotice message={error} />
+            {snapshot && telegram && (
+                <>
+                    <p
+                        className="performance-history-availability"
+                        hidden={view === "telegram"}
+                    >
+                        {historical
+                            ? recorded && loadedRange === rangeKey
+                                ? `Recorded interval averages (${historyDuration(recorded.bucket_seconds)} per point). Current values marked Now stay live. ${recorded.samples.some((sample) => sample.cpu_percent !== null || sample.memory_bytes !== null || sample.received_bytes_per_second !== null || sample.sent_bytes_per_second !== null) ? `Available history begins ${formatTimestamp(recorded.earliest_at)}.` : "No readings were recorded for this range."}`
+                                : range === "custom" && !customBounds
+                                  ? "Choose dates and apply a range to inspect recorded history."
+                                  : "Selected range has not loaded yet."
+                            : resourceHistory.length > 1
+                              ? `Showing ${historyDuration(resourceHistory.at(-1)!.at - resourceHistory[0].at)} of collected live history; up to 5 min selected.`
+                              : "Collecting live history; earlier readings are not available yet."}
+                    </p>
+                    <Tabs.Panel
+                        value="overview"
+                        className="performance-overview-grid"
+                    >
+                        <MetricChart
+                            windowSeconds={windowSeconds}
+                            historical={historical}
+                            bucketSeconds={
+                                historical ? recorded?.bucket_seconds || 60 : 3
+                            }
+                            title="Network traffic"
+                            samples={resourceHistory}
+                            series={[
+                                {
+                                    key: "received_bytes_per_second",
+                                    label: "Download to server",
+                                },
+                                {
+                                    key: "sent_bytes_per_second",
+                                    label: "Upload from server",
+                                    secondary: true,
+                                },
+                            ]}
+                            maximum={networkCeiling}
+                            format={(value) => formatBytes(value) + "/s"}
+                            scope="network_interface"
+                            current={
+                                "Download " +
+                                networkRate(
+                                    network?.received_bytes_per_second,
+                                ) +
+                                " · Upload " +
+                                networkRate(network?.sent_bytes_per_second)
+                            }
+                            note={
+                                "Includes Telegram, URL downloads, device uploads and viewer downloads" +
+                                (network?.interface
+                                    ? " on " + network.interface
+                                    : "") +
+                                "."
+                            }
+                        />
+                        {traffic && (
+                            <section
+                                className="performance-section performance-live-traffic"
+                                aria-labelledby="http-traffic-heading"
+                            >
+                                <div className="performance-section-title">
+                                    <h3 id="http-traffic-heading">
+                                        Live file transfers
+                                    </h3>
+                                    <span className="performance-chart-now">
+                                        Now
+                                    </span>
+                                </div>
+                                <dl className="performance-facts">
+                                    <div>
+                                        <dt>Downloads to viewers</dt>
+                                        <dd>
+                                            {typeof sendRate === "number"
+                                                ? formatBytes(sendRate) + "/s"
+                                                : "Measuring…"}
+                                        </dd>
+                                    </div>
+                                    <div>
+                                        <dt>Uploads from devices</dt>
+                                        <dd>
+                                            {typeof receiveRate === "number"
+                                                ? formatBytes(receiveRate) +
+                                                  "/s"
+                                                : "Measuring…"}
+                                        </dd>
+                                    </div>
+                                    <div>
+                                        <dt>Active requests</dt>
+                                        <dd>
+                                            {traffic.active.toLocaleString()}
+                                        </dd>
+                                    </div>
+                                    <div>
+                                        <dt>Failed requests this session</dt>
+                                        <dd>
+                                            {traffic.errors.toLocaleString()}
+                                        </dd>
+                                    </div>
+                                </dl>
+                                <p className="settings-help">
+                                    TGDrive file endpoints, including cached
+                                    downloads. These live readings are
+                                    independent of the chart time range.
+                                </p>
+                            </section>
+                        )}
+                        {recorded && (
+                            <section
+                                className="performance-all-time"
+                                aria-labelledby="all-time-heading"
+                            >
+                                <h3 id="all-time-heading">All-time totals</h3>
+                                <p className="settings-help">
+                                    {recorded.tracked_since
+                                        ? `Since ${formatTimestamp(recorded.tracked_since)}.`
+                                        : "Tracking has just started."}{" "}
+                                    Totals survive restart and are independent
+                                    of the time range.
+                                </p>
+                                <table className="performance-totals-table">
+                                    <thead>
+                                        <tr>
+                                            <th scope="col">Traffic source</th>
+                                            <th scope="col">
+                                                Received by server
+                                            </th>
+                                            <th scope="col">Sent by server</th>
+                                        </tr>
+                                    </thead>
+                                    <tbody>
+                                        {(
+                                            [
+                                                [
+                                                    "Server network",
+                                                    recorded.totals
+                                                        .network_received_bytes,
+                                                    recorded.totals
+                                                        .network_sent_bytes,
+                                                ],
+                                                [
+                                                    "TGDrive files",
+                                                    recorded.totals
+                                                        .http_upload_bytes,
+                                                    recorded.totals
+                                                        .http_download_bytes,
+                                                ],
+                                                [
+                                                    "Telegram",
+                                                    recorded.totals
+                                                        .telegram_download_bytes,
+                                                    recorded.totals
+                                                        .telegram_upload_bytes,
+                                                ],
+                                            ] as const
+                                        ).map(([label, received, sent]) => (
+                                            <tr key={label}>
+                                                <th scope="row">{label}</th>
+                                                <td>
+                                                    {typeof received ===
+                                                    "number"
+                                                        ? formatBytes(received)
+                                                        : "Not available"}
+                                                </td>
+                                                <td>
+                                                    {typeof sent === "number"
+                                                        ? formatBytes(sent)
+                                                        : "Not available"}
+                                                </td>
+                                            </tr>
+                                        ))}
+                                    </tbody>
+                                </table>
+                                <p className="settings-help">
+                                    Network includes Telegram, URL imports and
+                                    device traffic. The rows overlap; do not add
+                                    them together. Usage before tracking began
+                                    is not included.
+                                </p>
+                            </section>
+                        )}
+                    </Tabs.Panel>
+                    <Tabs.Panel
+                        value="telegram"
+                        className="performance-accounts-grid"
+                    >
+                        <section
+                            className="performance-section performance-account-section"
+                            aria-labelledby="account-load-heading"
+                        >
+                            <div className="performance-account-heading">
+                                <h3 id="account-load-heading">
+                                    Account capacity
+                                </h3>
+                                <section
+                                    className="performance-overview-status"
+                                    aria-label="Live Telegram activity"
+                                >
+                                    <span>
+                                        <strong>{uploads}</strong> uploading
+                                    </span>
+                                    <span>
+                                        <strong>{downloads}</strong> downloading
+                                        from Telegram
+                                    </span>
+                                    <span>
+                                        <strong>{telegram.queued}</strong>{" "}
+                                        waiting
+                                    </span>
+                                </section>
+                            </div>
+                            <p className="settings-help">
+                                Live account activity and current limits.
+                            </p>
+                            {telegram.accounts.length ? (
+                                <div
+                                    className="performance-table-wrap"
+                                    tabIndex={0}
+                                    role="region"
+                                    aria-label="Account capacity; scroll horizontally for more columns"
+                                >
+                                    <table className="performance-table">
+                                        <thead>
+                                            <tr>
+                                                <th>Account</th>
+                                                <th>Media operations</th>
+                                                <th>Origin bytes</th>
+                                                <th>Part requests</th>
+                                                <th>Pacing</th>
+                                                <th>Provider waits</th>
+                                            </tr>
+                                        </thead>
+                                        <tbody>
+                                            {telegram.accounts.map(
+                                                (account) => (
+                                                    <tr key={account.name}>
+                                                        <th scope="row">
+                                                            {account.name}
+                                                            <small>
+                                                                {account.kind ===
+                                                                "user"
+                                                                    ? "Premium account"
+                                                                    : "Storage bot"}
+                                                            </small>
+                                                        </th>
+                                                        <td>
+                                                            {account.uploads}{" "}
+                                                            upload ·{" "}
+                                                            {account.downloads}{" "}
+                                                            download
+                                                            <small>
+                                                                Combined limit{" "}
+                                                                {
+                                                                    account.combined_limit
+                                                                }
+                                                            </small>
+                                                        </td>
+                                                        <td>
+                                                            {typeof account
+                                                                .requests
+                                                                ?.upload_bytes ===
+                                                            "number" ? (
+                                                                <>
+                                                                    {formatBytes(
+                                                                        account
+                                                                            .requests
+                                                                            .upload_bytes,
+                                                                    )}{" "}
+                                                                    uploaded
+                                                                    <small>
+                                                                        {formatBytes(
+                                                                            account
+                                                                                .requests
+                                                                                .download_bytes,
+                                                                        )}{" "}
+                                                                        downloaded
+                                                                    </small>
+                                                                </>
+                                                            ) : (
+                                                                "Unavailable"
+                                                            )}
+                                                        </td>
+                                                        <td>
+                                                            {account.requests
+                                                                ? account
+                                                                      .requests
+                                                                      .active +
+                                                                  " active / " +
+                                                                  account
+                                                                      .requests
+                                                                      .effective_limit +
+                                                                  " limit"
+                                                                : "Unavailable"}
+                                                            <small>
+                                                                {account.requests
+                                                                    ? account
+                                                                          .requests
+                                                                          .queued +
+                                                                      " requests waiting"
+                                                                    : "No request sample"}
+                                                            </small>
+                                                        </td>
+                                                        <td>
+                                                            {account.requests
+                                                                ? account.requests.effective_parts_per_second.toFixed(
+                                                                      1,
+                                                                  ) +
+                                                                  " / second"
+                                                                : "—"}
+                                                            <small>
+                                                                {account.requests
+                                                                    ? "Configured ceiling " +
+                                                                      account
+                                                                          .requests
+                                                                          .configured_parts_per_second
+                                                                    : ""}
+                                                            </small>
+                                                        </td>
+                                                        <td>
+                                                            {Math.max(
+                                                                account.cooldown_seconds,
+                                                                account.requests
+                                                                    ?.cooldown_seconds ||
+                                                                    0,
+                                                            ) > 0
+                                                                ? queueWait(
+                                                                      Math.max(
+                                                                          account.cooldown_seconds,
+                                                                          account
+                                                                              .requests
+                                                                              ?.cooldown_seconds ||
+                                                                              0,
+                                                                      ),
+                                                                  )
+                                                                : "Ready"}
+                                                            <small>
+                                                                {account.requests
+                                                                    ? account
+                                                                          .requests
+                                                                          .floods +
+                                                                      " waits observed"
+                                                                    : ""}
+                                                            </small>
+                                                        </td>
+                                                    </tr>
+                                                ),
+                                            )}
+                                        </tbody>
+                                    </table>
+                                </div>
+                            ) : (
+                                <p className="performance-empty">
+                                    No account samples are available. Check
+                                    Connections.
+                                </p>
+                            )}
+                        </section>
+                        <section
+                            className="performance-section performance-account-section"
+                            aria-labelledby="media-queue-heading"
+                        >
+                            <h3 id="media-queue-heading">
+                                Waiting for Telegram
+                            </h3>
+                            <p className="settings-help">
+                                Demand reads have priority over background
+                                preparation. Estimates change with workload and
+                                provider cooldowns.
+                            </p>
+                            {telegram.queue.length ? (
+                                <div
+                                    className="performance-table-wrap"
+                                    tabIndex={0}
+                                    role="region"
+                                    aria-label="Telegram queue; scroll horizontally for more columns"
+                                >
+                                    <table className="performance-table">
+                                        <thead>
+                                            <tr>
+                                                <th>Position</th>
+                                                <th>Work</th>
+                                                <th>Priority</th>
+                                                <th>Waiting</th>
+                                                <th>Estimated wait</th>
+                                            </tr>
+                                        </thead>
+                                        <tbody>
+                                            {telegram.queue.map(
+                                                (entry, index) => (
+                                                    <tr
+                                                        key={
+                                                            (entry.request_id ||
+                                                                "queue") + index
+                                                        }
+                                                    >
+                                                        <td>
+                                                            {entry.position}
+                                                        </td>
+                                                        <td>
+                                                            {entry.operation ===
+                                                            "download"
+                                                                ? "Download"
+                                                                : "Upload"}
+                                                        </td>
+                                                        <td>
+                                                            {entry.priority ===
+                                                            "preload"
+                                                                ? "Background"
+                                                                : "Demand"}
+                                                        </td>
+                                                        <td>
+                                                            {Math.floor(
+                                                                entry.waiting_seconds,
+                                                            )}
+                                                            s
+                                                        </td>
+                                                        <td>
+                                                            {queueWait(
+                                                                entry.estimated_wait_seconds,
+                                                            )}
+                                                        </td>
+                                                    </tr>
+                                                ),
+                                            )}
+                                        </tbody>
+                                    </table>
+                                </div>
+                            ) : (
+                                <p className="performance-empty">
+                                    No origin operations are waiting.
+                                </p>
+                            )}
+                        </section>
+                        <section
+                            className="performance-section performance-account-section"
+                            aria-labelledby="recent-load-heading"
+                        >
+                            <h3 id="recent-load-heading">
+                                Recent Telegram load
+                            </h3>
+                            {history.length >= 2 && hasTelegramActivity ? (
+                                <>
+                                    <p className="settings-help">
+                                        0–{ceiling} simultaneous operations ·{" "}
+                                        {historyDuration(
+                                            history.at(-1)!.at - history[0].at,
+                                        )}{" "}
+                                        of sampled activity
+                                    </p>
+                                    <div className="performance-plot-legend">
+                                        <span>Active operations</span>
+                                        <span>Queued operations</span>
+                                    </div>
+                                    <svg
+                                        className="performance-load-plot"
+                                        role="img"
+                                        aria-label={
+                                            "Recent Telegram load, peak " +
+                                            ceiling +
+                                            " concurrent operations"
+                                        }
+                                        viewBox="0 0 600 130"
+                                        preserveAspectRatio="none"
+                                    >
+                                        <path
+                                            d="M0 120H600"
+                                            className="performance-plot-axis"
+                                        />
+                                        <polyline
+                                            points={loadPoints(
+                                                history,
+                                                "active",
+                                                ceiling,
+                                            )}
+                                            className="performance-plot-active"
+                                        />
+                                        <polyline
+                                            points={loadPoints(
+                                                history,
+                                                "queued",
+                                                ceiling,
+                                            )}
+                                            className="performance-plot-queued"
+                                        />
+                                    </svg>
+                                    <p className="settings-help">
+                                        Recent observations from this running
+                                        process.{" "}
+                                        {snapshot.history_scope ||
+                                            "Restart resets this operational history."}
+                                    </p>
+                                </>
+                            ) : (
+                                <p className="performance-empty">
+                                    {history.length < 2
+                                        ? "Collecting recent activity. Transfer counts are available above."
+                                        : "Telegram accounts are idle. Cached files can still be served directly."}
+                                </p>
+                            )}
+                        </section>
+                    </Tabs.Panel>
+                    <Tabs.Panel value="server">
+                        <div className="performance-overview-grid performance-resource-charts">
+                            <MetricChart
+                                windowSeconds={windowSeconds}
+                                historical={historical}
+                                bucketSeconds={
+                                    historical
+                                        ? recorded?.bucket_seconds || 60
+                                        : 3
+                                }
+                                title={
+                                    cpu?.scope === "host"
+                                        ? "Host CPU"
+                                        : "Container CPU"
+                                }
+                                samples={resourceHistory}
+                                series={[
+                                    { key: "cpu_percent", label: "Usage" },
+                                ]}
+                                maximum={100}
+                                format={(value) => value.toFixed(1) + "%"}
+                                scope="cpu_scope"
+                                current={
+                                    typeof cpu?.percent === "number"
+                                        ? cpu.percent.toFixed(1) + "%"
+                                        : "Measuring…"
+                                }
+                                note={
+                                    cpu?.capacity_cores
+                                        ? "100% uses the available " +
+                                          cpu.capacity_cores.toLocaleString() +
+                                          " CPU cores."
+                                        : "Measured CPU utilization; missing readings remain gaps."
+                                }
+                            />
+                            <MetricChart
+                                windowSeconds={windowSeconds}
+                                historical={historical}
+                                bucketSeconds={
+                                    historical
+                                        ? recorded?.bucket_seconds || 60
+                                        : 3
+                                }
+                                title="Container RAM"
+                                samples={resourceHistory}
+                                series={[
+                                    { key: "memory_bytes", label: "In use" },
+                                ]}
+                                maximum={memoryCeiling}
+                                format={formatBytes}
+                                current={
+                                    Number.isFinite(memoryUsed)
+                                        ? formatBytes(memoryUsed) +
+                                          (memoryLimit
+                                              ? " / " + formatBytes(memoryLimit)
+                                              : " in use")
+                                        : "Unavailable"
+                                }
+                                note={
+                                    memoryLimit
+                                        ? "Current container limit: " +
+                                          formatBytes(memoryLimit) +
+                                          ". Includes all processes in this container."
+                                        : "No container memory limit. The graph scales to observed usage, not total capacity."
+                                }
+                            />
+                        </div>
+                        <section
+                            className="performance-section"
+                            aria-labelledby="server-resource-heading"
+                        >
+                            <div className="performance-section-title">
+                                <h3 id="server-resource-heading">
+                                    Storage &amp; cache
+                                </h3>
+                                <span className="performance-chart-now">
+                                    Now
+                                </span>
+                            </div>
+                            <div className="performance-resource-summary">
+                                <UsageMeter
+                                    label="Cache filesystem"
+                                    used={snapshot.server.disk.used_bytes}
+                                    total={snapshot.server.disk.total_bytes}
+                                    detail={
+                                        formatBytes(
+                                            snapshot.server.disk.free_bytes,
+                                        ) + " free on the cache volume"
+                                    }
+                                />
+                                <UsageMeter
+                                    label="RAM cache"
+                                    used={snapshot.cache.memory.bytes}
+                                    total={
+                                        snapshot.cache.memory
+                                            .effective_max_bytes
+                                    }
+                                    detail={
+                                        snapshot.cache.memory
+                                            .effective_max_bytes === 0
+                                            ? "Disabled"
+                                            : "Retained media; part of container memory"
+                                    }
+                                />
+                                <UsageMeter
+                                    label="Disk cache"
+                                    used={snapshot.cache.disk.bytes}
+                                    total={snapshot.cache.disk.max_bytes}
+                                    detail={
+                                        !snapshot.cache.disk.available
+                                            ? "Unavailable"
+                                            : snapshot.cache.disk.max_bytes ===
+                                                0
+                                              ? "Disabled"
+                                              : "Disposable copies; originals stay in Telegram"
+                                    }
+                                />
+                            </div>
+                            <p className="performance-cache-link">
+                                <a
+                                    className="inline-link"
+                                    href="/?view=preloads"
+                                >
+                                    View cached files
+                                </a>
+                                <span>
+                                    {
+                                        snapshot.cache.files.filter(
+                                            cachedFileComplete,
+                                        ).length
+                                    }{" "}
+                                    ready ·{" "}
+                                    {
+                                        snapshot.cache.files.filter(
+                                            (file) => !cachedFileComplete(file),
+                                        ).length
+                                    }{" "}
+                                    partial
+                                </span>
+                            </p>
+                            <h3>Memory details</h3>
+                            <dl className="performance-facts performance-memory-details">
+                                <div>
+                                    <dt>TGDrive process</dt>
+                                    <dd>
+                                        {typeof snapshot.server
+                                            .process_rss_bytes === "number"
+                                            ? formatBytes(
+                                                  snapshot.server
+                                                      .process_rss_bytes,
+                                              )
+                                            : "Unavailable"}
+                                    </dd>
+                                    <small>
+                                        Part of container RAM · peak{" "}
+                                        {formatBytes(
+                                            snapshot.server
+                                                .process_peak_rss_bytes,
+                                        )}
+                                    </small>
+                                </div>
+                                <div>
+                                    <dt>Host memory available</dt>
+                                    <dd>
+                                        {typeof memory?.MemAvailable ===
+                                        "number"
+                                            ? formatBytes(memory.MemAvailable)
+                                            : "Unavailable"}
+                                    </dd>
+                                    <small>
+                                        {typeof memory?.MemTotal === "number"
+                                            ? "Host total " +
+                                              formatBytes(memory.MemTotal)
+                                            : "Host memory is unavailable"}
+                                    </small>
+                                </div>
+                                <StreamMemoryFact
+                                    scratch={snapshot.cache.scratch}
+                                />
+                                <div>
+                                    <dt>RAM cache lookups</dt>
+                                    <dd>
+                                        {snapshot.cache.memory.hits.toLocaleString()}{" "}
+                                        hits ·{" "}
+                                        {snapshot.cache.memory.misses.toLocaleString()}{" "}
+                                        misses
+                                    </dd>
+                                    <small>
+                                        Block lookups, including preloading; not
+                                        a bandwidth-saving percentage
+                                    </small>
+                                </div>
+                            </dl>
+                            <p className="settings-help">
+                                Upload staging budget:{" "}
+                                {formatBytes(
+                                    snapshot.server.staging_budget_bytes,
+                                )}
+                                .{" "}
+                                <a
+                                    className="inline-link"
+                                    href="/?view=storage"
+                                >
+                                    Storage &amp; Backups
+                                </a>
+                            </p>
+                            <details className="performance-detail-note">
+                                <summary>Resource measurement details</summary>
+                                <p className="settings-help">
+                                    {network?.scope ||
+                                        "Network interface scope unavailable."}{" "}
+                                    {snapshot.server.load_average.length
+                                        ? "Host load averages (1 / 5 / 15 minutes): " +
+                                          snapshot.server.load_average
+                                              .map((value) => value.toFixed(2))
+                                              .join(" / ") +
+                                          ". These are not CPU percentages."
+                                        : "Host load averages unavailable."}
+                                </p>
+                            </details>
+                        </section>
+                    </Tabs.Panel>
+                </>
+            )}
+        </Tabs>
+    );
+}
diff --git a/website/src/features/performance/PerformanceSettings.tsx b/website/src/features/performance/PerformanceSettings.tsx
new file mode 100644
index 00000000..1d0dab9f
--- /dev/null
+++ b/website/src/features/performance/PerformanceSettings.tsx
@@ -0,0 +1,495 @@
+import {
+    useCallback,
+    useEffect,
+    useRef,
+    useState,
+    type FormEvent,
+    type ReactNode,
+} from "react";
+import {
+    ExternalLink,
+    RefreshCw,
+    HardDrive,
+    PlayCircle,
+    Upload,
+    Globe,
+} from "lucide-react";
+import {
+    Button,
+    Fieldset,
+    NumberInput,
+    TextInput,
+    Switch,
+} from "@mantine/core";
+import { ApiError, errorMessage } from "../../shared/api";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import { useManualRefresh } from "../../shared/useManualRefresh";
+import {
+    numericPreferences,
+    performanceApi,
+    performanceChanges,
+    performanceDraft,
+    performanceCategoryDraft,
+    performanceCategoryKeys,
+    type PerformanceDraft,
+    type PerformancePreferences,
+} from "./performanceApi";
+import "./Performance.css";
+import DemoModeNotice from "../../shared/DemoModeNotice";
+import ThumbnailSettings from "./ThumbnailSettings";
+
+export default function PerformanceSettings({
+    onSaved,
+    onNotice,
+    category = "cache",
+    uploadPreferences,
+    demoMode = false,
+}: {
+    onSaved?: (value: PerformancePreferences) => void;
+    onNotice?: (message: string, error?: boolean) => void;
+    category?: "cache" | "transfers" | "regional";
+    uploadPreferences?: ReactNode;
+    demoMode?: boolean;
+} = {}) {
+    const [saved, setSaved] = useState<PerformancePreferences | null>(null);
+    const [draft, setDraft] = useState<PerformanceDraft | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    const [notice, setNotice] = useState("");
+    const [conflict, setConflict] = useState(false);
+    const latestLoad = useRef(0);
+    const { refreshing, run } = useManualRefresh(
+        onNotice ||
+            ((message, failed) => {
+                if (failed) setError(message);
+                else setNotice(message);
+            }),
+    );
+    const load = useCallback(async (signal?: AbortSignal, manual = false) => {
+        const request = ++latestLoad.current;
+        if (!manual) setLoading(true);
+        setError("");
+        try {
+            const value = await performanceApi.settings(signal);
+            if (signal?.aborted || request !== latestLoad.current) return false;
+            setSaved(value);
+            setDraft(performanceDraft(value));
+            setConflict(false);
+            setNotice("");
+            return true;
+        } catch (cause) {
+            if (!signal?.aborted && request === latestLoad.current)
+                setError(errorMessage(cause));
+            if (manual) throw cause;
+            return false;
+        } finally {
+            if (!signal?.aborted && request === latestLoad.current)
+                setLoading(false);
+        }
+    }, []);
+    const reloadSettings = () =>
+        void run(
+            (signal) => load(signal, true),
+            "Performance settings refreshed.",
+        );
+    useEffect(() => {
+        const controller = new AbortController();
+        void load(controller.signal);
+        return () => controller.abort();
+    }, [load]);
+    useEffect(() => {
+        setNotice("");
+        setError("");
+    }, [category]);
+    let changed = false;
+    if (saved && draft) {
+        try {
+            changed =
+                Object.keys(
+                    performanceChanges(
+                        performanceCategoryDraft(draft, saved, category),
+                        saved,
+                    ),
+                ).length > 0;
+        } catch {
+            changed = true;
+        }
+    }
+    const save = async (event: FormEvent) => {
+        event.preventDefault();
+        if (demoMode || !saved || !draft) return;
+        setBusy(true);
+        setError("");
+        setNotice("");
+        try {
+            const value = await performanceApi.save(
+                performanceChanges(
+                    performanceCategoryDraft(draft, saved, category),
+                    saved,
+                ),
+                saved.revision,
+            );
+            setSaved(value);
+            const refreshed = performanceDraft(value);
+            const baseline = performanceDraft(saved);
+            const next = { ...draft };
+            for (const key of Object.keys(
+                refreshed,
+            ) as (keyof PerformanceDraft)[])
+                if (
+                    performanceCategoryKeys(category).includes(key) ||
+                    draft[key] === baseline[key]
+                )
+                    Object.assign(next, { [key]: refreshed[key] });
+            setDraft(next);
+            setNotice(
+                "Performance settings saved for this section. New work uses these limits.",
+            );
+            setConflict(false);
+            onSaved?.(value);
+            window.dispatchEvent(
+                new Event("tgdrive:performance-settings-changed"),
+            );
+        } catch (cause) {
+            setError(errorMessage(cause));
+            setConflict(cause instanceof ApiError && cause.status === 409);
+        } finally {
+            setBusy(false);
+        }
+    };
+    const field = (definition: (typeof numericPreferences)[number]) => (
+        <div className="performance-field" key={definition.key}>
+            <div>
+                <label htmlFor={"perf-" + definition.key}>
+                    {definition.label}
+                </label>
+                <p id={"perf-help-" + definition.key}>{definition.help} </p>
+            </div>
+            <div className="configuration-value">
+                <NumberInput
+                    id={"perf-" + definition.key}
+                    min={definition.min}
+                    max={definition.max}
+                    step={definition.unit === 1 ? 1 : 0.25}
+                    allowDecimal={definition.unit !== 1}
+                    allowNegative={false}
+                    aria-label={definition.label}
+                    required
+                    disabled={demoMode || busy}
+                    aria-describedby={"perf-help-" + definition.key}
+                    value={draft![definition.key]}
+                    onChange={(value) => {
+                        setDraft({
+                            ...draft!,
+                            [definition.key]: String(value),
+                        });
+                        setNotice("");
+                    }}
+                />
+            </div>
+        </div>
+    );
+    return (
+        <section
+            className="settings-section performance-settings"
+            aria-labelledby="performance-settings-heading"
+        >
+            {demoMode && <DemoModeNotice />}
+            <div className="performance-section-heading">
+                <div>
+                    <h2 id="performance-settings-heading" className="sr-only">
+                        {
+                            {
+                                cache: "Cache storage and playback preparation",
+                                transfers: "Telegram transfer policy",
+                                regional: "Instance timezone",
+                            }[category]
+                        }
+                    </h2>
+                    <p>
+                        {
+                            {
+                                cache: "Control server resources and how much media stays ready for reuse.",
+                                transfers:
+                                    "Control upload splitting and the request capacity shared by Telegram clients.",
+                                regional:
+                                    "Choose the timezone used for dates and share expiry across this installation.",
+                            }[category]
+                        }
+                    </p>
+                </div>
+                <a
+                    className="inline-link"
+                    href={
+                        saved?.documentation_url ||
+                        "https://github.com/TechShreyash/TGDrive/blob/main/docs/configuration.md"
+                    }
+                    target="_blank"
+                    rel="noopener noreferrer"
+                >
+                    Configuration guide <ExternalLink size={14} />
+                </a>
+            </div>
+            <div hidden={category !== "transfers"}>{uploadPreferences}</div>
+            {loading ? (
+                <p className="performance-loading" role="status">
+                    <Spinner /> Loading performance settings…
+                </p>
+            ) : saved && draft ? (
+                <form noValidate onSubmit={(event) => void save(event)}>
+                    <Fieldset
+                        className="performance-setting-group"
+                        hidden={category !== "cache"}
+                        legend={
+                            <span className="configuration-group-title">
+                                <HardDrive size={18} aria-hidden="true" />
+                                Cache storage
+                            </span>
+                        }
+                    >
+                        <p className="settings-help">
+                            Budgets are shared by playback, downloads and
+                            preloads. They are filled only when needed.
+                        </p>
+                        {numericPreferences
+                            .filter((value) => value.key.startsWith("cache_"))
+                            .map(field)}
+                    </Fieldset>
+                    <Fieldset
+                        className="performance-setting-group"
+                        hidden={category !== "cache"}
+                        legend={
+                            <span className="configuration-group-title">
+                                <PlayCircle size={18} aria-hidden="true" />
+                                Automatic preloading
+                            </span>
+                        }
+                    >
+                        <p className="settings-help">
+                            Keep useful media ready while active playback and
+                            downloads take priority.
+                        </p>
+                        {numericPreferences
+                            .filter((value) => value.key === "preload_max_jobs")
+                            .map(field)}
+                        <Switch
+                            className="configuration-auto-preload"
+                            label="Preload during playback"
+                            description="Adapts extra server caching to media playback. Downloads fetch their requested ranges. Requested chunks and adaptive read-ahead still work when off; manual whole-file preloads stay available."
+                            checked={draft.auto_preload}
+                            onLabel="ON"
+                            offLabel="OFF"
+                            disabled={demoMode || busy}
+                            onChange={(event) => {
+                                setDraft({
+                                    ...draft,
+                                    auto_preload: event.currentTarget.checked,
+                                });
+                                setNotice("");
+                            }}
+                        />
+                    </Fieldset>
+                    <Fieldset
+                        className="performance-setting-group"
+                        hidden={category !== "transfers"}
+                        legend={
+                            <span className="configuration-group-title">
+                                <Upload size={18} aria-hidden="true" />
+                                Upload splitting
+                            </span>
+                        }
+                    >
+                        {numericPreferences
+                            .filter((value) => value.key === "upload_split_mib")
+                            .map(field)}
+                    </Fieldset>
+                    <Fieldset
+                        className="performance-setting-group"
+                        hidden={category !== "transfers"}
+                        legend={
+                            <span className="configuration-group-title">
+                                <Globe size={18} aria-hidden="true" />
+                                URL downloads
+                            </span>
+                        }
+                    >
+                        {numericPreferences
+                            .filter(
+                                (value) =>
+                                    value.key === "remote_download_concurrency",
+                            )
+                            .map(field)}
+                    </Fieldset>
+                    <Fieldset
+                        className="performance-setting-group"
+                        hidden={category !== "transfers"}
+                        legend={
+                            <span className="configuration-group-title">
+                                <HardDrive size={18} aria-hidden="true" />
+                                Upload storage
+                            </span>
+                        }
+                    >
+                        {numericPreferences
+                            .filter((value) =>
+                                [
+                                    "max_file_size",
+                                    "staging_budget_bytes",
+                                    "min_free_bytes",
+                                ].includes(value.key),
+                            )
+                            .map(field)}
+                    </Fieldset>
+                    <Fieldset
+                        className="performance-setting-group"
+                        hidden={category !== "regional"}
+                        legend={
+                            <span className="configuration-group-title">
+                                <Globe size={18} aria-hidden="true" />
+                                Display time
+                            </span>
+                        }
+                    >
+                        <div className="performance-field">
+                            <div>
+                                <label htmlFor="performance-timezone">
+                                    Timezone
+                                </label>
+                                <p id="performance-timezone-help">
+                                    Used for dates and share expiry. Examples:
+                                    Asia/Kolkata (IST), Europe/London or UTC.
+                                </p>
+                            </div>
+                            <TextInput
+                                id="performance-timezone"
+                                value={draft.timezone}
+                                required
+                                disabled={demoMode || busy}
+                                aria-describedby="performance-timezone-help"
+                                onChange={(event) => {
+                                    setDraft({
+                                        ...draft,
+                                        timezone: event.target.value,
+                                    });
+                                    setNotice("");
+                                }}
+                            />
+                        </div>
+                    </Fieldset>
+                    <details
+                        className="performance-advanced"
+                        hidden={category !== "transfers"}
+                    >
+                        <summary>Advanced Telegram limits</summary>
+                        <p>
+                            These limits share each account’s capacity. Higher
+                            values can increase cooldowns and compete with
+                            streaming.
+                        </p>
+                        {numericPreferences
+                            .filter((value) => value.advanced)
+                            .map(field)}
+                    </details>
+                    <p className="settings-help performance-save-scope">
+                        Save applies to this page. Restore defaults loads values
+                        for review before saving.
+                        {category === "transfers" &&
+                            " Parallel uploads has its own Save Changes action above."}
+                    </p>
+                    <div className="performance-actions">
+                        <span className="performance-save-state">
+                            {changed
+                                ? "Unsaved changes"
+                                : "Settings are up to date"}
+                        </span>
+                        <Button
+                            className="primary-button"
+                            type="submit"
+                            aria-label="Save Performance Settings"
+                            disabled={demoMode || busy || !changed || conflict}
+                        >
+                            {busy ? <Spinner /> : null}
+                            {busy ? "Saving…" : "Save changes"}
+                        </Button>
+                        <Button
+                            type="button"
+                            className="secondary-button"
+                            variant="default"
+                            disabled={demoMode || busy || refreshing}
+                            onClick={() => {
+                                if (conflict) {
+                                    reloadSettings();
+                                    return;
+                                }
+                                const baseline = performanceDraft(saved);
+                                const next = { ...draft };
+                                for (const key of performanceCategoryKeys(
+                                    category,
+                                ))
+                                    Object.assign(next, {
+                                        [key]: baseline[key],
+                                    });
+                                setDraft(next);
+                                setError("");
+                                setNotice("");
+                            }}
+                        >
+                            {refreshing ? <Spinner /> : <RefreshCw size={16} />}
+                            {refreshing
+                                ? "Refreshing…"
+                                : conflict
+                                  ? "Reload Latest Settings"
+                                  : "Discard changes"}
+                        </Button>
+                        <Button
+                            type="button"
+                            className="text-button"
+                            variant="subtle"
+                            disabled={
+                                demoMode || busy || conflict || !saved.defaults
+                            }
+                            onClick={() => {
+                                if (!saved.defaults) return;
+                                const defaults = performanceDraft(
+                                    saved.defaults,
+                                );
+                                const next = { ...draft };
+                                for (const key of performanceCategoryKeys(
+                                    category,
+                                ))
+                                    Object.assign(next, {
+                                        [key]: defaults[key],
+                                    });
+                                setDraft(next);
+                                setError("");
+                                setNotice(
+                                    "Default values loaded for this page. Review and save to apply.",
+                                );
+                            }}
+                        >
+                            Restore defaults
+                        </Button>
+                    </div>
+                    {notice && (
+                        <p className="performance-notice" role="status">
+                            {notice}
+                        </p>
+                    )}
+                </form>
+            ) : (
+                <Button
+                    className="secondary-button"
+                    disabled={refreshing}
+                    aria-busy={refreshing}
+                    onClick={reloadSettings}
+                >
+                    {refreshing && <Spinner />}
+                    {refreshing ? "Refreshing…" : "Try Again"}
+                </Button>
+            )}
+            <ErrorNotice message={error} />
+            {category === "cache" && <ThumbnailSettings demoMode={demoMode} />}
+        </section>
+    );
+}
diff --git a/website/src/features/performance/Preloads.css b/website/src/features/performance/Preloads.css
new file mode 100644
index 00000000..5508c002
--- /dev/null
+++ b/website/src/features/performance/Preloads.css
@@ -0,0 +1,428 @@
+.preloads-page.page-body {
+    max-width: none;
+}
+.preloads-page .preload-capacity {
+    padding: 16px;
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    background: var(--surface-subtle);
+}
+.preload-capacity-header > h3,
+.preload-inventory > h3,
+.preload-queue > h3 {
+    margin: 0;
+    color: var(--ink);
+    font-size: 16px;
+    font-weight: 600;
+}
+.preload-capacity-meters {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 32px;
+    margin-top: 12px;
+}
+.preload-capacity-tier {
+    min-width: 0;
+}
+.preload-capacity-tier h4 {
+    margin: 0 0 6px;
+    font-size: 16px;
+    font-weight: 500;
+}
+.preload-capacity-value {
+    display: flex;
+    align-items: baseline;
+    flex-wrap: wrap;
+    gap: 4px 8px;
+    font-variant-numeric: tabular-nums;
+}
+.preload-capacity-value strong {
+    color: var(--ink);
+    font-size: 20px;
+    font-weight: 600;
+    line-height: 1.3;
+}
+.preload-capacity-value > span {
+    color: var(--muted);
+    font-size: 13px;
+}
+.preload-capacity-value > span:last-child {
+    margin-left: auto;
+    color: var(--ink);
+}
+.preloads-page .preload-capacity-tier progress,
+.preload-capacity-unavailable {
+    display: block;
+    width: 100%;
+    height: 8px;
+    margin-top: 8px;
+    border: 0;
+    border-radius: 4px;
+    background: var(--line);
+    accent-color: var(--action);
+    appearance: none;
+    overflow: hidden;
+}
+.preload-capacity-tier progress::-webkit-progress-bar {
+    background: var(--line);
+}
+.preload-capacity-tier progress::-webkit-progress-value {
+    border-radius: 4px;
+    background: var(--action);
+}
+.preload-capacity-tier progress::-moz-progress-bar {
+    border-radius: 4px;
+    background: var(--action);
+}
+.preload-capacity-header {
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: 8px 16px;
+    color: var(--muted);
+    font-size: 13px;
+}
+.preload-capacity-header > h3 {
+    margin-right: auto;
+}
+.preload-capacity-header a {
+    min-height: 28px;
+}
+.preload-inventory {
+    margin-top: 20px;
+}
+.preload-inventory > h3 {
+    margin-bottom: 8px;
+}
+.preload-inventory-toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    padding-bottom: 8px;
+    border-bottom: 1px solid var(--line);
+}
+.preload-filters,
+.preload-inventory-actions {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+}
+.preload-filters button {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    min-height: 36px;
+    padding: 6px 12px;
+    border: 0;
+    border-radius: 6px;
+    background: transparent;
+    color: var(--muted);
+    font-weight: 500;
+    cursor: pointer;
+}
+.preload-filters button span {
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+}
+.preload-filters button:hover {
+    background: var(--hover);
+    color: var(--ink);
+}
+.preload-filters button[aria-pressed="true"] {
+    background: var(--action-soft);
+    color: var(--on-action-soft);
+}
+.preload-inventory-actions {
+    gap: 8px;
+}
+.preload-inventory-actions .secondary-button {
+    min-height: 36px;
+    padding-block: 6px;
+}
+.preloads-page .preload-filter-select {
+    display: none;
+}
+.preloads-page .cached-file {
+    position: relative;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+    gap: 16px;
+    padding-block: 10px;
+    border-bottom: 1px solid var(--line-subtle);
+}
+.preloads-page .cached-file > .file-icon {
+    margin-top: 2px;
+    flex: 0 0 24px;
+}
+.preloads-page .cache-coverage {
+    flex: 1;
+    min-width: 0;
+}
+.cached-file-heading {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 4px 12px;
+    min-height: 24px;
+    padding-right: 80px;
+}
+.preloads-page .cached-file-heading strong {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--ink);
+    font-size: 14px;
+    font-weight: 500;
+}
+.preloads-page .cache-ready-state {
+    flex-shrink: 0;
+    font-size: 12px;
+    line-height: 18px;
+}
+.preloads-page .cache-ready-state[data-complete="true"] {
+    padding: 0;
+    background: transparent;
+    color: var(--success);
+}
+.preloads-page .cached-file-meta {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 12px;
+    margin-top: 2px;
+    color: var(--muted);
+    font-size: 13px;
+    line-height: 20px;
+    font-variant-numeric: tabular-nums;
+}
+.preloads-page .cached-file-meta > span:last-child {
+    flex-shrink: 0;
+}
+.preloads-page .cache-coverage svg {
+    display: block;
+    width: 100%;
+    height: 8px;
+    margin-block: 6px 0;
+    border-radius: 4px;
+}
+.preloads-page .cache-coverage[data-complete="true"] .cache-coverage-ready {
+    fill: var(--icon);
+}
+.cached-file-actions {
+    position: absolute;
+    top: 4px;
+    right: 0;
+    display: flex;
+}
+.cached-file-actions > .icon-button {
+    width: 36px;
+    height: 36px;
+    flex: 0 0 36px;
+}
+.preloads-page .cached-file-error {
+    flex-basis: 100%;
+}
+.preload-empty {
+    padding: 44px 0;
+    text-align: center;
+    color: var(--muted);
+    font-size: 13px;
+}
+.preload-empty p {
+    margin: 0 0 6px;
+    color: var(--ink);
+    font-size: 14px;
+    font-weight: 500;
+}
+.preloads-page .preload-queue {
+    margin-top: 24px;
+}
+.preload-queue > h3 {
+    margin-bottom: 4px;
+}
+.preloads-page .preload-job {
+    align-items: center;
+    gap: 12px;
+    padding-block: 14px;
+}
+.preloads-page .preload-job-copy > span {
+    margin-top: 2px;
+    font-size: 12px;
+}
+.preload-job-progress {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 8px 12px;
+    margin-top: 8px;
+    color: var(--muted);
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+}
+.preloads-page .preload-job-progress progress {
+    width: 100%;
+    height: 8px;
+    margin: 0;
+}
+.preloads-page .preload-job-error {
+    margin-block: 6px 0;
+    font-size: 13px;
+}
+.preloads-page .preload-job[data-state="failed"] strong {
+    color: var(--muted);
+}
+.preloads-page details.preload-help,
+.preloads-page details.preload-recent {
+    margin-top: 20px;
+    padding: 0;
+    border: 0;
+    border-top: 1px solid var(--line);
+    border-radius: 0;
+    background: transparent;
+    color: var(--muted);
+    font-size: 13px;
+}
+.preload-help > summary,
+.preload-recent > summary {
+    width: fit-content;
+    min-height: 44px;
+    align-content: center;
+    cursor: pointer;
+}
+.preload-help > div {
+    max-width: 72ch;
+    padding-bottom: 12px;
+}
+.preload-help p {
+    margin-block: 0 12px;
+    line-height: 1.6;
+}
+.preload-help strong {
+    color: var(--ink);
+    font-weight: 500;
+}
+@media (max-width: 640px) {
+    .preloads-page .preload-capacity {
+        padding: 16px;
+    }
+    .preload-capacity-meters {
+        gap: 20px;
+        margin-top: 16px;
+    }
+    .preload-capacity-tier h4 {
+        margin-bottom: 10px;
+        font-size: 14px;
+    }
+    .preload-capacity-value {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto;
+        gap: 4px;
+    }
+    .preload-capacity-value strong {
+        font-size: 18px;
+    }
+    .preload-capacity-value > span:nth-child(2) {
+        grid-column: 1 / -1;
+        grid-row: 2;
+        font-size: 12px;
+    }
+    .preload-capacity-value > span:last-child {
+        grid-column: 2;
+        grid-row: 1;
+        align-self: center;
+        font-size: 12px;
+    }
+    .preload-capacity-header {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) auto;
+        gap: 2px 12px;
+        font-size: 12px;
+    }
+    .preload-capacity-header > h3 {
+        grid-column: 1;
+        grid-row: 1;
+    }
+    .preload-capacity-activity {
+        grid-column: 1;
+        grid-row: 2;
+    }
+    .preload-capacity-header a {
+        grid-column: 2;
+        grid-row: 1 / 3;
+        min-height: 44px;
+    }
+    .preload-inventory {
+        margin-top: 20px;
+    }
+    .preload-inventory-toolbar {
+        gap: 8px;
+    }
+    .preload-filters {
+        display: none;
+    }
+    .preloads-page .preload-filter-select {
+        display: block;
+        min-width: 0;
+        width: auto;
+        max-width: 210px;
+        min-height: 44px;
+        margin: 0;
+        flex: 1;
+        font-size: 16px;
+    }
+    .preload-inventory-actions .secondary-button {
+        width: 44px;
+        height: 44px;
+        padding: 0;
+    }
+    .preload-inventory-actions .secondary-button > span {
+        display: none;
+    }
+    .preloads-page .cached-file {
+        padding-block: 12px;
+        flex-wrap: wrap;
+    }
+    .preloads-page .cached-file > .file-icon {
+        display: none;
+    }
+    .cached-file-heading {
+        display: block;
+        min-height: 44px;
+        padding-right: 92px;
+    }
+    .preloads-page .cached-file-heading strong {
+        display: block;
+        max-width: 100%;
+        white-space: normal;
+        overflow-wrap: anywhere;
+        line-height: 21px;
+    }
+    .preloads-page .cache-ready-state {
+        margin-top: 4px;
+    }
+    .preloads-page .cached-file-meta {
+        margin-top: 8px;
+        font-size: 12px;
+    }
+    .cached-file-actions {
+        top: 8px;
+    }
+    .cached-file-actions > .icon-button {
+        width: 44px;
+        height: 44px;
+        flex-basis: 44px;
+    }
+    .preloads-page .preload-job {
+        align-items: flex-start;
+    }
+    .preload-job > button {
+        padding-inline: 10px;
+        min-height: 44px;
+    }
+    .preload-job > button svg {
+        display: none;
+    }
+}
diff --git a/website/src/features/performance/Preloads.tsx b/website/src/features/performance/Preloads.tsx
new file mode 100644
index 00000000..5eed7573
--- /dev/null
+++ b/website/src/features/performance/Preloads.tsx
@@ -0,0 +1,764 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { RefreshCw, Trash2, X, AlertCircle, Settings2 } from "lucide-react";
+import { errorMessage } from "../../shared/api";
+import { ErrorNotice, Spinner, FileIcon, Modal } from "../../shared/components";
+import { formatByteProgress, formatBytes } from "../../shared/types";
+import { useManualRefresh } from "../../shared/useManualRefresh";
+import {
+    performanceApi,
+    type CachedFile,
+    type PreloadJob,
+    type PreloadSnapshot,
+} from "./performanceApi";
+import "./Performance.css";
+import "./Preloads.css";
+
+/** Normalize half-open byte ranges before painting coverage; never paint past EOF. */
+export function coverageRanges(
+    ranges: [number, number][],
+    size: number,
+): [number, number][] {
+    if (!Number.isFinite(size) || size <= 0) return [];
+    const clean = ranges
+        .filter(
+            ([start, end]) =>
+                Number.isFinite(start) && Number.isFinite(end) && end > start,
+        )
+        .map(
+            ([start, end]) =>
+                [Math.max(0, start), Math.min(size, end)] as [number, number],
+        )
+        .filter(([start, end]) => end > start)
+        .sort((a, b) => a[0] - b[0]);
+    const merged: [number, number][] = [];
+    for (const [start, end] of clean) {
+        const previous = merged.at(-1);
+        if (previous && start <= previous[1])
+            previous[1] = Math.max(previous[1], end);
+        else merged.push([start, end]);
+    }
+    return merged;
+}
+export function CacheCoverage({
+    file,
+    status,
+    showName = false,
+}: {
+    file: CachedFile;
+    status?: string;
+    showName?: boolean;
+}) {
+    const ranges = coverageRanges(file.ready_ranges || [], file.size);
+    const ready = ranges.reduce((sum, [start, end]) => sum + end - start, 0);
+    const complete = cachedFileComplete(file);
+    const percent =
+        file.size > 0
+            ? Math.min(100, Math.floor((ready / file.size) * 100))
+            : 0;
+    return (
+        <div className="cache-coverage" data-complete={complete}>
+            <div className="cached-file-heading">
+                {showName && (
+                    <strong title={file.name || "Cached file"}>
+                        {file.name || "Cached file"}
+                    </strong>
+                )}
+                <span className="cache-ready-state" data-complete={complete}>
+                    {complete ? "Ready" : status || "Partial"}
+                </span>
+            </div>
+            <div className="cached-file-meta">
+                <span>{formatByteProgress(ready, file.size)} cached</span>
+                <span>{percent}%</span>
+            </div>
+            <svg
+                role="img"
+                aria-label={`${formatByteProgress(ready, file.size)} cached · ${percent}% · ${complete ? "Ready" : status || "Partial"}`}
+                viewBox="0 0 1000 8"
+                preserveAspectRatio="none"
+            >
+                <rect
+                    x="0"
+                    y="0"
+                    width="1000"
+                    height="8"
+                    className="cache-coverage-track"
+                />
+                {ranges.map(([start, end], index) => (
+                    <rect
+                        key={index}
+                        x={(start / file.size) * 1000}
+                        y="0"
+                        width={((end - start) / file.size) * 1000}
+                        height="8"
+                        className="cache-coverage-ready"
+                    />
+                ))}
+            </svg>
+        </div>
+    );
+}
+export function CacheCapacity({
+    label,
+    used,
+    limit,
+    disabled = false,
+    unavailable = false,
+}: {
+    label: string;
+    used: number;
+    limit: number;
+    disabled?: boolean;
+    unavailable?: boolean;
+}) {
+    const available = !disabled && !unavailable && limit > 0;
+    const percent = available ? Math.round((used / limit) * 100) : 0;
+    return (
+        <div className="preload-capacity-tier" role="group" aria-label={label}>
+            <h4>{label}</h4>
+            <div className="preload-capacity-value">
+                {available ? (
+                    <>
+                        <strong>{formatBytes(used)}</strong>
+                        <span>of {formatBytes(limit)} used</span>
+                        <span>{percent}%</span>
+                    </>
+                ) : (
+                    <strong>{disabled ? "Disabled" : "Unavailable"}</strong>
+                )}
+            </div>
+            {available ? (
+                <progress
+                    aria-label={label + " usage"}
+                    aria-valuetext={`${formatByteProgress(used, limit)} used (${percent}%)`}
+                    max={limit}
+                    value={Math.min(used, limit)}
+                />
+            ) : (
+                <div
+                    className="preload-capacity-unavailable"
+                    aria-hidden="true"
+                />
+            )}
+        </div>
+    );
+}
+export function cachedFileComplete(file: CachedFile): boolean {
+    const ranges = coverageRanges(file.ready_ranges || [], file.size);
+    return (
+        ranges.length === 1 && ranges[0][0] === 0 && ranges[0][1] === file.size
+    );
+}
+/** Snapshots are newest first; older outcomes do not describe a file's current job. */
+export function currentPreloadJobs(jobs: PreloadJob[]): PreloadJob[] {
+    const seen = new Set<string>();
+    return jobs.filter((job) => {
+        if (seen.has(job.file_id)) return false;
+        seen.add(job.file_id);
+        return true;
+    });
+}
+function jobLabel(job: PreloadJob) {
+    return job.state === "ready"
+        ? job.target_bytes >= job.size
+            ? "Preload finished"
+            : "Upcoming chunks cached"
+        : job.state === "preparing"
+          ? "Preloading"
+          : job.state === "failed"
+            ? "Needs attention"
+            : job.state === "cancelled"
+              ? "Cancelled"
+              : "Queued";
+}
+export default function Preloads({
+    onError,
+    onNotice,
+    query = "",
+}: {
+    onError?: (message: string) => void;
+    onNotice?: (message: string, error?: boolean) => void;
+    query?: string;
+} = {}) {
+    const [snapshot, setSnapshot] = useState<PreloadSnapshot | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState("");
+    const [notice, setNotice] = useState("");
+    const [busy, setBusy] = useState("");
+    const [clearing, setClearing] = useState<{
+        id?: string;
+        name?: string;
+    } | null>(null);
+    const [refresh, setRefresh] = useState(0);
+    const [filter, setFilter] = useState<"all" | "ready" | "partial">("all");
+    const latestLoad = useRef(0);
+    const manualLoading = useRef(false);
+    const { refreshing, run } = useManualRefresh(
+        onNotice ||
+            ((message, failed) => {
+                if (failed) setError(message);
+                else setNotice(message);
+            }),
+    );
+    const load = useCallback(async (signal?: AbortSignal, manual = false) => {
+        if (!manual && manualLoading.current) return false;
+        const request = ++latestLoad.current;
+        try {
+            const value = await performanceApi.preloads(signal);
+            if (!signal?.aborted && request === latestLoad.current) {
+                setSnapshot(value);
+                setError("");
+                return true;
+            }
+            return false;
+        } catch (cause) {
+            if (!signal?.aborted && request === latestLoad.current)
+                setError(errorMessage(cause));
+            if (manual) throw cause;
+            return false;
+        } finally {
+            if (!signal?.aborted && request === latestLoad.current)
+                setLoading(false);
+        }
+    }, []);
+    const refreshInventory = () =>
+        void run(async (signal) => {
+            manualLoading.current = true;
+            setNotice("");
+            try {
+                return await load(signal, true);
+            } finally {
+                manualLoading.current = false;
+            }
+        }, "Cache inventory refreshed.");
+    useEffect(() => {
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            await load(controller.signal);
+            if (!controller.signal.aborted)
+                timer = setTimeout(poll, document.hidden ? 15000 : 3000);
+        };
+        void poll();
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [load, refresh]);
+    const act = async (
+        key: string,
+        task: () => Promise<unknown>,
+        message: string,
+    ) => {
+        setBusy(key);
+        setError("");
+        setNotice("");
+        try {
+            await task();
+            if (onNotice) onNotice(message);
+            else setNotice(message);
+            setRefresh((value) => value + 1);
+        } catch (cause) {
+            const message = errorMessage(cause);
+            setError(message);
+            onError?.(message);
+        } finally {
+            setBusy("");
+        }
+    };
+    const cache = snapshot?.cache;
+    const files = cache?.files || [];
+    const readyCount = files.filter(cachedFileComplete).length;
+    const visibleFiles = files.filter(
+        (file) =>
+            (file.name || "Cached file")
+                .toLocaleLowerCase()
+                .includes(query.trim().toLocaleLowerCase()) &&
+            (filter === "all" ||
+                cachedFileComplete(file) === (filter === "ready")),
+    );
+    const currentJobs = currentPreloadJobs(snapshot?.jobs || []);
+    const jobs = currentJobs.filter((job) =>
+        (job.name || "File preload")
+            .toLocaleLowerCase()
+            .includes(query.trim().toLocaleLowerCase()),
+    );
+    const pending = jobs.filter((job) =>
+        ["queued", "preparing", "failed"].includes(job.state),
+    );
+    const unlistedJobs = pending.filter(
+        (job) => !files.some((file) => file.id === job.file_id),
+    );
+    const finished = jobs.filter(
+        (job) =>
+            job.state === "cancelled" &&
+            !files.some((file) => file.id === job.file_id),
+    );
+    const hasActiveJobs = currentJobs.some((job) =>
+        ["queued", "preparing"].includes(job.state),
+    );
+    const filters = [
+        ["all", "All", files.length],
+        ["ready", "Ready", readyCount],
+        ["partial", "Partial", files.length - readyCount],
+    ] as const;
+    const renderJob = (job: PreloadJob) => (
+        <li key={job.id} className="preload-job" data-state={job.state}>
+            <div className="preload-job-copy">
+                <strong>{job.name || "File preload"}</strong>
+                <span>
+                    {jobLabel(job)} ·{" "}
+                    {job.mode === "auto" ? "Automatic" : "Manual"}
+                </span>
+                {["queued", "preparing"].includes(job.state) && (
+                    <div className="preload-job-progress">
+                        <progress
+                            max={Math.max(1, job.target_bytes)}
+                            value={Math.min(job.bytes_done, job.target_bytes)}
+                            aria-label={"Preloading " + (job.name || "file")}
+                        />
+                        <span>
+                            {formatByteProgress(
+                                job.bytes_done,
+                                job.target_bytes,
+                            )}
+                        </span>
+                    </div>
+                )}
+                {job.error && (
+                    <p className="preload-job-error">
+                        <AlertCircle size={15} aria-hidden="true" />
+                        {job.error}
+                    </p>
+                )}
+            </div>
+            {["queued", "preparing"].includes(job.state) && (
+                <button
+                    className="secondary-button"
+                    disabled={!!busy || refreshing}
+                    onClick={() =>
+                        void act(
+                            "job:" + job.id,
+                            () => performanceApi.cancel(job.id),
+                            "Preload cancelled. Active streams and downloads can continue.",
+                        )
+                    }
+                    aria-label={"Cancel preload of " + (job.name || "file")}
+                >
+                    {busy === "job:" + job.id ? (
+                        <Spinner />
+                    ) : (
+                        <X size={16} aria-hidden="true" />
+                    )}{" "}
+                    Cancel
+                </button>
+            )}
+        </li>
+    );
+    return (
+        <div className="preloads-page page-body">
+            {loading && (
+                <p className="performance-loading" role="status">
+                    <Spinner /> Loading cache inventory…
+                </p>
+            )}
+            <ErrorNotice message={error} />
+            {cache && (
+                <>
+                    <section
+                        className="preload-capacity"
+                        aria-labelledby="preload-capacity-heading"
+                    >
+                        <div className="preload-capacity-header">
+                            <h3 id="preload-capacity-heading">
+                                Cache capacity
+                            </h3>
+                            <span className="preload-capacity-activity">
+                                {snapshot.active_jobs
+                                    ? snapshot.active_jobs +
+                                      (snapshot.active_jobs === 1
+                                          ? " preload running"
+                                          : " preloads running")
+                                    : "No preloads running"}
+                            </span>
+                            <a
+                                className="inline-link"
+                                href="/?view=settings&section=performance"
+                            >
+                                <Settings2 size={15} aria-hidden="true" /> Cache
+                                settings
+                            </a>
+                        </div>
+                        <div
+                            className="preload-capacity-meters"
+                            role="group"
+                            aria-label="Server cache usage"
+                        >
+                            <CacheCapacity
+                                label="Memory cache"
+                                used={cache.memory.bytes}
+                                limit={cache.memory.effective_max_bytes}
+                                disabled={cache.memory.max_bytes === 0}
+                                unavailable={
+                                    cache.memory.effective_max_bytes <= 0
+                                }
+                            />
+                            <CacheCapacity
+                                label="Disk cache"
+                                used={cache.disk.bytes}
+                                limit={cache.disk.max_bytes}
+                                disabled={cache.disk.max_bytes === 0}
+                                unavailable={!cache.disk.available}
+                            />
+                        </div>
+                    </section>
+                    <section
+                        className="preload-inventory"
+                        aria-labelledby="cached-files-heading"
+                    >
+                        <h3 id="cached-files-heading">Cached files</h3>
+                        <div className="preload-inventory-toolbar">
+                            <div
+                                className="preload-filters"
+                                role="group"
+                                aria-label="Filter cached files"
+                            >
+                                {filters.map(([key, label, count]) => (
+                                    <button
+                                        type="button"
+                                        key={key}
+                                        aria-pressed={filter === key}
+                                        onClick={() => setFilter(key)}
+                                    >
+                                        {label} <span>{count}</span>
+                                    </button>
+                                ))}
+                            </div>
+                            <select
+                                className="preload-filter-select"
+                                aria-label="Filter cached files"
+                                value={filter}
+                                onChange={(event) =>
+                                    setFilter(
+                                        event.currentTarget
+                                            .value as typeof filter,
+                                    )
+                                }
+                            >
+                                {filters.map(([key, label, count]) => (
+                                    <option key={key} value={key}>
+                                        {label === "All" ? "All files" : label}{" "}
+                                        ({count})
+                                    </option>
+                                ))}
+                            </select>
+                            <div className="preload-inventory-actions">
+                                <button
+                                    className="secondary-button"
+                                    disabled={!!busy || refreshing}
+                                    aria-busy={refreshing}
+                                    onClick={refreshInventory}
+                                    aria-label="Refresh Cache Inventory"
+                                    title="Refresh cache inventory"
+                                >
+                                    {refreshing ? (
+                                        <Spinner />
+                                    ) : (
+                                        <RefreshCw
+                                            size={16}
+                                            aria-hidden="true"
+                                        />
+                                    )}
+                                    <span>
+                                        {refreshing ? "Refreshing…" : "Refresh"}
+                                    </span>
+                                </button>
+                                <button
+                                    className="secondary-button"
+                                    disabled={
+                                        !!busy ||
+                                        refreshing ||
+                                        (!files.length && !hasActiveJobs)
+                                    }
+                                    onClick={() => setClearing({})}
+                                    aria-label="Clear Cache"
+                                    title="Clear all cached files"
+                                >
+                                    {busy === "clear" ? (
+                                        <Spinner />
+                                    ) : (
+                                        <Trash2 size={16} aria-hidden="true" />
+                                    )}
+                                    <span>
+                                        {busy === "clear"
+                                            ? "Clearing…"
+                                            : "Clear cache"}
+                                    </span>
+                                </button>
+                            </div>
+                        </div>
+                        {files.length ? (
+                            <>
+                                <ul
+                                    className="cached-file-list"
+                                    aria-label="Cached files"
+                                >
+                                    {visibleFiles.map((file) => {
+                                        const job = pending.find(
+                                            (job) => job.file_id === file.id,
+                                        );
+                                        return (
+                                            <li
+                                                className="cached-file"
+                                                key={file.id}
+                                            >
+                                                <FileIcon
+                                                    name={
+                                                        file.name ||
+                                                        "Cached file"
+                                                    }
+                                                />
+                                                <CacheCoverage
+                                                    file={file}
+                                                    showName
+                                                    status={
+                                                        job?.state ===
+                                                        "preparing"
+                                                            ? "Partial · Preloading"
+                                                            : job?.state ===
+                                                                "queued"
+                                                              ? "Partial · Queued"
+                                                              : job?.state ===
+                                                                  "failed"
+                                                                ? "Needs attention"
+                                                                : undefined
+                                                    }
+                                                />
+                                                <div className="cached-file-actions">
+                                                    {job &&
+                                                        [
+                                                            "queued",
+                                                            "preparing",
+                                                        ].includes(
+                                                            job.state,
+                                                        ) && (
+                                                            <button
+                                                                className="icon-button"
+                                                                disabled={
+                                                                    !!busy ||
+                                                                    refreshing
+                                                                }
+                                                                aria-label={
+                                                                    "Cancel preload of " +
+                                                                    (file.name ||
+                                                                        "file")
+                                                                }
+                                                                title="Cancel preload"
+                                                                onClick={() =>
+                                                                    void act(
+                                                                        "job:" +
+                                                                            job.id,
+                                                                        () =>
+                                                                            performanceApi.cancel(
+                                                                                job.id,
+                                                                            ),
+                                                                        "Preload cancelled. Active streams and downloads can continue.",
+                                                                    )
+                                                                }
+                                                            >
+                                                                {busy ===
+                                                                "job:" +
+                                                                    job.id ? (
+                                                                    <Spinner />
+                                                                ) : (
+                                                                    <X
+                                                                        size={
+                                                                            17
+                                                                        }
+                                                                        aria-hidden="true"
+                                                                    />
+                                                                )}
+                                                            </button>
+                                                        )}
+                                                    <button
+                                                        className="icon-button"
+                                                        disabled={
+                                                            !!busy || refreshing
+                                                        }
+                                                        aria-label={
+                                                            "Evict cached bytes for " +
+                                                            (file.name ||
+                                                                "file")
+                                                        }
+                                                        title="Clear cached bytes"
+                                                        onClick={() =>
+                                                            setClearing({
+                                                                id: file.id,
+                                                                name:
+                                                                    file.name ||
+                                                                    "Cached file",
+                                                            })
+                                                        }
+                                                    >
+                                                        {busy ===
+                                                        "file:" + file.id ? (
+                                                            <Spinner />
+                                                        ) : (
+                                                            <Trash2
+                                                                size={17}
+                                                                aria-hidden="true"
+                                                            />
+                                                        )}
+                                                    </button>
+                                                </div>
+                                                {job?.error && (
+                                                    <p className="preload-job-error cached-file-error">
+                                                        <AlertCircle
+                                                            size={15}
+                                                            aria-hidden="true"
+                                                        />
+                                                        {job.error}
+                                                    </p>
+                                                )}
+                                            </li>
+                                        );
+                                    })}
+                                </ul>
+                            </>
+                        ) : (
+                            <div className="preload-empty">
+                                <p>No files cached yet</p>
+                                <span>
+                                    In My Files, choose{" "}
+                                    <strong>Preload file</strong> from a file’s
+                                    menu.
+                                </span>
+                            </div>
+                        )}
+                        {!!files.length && !visibleFiles.length && (
+                            <p className="performance-empty">
+                                No cached files match this filter. Try another
+                                search or choose All.
+                            </p>
+                        )}
+                    </section>
+                    {unlistedJobs.length > 0 && (
+                        <section
+                            className="preload-queue"
+                            aria-labelledby="preparation-heading"
+                        >
+                            <h3 id="preparation-heading">Preload queue</h3>
+                            <ul className="preload-jobs">
+                                {unlistedJobs.map(renderJob)}
+                            </ul>
+                        </section>
+                    )}
+                    {finished.length > 0 && (
+                        <details className="preload-recent">
+                            <summary>
+                                Recently stopped ({finished.length})
+                            </summary>
+                            <ul className="preload-jobs">
+                                {finished.slice(0, 5).map(renderJob)}
+                            </ul>
+                        </details>
+                    )}
+                    {notice && (
+                        <p className="performance-notice" role="status">
+                            {notice}
+                        </p>
+                    )}
+                </>
+            )}
+            <details className="preload-help">
+                <summary>About preloading</summary>
+                <div>
+                    <p>
+                        Choose <strong>Preload file</strong> from a file’s menu
+                        in My Files to cache the whole file on the server.
+                        Follow its progress here; <strong>Ready</strong> means
+                        every byte is currently cached.
+                    </p>
+                    <p>
+                        Media playback fetches requested chunks with bounded
+                        read-ahead. Automatic preloading can warm additional
+                        upcoming playback chunks; downloads fetch their
+                        requested ranges.
+                    </p>
+                    <p>
+                        Cache space is shared. Cached bytes may be removed when
+                        space is needed. Clearing cache removes server copies
+                        and stops preloading; originals stay in Telegram. Your
+                        device still needs a connection to the server.
+                    </p>
+                    <a
+                        className="inline-link"
+                        href="https://github.com/TechShreyash/TGDrive/blob/main/docs/usage.md#preload-a-file-for-smoother-playback-and-downloads"
+                        target="_blank"
+                        rel="noopener noreferrer"
+                    >
+                        Read the preloading guide
+                    </a>
+                </div>
+            </details>
+            {clearing && (
+                <Modal
+                    title={
+                        clearing.id
+                            ? "Clear cached file?"
+                            : "Clear all cached files?"
+                    }
+                    onClose={() => setClearing(null)}
+                    initialFocus=".preload-keep-cache"
+                >
+                    <p className="dialog-description">
+                        {clearing.id
+                            ? `Remove the server copy of “${clearing.name}”?`
+                            : "Remove all cached server copies and stop background preloading?"}{" "}
+                        Originals stay in Telegram. Future playback or downloads
+                        may need to fetch the data again.
+                    </p>
+                    <div className="dialog-actions">
+                        <button
+                            type="button"
+                            className="secondary-button preload-keep-cache"
+                            onClick={() => setClearing(null)}
+                        >
+                            Keep Cache
+                        </button>
+                        <button
+                            type="button"
+                            className="danger-button"
+                            onClick={() => {
+                                const target = clearing;
+                                setClearing(null);
+                                void act(
+                                    target.id ? "file:" + target.id : "clear",
+                                    () => performanceApi.clear(target.id),
+                                    target.id
+                                        ? "Cached bytes evicted. The original is unchanged."
+                                        : "Cached bytes cleared. Originals remain in Telegram.",
+                                );
+                            }}
+                        >
+                            {clearing.id
+                                ? "Clear Cached File"
+                                : "Clear All Cache"}
+                        </button>
+                    </div>
+                </Modal>
+            )}
+            {!snapshot && !loading && error && (
+                <button
+                    className="secondary-button"
+                    disabled={refreshing}
+                    aria-busy={refreshing}
+                    onClick={refreshInventory}
+                >
+                    {refreshing && <Spinner />}
+                    {refreshing ? "Refreshing…" : "Try Again"}
+                </button>
+            )}
+        </div>
+    );
+}
diff --git a/website/src/features/performance/StreamMemoryFact.tsx b/website/src/features/performance/StreamMemoryFact.tsx
new file mode 100644
index 00000000..91a56752
--- /dev/null
+++ b/website/src/features/performance/StreamMemoryFact.tsx
@@ -0,0 +1,20 @@
+import { formatByteProgress } from "../../shared/types";
+import type { ScratchSnapshot } from "./performanceApi";
+
+export default function StreamMemoryFact({
+    scratch,
+}: {
+    scratch?: ScratchSnapshot;
+}) {
+    if (!scratch) return null;
+    return (
+        <div>
+            <dt>Active stream memory</dt>
+            <dd>{formatByteProgress(scratch.bytes, scratch.max_bytes)}</dd>
+            <small>
+                {scratch.active_streams} streams · {scratch.waiting_heads}{" "}
+                waiting for memory; separate from retained cache
+            </small>
+        </div>
+    );
+}
diff --git a/website/src/features/performance/ThumbnailSettings.css b/website/src/features/performance/ThumbnailSettings.css
new file mode 100644
index 00000000..a2871bbc
--- /dev/null
+++ b/website/src/features/performance/ThumbnailSettings.css
@@ -0,0 +1,29 @@
+.thumbnail-rebuild-status {
+    margin-block: 16px;
+}
+.thumbnail-rebuild-status > p:first-child {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.thumbnail-rebuild-status progress {
+    width: 100%;
+    height: 8px;
+    accent-color: var(--action);
+}
+.thumbnail-rebuild-status p {
+    margin-block: 8px;
+}
+.thumbnail-current-file {
+    overflow-wrap: anywhere;
+}
+.thumbnail-rebuild-actions {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: flex-end;
+    gap: 12px;
+    margin-top: 24px;
+}
+.thumbnail-settings > button {
+    margin-top: 12px;
+}
diff --git a/website/src/features/performance/ThumbnailSettings.test.ts b/website/src/features/performance/ThumbnailSettings.test.ts
new file mode 100644
index 00000000..e382b4f9
--- /dev/null
+++ b/website/src/features/performance/ThumbnailSettings.test.ts
@@ -0,0 +1,14 @@
+import { expect, it } from "vitest";
+import { rebuildPercent, type ThumbnailRebuild } from "./ThumbnailSettings";
+
+it("reports checked files rather than implying byte completion while finding files", () => {
+    const state = {
+        status: "running",
+        total: 0,
+        processed: 0,
+    } as ThumbnailRebuild;
+    expect(rebuildPercent(state)).toBeUndefined();
+    expect(rebuildPercent({ ...state, total: 100, processed: 23 })).toBe(23);
+    expect(rebuildPercent({ ...state, status: "completed" })).toBe(100);
+    expect(rebuildPercent({ ...state, total: 2, processed: 4 })).toBe(100);
+});
diff --git a/website/src/features/performance/ThumbnailSettings.tsx b/website/src/features/performance/ThumbnailSettings.tsx
new file mode 100644
index 00000000..3f872b52
--- /dev/null
+++ b/website/src/features/performance/ThumbnailSettings.tsx
@@ -0,0 +1,225 @@
+import { useEffect, useRef, useState } from "react";
+import { Button, Fieldset } from "@mantine/core";
+import { RefreshCw } from "lucide-react";
+import { errorMessage, request } from "../../shared/api";
+import { ErrorNotice, Modal, Spinner } from "../../shared/components";
+import { formatBytes } from "../../shared/types";
+import "./ThumbnailSettings.css";
+
+export type ThumbnailRebuild = {
+    status:
+        | "idle"
+        | "running"
+        | "completed"
+        | "cancelled"
+        | "interrupted"
+        | "failed";
+    phase: string;
+    total: number;
+    processed: number;
+    generated: number;
+    skipped: number;
+    failed: number;
+    source_bytes: number;
+    persistence_warning?: string;
+    current_bytes?: number;
+    current_name?: string;
+    recent_issues?: { name: string; reason: string }[];
+};
+export function rebuildPercent(state: ThumbnailRebuild): number | undefined {
+    if (state.phase === "Finding files") return undefined;
+    if (!state.total) return state.status === "completed" ? 100 : undefined;
+    return Math.min(
+        100,
+        Math.max(0, Math.floor((state.processed / state.total) * 100)),
+    );
+}
+const endpoint = "/api/v1/settings/thumbnails/rebuild";
+export default function ThumbnailSettings({
+    demoMode = false,
+}: {
+    demoMode?: boolean;
+}) {
+    const [state, setState] = useState<ThumbnailRebuild | null>(null);
+    const [confirm, setConfirm] = useState(false);
+    const [busy, setBusy] = useState(false);
+    const [refresh, setRefresh] = useState(0);
+    const [loadError, setLoadError] = useState("");
+    const [error, setError] = useState("");
+    const action = useRef(false);
+    const mounted = useRef(true);
+    const generation = useRef(0);
+    useEffect(() => {
+        mounted.current = true;
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            let delay = 2000;
+            if (!action.current) {
+                const id = ++generation.current;
+                try {
+                    const value = await request<ThumbnailRebuild>(
+                        endpoint,
+                        undefined,
+                        {
+                            signal: controller.signal,
+                            timeoutMs: 15000,
+                        },
+                    );
+                    if (
+                        !controller.signal.aborted &&
+                        id === generation.current
+                    ) {
+                        setState(value);
+                        setLoadError("");
+                    }
+                    delay = value.status === "running" ? 2000 : 10000;
+                } catch (cause) {
+                    if (!controller.signal.aborted && id === generation.current)
+                        setLoadError(errorMessage(cause));
+                }
+            }
+            if (!controller.signal.aborted) timer = setTimeout(poll, delay);
+        };
+        void poll();
+        return () => {
+            mounted.current = false;
+            controller.abort();
+            clearTimeout(timer);
+            ++generation.current;
+        };
+    }, [refresh]);
+    const change = async (cancel = false) => {
+        if (demoMode || action.current) return;
+        action.current = true;
+        ++generation.current;
+        setBusy(true);
+        setError("");
+        try {
+            const value = await request<ThumbnailRebuild>(
+                endpoint + (cancel ? "/cancel" : ""),
+                cancel ? {} : { confirmed: true },
+            );
+            if (mounted.current) {
+                setState(value);
+                setConfirm(false);
+                setRefresh((value) => value + 1);
+            }
+        } catch (cause) {
+            if (mounted.current) setError(errorMessage(cause));
+        } finally {
+            action.current = false;
+            if (mounted.current) setBusy(false);
+        }
+    };
+    const running = state?.status === "running";
+    const percent = state ? rebuildPercent(state) : undefined;
+    return (
+        <Fieldset
+            className="performance-setting-group thumbnail-settings"
+            legend="Thumbnails"
+        >
+            <p className="settings-help">
+                New uploads generate thumbnails automatically. Rebuild covers
+                for files already stored, including old or missing covers.
+                Originals stay unchanged.
+            </p>
+            {state && state.status !== "idle" && (
+                <div className="thumbnail-rebuild-status">
+                    <p role="status">
+                        {running && <Spinner />} {state.phase}
+                    </p>
+                    <progress
+                        aria-label="Thumbnail rebuild progress"
+                        max={100}
+                        value={percent}
+                    />
+                    <p>
+                        {state.processed} / {state.total} files checked
+                        {percent !== undefined ? " · " + percent + "%" : ""}
+                    </p>
+                    <p>
+                        {state.generated} regenerated · {state.skipped} skipped
+                        · {state.failed} failed
+                    </p>
+                    {running && state.current_name && (
+                        <p className="thumbnail-current-file">
+                            {state.current_name} ·{" "}
+                            {formatBytes(state.current_bytes)} read
+                        </p>
+                    )}
+                    <p className="settings-help">
+                        {formatBytes(state.source_bytes)} source data read,
+                        including cached data. Existing covers remain when
+                        generation fails.
+                    </p>
+                    {(state.recent_issues?.length || 0) > 0 && (
+                        <details>
+                            <summary>Recent skipped or failed files</summary>
+                            <ul>
+                                {state.recent_issues?.map((issue, i) => (
+                                    <li key={i}>
+                                        {issue.name}: {issue.reason}
+                                    </li>
+                                ))}
+                            </ul>
+                        </details>
+                    )}
+                </div>
+            )}
+            {!confirm && <ErrorNotice message={error || loadError} />}
+            <ErrorNotice message={state?.persistence_warning || ""} />
+            <Button
+                type="button"
+                variant="default"
+                disabled={demoMode || busy || !state}
+                onClick={() => (running ? void change(true) : setConfirm(true))}
+            >
+                {busy ? <Spinner /> : <RefreshCw size={16} />}{" "}
+                {running ? "Cancel rebuild" : "Regenerate all thumbnails"}
+            </Button>
+            {confirm && (
+                <Modal
+                    title="Regenerate all thumbnails?"
+                    onClose={() => {
+                        if (!busy) setConfirm(false);
+                    }}
+                    initialFocus="[data-cancel-rebuild]"
+                >
+                    <p>
+                        This can take a long time and use substantial bandwidth
+                        when many files are stored. Cached data is reused where
+                        possible; some formats, especially PDFs, need larger
+                        reads.
+                    </p>
+                    <p>
+                        The task runs on the server after you close this page.
+                        It processes one file at a time, yields to active
+                        transfers and playback, and can be cancelled here. Some
+                        unsupported or oversized files will keep their existing
+                        cover or icon.
+                    </p>
+                    <ErrorNotice message={error} />
+                    <div className="thumbnail-rebuild-actions">
+                        <Button
+                            type="button"
+                            variant="default"
+                            data-cancel-rebuild
+                            disabled={busy}
+                            onClick={() => setConfirm(false)}
+                        >
+                            Cancel
+                        </Button>
+                        <Button
+                            type="button"
+                            disabled={busy}
+                            onClick={() => void change()}
+                        >
+                            {busy && <Spinner />} Start background rebuild
+                        </Button>
+                    </div>
+                </Modal>
+            )}
+        </Fieldset>
+    );
+}
diff --git a/website/src/features/performance/performance.test.tsx b/website/src/features/performance/performance.test.tsx
new file mode 100644
index 00000000..35acc454
--- /dev/null
+++ b/website/src/features/performance/performance.test.tsx
@@ -0,0 +1,576 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { ApiError } from "../../shared/api";
+import {
+    CacheCoverage,
+    CacheCapacity,
+    coverageRanges,
+    cachedFileComplete,
+    currentPreloadJobs,
+} from "./Preloads";
+import {
+    httpRates,
+    loadPoints,
+    queueWait,
+    recentSamples,
+    samplesInWindow,
+    nearestSampleAt,
+    customHistoryBounds,
+    historyDuration,
+    UsageMeter,
+    metricSegments,
+    metricCeiling,
+} from "./PerformancePanel";
+import StreamMemoryFact from "./StreamMemoryFact";
+import {
+    GIB,
+    MIB,
+    performanceApi,
+    performanceChanges,
+    performanceDraft,
+    performanceCategoryDraft,
+    type PerformancePreferences,
+    type PreloadJob,
+    type ResourceSample,
+} from "./performanceApi";
+
+export const preferences: PerformancePreferences = {
+    revision: '"revision-one"',
+    timezone: "Asia/Kolkata",
+    cache_memory_bytes: 256 * MIB,
+    cache_disk_bytes: 10 * GIB,
+    cache_min_free_bytes: GIB,
+    cache_ttl_seconds: 86400,
+    auto_preload: true,
+    preload_max_jobs: 2,
+    remote_download_concurrency: 2,
+    telegram_upload_pipeline: 4,
+    telegram_request_limit: 8,
+    telegram_parts_per_second: 24,
+    telegram_media_per_bot: 3,
+    telegram_max_queue: 256,
+    upload_split_mib: 2000,
+    max_file_size: 16 * GIB,
+    staging_budget_bytes: 16 * GIB,
+    min_free_bytes: GIB,
+};
+beforeEach(() => vi.stubGlobal("window", new EventTarget()));
+afterEach(() => vi.unstubAllGlobals());
+
+describe("performance settings and HTTP boundaries", () => {
+    it("saves only the visible category while unrelated invalid drafts remain untouched", () => {
+        const draft = {
+            ...performanceDraft(preferences),
+            timezone: "UTC",
+            cache_memory_bytes: "",
+        };
+        expect(
+            performanceChanges(
+                performanceCategoryDraft(draft, preferences, "regional"),
+                preferences,
+            ),
+        ).toEqual({ timezone: "UTC" });
+        expect(draft.cache_memory_bytes).toBe("");
+        expect(() =>
+            performanceChanges(
+                performanceCategoryDraft(draft, preferences, "cache"),
+                preferences,
+            ),
+        ).toThrow("Memory cache");
+        expect(
+            performanceChanges(
+                performanceCategoryDraft(
+                    { ...draft, upload_split_mib: "512" },
+                    preferences,
+                    "transfers",
+                ),
+                preferences,
+            ),
+        ).toEqual({ upload_split_mib: 512 });
+    });
+    it("roundtrips saved byte limits and sends only changed unit conversions", () => {
+        const draft = performanceDraft(preferences);
+        expect(draft.cache_memory_bytes).toBe("256");
+        expect(draft.cache_disk_bytes).toBe("10");
+        expect(draft.cache_ttl_seconds).toBe("24");
+        expect(performanceChanges(draft, preferences)).toEqual({});
+        expect(
+            performanceChanges(
+                {
+                    ...draft,
+                    cache_disk_bytes: "1.5",
+                    cache_memory_bytes: "512",
+                    cache_ttl_seconds: "2",
+                },
+                preferences,
+            ),
+        ).toEqual({
+            cache_disk_bytes: 1.5 * GIB,
+            cache_memory_bytes: 512 * MIB,
+            cache_ttl_seconds: 7200,
+        });
+        const odd = { ...preferences, cache_disk_bytes: GIB + 31 };
+        expect(performanceChanges(performanceDraft(odd), odd)).toEqual({});
+    });
+    it.each(["", "-1", "NaN", "Infinity", "9000"])(
+        "rejects invalid cache memory %s",
+        (value) => {
+            expect(() =>
+                performanceChanges(
+                    {
+                        ...performanceDraft(preferences),
+                        cache_memory_bytes: value,
+                    },
+                    preferences,
+                ),
+            ).toThrow("Memory cache");
+        },
+    );
+    it("rejects fractional concurrency and unknown timezones without coercion", () => {
+        expect(() =>
+            performanceChanges(
+                { ...performanceDraft(preferences), preload_max_jobs: "1.5" },
+                preferences,
+            ),
+        ).toThrow("whole number");
+        expect(() =>
+            performanceChanges(
+                { ...performanceDraft(preferences), timezone: "not/a-zone" },
+                preferences,
+            ),
+        ).toThrow("valid timezone");
+    });
+    it("guards preference writes with the exact revision and same-origin cookies", async () => {
+        const fetcher = vi.fn(async () => Response.json(preferences));
+        vi.stubGlobal("fetch", fetcher);
+        await performanceApi.save(
+            { cache_disk_bytes: GIB },
+            preferences.revision,
+        );
+        const [url, options] = fetcher.mock.calls[0] as unknown as [
+            string,
+            RequestInit,
+        ];
+        expect(url).toBe("/api/v1/settings/performance");
+        expect(options.credentials).toBe("same-origin");
+        expect(options.method).toBe("PATCH");
+        expect(new Headers(options.headers).get("If-Match")).toBe(
+            preferences.revision,
+        );
+        expect(JSON.parse(options.body as string)).toEqual({
+            cache_disk_bytes: GIB,
+        });
+    });
+    it("preserves conflict and preparation-capacity errors for actionable UI", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    {
+                        detail: "Reload the changed settings",
+                        code: "SETTINGS_CONFLICT",
+                    },
+                    { status: 409 },
+                ),
+            ),
+        );
+        await expect(
+            performanceApi.save({}, preferences.revision),
+        ).rejects.toMatchObject({ status: 409, code: "SETTINGS_CONFLICT" });
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    {
+                        detail: "Increase cache capacity",
+                        code: "PRELOAD_CAPACITY",
+                    },
+                    { status: 507 },
+                ),
+            ),
+        );
+        await expect(
+            performanceApi.prepare("/private-id"),
+        ).rejects.toBeInstanceOf(ApiError);
+        await expect(performanceApi.prepare("/private-id")).rejects.toThrow(
+            "Increase cache capacity",
+        );
+    });
+    it("encodes cancellation IDs and clears one cache file without passing source locations", async () => {
+        const fetcher = vi.fn(async () => Response.json({ status: "ok" }));
+        vi.stubGlobal("fetch", fetcher);
+        await performanceApi.cancel("opaque/id");
+        await performanceApi.clear("cache-id");
+        await performanceApi.clear();
+        const calls = fetcher.mock.calls as unknown as [string, RequestInit][];
+        expect(calls[0][0]).toBe("/api/v1/preloads/opaque%2Fid/cancel");
+        expect(JSON.parse(calls[1][1].body as string)).toEqual({
+            file_id: "cache-id",
+        });
+        expect(JSON.parse(calls[2][1].body as string)).toEqual({});
+    });
+});
+
+describe("cache coverage and observed queue estimates", () => {
+    it("shows actual tier usage and distinguishes zero capacity from unavailable memory", () => {
+        const usage = renderToStaticMarkup(
+            <CacheCapacity
+                label="Memory cache"
+                used={80 * MIB}
+                limit={256 * MIB}
+            />,
+        );
+        expect(usage).toContain("80 MB");
+        expect(usage).toContain("256 MB");
+        expect(usage).toContain("31%");
+        expect(usage).toContain('aria-valuetext="80 / 256 MB used (31%)"');
+        const disabled = renderToStaticMarkup(
+            <CacheCapacity
+                label="Disk cache"
+                used={0}
+                limit={0}
+                disabled
+                unavailable
+            />,
+        );
+        expect(disabled).toContain("Disabled");
+        expect(disabled).not.toContain("<progress");
+        const pressure = renderToStaticMarkup(
+            <CacheCapacity
+                label="Memory cache"
+                used={20}
+                limit={0}
+                unavailable
+            />,
+        );
+        expect(pressure).toContain("Unavailable");
+        expect(pressure).not.toContain("Disabled");
+        expect(pressure).not.toContain("NaN");
+    });
+    it("uses the latest per-file job before searching or showing old failures", () => {
+        const job = (
+            file_id: string,
+            state: string,
+            name: string,
+        ): PreloadJob => ({
+            id: name,
+            file_id,
+            state,
+            name,
+            mode: "manual",
+            bytes_done: 0,
+            target_bytes: 100,
+            size: 100,
+            start: 0,
+            end: 100,
+        });
+        const newest = job("finished", "ready", "Renamed movie.mp4");
+        const active = job("active", "preparing", "Streaming movie.mp4");
+        const cancelled = job("stopped", "cancelled", "Stopped movie.mp4");
+        const jobs = currentPreloadJobs([
+            newest,
+            active,
+            cancelled,
+            job("finished", "failed", "Old movie.mp4"),
+            job("active", "failed", "Old streaming movie.mp4"),
+            job("stopped", "failed", "Old stopped movie.mp4"),
+        ]);
+        expect(jobs).toEqual([newest, active, cancelled]);
+        expect(jobs.filter((value) => value.name.includes("Old"))).toEqual([]);
+        expect(jobs.filter((value) => value.state === "failed")).toEqual([]);
+    });
+    it("filters selected history without fabricating samples or joining missing intervals", () => {
+        const samples = Array.from({ length: 31 }, (_, index) => ({
+            at: index * 30,
+        }));
+        expect(samplesInWindow(samples, 60)).toEqual([
+            { at: 840 },
+            { at: 870 },
+            { at: 900 },
+        ]);
+        expect(samplesInWindow(samples, 900)).toHaveLength(31);
+        expect(samplesInWindow([{ at: Number.NaN }], 300)).toEqual([]);
+        expect(nearestSampleAt([{ at: 0 }, { at: 60 }, { at: 180 }], 100)).toBe(
+            60,
+        );
+        expect(nearestSampleAt([], 100)).toBeNull();
+        expect(historyDuration(225)).toBe("3 min 45 sec");
+        expect(historyDuration(3600)).toBe("1 hr");
+        expect(historyDuration(90000)).toBe("1 day 1 hr");
+    });
+    it("parses absolute UTC custom bounds and rejects normalized dates, reversed or excessive ranges", () => {
+        const now = Date.parse("2026-10-20T12:00:00Z") / 1000;
+        expect(
+            customHistoryBounds("2026-10-20T10:00", "2026-10-20T11:00", now),
+        ).toEqual({ start: now - 7200, end: now - 3600 });
+        expect(() =>
+            customHistoryBounds("2026-02-30T00:00", "2026-10-20T11:00", now),
+        ).toThrow("valid start");
+        expect(() =>
+            customHistoryBounds("2026-10-20T11:00", "2026-10-20T10:00", now),
+        ).toThrow("after start");
+        expect(() =>
+            customHistoryBounds("2026-09-01T00:00", "2026-10-20T11:00", now),
+        ).toThrow("at most 31");
+        expect(() =>
+            customHistoryBounds("2026-10-20T10:00", "2026-10-21T11:00", now),
+        ).toThrow("future");
+    });
+    it("plots real timestamp spacing and leaves null readings and source changes as gaps", () => {
+        const sample = (
+            at: number,
+            value: number | null,
+            scope: "cgroup" | "host" = "cgroup",
+        ): ResourceSample => ({
+            at,
+            cpu_percent: value,
+            cpu_scope: scope,
+            memory_bytes: null,
+            memory_limit_bytes: null,
+            received_bytes_per_second: null,
+            sent_bytes_per_second: null,
+            network_interface: "eth0",
+        });
+        expect(
+            metricSegments(
+                [sample(1, 0), sample(4, 50), sample(10, 100)],
+                "cpu_percent",
+                100,
+                "cpu_scope",
+            ),
+        ).toEqual(["0,112 200,62 600,12"]);
+        expect(
+            metricSegments(
+                [
+                    sample(1, 10),
+                    sample(4, null),
+                    sample(7, 50),
+                    sample(10, 60, "host"),
+                ],
+                "cpu_percent",
+                100,
+                "cpu_scope",
+            ),
+        ).toEqual(["0,102", "400,62", "600,52"]);
+        expect(
+            metricSegments([sample(1, 10), sample(40, 20)], "cpu_percent", 100),
+        ).toHaveLength(2);
+        expect(metricCeiling(0)).toBe(0);
+        expect(metricCeiling(12 * MIB)).toBe(20 * MIB);
+    });
+    it("keeps charts within a recent continuous window and rejects polling gaps", () => {
+        const history = [{ at: 1 }, { at: 4 }, { at: 400 }, { at: 403 }];
+        expect(recentSamples(history)).toEqual([{ at: 400 }, { at: 403 }]);
+        expect(recentSamples([{ at: 0 }, { at: 300 }, { at: 301 }])).toEqual([
+            { at: 300 },
+            { at: 301 },
+        ]);
+        expect(
+            httpRates([
+                {
+                    at: 0,
+                    upload_bytes: 0,
+                    download_bytes: 0,
+                    requests: 0,
+                    active: 0,
+                    errors: 0,
+                },
+                {
+                    at: 300,
+                    upload_bytes: 100,
+                    download_bytes: 100,
+                    requests: 1,
+                    active: 0,
+                    errors: 0,
+                },
+            ]),
+        ).toEqual([]);
+    });
+    it("does not invent resource utilization when the limit is unavailable", () => {
+        const html = renderToStaticMarkup(
+            <UsageMeter
+                label="RAM cache"
+                used={0}
+                total={0}
+                detail="Disabled"
+            />,
+        );
+        expect(html).toContain("Disabled");
+        expect(html).not.toContain("progress");
+        expect(
+            renderToStaticMarkup(
+                <UsageMeter label="Server RAM" used={50} total={100} />,
+            ),
+        ).toContain('value="50"');
+    });
+    it("shows sampled CPU as a percentage and preserves an unknown baseline", () => {
+        expect(
+            renderToStaticMarkup(
+                <UsageMeter
+                    label="Container CPU"
+                    used={25}
+                    total={100}
+                    percent
+                />,
+            ),
+        ).toContain("25.0%");
+        const missing = renderToStaticMarkup(
+            <UsageMeter
+                label="Container CPU"
+                used={NaN}
+                total={100}
+                percent
+                unavailableLabel="Measuring…"
+            />,
+        );
+        expect(missing).toContain("Measuring…");
+        expect(missing).not.toContain("0.0%");
+        expect(missing).not.toContain("progress");
+    });
+    it("shows the separate effective stream memory budget and tolerates older snapshots", () => {
+        expect(renderToStaticMarkup(<StreamMemoryFact />)).toBe("");
+        const html = renderToStaticMarkup(
+            <StreamMemoryFact
+                scratch={{
+                    bytes: MIB,
+                    max_bytes: 2 * MIB,
+                    configured_max_bytes: 32 * MIB,
+                    peak_bytes: 2 * MIB,
+                    active_streams: 4,
+                    waiting_heads: 2,
+                }}
+            />,
+        );
+        expect(html).toContain("1 / 2 MB");
+        expect(html).not.toContain("32 MB");
+        expect(html).toContain("4 streams · 2 waiting for memory");
+        expect(html).toContain("separate from retained cache");
+    });
+    it("merges verified coverage, clips EOF and ignores invalid ranges", () => {
+        expect(
+            coverageRanges(
+                [
+                    [8, 20],
+                    [-2, 4],
+                    [3, 8],
+                    [9, 7],
+                    [Number.NaN, 8],
+                ],
+                10,
+            ),
+        ).toEqual([[0, 10]]);
+        expect(coverageRanges([[0, 10]], 0)).toEqual([]);
+    });
+    it("paints fragmented cached ranges at their byte offsets without claiming complete", () => {
+        expect(
+            cachedFileComplete({
+                id: "x",
+                name: "Video",
+                size: 100,
+                ready_bytes: 100,
+                complete: true,
+                ready_ranges: [
+                    [0, 10],
+                    [90, 100],
+                ],
+            }),
+        ).toBe(false);
+        expect(
+            cachedFileComplete({
+                id: "x",
+                name: "Video",
+                size: 100,
+                ready_bytes: 0,
+                complete: false,
+                ready_ranges: [
+                    [0, 50],
+                    [50, 100],
+                ],
+            }),
+        ).toBe(true);
+        const html = renderToStaticMarkup(
+            <CacheCoverage
+                file={{
+                    id: "x",
+                    name: "Video",
+                    size: 100,
+                    ready_bytes: 99,
+                    complete: true,
+                    ready_ranges: [
+                        [0, 10],
+                        [90, 100],
+                    ],
+                }}
+            />,
+        );
+        expect(html).toContain('x="900"');
+        expect(html).toContain('width="100"');
+        expect(html).not.toContain("Complete");
+        expect(html).toContain("20 / 100 B cached");
+        expect(html).toContain("20% · Partial");
+        expect(html).toContain('data-complete="false"');
+        const complete = renderToStaticMarkup(
+            <CacheCoverage
+                file={{
+                    id: "ready",
+                    name: "Ready",
+                    size: 100,
+                    ready_bytes: 0,
+                    complete: false,
+                    ready_ranges: [
+                        [0, 50],
+                        [50, 100],
+                    ],
+                }}
+            />,
+        );
+        expect(complete).toContain('data-complete="true"');
+        expect(complete).toContain(
+            'width="1000" height="8" class="cache-coverage-ready"',
+        );
+        expect(complete).toContain("100% · Ready");
+    });
+    it("does not turn missing queue samples into a zero wait promise", () => {
+        expect(queueWait(null)).toBe("Estimating…");
+        expect(queueWait(Number.NaN)).toBe("Estimating…");
+        expect(queueWait(0)).toBe("Less than 1s");
+        expect(queueWait(61)).toBe("About 2m");
+        expect(loadPoints([], "active", 5)).toBe("");
+    });
+    it("uses measured byte differences and real sample spacing for throughput", () => {
+        const sample = (
+            at: number,
+            download_bytes: number,
+            upload_bytes: number,
+        ) => ({
+            at,
+            download_bytes,
+            upload_bytes,
+            requests: 1,
+            active: 0,
+            errors: 0,
+        });
+        expect(
+            httpRates([
+                sample(0, 0, 0),
+                sample(2, 200, 40),
+                sample(5, 500, 100),
+            ]),
+        ).toEqual([
+            { at: 2, active: 100, queued: 20 },
+            { at: 5, active: 100, queued: 20 },
+        ]);
+        expect(httpRates([sample(5, 500, 100), sample(6, 0, 0)])).toEqual([]);
+        expect(
+            loadPoints(
+                [
+                    { at: 0, active: 0, queued: 0 },
+                    { at: 3, active: 0, queued: 0 },
+                    { at: 9, active: 0, queued: 0 },
+                ],
+                "active",
+                1,
+            ),
+        ).toBe("0,120 200,120 600,120");
+    });
+});
diff --git a/website/src/features/performance/performanceApi.ts b/website/src/features/performance/performanceApi.ts
new file mode 100644
index 00000000..d7177143
--- /dev/null
+++ b/website/src/features/performance/performanceApi.ts
@@ -0,0 +1,534 @@
+import { request } from "../../shared/api";
+
+export const MIB = 1024 ** 2;
+export const GIB = 1024 ** 3;
+export interface PerformancePolicy {
+    timezone: string;
+    cache_memory_bytes: number;
+    cache_disk_bytes: number;
+    cache_min_free_bytes: number;
+    cache_ttl_seconds: number;
+    auto_preload: boolean;
+    preload_max_jobs: number;
+    remote_download_concurrency: number;
+    telegram_upload_pipeline: number;
+    telegram_request_limit: number;
+    telegram_parts_per_second: number;
+    telegram_media_per_bot: number;
+    telegram_max_queue: number;
+    upload_split_mib: number;
+    max_file_size: number;
+    staging_budget_bytes: number;
+    min_free_bytes: number;
+}
+export interface PerformancePreferences extends PerformancePolicy {
+    revision: string;
+    documentation_url?: string;
+    defaults?: PerformancePolicy;
+}
+export type NumericPreference = Exclude<
+    keyof PerformancePolicy,
+    "timezone" | "auto_preload"
+>;
+export const numericPreferences: {
+    key: NumericPreference;
+    label: string;
+    unit: number;
+    min: number;
+    max: number;
+    appDefault: number;
+    unitLabel?: string;
+    help: string;
+    advanced?: boolean;
+}[] = [
+    {
+        key: "remote_download_concurrency",
+        label: "Full-speed URL downloads",
+        unit: 1,
+        min: 1,
+        max: 8,
+        appDefault: 2,
+        help: "Imports downloading at full speed together. Queued sources receive slowly while connection and storage limits permit; expiring links can still fail.",
+    },
+    {
+        key: "cache_memory_bytes",
+        label: "Memory cache (MiB)",
+        unit: MIB,
+        min: 0,
+        max: 8192,
+        appDefault: 256,
+        unitLabel: "MiB",
+        help: "Recently viewed media kept in RAM. TGDrive reduces this budget when memory is tight. 0 turns this cache off.",
+    },
+    {
+        key: "cache_disk_bytes",
+        label: "Disk cache (GiB)",
+        unit: GIB,
+        min: 0,
+        max: 2048,
+        appDefault: 10,
+        unitLabel: "GiB",
+        help: "Disposable copies for repeat access, filled only as data arrives. 0 turns disk caching off; originals stay in Telegram.",
+    },
+    {
+        key: "cache_min_free_bytes",
+        label: "Cache free-space floor (GiB)",
+        unit: GIB,
+        min: 0,
+        max: 2048,
+        appDefault: 1,
+        unitLabel: "GiB",
+        help: "Leave this much disk space free when caching. It is not allocated or reserved. Keep 1 GiB or more for normal use.",
+    },
+    {
+        key: "cache_ttl_seconds",
+        label: "Disk cache retention (hours)",
+        unit: 3600,
+        min: 60 / 3600,
+        max: 744,
+        appDefault: 24,
+        unitLabel: "hours",
+        help: "Remove disk bytes after this much time without reuse. Space pressure can remove them sooner.",
+    },
+    {
+        key: "preload_max_jobs",
+        label: "Concurrent preloads",
+        unit: 1,
+        min: 1,
+        max: 8,
+        appDefault: 2,
+        help: "Files prepared in the background at once. Active playback and downloads always go first.",
+    },
+    {
+        key: "max_file_size",
+        label: "Maximum file size (GiB)",
+        unit: GIB,
+        min: 1 / GIB,
+        max: 2048,
+        appDefault: 16,
+        unitLabel: "GiB",
+        help: "Largest file accepted for a new upload. Large files are split automatically for Telegram. Must fit within the temporary upload budget.",
+    },
+    {
+        key: "staging_budget_bytes",
+        label: "Temporary upload budget (GiB)",
+        unit: GIB,
+        min: 1 / GIB,
+        max: 2048,
+        appDefault: 16,
+        unitLabel: "GiB",
+        help: "Space all unfinished uploads may use together. This is a ceiling, not preallocated disk space. Each upload also needs real free space.",
+    },
+    {
+        key: "min_free_bytes",
+        label: "Upload free-space reserve (GiB)",
+        unit: GIB,
+        min: 0.0625,
+        max: 2048,
+        appDefault: 1,
+        unitLabel: "GiB",
+        help: "Space uploads must leave free on their storage drive. Reservations from other uploads are checked before file data is sent.",
+    },
+    {
+        key: "upload_split_mib",
+        label: "File split size (MiB)",
+        unit: 1,
+        min: 0,
+        max: 2000,
+        appDefault: 2000,
+        unitLabel: "MiB",
+        help: "Default and maximum: 2000 MiB per Telegram document for every account. Choose a smaller size to split sooner; 0 uses 2000 MiB. Existing transfers keep their plan.",
+    },
+    {
+        key: "telegram_upload_pipeline",
+        label: "Upload pipeline",
+        unit: 1,
+        min: 1,
+        max: 16,
+        appDefault: 4,
+        help: "Parts sent in parallel within one upload. The shared account request limit also applies.",
+        advanced: true,
+    },
+    {
+        key: "telegram_request_limit",
+        label: "Requests per account",
+        unit: 1,
+        min: 1,
+        max: 32,
+        appDefault: 8,
+        help: "Concurrent Telegram requests, shared by uploads, downloads and file metadata.",
+        advanced: true,
+    },
+    {
+        key: "telegram_parts_per_second",
+        label: "Requests per second",
+        unit: 1,
+        min: 1,
+        max: 128,
+        appDefault: 48,
+        help: "Request pacing ceiling per account. Telegram cooldowns reduce the actual rate.",
+        advanced: true,
+    },
+    {
+        key: "telegram_media_per_bot",
+        label: "Media operations per account",
+        unit: 1,
+        min: 1,
+        max: 16,
+        appDefault: 3,
+        help: "Upload and download operations sharing one account. Cached viewers do not need a Telegram download slot.",
+        advanced: true,
+    },
+    {
+        key: "telegram_max_queue",
+        label: "Maximum queued operations",
+        unit: 1,
+        min: 1,
+        max: 4096,
+        appDefault: 256,
+        help: "Waiting Telegram operations before excess work is asked to retry. A larger queue allows longer waits, not more speed.",
+        advanced: true,
+    },
+];
+export type PerformanceDraft = Record<NumericPreference, string> & {
+    timezone: string;
+    auto_preload: boolean;
+};
+export type PerformanceCategory = "cache" | "transfers" | "regional";
+export function performanceCategoryKeys(
+    category: PerformanceCategory,
+): (keyof PerformanceDraft)[] {
+    if (category === "regional") return ["timezone"];
+    return [
+        ...numericPreferences
+            .filter(({ key }) =>
+                category === "cache"
+                    ? key.startsWith("cache_") || key === "preload_max_jobs"
+                    : key.startsWith("telegram_") ||
+                      [
+                          "upload_split_mib",
+                          "max_file_size",
+                          "staging_budget_bytes",
+                          "min_free_bytes",
+                          "remote_download_concurrency",
+                      ].includes(key),
+            )
+            .map(({ key }) => key),
+        ...(category === "cache" ? ["auto_preload" as const] : []),
+    ];
+}
+export function performanceCategoryDraft(
+    draft: PerformanceDraft,
+    saved: PerformancePreferences,
+    category: PerformanceCategory,
+): PerformanceDraft {
+    const result = performanceDraft(saved);
+    for (const key of performanceCategoryKeys(category))
+        Object.assign(result, { [key]: draft[key] });
+    return result;
+}
+export function performanceDraft(saved: PerformancePolicy): PerformanceDraft {
+    return Object.fromEntries([
+        ...numericPreferences.map(({ key, unit }) => [
+            key,
+            String(
+                (saved[key] ??
+                    (key === "max_file_size" || key === "staging_budget_bytes"
+                        ? 16 * GIB
+                        : key === "min_free_bytes"
+                          ? GIB
+                          : key === "remote_download_concurrency"
+                            ? 2
+                            : 0)) / unit,
+            ),
+        ]),
+        ["timezone", saved.timezone],
+        ["auto_preload", saved.auto_preload],
+    ]) as PerformanceDraft;
+}
+export function performanceChanges(
+    draft: PerformanceDraft,
+    saved: PerformancePreferences,
+): Partial<PerformancePreferences> {
+    const changes: Partial<PerformancePreferences> = {};
+    const baseline = performanceDraft(saved);
+    for (const { key, label, unit, min, max } of numericPreferences) {
+        const value = Number(draft[key]);
+        if (
+            !draft[key].trim() ||
+            !Number.isFinite(value) ||
+            value < min ||
+            value > max ||
+            (unit === 1 && !Number.isInteger(value))
+        )
+            throw new Error(
+                label +
+                    " must be " +
+                    (unit === 1 ? "a whole number " : "a number ") +
+                    "between " +
+                    min +
+                    " and " +
+                    max +
+                    ".",
+            );
+        const converted = Math.round(value * unit);
+        if (!Number.isSafeInteger(converted))
+            throw new Error(label + " is too large.");
+        if (converted !== Math.round(Number(baseline[key]) * unit))
+            changes[key] = converted;
+    }
+    const timezone = draft.timezone.trim();
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: timezone }).format();
+    } catch {
+        throw new Error("Use a valid timezone, such as Asia/Kolkata.");
+    }
+    if (timezone !== saved.timezone) changes.timezone = timezone;
+    if (draft.auto_preload !== saved.auto_preload)
+        changes.auto_preload = draft.auto_preload;
+    return changes;
+}
+export interface CachedFile {
+    id: string;
+    last_download?: number;
+    name: string;
+    size: number;
+    ready_bytes: number;
+    complete: boolean;
+    ready_ranges: [number, number][];
+    memory_ranges?: [number, number][];
+    disk_ranges?: [number, number][];
+}
+export interface ScratchSnapshot {
+    bytes: number;
+    max_bytes: number;
+    configured_max_bytes: number;
+    peak_bytes: number;
+    waiting_heads: number;
+    active_streams: number;
+}
+export interface CacheSnapshot {
+    scratch?: ScratchSnapshot;
+    memory: {
+        bytes: number;
+        max_bytes: number;
+        effective_max_bytes: number;
+        hits: number;
+        misses: number;
+        entries?: number;
+    };
+    disk: {
+        available: boolean;
+        bytes: number;
+        max_bytes: number;
+        free_bytes?: number | null;
+        min_free_bytes?: number;
+        hits?: number;
+        misses?: number;
+        evictions?: number;
+        write_failures?: number;
+        entries?: number;
+    };
+    files: CachedFile[];
+    pending_writes: number;
+}
+export interface PreloadJob {
+    id: string;
+    file_id: string;
+    name: string;
+    state: string;
+    mode: string;
+    bytes_done: number;
+    target_bytes: number;
+    size: number;
+    start: number;
+    end: number;
+    ready_bytes?: number;
+    complete?: boolean;
+    error?: string | null;
+}
+export interface PreloadSnapshot {
+    jobs: PreloadJob[];
+    active_jobs: number;
+    max_background_jobs: number;
+    cache: CacheSnapshot;
+}
+export interface LoadSample {
+    at: number;
+    active: number;
+    queued: number;
+}
+export interface QueueEntry {
+    position: number;
+    priority: string;
+    operation: string;
+    waiting_seconds: number;
+    estimated_wait_seconds: number | null;
+    request_id?: string;
+    client_name?: string | null;
+}
+export interface AccountPerformance {
+    name: string;
+    kind: string;
+    uploads: number;
+    downloads: number;
+    combined_limit: number;
+    cooldown_seconds: number;
+    requests?: {
+        active: number;
+        queued: number;
+        configured_limit: number;
+        effective_limit: number;
+        configured_parts_per_second: number;
+        effective_parts_per_second: number;
+        floods: number;
+        failed: number;
+        completed: number;
+        bytes: number;
+        cooldown_seconds?: number;
+        upload_bytes?: number;
+        download_bytes?: number;
+    } | null;
+}
+export interface PerformanceSnapshot {
+    traffic?: TrafficSample & {
+        started_at: number;
+        history: TrafficSample[];
+        download_bytes_per_second?: number | null;
+        upload_bytes_per_second?: number | null;
+    };
+    telegram: {
+        active: number;
+        queued: number;
+        max_queue: number;
+        estimates: boolean;
+        mean_activity_seconds: number | null;
+        queue: QueueEntry[];
+        accounts: AccountPerformance[];
+        history: LoadSample[];
+        active_requests?: {
+            request_id: string;
+            client_name: string;
+            priority: string;
+            operation: string;
+            elapsed_seconds: number;
+        }[];
+    };
+    cache: CacheSnapshot;
+    server: {
+        history?: ResourceSample[];
+        at: number;
+        memory: Record<string, number | null>;
+        process_peak_rss_bytes: number;
+        process_rss_bytes?: number | null;
+        cpu_count?: number;
+        cpu?: {
+            percent: number | null;
+            scope: "cgroup" | "host" | null;
+            capacity_cores?: number;
+        };
+        network?: {
+            available: boolean;
+            interface: string | null;
+            started_at: number;
+            received_bytes: number;
+            sent_bytes: number;
+            received_bytes_per_second: number | null;
+            sent_bytes_per_second: number | null;
+            scope: string;
+        };
+        load_average: number[];
+        disk: { total_bytes: number; free_bytes: number; used_bytes: number };
+        staging_budget_bytes: number;
+    };
+    drive: { files: number; folders: number; total_bytes: number };
+    history_scope?: string;
+}
+export interface ResourceSample {
+    at: number;
+    end_at?: number;
+    cpu_percent: number | null;
+    cpu_scope: "cgroup" | "host" | null;
+    memory_bytes: number | null;
+    memory_limit_bytes: number | null;
+    received_bytes_per_second: number | null;
+    sent_bytes_per_second: number | null;
+    network_interface: string | null;
+    coverage_seconds?: Record<string, number>;
+}
+export interface PerformanceHistory {
+    start: number;
+    end: number;
+    bucket_seconds: number;
+    samples: ResourceSample[];
+    retention_seconds: number;
+    earliest_at: number | null;
+    tracked_since: number | null;
+    last_updated?: number | null;
+    available: boolean;
+    totals: {
+        network_received_bytes: number | null;
+        network_sent_bytes: number | null;
+        http_upload_bytes: number | null;
+        http_download_bytes: number | null;
+        http_requests: number | null;
+        http_errors: number | null;
+        telegram_upload_bytes?: number | null;
+        telegram_download_bytes?: number | null;
+    };
+}
+export interface TrafficSample {
+    at: number;
+    requests: number;
+    active: number;
+    download_bytes: number;
+    upload_bytes: number;
+    errors: number;
+}
+export const performanceApi = {
+    history: (start: number, end: number, signal?: AbortSignal) =>
+        request<PerformanceHistory>(
+            "/api/v1/performance/history?" +
+                new URLSearchParams({ start: String(start), end: String(end) }),
+            undefined,
+            {
+                signal,
+                timeoutMs: 15000,
+            },
+        ),
+    settings: (signal?: AbortSignal) =>
+        request<PerformancePreferences>(
+            "/api/v1/settings/performance",
+            undefined,
+            {
+                signal,
+            },
+        ),
+    save: (changes: Partial<PerformancePreferences>, revision: string) =>
+        request<PerformancePreferences>(
+            "/api/v1/settings/performance",
+            changes,
+            {
+                method: "PATCH",
+                headers: { "If-Match": revision },
+            },
+        ),
+    preloads: (signal?: AbortSignal) =>
+        request<PreloadSnapshot>("/api/v1/preloads", undefined, { signal }),
+    prepare: (path: string) =>
+        request<PreloadJob>("/api/v1/preloads", { path }),
+    clear: (fileId?: string) =>
+        request<{ status: string }>(
+            "/api/v1/preloads/clear",
+            fileId ? { file_id: fileId } : {},
+        ),
+    cancel: (id: string) =>
+        request<{ status: string }>(
+            "/api/v1/preloads/" + encodeURIComponent(id) + "/cancel",
+            {},
+        ),
+    snapshot: (signal?: AbortSignal) =>
+        request<PerformanceSnapshot>("/api/v1/performance", undefined, {
+            signal,
+        }),
+};
diff --git a/website/src/features/previews/Preview.css b/website/src/features/previews/Preview.css
new file mode 100644
index 00000000..38ba8959
--- /dev/null
+++ b/website/src/features/previews/Preview.css
@@ -0,0 +1,54 @@
+/* Keep preview controls reachable when browser chrome or rotation reduces space. */
+.file-preview .preview-surface-message {
+    overflow: auto;
+    overscroll-behavior: contain;
+}
+.file-preview .preview-surface-message > .empty-state {
+    flex-shrink: 0;
+    width: min(100%, 55ch);
+    margin: auto;
+    overflow-wrap: anywhere;
+}
+.file-preview:not(.file-details) .preview-header {
+    padding-left: max(10px, env(safe-area-inset-left));
+    padding-right: max(16px, env(safe-area-inset-right));
+}
+.file-preview .preview-surface-audio {
+    padding-bottom: max(24px, env(safe-area-inset-bottom));
+}
+
+@media (max-width: 720px), (pointer: coarse) {
+    .file-preview:not(.file-details) .preview-header {
+        padding-top: max(8px, env(safe-area-inset-top));
+        padding-right: max(10px, env(safe-area-inset-right));
+    }
+    .file-preview .preview-header .icon-button,
+    .file-preview .preview-download {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .file-preview .preview-document-toolbar {
+        flex-wrap: wrap;
+        gap: 4px 12px;
+    }
+    .file-preview .preview-document-toolbar label {
+        min-height: 44px;
+    }
+    .file-preview .preview-quality {
+        flex-wrap: wrap;
+        gap: 4px 12px;
+        padding-left: max(12px, env(safe-area-inset-left));
+        padding-right: max(12px, env(safe-area-inset-right));
+    }
+    .file-preview .preview-quality select {
+        min-height: 44px;
+    }
+    .file-preview .preview-surface-audio {
+        padding-bottom: max(12px, env(safe-area-inset-bottom));
+    }
+    .file-preview .preview-surface-message .secondary-button {
+        min-height: 44px;
+        max-width: 100%;
+        white-space: normal;
+    }
+}
diff --git a/website/src/features/previews/Preview.routing.test.ts b/website/src/features/previews/Preview.routing.test.ts
new file mode 100644
index 00000000..8865a184
--- /dev/null
+++ b/website/src/features/previews/Preview.routing.test.ts
@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { loadPreview, nativePreviewKind } from "./Preview";
+
+afterEach(() => vi.unstubAllGlobals());
+
+describe("content-confirmed transport stream routing", () => {
+    it.each(["async-await.ts", "lecture.TS", "module.mts", "module.cts"])(
+        "asks the bounded descriptor before choosing a viewer for %s",
+        (name) => {
+            expect(nativePreviewKind(name)).toBeNull();
+        },
+    );
+
+    it("accepts the additive content-confirmed video descriptor", async () => {
+        const descriptor = { kind: "video", name: "actual.ts", size: 100956 };
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json(descriptor)),
+        );
+        await expect(
+            loadPreview("/bound-file-id", "", new AbortController().signal),
+        ).resolves.toEqual(descriptor);
+    });
+
+    it("retains inert TypeScript source when the descriptor says text", async () => {
+        const descriptor = {
+            kind: "text",
+            text: "export const video = '<script>safe</script>';",
+            language: "typescript",
+            size: 50,
+        };
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json(descriptor)),
+        );
+        await expect(
+            loadPreview("/bound-file-id", "", new AbortController().signal),
+        ).resolves.toEqual(descriptor);
+    });
+
+    it("routes SVGs to the passive image viewer", () => {
+        expect(nativePreviewKind("drawing.svg")).toBe("image");
+        expect(nativePreviewKind("drawing.SVG")).toBe("image");
+        expect(nativePreviewKind("movie.m2ts")).toBe("video");
+    });
+
+    it("rejects unrecognized descriptor viewers", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json({ kind: "html", size: 12 })),
+        );
+        await expect(
+            loadPreview("/bound-file-id", "", new AbortController().signal),
+        ).rejects.toThrow("invalid preview");
+    });
+});
diff --git a/website/src/features/previews/Preview.test.ts b/website/src/features/previews/Preview.test.ts
new file mode 100644
index 00000000..0ec15acf
--- /dev/null
+++ b/website/src/features/previews/Preview.test.ts
@@ -0,0 +1,211 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import {
+    displayText,
+    loadPreview,
+    nativePreviewKind,
+    previewRetryDelay,
+} from "./Preview";
+import { fileUrl } from "../../shared/types";
+import { api } from "../../shared/api";
+const viewerLoaders = vi.hoisted(
+    () => [] as Parameters<(typeof import("react"))["lazy"]>[0][],
+);
+vi.mock("react", async (importOriginal) => {
+    const react = await importOriginal<typeof import("react")>();
+    return {
+        ...react,
+        lazy(load: Parameters<typeof react.lazy>[0]) {
+            viewerLoaders.push(load);
+            return react.lazy(load);
+        },
+    };
+});
+vi.mock("./pdf/PdfPreview", () => {
+    throw new Error("The PDF viewer chunk is unavailable.");
+});
+vi.mock("./books/BookPreview", () => {
+    throw new Error("The book viewer chunk is unavailable.");
+});
+afterEach(() => vi.unstubAllGlobals());
+describe("bounded safe previews", () => {
+    it("retries a full Telegram queue twice without shortening its retry delay", () => {
+        const status = {
+            phase: "retry_wait" as const,
+            code: "TELEGRAM_QUEUE_FULL",
+            retry_after: 17,
+        };
+        expect(previewRetryDelay(status, 0)).toBe(17000);
+        expect(previewRetryDelay(status, 1)).toBe(17000);
+        expect(previewRetryDelay(status, 2)).toBeNull();
+        expect(previewRetryDelay({ ...status, retry_after: 0 }, 0)).toBe(1000);
+    });
+    it("does not auto-retry permanent, unclassified or invalid preview failures", () => {
+        expect(previewRetryDelay({}, 0)).toBeNull();
+        expect(
+            previewRetryDelay({ phase: "error", code: "FILE_REMOVED" }, 0),
+        ).toBeNull();
+        expect(
+            previewRetryDelay({ code: "TELEGRAM_QUEUE_FULL" }, 0),
+        ).toBeNull();
+        for (const seconds of [-1, Number.NaN, Infinity, 2147484])
+            expect(
+                previewRetryDelay(
+                    {
+                        phase: "retry_wait",
+                        code: "TELEGRAM_QUEUE_FULL",
+                        retry_after: seconds,
+                    },
+                    0,
+                ),
+            ).toBeNull();
+    });
+    it("does not let a delayed preview 401 dismiss a newer login", async () => {
+        const events = new EventTarget();
+        const expired = vi.fn();
+        events.addEventListener("tgdrive:auth-required", expired);
+        vi.stubGlobal("window", events);
+        let finish!: (response: Response) => void;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn((url: string) =>
+                url.startsWith("/api/v1/preview?")
+                    ? new Promise<Response>((resolve) => {
+                          finish = resolve;
+                      })
+                    : Promise.resolve(Response.json({ status: "ok" })),
+            ),
+        );
+        const pending = loadPreview(
+            "/id",
+            "",
+            new AbortController().signal,
+        ).catch((error) => error);
+        await api.login("owner");
+        finish(
+            Response.json(
+                { detail: "Old preview session expired" },
+                { status: 401 },
+            ),
+        );
+        expect(await pending).toBeInstanceOf(Error);
+        expect(expired).not.toHaveBeenCalled();
+    });
+
+    it("keeps recovery controls available when a document viewer chunk rejects", async () => {
+        expect(viewerLoaders).toHaveLength(2);
+        for (const load of viewerLoaders) {
+            const viewer = await load();
+            const html = renderToStaticMarkup(createElement(viewer.default));
+            expect(html).toContain("Viewer could not load");
+            expect(html).toContain("Reload Viewer");
+            expect(html).toContain("download the original");
+        }
+    });
+    it("formats valid JSON while preserving incomplete JSON and markup as text", () => {
+        expect(displayText('{"ok":true}', "json")).toBe('{\n  "ok": true\n}');
+        expect(displayText('{"incomplete":', "json")).toBe('{"incomplete":');
+        expect(displayText("<script>alert(1)</script>", "html")).toBe(
+            "<script>alert(1)</script>",
+        );
+        expect(nativePreviewKind("drawing.svg")).toBe("image");
+        expect(nativePreviewKind("clip.MP4")).toBe("video");
+    });
+    it("keeps original download policy separate from preview/playback", () => {
+        const url = new URL(
+            fileUrl("/folder/id", "scoped token", true),
+            "https://drive.test",
+        );
+        expect(url.searchParams.get("download")).toBe("1");
+        expect(url.searchParams.get("auth")).toBe("scoped token");
+        expect(url.searchParams.has("quality")).toBe(false);
+        expect(fileUrl("/folder/id")).not.toContain("download");
+    });
+    it("passes scoped authorization and cancellation to the descriptor request", async () => {
+        const fetcher = vi.fn(async () =>
+            Response.json({
+                kind: "text",
+                text: "safe",
+                size: 4,
+                language: "text",
+            }),
+        );
+        vi.stubGlobal("fetch", fetcher);
+        const controller = new AbortController();
+        expect(
+            await loadPreview("/id", "share secret", controller.signal),
+        ).toMatchObject({ text: "safe" });
+        const [url, options] = fetcher.mock.calls[0] as unknown as [
+            string,
+            RequestInit,
+        ];
+        expect(
+            new URL(url, "https://drive.test").searchParams.get("auth"),
+        ).toBe("share secret");
+        expect(options.credentials).toBe("same-origin");
+        expect(options.signal).toBeInstanceOf(AbortSignal);
+        controller.abort();
+        expect(options.signal?.aborted).toBe(true);
+    });
+    it("rejects oversized and malformed responses instead of rendering them", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => new Response("x".repeat(2 * 1024 * 1024 + 1))),
+        );
+        await expect(
+            loadPreview("/id", "", new AbortController().signal),
+        ).rejects.toThrow("too large");
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json({ kind: "text", text: 17 })),
+        );
+        await expect(
+            loadPreview("/id", "", new AbortController().signal),
+        ).rejects.toThrow("invalid preview");
+    });
+    it.each([
+        { kind: "unsupported", size: -1 },
+        { kind: "unsupported", size: "10" },
+        { kind: "unsupported", size: 10, reason: { text: "untrusted object" } },
+        { kind: "unsupported", size: 10, reason: "x".repeat(2001) },
+        { kind: "text", text: "safe", size: 4, language: {} },
+        { kind: "text", text: "safe", size: 4, truncated: "yes" },
+    ])("rejects invalid optional descriptor fields: %j", async (data) => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json(data)),
+        );
+        await expect(
+            loadPreview("/id", "", new AbortController().signal),
+        ).rejects.toThrow("invalid preview");
+    });
+    it("preserves a zero-byte unsupported file and its plain-text explanation", async () => {
+        const data = {
+            kind: "unsupported",
+            size: 0,
+            reason: "This format does not have a browser preview.",
+        };
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json(data)),
+        );
+        await expect(
+            loadPreview("/id", "", new AbortController().signal),
+        ).resolves.toEqual(data);
+    });
+    it("preserves actionable authorization and backend errors", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    { detail: "This link has expired." },
+                    { status: 403 },
+                ),
+            ),
+        );
+        await expect(
+            loadPreview("/id", "", new AbortController().signal),
+        ).rejects.toThrow("expired");
+    });
+});
diff --git a/website/src/features/previews/Preview.tsx b/website/src/features/previews/Preview.tsx
new file mode 100644
index 00000000..e7954a92
--- /dev/null
+++ b/website/src/features/previews/Preview.tsx
@@ -0,0 +1,928 @@
+import AdvancedVideo from "./video/AdvancedVideo";
+import "./Preview.css";
+import "./Reader.css";
+import { readBoundedResponse, PreviewLimitError } from "./previewIO";
+import { lazy, Suspense, useEffect, useRef, useState } from "react";
+import {
+    AlertCircle,
+    ArrowLeft,
+    ChevronDown,
+    ChevronUp,
+    Download,
+    Maximize,
+    Minimize,
+    RefreshCw,
+    X,
+} from "lucide-react";
+import { request, errorMessage, sessionExpiryHandler } from "../../shared/api";
+import {
+    itemPath,
+    fileUrl,
+    formatBytes,
+    formatDate,
+    mediaRequestId,
+    type DriveItem,
+    type PreviewDescriptor,
+} from "../../shared/types";
+import { FileIcon, Spinner } from "../../shared/components";
+
+function ViewerUnavailable() {
+    return (
+        <div className="empty-state">
+            <AlertCircle size={34} />
+            <h3>Viewer could not load</h3>
+            <p>
+                Check your connection and reload the viewer, or download the
+                original.
+            </p>
+            <button
+                className="secondary-button"
+                onClick={() => window.location.reload()}
+            >
+                <RefreshCw size={16} /> Reload Viewer
+            </button>
+        </div>
+    );
+}
+const PdfPreview = lazy(() =>
+    import("./pdf/PdfPreview").catch(() => ({ default: ViewerUnavailable })),
+);
+
+const BookPreview = lazy(() =>
+    import("./books/BookPreview").catch(() => ({ default: ViewerUnavailable })),
+);
+
+export function nativePreviewKind(
+    name: string,
+): "image" | "video" | "audio" | null {
+    const extension = name.split(".").at(-1)?.toLowerCase() || "";
+    if (
+        [
+            "png",
+            "jpg",
+            "jpeg",
+            "gif",
+            "webp",
+            "avif",
+            "bmp",
+            "ico",
+            "svg",
+        ].includes(extension)
+    )
+        return "image";
+    if (
+        [
+            "mp4",
+            "mkv",
+            "webm",
+            "mov",
+            "ogv",
+            "m4v",
+            "avi",
+            "mpeg",
+            "mpg",
+            "3gp",
+            "m2ts",
+            "flv",
+            "wmv",
+            "vob",
+        ].includes(extension)
+    )
+        return "video";
+    if (
+        ["mp3", "wav", "ogg", "flac", "m4a", "aac", "opus", "weba"].includes(
+            extension,
+        )
+    )
+        return "audio";
+    return null;
+}
+export function displayText(text: string, language?: string): string {
+    if (language?.toLowerCase() === "json") {
+        try {
+            const formatted = JSON.stringify(JSON.parse(text), null, 2);
+            return formatted.length <= 524288 ? formatted : text;
+        } catch {
+            /* Keep incomplete/invalid JSON readable. */
+        }
+    }
+    return text;
+}
+/** Bound even an unexpectedly large proxy response; never interpret file text as markup. */
+export async function loadPreview(
+    path: string,
+    auth: string,
+    signal: AbortSignal,
+): Promise<PreviewDescriptor> {
+    const expireSession = sessionExpiryHandler();
+    const params = new URLSearchParams({ path });
+    if (auth) params.set("auth", auth);
+    const response = await fetch("/api/v1/preview?" + params, {
+        credentials: "same-origin",
+        signal: AbortSignal.any([signal, AbortSignal.timeout(30000)]),
+        headers: { Accept: "application/json" },
+    });
+    expireSession(response.status);
+    let content: string;
+    try {
+        content = new TextDecoder().decode(
+            await readBoundedResponse(response, 2 * 1024 * 1024, signal),
+        );
+    } catch (error) {
+        if (error instanceof PreviewLimitError)
+            throw new Error(
+                "This preview is too large to display. Download the original instead.",
+            );
+        throw error;
+    }
+    let data: PreviewDescriptor & { detail?: string };
+    try {
+        data = JSON.parse(content);
+    } catch {
+        throw new Error(
+            "The server returned an unreadable preview. Try Again.",
+        );
+    }
+    if (!response.ok) {
+        throw new Error(
+            typeof data?.detail === "string"
+                ? data.detail
+                : "This preview could not be loaded. Try Again.",
+        );
+    }
+    if (
+        !data ||
+        typeof data !== "object" ||
+        !["text", "pdf", "video", "book", "unsupported"].includes(data.kind) ||
+        (data.size !== undefined &&
+            (!Number.isSafeInteger(data.size) || data.size < 0)) ||
+        (data.reason !== undefined &&
+            (typeof data.reason !== "string" || data.reason.length > 2000)) ||
+        (data.language !== undefined && typeof data.language !== "string") ||
+        (data.truncated !== undefined && typeof data.truncated !== "boolean") ||
+        (data.url !== undefined && typeof data.url !== "string") ||
+        (data.kind === "text" &&
+            (typeof data.text !== "string" || data.text.length > 262144))
+    )
+        throw new Error(
+            "The server returned an invalid preview. Download the original instead.",
+        );
+    return data;
+}
+function safePdfUrl(value?: string): string | undefined {
+    if (!value) return;
+    try {
+        const url = new URL(value, window.location.origin);
+        if (
+            url.origin === window.location.origin &&
+            url.pathname === "/file" &&
+            url.searchParams.get("preview") === "1"
+        )
+            return url.pathname + url.search;
+    } catch {
+        /* An invalid descriptor cannot become an iframe navigation. */
+    }
+}
+type FileRequestStatus = {
+    queue?: {
+        position: number;
+        estimated_wait_seconds: number | null;
+    } | null;
+    phase?:
+        | "checking_file"
+        | "waiting_for_telegram"
+        | "receiving"
+        | "retry_wait"
+        | "error"
+        | null;
+    retry_after?: number | null;
+    code?: string | null;
+};
+export function previewRetryDelay(status: FileRequestStatus, retries: number) {
+    if (
+        retries >= 2 ||
+        status.code !== "TELEGRAM_QUEUE_FULL" ||
+        status.phase !== "retry_wait"
+    )
+        return null;
+    const seconds = status.retry_after ?? 1;
+    if (!Number.isFinite(seconds) || seconds < 0 || seconds > 2147483)
+        return null;
+    return Math.max(1000, Math.ceil(seconds * 1000));
+}
+export default function Preview({
+    item,
+    auth,
+    onClose,
+}: {
+    item: DriveItem;
+    auth: string;
+    onClose: () => void;
+}) {
+    const nativeKind = nativePreviewKind(item.name);
+    const path = itemPath(item);
+    const viewer = useRef<HTMLDialogElement>(null);
+    const fullscreenSurface = useRef<HTMLDivElement>(null);
+    const [fullscreen, setFullscreen] = useState(false);
+    const [toolbarCollapsed, setToolbarCollapsed] = useState(false);
+    const [fullscreenError, setFullscreenError] = useState("");
+    useEffect(() => {
+        const surface = fullscreenSurface.current;
+        let wasFullscreen = false;
+        const update = () => {
+            const fullscreenElement = document.fullscreenElement;
+            const active = fullscreenElement === surface;
+            const containsFullscreen = Boolean(
+                fullscreenElement && surface?.contains(fullscreenElement),
+            );
+            const exited = wasFullscreen && !containsFullscreen;
+            wasFullscreen = containsFullscreen;
+            setFullscreen(active);
+            setToolbarCollapsed(false);
+            if (active || exited)
+                requestAnimationFrame(() =>
+                    surface
+                        ?.querySelector<HTMLButtonElement>(
+                            active
+                                ? ".preview-toolbar-toggle"
+                                : ".preview-fullscreen",
+                        )
+                        ?.focus({ preventScroll: true }),
+                );
+        };
+        document.addEventListener("fullscreenchange", update);
+        return () => {
+            document.removeEventListener("fullscreenchange", update);
+            if (
+                document.fullscreenElement &&
+                surface?.contains(document.fullscreenElement)
+            )
+                void document.exitFullscreen().catch(() => {});
+        };
+    }, []);
+    async function toggleFullscreen() {
+        setFullscreenError("");
+        try {
+            const surface = fullscreenSurface.current;
+            const target =
+                kind === "video"
+                    ? surface?.querySelector<HTMLElement>("movi-player")
+                    : surface;
+            if (
+                document.fullscreenElement &&
+                surface?.contains(document.fullscreenElement)
+            )
+                await document.exitFullscreen();
+            else if (kind === "video" && !target)
+                setFullscreenError(
+                    "The video player is still loading. Try fullscreen again in a moment.",
+                );
+            else if (document.fullscreenEnabled && target?.requestFullscreen) {
+                await target.requestFullscreen();
+                if (kind === "video") target.focus({ preventScroll: true });
+            } else
+                setFullscreenError(
+                    "Fullscreen is not available in this browser.",
+                );
+        } catch {
+            setFullscreenError(
+                "Fullscreen could not open. Try again or use your browser's fullscreen control.",
+            );
+        }
+    }
+    const [fileStatus, setFileStatus] = useState<FileRequestStatus | null>(null);
+    const [toolbarTarget, setToolbarTarget] = useState<HTMLDivElement | null>(
+        null,
+    );
+    useEffect(() => {
+        const node = viewer.current!;
+        const trigger = document.activeElement as HTMLElement | null;
+        const previousOverflow = document.body.style.overflow;
+        const position = { x: window.scrollX, y: window.scrollY };
+        document.body.style.overflow = "hidden";
+        node.showModal();
+        node.querySelector<HTMLButtonElement>(".preview-close")?.focus();
+        return () => {
+            node.querySelectorAll<HTMLMediaElement>("video,audio").forEach(
+                (media) => {
+                    media.pause();
+                    media.removeAttribute("src");
+                    media.load();
+                },
+            );
+            node.close();
+            document.body.style.overflow = previousOverflow;
+            requestAnimationFrame(() => {
+                if (document.querySelector(".file-preview[open]")) return;
+                const row = document.querySelector<HTMLElement>(
+                    '[data-item-id="' +
+                        CSS.escape(item.id) +
+                        '"] .item-name-button',
+                );
+                const target =
+                    trigger?.isConnected && trigger.getClientRects().length
+                        ? trigger
+                        : row || document.getElementById("main-content");
+                target?.focus({ preventScroll: true });
+                window.scrollTo(position.x, position.y);
+            });
+        };
+    }, [item.id]);
+    const [failed, setFailed] = useState(false);
+    const [preview, setPreview] = useState<{
+        path: string;
+        value: PreviewDescriptor;
+    } | null>(null);
+    const descriptor = preview?.path === path ? preview.value : null;
+    const kind = nativeKind || (descriptor?.kind === "video" ? "video" : null);
+    useEffect(() => {
+        setFileStatus(null);
+        // The player's own readiness state is authoritative for video. A server
+        // transfer queue can stay busy while cached video is already playing.
+        if (kind === "video" || (!nativeKind && !descriptor)) return;
+        const controller = new AbortController();
+        const params = new URLSearchParams({
+            path,
+            request_id: mediaRequestId(path, auth),
+        });
+        if (auth) params.set("auth", auth);
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            try {
+                const data = await request<FileRequestStatus>(
+                    "/api/v1/file-status?" + params,
+                    undefined,
+                    { signal: controller.signal },
+                );
+                if (!controller.signal.aborted) setFileStatus(data);
+            } catch {
+                /* Previews remain usable if queue diagnostics are unavailable. */
+            }
+            if (!controller.signal.aborted) timer = setTimeout(poll, 2500);
+        };
+        void poll();
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [path, auth, kind, nativeKind, descriptor]);
+    const [error, setError] = useState("");
+    const [loading, setLoading] = useState(!nativeKind);
+    const [attempt, setAttempt] = useState(0);
+    const [wrap, setWrap] = useState(true);
+    const [variants, setVariants] = useState<{ id: string; label: string }[]>(
+        [],
+    );
+    const [quality, setQuality] = useState("original");
+    const [mediaFailure, setMediaFailure] = useState<
+        "checking" | "retrying" | "busy" | null
+    >(null);
+    const mediaRetries = useRef(0);
+    useEffect(() => {
+        mediaRetries.current = 0;
+        setMediaFailure(null);
+    }, [path, auth, quality]);
+    useEffect(() => {
+        if (!failed || (kind !== "image" && kind !== "audio")) return;
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const params = new URLSearchParams({
+            path,
+            request_id: mediaRequestId(path, auth),
+        });
+        if (auth) params.set("auth", auth);
+        void request<FileRequestStatus>(
+            "/api/v1/file-status?" + params,
+            undefined,
+            { signal: controller.signal, timeoutMs: 10000 },
+        )
+            .then((status) => {
+                if (controller.signal.aborted) return;
+                setFileStatus(status);
+                if (status.code !== "TELEGRAM_QUEUE_FULL") {
+                    setMediaFailure(null);
+                    return;
+                }
+                const delay = previewRetryDelay(status, mediaRetries.current);
+                setMediaFailure(delay === null ? "busy" : "retrying");
+                if (delay === null) return;
+                mediaRetries.current++;
+                timer = setTimeout(() => {
+                    setFailed(false);
+                    setMediaFailure(null);
+                    setAttempt((value) => value + 1);
+                }, delay);
+            })
+            .catch(() => {
+                if (!controller.signal.aborted) setMediaFailure(null);
+            });
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [failed, path, auth, kind, attempt]);
+    function mediaFailed() {
+        setMediaFailure("checking");
+        setFailed(true);
+    }
+    const playback = useRef<{ time: number; playing: boolean } | null>(null);
+    const src =
+        fileUrl(path, auth) +
+        (kind === "video" || kind === "audio" ? "&preview=1" : "") +
+        (quality === "original"
+            ? ""
+            : "&quality=" + encodeURIComponent(quality));
+    useEffect(() => {
+        setVariants([]);
+        setQuality("original");
+        if (kind !== "image" && kind !== "video") return;
+        const controller = new AbortController();
+        const params = new URLSearchParams({ path });
+        if (auth) params.set("auth", auth);
+        void fetch("/api/v1/media?" + params, {
+            credentials: "same-origin",
+            signal: AbortSignal.any([
+                controller.signal,
+                AbortSignal.timeout(15000),
+            ]),
+        })
+            .then(async (response) => {
+                if (!response.ok) return;
+                const data = await response.json();
+                if (!controller.signal.aborted && Array.isArray(data.variants))
+                    setVariants(
+                        data.variants
+                            .filter(
+                                (value: { id?: string; label?: string }) =>
+                                    typeof value.id === "string" &&
+                                    typeof value.label === "string",
+                            )
+                            .slice(0, 20),
+                    );
+            })
+            .catch(() => {
+                /* Original playback is independent of optional native variants. */
+            });
+        return () => controller.abort();
+    }, [path, auth, kind]);
+    useEffect(() => {
+        setFailed(false);
+        if (nativeKind) {
+            setLoading(false);
+            return;
+        }
+        const controller = new AbortController();
+        setLoading(true);
+        setError("");
+        setPreview(null);
+        void loadPreview(path, auth, controller.signal)
+            .then((value) => {
+                if (!controller.signal.aborted) setPreview({ path, value });
+            })
+            .catch((error) => {
+                if (!controller.signal.aborted) setError(errorMessage(error));
+            })
+            .finally(() => {
+                if (!controller.signal.aborted) setLoading(false);
+            });
+        return () => controller.abort();
+    }, [path, auth, nativeKind, attempt]);
+    const pdf =
+        descriptor?.kind === "pdf" ? safePdfUrl(descriptor.url) : undefined;
+    const documentPreview = !!pdf || descriptor?.kind === "book";
+    const details =
+        !kind && !error && (loading || descriptor?.kind === "unsupported");
+    const suffix = item.name.includes(".")
+        ? item.name.slice(item.name.lastIndexOf(".") + 1)
+        : "";
+    const fileType = /^[a-z0-9]{1,12}$/i.test(suffix)
+        ? suffix.toUpperCase() + " file"
+        : "File";
+    const queue = fileStatus?.queue;
+    const waiting =
+        fileStatus?.phase === "waiting_for_telegram" ||
+        (queue != null && queue.position > 0);
+    const waitMessage = waiting
+        ? "Waiting for Telegram capacity"
+        : fileStatus?.phase === "checking_file"
+          ? "Checking file…"
+          : fileStatus?.phase === "receiving"
+            ? "Receiving file…"
+            : null;
+    return (
+        <dialog
+            ref={viewer}
+            className={"file-preview" + (details ? " file-details" : "")}
+            aria-labelledby="preview-title"
+            aria-describedby={details ? "file-details-reason" : undefined}
+            onClick={(event) => {
+                if (!details || event.target !== event.currentTarget) return;
+                const bounds = event.currentTarget.getBoundingClientRect();
+                if (
+                    event.clientX < bounds.left ||
+                    event.clientX > bounds.right ||
+                    event.clientY < bounds.top ||
+                    event.clientY > bounds.bottom
+                )
+                    onClose();
+            }}
+            onCancel={(event) => {
+                event.preventDefault();
+                if (
+                    document.fullscreenElement &&
+                    fullscreenSurface.current?.contains(
+                        document.fullscreenElement,
+                    )
+                ) {
+                    void document.exitFullscreen().catch(() => {});
+                    return;
+                }
+                onClose();
+            }}
+        >
+            <div className="preview-fullscreen-surface" ref={fullscreenSurface}>
+                {fullscreen && (
+                    <button
+                        className="preview-toolbar-toggle"
+                        type="button"
+                        aria-label={
+                            toolbarCollapsed ? "Show Toolbar" : "Hide Toolbar"
+                        }
+                        title={
+                            toolbarCollapsed ? "Show Toolbar" : "Hide Toolbar"
+                        }
+                        aria-controls="preview-header"
+                        aria-expanded={!toolbarCollapsed}
+                        onClick={() =>
+                            setToolbarCollapsed((collapsed) => !collapsed)
+                        }
+                    >
+                        {toolbarCollapsed ? (
+                            <ChevronDown size={19} aria-hidden="true" />
+                        ) : (
+                            <ChevronUp size={19} aria-hidden="true" />
+                        )}
+                    </button>
+                )}
+                <header
+                    id="preview-header"
+                    hidden={fullscreen && toolbarCollapsed}
+                    className={
+                        "preview-header" +
+                        (documentPreview
+                            ? " preview-header-pdf preview-header-reader"
+                            : "") +
+                        (descriptor?.kind === "book"
+                            ? " preview-header-book"
+                            : "")
+                    }
+                >
+                    <button
+                        className="preview-close icon-button"
+                        type="button"
+                        aria-label="Close Preview"
+                        onClick={onClose}
+                    >
+                        {details ? <X size={21} /> : <ArrowLeft size={22} />}
+                    </button>
+                    {!details && (
+                        <>
+                            <FileIcon name={item.name} />
+                            <div className="preview-heading">
+                                <h2 id="preview-title" title={item.name}>
+                                    {item.name}
+                                </h2>
+                                <span>
+                                    {formatBytes(item.size)} ·{" "}
+                                    {formatDate(item.upload_date)}
+                                </span>
+                            </div>
+                            {documentPreview && (
+                                <div
+                                    className="preview-toolbar-slot"
+                                    ref={setToolbarTarget}
+                                />
+                            )}
+                            <button
+                                className="icon-button preview-fullscreen"
+                                aria-label={
+                                    fullscreen
+                                        ? "Exit Fullscreen"
+                                        : "Enter Fullscreen"
+                                }
+                                title={
+                                    fullscreen
+                                        ? "Exit Fullscreen"
+                                        : "Enter Fullscreen"
+                                }
+                                onClick={() => void toggleFullscreen()}
+                            >
+                                {fullscreen ? (
+                                    <Minimize size={19} />
+                                ) : (
+                                    <Maximize size={19} />
+                                )}
+                            </button>
+                            <a
+                                className="preview-download"
+                                href={fileUrl(path, auth, true)}
+                                download={item.name}
+                                aria-label="Download Original"
+                                title="Download Original"
+                            >
+                                <Download size={19} />
+                                <span>Download</span>
+                            </a>
+                        </>
+                    )}
+                </header>
+                {fullscreenError && (
+                    <p className="preview-limit" role="alert">
+                        {fullscreenError}
+                    </p>
+                )}
+                {kind !== "video" && !failed && waitMessage && (
+                    <p className="preview-limit" role="status">
+                        {waitMessage}
+                        {waiting && queue?.estimated_wait_seconds != null
+                            ? " · About " +
+                              Math.ceil(queue.estimated_wait_seconds) +
+                              " seconds"
+                            : ""}
+                    </p>
+                )}
+                {details ? (
+                    <section className="file-details-body">
+                        <div className="file-details-icon">
+                            <FileIcon name={item.name} />
+                        </div>
+                        <h2 id="preview-title">{item.name}</h2>
+                        {loading ? (
+                            <p
+                                id="file-details-reason"
+                                className="file-details-checking"
+                                role="status"
+                            >
+                                <Spinner /> Checking preview…
+                            </p>
+                        ) : (
+                            <p id="file-details-reason">
+                                {descriptor?.reason ||
+                                    "Download this file to open it on your device."}
+                            </p>
+                        )}
+                        <dl className="file-details-metadata">
+                            <div>
+                                <dt>Type</dt>
+                                <dd>{fileType}</dd>
+                            </div>
+                            <div>
+                                <dt>Size</dt>
+                                <dd>
+                                    {formatBytes(descriptor?.size ?? item.size)}
+                                </dd>
+                            </div>
+                            <div>
+                                <dt>Added</dt>
+                                <dd>{formatDate(item.upload_date)}</dd>
+                            </div>
+                        </dl>
+                        <a
+                            className="primary-button file-details-download"
+                            href={fileUrl(path, auth, true)}
+                            download={item.name}
+                            aria-label="Download Original"
+                        >
+                            <Download size={19} /> Download File
+                        </a>
+                    </section>
+                ) : (
+                    <>
+                        {kind !== "video" && variants.length > 0 && (
+                            <label
+                                className="preview-quality"
+                                hidden={fullscreen && toolbarCollapsed}
+                            >
+                                Preview Quality
+                                <select
+                                    value={quality}
+                                    onChange={(event) => {
+                                        setFailed(false);
+                                        setQuality(event.target.value);
+                                    }}
+                                >
+                                    <option value="original">Original</option>
+                                    {variants.map((value) => (
+                                        <option key={value.id} value={value.id}>
+                                            {value.label}
+                                        </option>
+                                    ))}
+                                </select>
+                            </label>
+                        )}
+                        <div
+                            className={
+                                "preview-surface preview-surface-" +
+                                (pdf
+                                    ? "pdf"
+                                    : descriptor?.kind === "text"
+                                      ? "text"
+                                      : kind || "other") +
+                                (error || failed
+                                    ? " preview-surface-message"
+                                    : "")
+                            }
+                        >
+                            {loading ? (
+                                <div className="preview-loading" role="status">
+                                    <Spinner /> Loading preview…
+                                </div>
+                            ) : error ? (
+                                <div className="empty-state">
+                                    <AlertCircle size={34} />
+                                    <p role="alert">{error}</p>
+                                    <button
+                                        className="secondary-button"
+                                        onClick={() =>
+                                            setAttempt((value) => value + 1)
+                                        }
+                                    >
+                                        <RefreshCw size={16} /> Try Preview
+                                        Again
+                                    </button>
+                                </div>
+                            ) : failed ? (
+                                <div className="empty-state">
+                                    {mediaFailure === "checking" ||
+                                    mediaFailure === "retrying" ? (
+                                        <Spinner />
+                                    ) : (
+                                        <AlertCircle size={34} />
+                                    )}
+                                    <h3>
+                                        {mediaFailure === "checking"
+                                            ? "Checking preview…"
+                                            : mediaFailure
+                                              ? "Telegram is busy"
+                                              : "Preview Unavailable"}
+                                    </h3>
+                                    <p role={mediaFailure ? "status" : undefined}>
+                                        {mediaFailure === "checking"
+                                            ? "Checking whether Telegram is temporarily busy."
+                                            : mediaFailure === "retrying"
+                                              ? "Waiting for Telegram capacity. This preview will retry automatically."
+                                              : mediaFailure === "busy"
+                                                ? "Telegram's waiting queue is full. Try again in a moment."
+                                                : "This file could not be played or displayed by your browser. Download the original to open it on your device."}
+                                    </p>
+                                    {mediaFailure !== "checking" &&
+                                        mediaFailure !== "retrying" && (
+                                            <button
+                                                className="secondary-button"
+                                                onClick={() => {
+                                                    mediaRetries.current = 0;
+                                                    setMediaFailure(null);
+                                                    setFailed(false);
+                                                    setAttempt(
+                                                        (value) => value + 1,
+                                                    );
+                                                }}
+                                            >
+                                                <RefreshCw size={16} /> Try
+                                                Preview Again
+                                            </button>
+                                        )}
+                                </div>
+                            ) : kind === "image" ? (
+                                <img
+                                    key={attempt}
+                                    src={src}
+                                    alt={item.name}
+                                    onError={mediaFailed}
+                                />
+                            ) : kind === "video" ? (
+                                <AdvancedVideo
+                                    key={attempt}
+                                    src={src}
+                                    name={item.name}
+                                    playback={playback}
+                                    qualityControl={
+                                        variants.length > 0
+                                            ? {
+                                                  variants,
+                                                  selected: quality,
+                                                  onChange: (value) => {
+                                                      setFailed(false);
+                                                      setQuality(value);
+                                                  },
+                                              }
+                                            : undefined
+                                    }
+                                />
+                            ) : kind === "audio" ? (
+                                <audio
+                                    key={attempt}
+                                    src={src}
+                                    controls
+                                    preload="metadata"
+                                    onError={mediaFailed}
+                                />
+                            ) : descriptor?.kind === "text" ? (
+                                <div className="text-preview">
+                                    <div className="preview-document-toolbar">
+                                        <span>
+                                            {descriptor.language ||
+                                                "Plain Text"}{" "}
+                                            · Read-only
+                                        </span>
+                                        <label>
+                                            <input
+                                                type="checkbox"
+                                                checked={wrap}
+                                                onChange={(event) =>
+                                                    setWrap(
+                                                        event.target.checked,
+                                                    )
+                                                }
+                                            />{" "}
+                                            Wrap Lines
+                                        </label>
+                                    </div>
+                                    {descriptor.truncated && (
+                                        <p
+                                            className="preview-limit"
+                                            role="status"
+                                        >
+                                            Showing the first 256 KB. Download
+                                            the original for the complete file.
+                                        </p>
+                                    )}
+                                    <pre
+                                        className={wrap ? "wrap-lines" : ""}
+                                        tabIndex={0}
+                                        aria-label={"Contents of " + item.name}
+                                    >
+                                        <code>
+                                            {displayText(
+                                                descriptor.text || "",
+                                                descriptor.language,
+                                            )}
+                                        </code>
+                                    </pre>
+                                </div>
+                            ) : descriptor?.kind === "book" ? (
+                                <Suspense
+                                    fallback={
+                                        <div
+                                            className="preview-loading"
+                                            role="status"
+                                        >
+                                            <Spinner />
+                                            Loading reader…
+                                        </div>
+                                    }
+                                >
+                                    <BookPreview
+                                        key={path + auth}
+                                        path={path}
+                                        auth={auth}
+                                        toolbarTarget={toolbarTarget}
+                                    />
+                                </Suspense>
+                            ) : pdf ? (
+                                <Suspense
+                                    fallback={
+                                        <div
+                                            className="preview-loading"
+                                            role="status"
+                                        >
+                                            <Spinner /> Loading PDF viewer…
+                                        </div>
+                                    }
+                                >
+                                    <PdfPreview
+                                        url={pdf}
+                                        name={item.name}
+                                        size={
+                                            descriptor?.size || item.size || 0
+                                        }
+                                        toolbarTarget={toolbarTarget}
+                                    />
+                                </Suspense>
+                            ) : (
+                                <div className="empty-state">
+                                    <FileIcon name={item.name} />
+                                    <h3>No Preview for This File</h3>
+                                    <p>
+                                        {descriptor?.reason ||
+                                            "Download the original to open this format on your device."}
+                                    </p>
+                                </div>
+                            )}
+                        </div>
+                    </>
+                )}
+            </div>
+        </dialog>
+    );
+}
diff --git a/website/src/features/previews/Reader.css b/website/src/features/previews/Reader.css
new file mode 100644
index 00000000..62fb1000
--- /dev/null
+++ b/website/src/features/previews/Reader.css
@@ -0,0 +1,117 @@
+/* Shared document chrome; the content keeps each format's reading controls. */
+.file-preview .preview-header-reader {
+    color: var(--ink);
+    background: var(--surface);
+    border-color: var(--line);
+}
+.file-preview
+    .preview-header-reader
+    :is(.icon-button, .preview-download, .pdf-toolbar, .pdf-fit) {
+    color: var(--ink);
+}
+.file-preview
+    .preview-header-reader
+    :is(.icon-button, .preview-download, .pdf-fit):hover {
+    background: var(--hover);
+}
+.file-preview .preview-header-reader .preview-heading > span {
+    color: var(--muted);
+}
+.file-preview .preview-header-reader .pdf-fit {
+    min-height: 40px;
+    background: var(--surface);
+    border-color: var(--line);
+}
+.file-preview .preview-header-reader .pdf-fit[aria-pressed="true"] {
+    background: var(--hover);
+}
+.file-preview .preview-header-reader .pdf-controls {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+.reader-navigation {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+}
+.reader-navigation .book-position {
+    color: var(--muted);
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+.reader-navigation select {
+    min-width: 90px;
+    max-width: 130px;
+    height: 40px;
+    padding: 4px 8px;
+    color: var(--ink);
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: 6px;
+    font: inherit;
+}
+.file-preview .preview-header-reader .reader-navigation .icon-button {
+    min-height: 40px;
+    min-width: 40px;
+}
+.file-preview .pdf-scroll {
+    background: var(--surface-soft, var(--surface));
+}
+.file-preview .preview-pdf-error {
+    color: var(--ink);
+}
+@media (max-width: 720px) {
+    .file-preview .preview-header-reader {
+        display: grid;
+        grid-template-columns: 44px minmax(0, 1fr) 44px 44px;
+        gap: 4px 8px;
+    }
+    .file-preview .preview-header-reader .preview-close {
+        grid-column: 1;
+        grid-row: 1;
+    }
+    .file-preview .preview-header-reader .preview-heading {
+        grid-column: 2;
+        grid-row: 1;
+    }
+    .file-preview .preview-header-reader .preview-fullscreen {
+        grid-column: 3;
+        grid-row: 1;
+    }
+    .file-preview .preview-header-reader .preview-download {
+        grid-column: 4;
+        grid-row: 1;
+    }
+    .file-preview .preview-header-reader .preview-toolbar-slot {
+        grid-column: 1/-1;
+        grid-row: 2;
+        min-width: 0;
+    }
+    .reader-navigation {
+        flex: 1;
+        min-width: 0;
+    }
+    .reader-navigation select {
+        flex: 1;
+        min-width: 0;
+        max-width: none;
+        height: 44px;
+        font-size: 16px;
+    }
+    .file-preview .preview-header-reader .reader-navigation .icon-button {
+        min-width: 44px;
+        min-height: 44px;
+    }
+}
+@media (max-width: 720px), (pointer: coarse) {
+    .file-preview .preview-header-reader .pdf-controls .pdf-toolbar {
+        inset-block-start: calc(112px + env(safe-area-inset-top));
+        color: var(--ink);
+        background: var(--surface);
+        border-color: var(--line);
+        border-radius: 8px;
+        box-shadow: 0 2px 8px #0002;
+    }
+}
diff --git a/website/src/features/previews/books/BookImage.tsx b/website/src/features/previews/books/BookImage.tsx
new file mode 100644
index 00000000..1a023278
--- /dev/null
+++ b/website/src/features/previews/books/BookImage.tsx
@@ -0,0 +1,131 @@
+import { useEffect, useRef, useState } from "react";
+import { errorMessage } from "../../../shared/api";
+import { Spinner } from "../../../shared/components";
+import { loadBookImage, type ImageProgress } from "./bookImage";
+
+export default function BookImage({
+    src,
+    alt,
+    eager = false,
+}: {
+    src: string;
+    alt: string;
+    eager?: boolean;
+}) {
+    const container = useRef<HTMLSpanElement>(null);
+    const [visible, setVisible] = useState(eager);
+    const [placeholderHeight, setPlaceholderHeight] = useState(48);
+    const [attempt, setAttempt] = useState(0);
+    const [url, setUrl] = useState("");
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState("");
+    const [progress, setProgress] = useState<ImageProgress>({
+        received: 0,
+        total: 0,
+        attempt: 1,
+        retrying: false,
+    });
+    useEffect(() => {
+        if (eager) {
+            setVisible(true);
+            return;
+        }
+        if (!container.current) return;
+        const observer = new IntersectionObserver(
+            (entries) => {
+                const entry = entries[0];
+                if (!entry.isIntersecting)
+                    setPlaceholderHeight(entry.boundingClientRect.height);
+                setVisible(entry.isIntersecting);
+            },
+            { rootMargin: "200px" },
+        );
+        observer.observe(container.current);
+        return () => observer.disconnect();
+    }, [eager]);
+    useEffect(() => {
+        if (!visible) {
+            setUrl("");
+            setReady(false);
+            return;
+        }
+        const controller = new AbortController();
+        let objectUrl = "";
+        setUrl("");
+        setReady(false);
+        setError("");
+        void loadBookImage(src, controller.signal, setProgress)
+            .then((blob) => {
+                if (controller.signal.aborted) return;
+                objectUrl = URL.createObjectURL(blob);
+                setUrl(objectUrl);
+            })
+            .catch((cause) => {
+                if (!controller.signal.aborted) setError(errorMessage(cause));
+            });
+        return () => {
+            controller.abort();
+            if (objectUrl) URL.revokeObjectURL(objectUrl);
+        };
+    }, [src, attempt, visible]);
+    const amount = (progress.received / 1024 / 1024).toFixed(1) + " MiB";
+    return (
+        <span
+            ref={container}
+            className="book-image"
+            aria-busy={visible && !ready && !error}
+            style={
+                !eager && (!visible || !ready)
+                    ? { minHeight: placeholderHeight }
+                    : undefined
+            }
+        >
+            {visible && !ready && !error && (
+                <span className="book-image-status" role="status">
+                    <Spinner />
+                    {progress.retrying
+                        ? "Connection interrupted. Retrying page…"
+                        : url
+                          ? "Displaying page…"
+                          : "Loading page…"}
+                    {progress.received > 0 && (
+                        <span>
+                            {amount}
+                            {progress.total > 0
+                                ? " / " +
+                                  (progress.total / 1024 / 1024).toFixed(1) +
+                                  " MiB"
+                                : " received"}
+                        </span>
+                    )}
+                </span>
+            )}
+            {visible && error && (
+                <span className="book-image-error" role="alert">
+                    <span>{alt}</span>
+                    <span>{error}</span>
+                    <button
+                        className="text-button"
+                        onClick={() => setAttempt((n) => n + 1)}
+                    >
+                        Retry image
+                    </button>
+                </span>
+            )}
+            {visible && url && !error && (
+                <img
+                    src={url}
+                    alt={alt}
+                    hidden={!ready}
+                    decoding="async"
+                    onLoad={() => setReady(true)}
+                    onError={() =>
+                        setError(
+                            "The browser could not decode this image. Download the original to open it in another reader.",
+                        )
+                    }
+                />
+            )}
+        </span>
+    );
+}
diff --git a/website/src/features/previews/books/BookPreview.css b/website/src/features/previews/books/BookPreview.css
new file mode 100644
index 00000000..b37f5986
--- /dev/null
+++ b/website/src/features/previews/books/BookPreview.css
@@ -0,0 +1,356 @@
+.book-reader {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    height: 100%;
+    width: 100%;
+    color: var(--ink);
+    background: var(--surface);
+}
+.book-toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 4px 8px;
+    min-width: 0;
+}
+.book-toolbar select {
+    min-width: 0;
+    max-width: 240px;
+    width: auto;
+    height: 40px;
+    padding: 4px 8px;
+    font: inherit;
+    color: var(--ink);
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: 6px;
+}
+.book-toolbar #book-entry {
+    flex: 1;
+    min-width: 90px;
+}
+.book-toolbar .icon-button {
+    min-width: 40px;
+    min-height: 40px;
+}
+.book-position {
+    font-size: 12px;
+    color: var(--muted);
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+.book-direction {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    min-height: 44px;
+    font-size: 12px;
+    white-space: nowrap;
+}
+.book-content {
+    overflow: auto;
+    flex: 1;
+    min-height: 0;
+    outline-offset: -3px;
+    padding: 24px;
+    overscroll-behavior: contain;
+}
+.book-chapter {
+    max-width: min(64ch, 760px);
+    margin: 0 auto;
+    line-height: 1.7;
+    overflow-wrap: anywhere;
+}
+.book-chapter :is(h1, h2, h3, h4, h5, h6) {
+    margin: 1.5em 0 0.65em;
+    line-height: 1.3;
+}
+.book-chapter p {
+    margin: 0.8em 0;
+}
+.book-chapter :is(pre, table) {
+    max-width: 100%;
+    overflow: auto;
+}
+.book-chapter pre {
+    white-space: pre-wrap;
+}
+.book-chapter td,
+.book-chapter th {
+    padding: 4px 8px;
+    border: 1px solid var(--line);
+}
+.book-chapter blockquote {
+    margin: 1em 0;
+    padding-inline: 16px;
+    border-inline-start: 1px solid var(--line);
+}
+.book-chapter img {
+    max-width: 100%;
+    height: auto;
+    display: block;
+    margin: 16px auto;
+}
+.book-reference {
+    display: inline;
+    font: inherit;
+    color: var(--action);
+    padding: 0;
+    border: 0;
+    background: none;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+    cursor: pointer;
+    text-align: inherit;
+}
+.book-fit-width > .book-image > img {
+    display: block;
+    width: 100%;
+    max-width: 1100px;
+    height: auto;
+    margin: 0 auto;
+}
+.book-fit-page > .book-image > img {
+    display: block;
+    width: auto;
+    max-width: 100%;
+    height: 100%;
+    object-fit: contain;
+    margin: 0 auto;
+}
+.book-message {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-wrap: wrap;
+    gap: 12px;
+    padding: 24px;
+}
+.book-image-error {
+    display: block;
+    color: var(--muted);
+    text-align: center;
+    padding: 24px;
+}
+.book-font-16 .book-chapter {
+    font-size: 16px;
+}
+.book-font-18 .book-chapter {
+    font-size: 18px;
+}
+.book-font-20 .book-chapter {
+    font-size: 20px;
+}
+.book-font-22 .book-chapter {
+    font-size: 22px;
+}
+.book-font-24 .book-chapter {
+    font-size: 24px;
+}
+@media (max-width: 720px), (pointer: coarse) {
+    .book-content {
+        padding: 16px max(16px, env(safe-area-inset-right))
+            max(16px, env(safe-area-inset-bottom))
+            max(16px, env(safe-area-inset-left));
+    }
+    .book-toolbar {
+        gap: 4px;
+    }
+    .book-toolbar .icon-button {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .book-toolbar select {
+        height: 44px;
+        font-size: 16px;
+    }
+    .book-toolbar #book-entry {
+        max-width: 180px;
+    }
+    .book-direction {
+        margin-inline: 4px;
+    }
+    .book-position {
+        font-size: 11px;
+    }
+}
+
+.preview-header-book {
+    color: var(--ink);
+    background: var(--surface);
+    border-color: var(--line);
+}
+.preview-header-book .icon-button,
+.preview-header-book .preview-download {
+    color: var(--ink);
+}
+.preview-header-book .icon-button:hover,
+.preview-header-book .preview-download:hover {
+    background: var(--hover);
+}
+.preview-header-book .preview-heading > span {
+    color: var(--muted);
+}
+.preview-header-book .preview-toolbar-slot {
+    flex: 0 1 500px;
+    min-width: 300px;
+}
+.book-options {
+    position: relative;
+    flex: 0 0 auto;
+}
+.book-options summary {
+    list-style: none;
+    cursor: pointer;
+}
+.book-options summary::-webkit-details-marker {
+    display: none;
+}
+.book-options-panel {
+    position: absolute;
+    top: calc(100% + 8px);
+    right: 0;
+    z-index: 6;
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    flex-wrap: wrap;
+    width: max-content;
+    max-width: 260px;
+    max-height: calc(
+        100dvh - 140px - env(safe-area-inset-top) - env(safe-area-inset-bottom)
+    );
+    overflow: auto;
+    overscroll-behavior: contain;
+    padding: 12px;
+    background: var(--surface);
+    color: var(--ink);
+    border: 1px solid var(--line);
+    border-radius: 8px;
+    box-shadow: 0 2px 8px #0002;
+}
+@media (max-width: 720px) {
+    .preview-header-book {
+        display: grid;
+        grid-template-columns: 44px minmax(0, 1fr) 44px 44px;
+        gap: 4px 8px;
+    }
+    .preview-header-book .preview-close {
+        grid-column: 1;
+        grid-row: 1;
+    }
+    .preview-header-book .preview-heading {
+        grid-column: 2;
+        grid-row: 1;
+    }
+    .preview-header-book .preview-fullscreen {
+        grid-column: 3;
+        grid-row: 1;
+    }
+    .preview-header-book .preview-download {
+        grid-column: 4;
+        grid-row: 1;
+    }
+    .preview-header-book .preview-toolbar-slot {
+        grid-column: 1/-1;
+        grid-row: 2;
+        min-width: 0;
+    }
+    .preview-header-book .book-toolbar {
+        width: 100%;
+        flex-wrap: nowrap;
+    }
+    .preview-header-book .book-toolbar #book-entry {
+        min-width: 0;
+        max-width: none;
+    }
+    .book-toolbar .icon-button {
+        flex: 0 0 44px;
+    }
+}
+
+.book-typeface-serif .book-chapter {
+    font-family: Georgia, "Times New Roman", serif;
+}
+.book-chapter > :first-child {
+    margin-block-start: 0;
+}
+.book-chapter :is(h1, h2, h3) {
+    text-wrap: balance;
+    font-weight: 600;
+}
+.book-chapter h2 {
+    font-size: 1.45em;
+}
+.book-chapter h3 {
+    font-size: 1.15em;
+}
+.book-chapter p {
+    margin-block: 1em;
+}
+.book-chapter .book-reference:has(img) {
+    display: inline-block;
+    vertical-align: middle;
+}
+.book-chapter .book-reference img {
+    margin: 0;
+}
+.book-chapter img {
+    max-height: 80dvh;
+    object-fit: contain;
+}
+.book-typeface-control {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    width: 100%;
+}
+.book-typeface-control select {
+    flex: 1;
+}
+
+/* Image-only EPUB chapters use the same page fit as comic archives. */
+.book-chapter.book-illustrated-page {
+    max-width: 1100px;
+}
+.book-illustrated-page :is(p, div, figure) {
+    margin: 0;
+}
+.book-fit-width .book-illustrated-page img {
+    width: 100%;
+    max-height: none;
+    height: auto;
+    margin: 0 auto;
+}
+.book-fit-page .book-illustrated-page img {
+    width: auto;
+    max-width: 100%;
+    max-height: calc(100dvh - 180px);
+    height: auto;
+    margin: 0 auto;
+}
+
+.book-image {
+    display: block;
+    min-height: 48px;
+}
+.book-content > .book-image {
+    height: 100%;
+}
+.book-image-status,
+.book-image-error {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 12px;
+    min-height: 180px;
+    padding: 24px;
+    color: var(--muted);
+    font: 14px/1.5 var(--font-body, sans-serif);
+    text-align: center;
+}
+.book-image > img[hidden] {
+    display: none;
+}
diff --git a/website/src/features/previews/books/BookPreview.test.ts b/website/src/features/previews/books/BookPreview.test.ts
new file mode 100644
index 00000000..1d9662ed
--- /dev/null
+++ b/website/src/features/previews/books/BookPreview.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+import {
+    bookUrl,
+    validateBook,
+    safeNodes,
+    bookJson,
+    bookEntryLabel,
+    isIllustratedPage,
+} from "./BookPreview";
+
+afterEach(() => vi.unstubAllGlobals());
+describe("bounded reader descriptors", () => {
+    it("encodes archive resources without navigating outside the local endpoint", () => {
+        const url = bookUrl("/opaque book", "private-token", "OPS/page #1.png");
+        expect(url.startsWith("/api/v1/books?")).toBe(true);
+        expect(new URLSearchParams(url.split("?")[1]).get("entry")).toBe(
+            "OPS/page #1.png",
+        );
+    });
+    it("accepts a reading order and rejects unsafe or empty indexes", () => {
+        expect(
+            validateBook({
+                kind: "comic",
+                entries: [{ name: "1.png", label: "Page 1" }],
+            }).entries,
+        ).toHaveLength(1);
+        expect(() => validateBook({ kind: "epub", entries: [] })).toThrow();
+        expect(() =>
+            validateBook({
+                kind: "comic",
+                entries: [{ name: "../secret", label: "Bad" }],
+            }),
+        ).toThrow();
+    });
+    it("only accepts passive structured chapter nodes and drops untrusted attributes", () => {
+        expect(() =>
+            safeNodes([{ tag: "script", children: ["alert(1)"] }]),
+        ).toThrow();
+        const nodes = safeNodes([
+            {
+                tag: "img",
+                children: [],
+                src: "https://tracker.invalid/x",
+                onerror: "alert(1)",
+            },
+        ]);
+        expect(nodes).toEqual([
+            {
+                tag: "img",
+                children: [],
+                src: undefined,
+                href: undefined,
+                alt: "",
+                id: undefined,
+            },
+        ]);
+        expect(() => safeNodes({ html: "<img onerror=alert(1)>" })).toThrow();
+    });
+    it("bounds oversized proxy responses and reports reader errors", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue(
+                new Response("{}", {
+                    headers: { "Content-Length": String(9 * 1024 * 1024) },
+                }),
+            ),
+        );
+        await expect(
+            bookJson("/api/v1/books?path=x", new AbortController().signal),
+        ).rejects.toThrow();
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue(
+                new Response(
+                    JSON.stringify({ detail: "The book is encrypted" }),
+                    {
+                        status: 422,
+                    },
+                ),
+            ),
+        );
+        await expect(
+            bookJson("/api/v1/books?path=x", new AbortController().signal),
+        ).rejects.toThrow("encrypted");
+    });
+});
+
+it("keeps real chapter names and turns generated wrapper filenames into readable labels", () => {
+    expect(bookEntryLabel({ name: "c2.xhtml", label: "CHAPTER II." }, 2)).toBe(
+        "CHAPTER II.",
+    );
+    expect(
+        bookEntryLabel({ name: "wrap0000.xhtml", label: "wrap0000.xhtml" }, 0),
+    ).toBe("Cover");
+    expect(
+        bookEntryLabel(
+            { name: "long-cover.wrap.xhtml", label: "long-cover.wrap.xhtml" },
+            12,
+        ),
+    ).toBe("Cover");
+    expect(
+        bookEntryLabel(
+            { name: "image.jpg.wrap.xhtml", label: "image.jpg.wrap.xhtml" },
+            12,
+        ),
+    ).toBe("Illustration 13");
+});
+
+it("fits image-based EPUB manga pages without treating illustrated prose as a comic page", () => {
+    const image = { tag: "img", children: [], src: "pages/01.jpg" };
+    expect(
+        isIllustratedPage([{ tag: "div", children: [image, "Page 1"] }]),
+    ).toBe(true);
+    expect(
+        isIllustratedPage([image, "A long prose paragraph. ".repeat(20)]),
+    ).toBe(false);
+    expect(isIllustratedPage(["A text-only chapter."])).toBe(false);
+});
diff --git a/website/src/features/previews/books/BookPreview.tsx b/website/src/features/previews/books/BookPreview.tsx
new file mode 100644
index 00000000..606a0c0d
--- /dev/null
+++ b/website/src/features/previews/books/BookPreview.tsx
@@ -0,0 +1,533 @@
+import {
+    createElement,
+    useEffect,
+    useRef,
+    useState,
+    type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import {
+    ChevronLeft,
+    ChevronRight,
+    Minus,
+    Plus,
+    RefreshCw,
+    Settings2,
+} from "lucide-react";
+import { readBoundedResponse } from "../previewIO";
+import { errorMessage } from "../../../shared/api";
+import { ErrorNotice, Spinner } from "../../../shared/components";
+import "./BookPreview.css";
+import BookImage from "./BookImage";
+
+type Entry = { name: string; label: string };
+type Book = { kind: "epub" | "comic"; title?: string; entries: Entry[] };
+type Node =
+    | string
+    | {
+          tag: string;
+          children: Node[];
+          src?: string;
+          alt?: string;
+          href?: string;
+          id?: string;
+      };
+const tags = new Set(
+    "p div span h1 h2 h3 h4 h5 h6 strong b em i u s a img ul ol li blockquote pre code br hr table thead tbody tr th td caption dl dt dd sup sub figure figcaption section article".split(
+        " ",
+    ),
+);
+const positionKey = "tgdrive.reader.positions";
+function positions(): Record<string, string> {
+    try {
+        const data = JSON.parse(localStorage.getItem(positionKey) || "{}");
+        return data && typeof data === "object" && !Array.isArray(data)
+            ? data
+            : {};
+    } catch {
+        return {};
+    }
+}
+function safeEntry(name: string) {
+    return (
+        name.length > 0 &&
+        name.length <= 1024 &&
+        !name.startsWith("/") &&
+        !/^[a-z][a-z0-9+.-]*:/i.test(name) &&
+        !name.includes("\\") &&
+        !/[\x00-\x1f]/.test(name) &&
+        !name.split("/").some((part) => part === ".." || part === ".")
+    );
+}
+export function bookUrl(path: string, auth: string, entry?: string) {
+    const params = new URLSearchParams({ path });
+    if (auth) params.set("auth", auth);
+    if (entry) params.set("entry", entry);
+    return "/api/v1/books?" + params;
+}
+export async function bookJson(url: string, signal: AbortSignal) {
+    const response = await fetch(url, {
+        credentials: "same-origin",
+        signal: AbortSignal.any([signal, AbortSignal.timeout(60000)]),
+        headers: { Accept: "application/json" },
+    });
+    const data = JSON.parse(
+        new TextDecoder().decode(
+            await readBoundedResponse(response, 8 * 1024 * 1024, signal),
+        ),
+    );
+    if (!response.ok)
+        throw new Error(
+            typeof data.detail === "string"
+                ? data.detail
+                : "The book could not be read. Try again.",
+        );
+    return data;
+}
+export function validateBook(data: Book): Book {
+    if (
+        !data ||
+        !["epub", "comic"].includes(data.kind) ||
+        !Array.isArray(data.entries) ||
+        !data.entries.length ||
+        data.entries.length > 10000 ||
+        !data.entries.every(
+            (entry) =>
+                entry &&
+                typeof entry.name === "string" &&
+                safeEntry(entry.name) &&
+                typeof entry.label === "string" &&
+                entry.label.length <= 1024,
+        )
+    )
+        throw new Error("The server returned an unreadable book index.");
+    return data;
+}
+export function safeNodes(data: unknown): Node[] {
+    let count = 0;
+    function visit(value: unknown, depth: number): Node {
+        if (++count > 20000 || depth > 100)
+            throw new Error("This chapter is too complex to display.");
+        if (typeof value === "string") return value;
+        const node = value as Exclude<Node, string>;
+        if (
+            !node ||
+            typeof node !== "object" ||
+            !tags.has(node.tag) ||
+            !Array.isArray(node.children)
+        )
+            throw new Error("The server returned an unreadable chapter.");
+        return {
+            tag: node.tag,
+            children: node.children.map((child) => visit(child, depth + 1)),
+            src:
+                typeof node.src === "string" &&
+                safeEntry(node.src.split("#")[0])
+                    ? node.src.split("#")[0]
+                    : undefined,
+            href:
+                typeof node.href === "string" &&
+                safeEntry(node.href.split("#")[0])
+                    ? node.href
+                    : undefined,
+            alt: typeof node.alt === "string" ? node.alt.slice(0, 500) : "",
+            id: typeof node.id === "string" ? node.id.slice(0, 128) : undefined,
+        };
+    }
+    if (!Array.isArray(data)) throw new Error("The chapter could not be read.");
+    return data.map((node) => visit(node, 0));
+}
+export function bookEntryLabel(entry: Entry, index: number): string {
+    if (!/\.(xhtml|html?)$/i.test(entry.label)) return entry.label;
+    if (index === 0 || /cover/i.test(entry.label)) return "Cover";
+    if (/wrap|spine/i.test(entry.label)) return "Illustration " + (index + 1);
+    return "Section " + (index + 1);
+}
+export function isIllustratedPage(nodes: Node[]): boolean {
+    let images = 0;
+    let textLength = 0;
+    const visit = (node: Node) => {
+        if (typeof node === "string") textLength += node.trim().length;
+        else {
+            if (node.tag === "img" && node.src) images++;
+            node.children.forEach(visit);
+        }
+    };
+    nodes.forEach(visit);
+    return images > 0 && textLength <= 80;
+}
+function readerPreferences() {
+    try {
+        const value = JSON.parse(
+            localStorage.getItem("tgdrive.reader.preferences") || "{}",
+        );
+        return {
+            font: [16, 18, 20, 22, 24].includes(value.font)
+                ? Number(value.font)
+                : 18,
+            typeface: value.typeface === "sans" ? "sans" : "serif",
+        };
+    } catch {
+        return { font: 18, typeface: "serif" };
+    }
+}
+export default function BookPreview({
+    path,
+    auth,
+    toolbarTarget,
+}: {
+    path: string;
+    auth: string;
+    toolbarTarget: HTMLElement | null;
+}) {
+    const [book, setBook] = useState<Book | null>(null);
+    const [selected, setSelected] = useState("");
+    const [nodes, setNodes] = useState<Node[]>([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState("");
+    const [indexAttempt, setIndexAttempt] = useState(0);
+    const [attempt, setAttempt] = useState(0);
+    const [rtl, setRtl] = useState(false);
+    const [font, setFont] = useState(() => readerPreferences().font);
+    const [typeface, setTypeface] = useState(
+        () => readerPreferences().typeface,
+    );
+    useEffect(() => {
+        try {
+            localStorage.setItem(
+                "tgdrive.reader.preferences",
+                JSON.stringify({ font, typeface }),
+            );
+        } catch {
+            /* Reading works without persistence. */
+        }
+    }, [font, typeface]);
+    const [fit, setFit] = useState<"width" | "page">("width");
+    const content = useRef<HTMLDivElement>(null);
+    const fragment = useRef("");
+    useEffect(() => {
+        const controller = new AbortController();
+        setLoading(true);
+        setError("");
+        void bookJson(bookUrl(path, auth), controller.signal)
+            .then(validateBook)
+            .then((result) => {
+                if (controller.signal.aborted) return;
+                setBook(result);
+                const saved = positions()[path];
+                setSelected(
+                    result.entries.some((entry) => entry.name === saved)
+                        ? saved
+                        : result.entries[0].name,
+                );
+                if (result.kind === "comic") setLoading(false);
+            })
+            .catch((cause) => {
+                if (!controller.signal.aborted) {
+                    setError(errorMessage(cause));
+                    setLoading(false);
+                }
+            });
+        return () => controller.abort();
+    }, [path, auth, indexAttempt]);
+    useEffect(() => {
+        if (!book || !selected) return;
+        try {
+            const saved = positions();
+            delete saved[path];
+            saved[path] = selected;
+            localStorage.setItem(
+                positionKey,
+                JSON.stringify(
+                    Object.fromEntries(Object.entries(saved).slice(-50)),
+                ),
+            );
+        } catch {
+            /* Reader works with storage disabled. */
+        }
+        content.current?.scrollTo({ top: 0 });
+        if (book.kind !== "epub") return;
+        const controller = new AbortController();
+        setLoading(true);
+        setError("");
+        setNodes([]);
+        void bookJson(bookUrl(path, auth, selected), controller.signal)
+            .then((result) => {
+                if (result.kind !== "chapter")
+                    throw new Error(
+                        "This EPUB chapter could not be displayed.",
+                    );
+                const chapter = safeNodes(result.nodes);
+                if (!controller.signal.aborted) {
+                    setNodes(chapter);
+                    setLoading(false);
+                }
+            })
+            .catch((cause) => {
+                if (!controller.signal.aborted) {
+                    setError(errorMessage(cause));
+                    setLoading(false);
+                }
+            });
+        return () => controller.abort();
+    }, [path, auth, book, selected, attempt]);
+    useEffect(() => {
+        if (!loading && fragment.current) {
+            document
+                .getElementById("book-anchor-" + fragment.current)
+                ?.scrollIntoView({ block: "start" });
+            fragment.current = "";
+        }
+    }, [loading, nodes]);
+    const index =
+        book?.entries.findIndex((entry) => entry.name === selected) ?? 0;
+    const move = (delta: number) => {
+        if (!book) return;
+        const entry = book.entries[index + delta];
+        if (entry) {
+            setError("");
+            setSelected(entry.name);
+            setAttempt(0);
+        }
+    };
+    const follow = (href?: string) => {
+        if (!href || !book) return;
+        const [entry, id] = href.split("#");
+        if (entry === selected && id) {
+            document
+                .getElementById("book-anchor-" + id)
+                ?.scrollIntoView({ block: "start" });
+            return;
+        }
+        if (book.entries.some((item) => item.name === entry)) {
+            fragment.current = id || "";
+            setSelected(entry);
+        }
+    };
+    const render = (node: Node, key: number): ReactNode => {
+        if (typeof node === "string") return node;
+        const children = node.children.map(render);
+        if (node.tag === "img")
+            return node.src ? (
+                <BookImage
+                    key={key}
+                    src={bookUrl(path, auth, node.src)}
+                    alt={node.alt || ""}
+                />
+            ) : null;
+        if (node.tag === "a")
+            return node.href ? (
+                <button
+                    key={key}
+                    className="book-reference"
+                    onClick={() => follow(node.href)}
+                >
+                    {children}
+                </button>
+            ) : (
+                <span key={key}>{children}</span>
+            );
+        return createElement(
+            node.tag,
+            { key, id: node.id ? "book-anchor-" + node.id : undefined },
+            ...(node.tag === "br" || node.tag === "hr" ? [] : children),
+        );
+    };
+    const toolbar = book && (
+        <div className="book-toolbar" role="group" aria-label="Reader controls">
+            <button
+                className="icon-button"
+                aria-label="Previous chapter or page"
+                disabled={index <= 0}
+                onClick={() => move(-1)}
+            >
+                {rtl ? <ChevronRight size={20} /> : <ChevronLeft size={20} />}
+            </button>
+            <label className="sr-only" htmlFor="book-entry">
+                {book.kind === "epub" ? "Chapter" : "Page"}
+            </label>
+            <select
+                id="book-entry"
+                value={selected}
+                onChange={(event) => setSelected(event.target.value)}
+            >
+                {book.entries.map((entry, i) => (
+                    <option key={i} value={entry.name}>
+                        {bookEntryLabel(entry, i)}
+                    </option>
+                ))}
+            </select>
+            <span className="book-position" aria-live="polite">
+                {index + 1} / {book.entries.length}
+            </span>
+            <button
+                className="icon-button"
+                aria-label="Next chapter or page"
+                disabled={index >= book.entries.length - 1}
+                onClick={() => move(1)}
+            >
+                {rtl ? <ChevronLeft size={20} /> : <ChevronRight size={20} />}
+            </button>
+            <details
+                className="book-options"
+                onKeyDown={(event) => {
+                    if (event.key === "Escape") {
+                        event.preventDefault();
+                        event.stopPropagation();
+                        event.currentTarget.open = false;
+                        event.currentTarget.querySelector("summary")?.focus();
+                    }
+                }}
+            >
+                <summary className="icon-button" aria-label="Reading options">
+                    <Settings2 size={19} />
+                </summary>
+                <div className="book-options-panel">
+                    {book.kind === "epub" ? (
+                        <>
+                            <button
+                                className="icon-button"
+                                aria-label="Decrease text size"
+                                disabled={font <= 16}
+                                onClick={() => setFont((n) => n - 2)}
+                            >
+                                <Minus size={17} />
+                            </button>
+                            <span>{font}px</span>
+                            <button
+                                className="icon-button"
+                                aria-label="Increase text size"
+                                disabled={font >= 24}
+                                onClick={() => setFont((n) => n + 2)}
+                            >
+                                <Plus size={17} />
+                            </button>
+                            <label className="book-typeface-control">
+                                Typeface
+                                <select
+                                    value={typeface}
+                                    onChange={(event) =>
+                                        setTypeface(event.target.value)
+                                    }
+                                >
+                                    <option value="serif">Serif</option>
+                                    <option value="sans">Sans serif</option>
+                                </select>
+                            </label>
+                        </>
+                    ) : null}
+                    <>
+                        <label className="sr-only" htmlFor="comic-fit">
+                            Page fit
+                        </label>
+                        <select
+                            id="comic-fit"
+                            value={fit}
+                            onChange={(event) =>
+                                setFit(event.target.value as typeof fit)
+                            }
+                        >
+                            <option value="width">Fit width</option>
+                            <option value="page">Fit page</option>
+                        </select>
+                        <label className="book-direction">
+                            <input
+                                type="checkbox"
+                                checked={rtl}
+                                onChange={(event) =>
+                                    setRtl(event.target.checked)
+                                }
+                            />
+                            Right to left
+                        </label>
+                    </>
+                </div>
+            </details>
+        </div>
+    );
+    return (
+        <div
+            className={
+                "book-reader book-font-" + font + " book-typeface-" + typeface
+            }
+        >
+            {toolbarTarget && toolbar
+                ? createPortal(toolbar, toolbarTarget)
+                : toolbar}
+            {error ? (
+                <div className="book-message">
+                    <ErrorNotice message={error} />
+                    <button
+                        className="secondary-button"
+                        onClick={() =>
+                            book
+                                ? (setError(""), setAttempt((n) => n + 1))
+                                : setIndexAttempt((n) => n + 1)
+                        }
+                    >
+                        <RefreshCw size={16} />
+                        Try again
+                    </button>
+                </div>
+            ) : null}
+            {loading && (
+                <div className="book-message" role="status">
+                    <Spinner />
+                    Loading {book?.kind === "epub" ? "chapter" : "book"}…
+                </div>
+            )}
+            <div
+                ref={content}
+                className={"book-content book-fit-" + fit}
+                tabIndex={0}
+                aria-label={
+                    book?.kind === "epub" ? "Book chapter" : "Comic page"
+                }
+                onKeyDown={(event) => {
+                    if (
+                        (event.target as HTMLElement).closest(
+                            "button,input,select,a",
+                        ) ||
+                        event.ctrlKey ||
+                        event.metaKey ||
+                        event.altKey
+                    )
+                        return;
+                    if (
+                        event.key === "ArrowRight" ||
+                        event.key === "ArrowLeft"
+                    ) {
+                        event.preventDefault();
+                        move(
+                            (event.key === "ArrowRight" ? 1 : -1) *
+                                (rtl ? -1 : 1),
+                        );
+                    }
+                }}
+            >
+                {!error && book?.kind === "comic" && selected && (
+                    <BookImage
+                        key={selected + attempt}
+                        eager
+                        src={bookUrl(path, auth, selected)}
+                        alt={
+                            "Page " + (index + 1) + " of " + book.entries.length
+                        }
+                    />
+                )}
+                {!error && !loading && book?.kind === "epub" && (
+                    <article
+                        className={
+                            "book-chapter" +
+                            (isIllustratedPage(nodes)
+                                ? " book-illustrated-page"
+                                : "")
+                        }
+                    >
+                        {nodes.map(render)}
+                    </article>
+                )}
+            </div>
+        </div>
+    );
+}
diff --git a/website/src/features/previews/books/bookImage.test.ts b/website/src/features/previews/books/bookImage.test.ts
new file mode 100644
index 00000000..e22aa963
--- /dev/null
+++ b/website/src/features/previews/books/bookImage.test.ts
@@ -0,0 +1,192 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { loadBookImage, MAX_BOOK_IMAGE } from "./bookImage";
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+});
+const image = (bytes: Uint8Array<ArrayBuffer>) =>
+    new Response(bytes, {
+        headers: {
+            "Content-Type": "image/png",
+            "Content-Length": String(bytes.length),
+        },
+    });
+describe("original book page downloads", () => {
+    it("keeps a page above the old 16 MiB limit byte-for-byte and reports measured progress", async () => {
+        const bytes = new Uint8Array(17 * 1024 * 1024);
+        bytes[0] = 137;
+        bytes[bytes.length - 1] = 41;
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue(image(bytes)));
+        const progress = vi.fn();
+        const result = await loadBookImage(
+            "/api/v1/books?entry=page.png",
+            new AbortController().signal,
+            progress,
+        );
+        expect(result.size).toBe(bytes.length);
+        expect(
+            Buffer.from(await result.arrayBuffer()).equals(
+                Buffer.from(bytes.buffer),
+            ),
+        ).toBe(true);
+        expect(progress).toHaveBeenLastCalledWith({
+            received: bytes.length,
+            total: bytes.length,
+            attempt: 1,
+            retrying: false,
+        });
+    });
+    it.each(["gzip", "br", " GZip ", "gzip, br"])(
+        "accepts decoded %s responses without comparing the compressed length",
+        async (encoding) => {
+            const bytes = new Uint8Array([1, 2, 3]);
+            const response = image(bytes);
+            response.headers.set("Content-Encoding", encoding);
+            response.headers.set("Content-Length", "2");
+            const fetcher = vi.fn().mockResolvedValue(response);
+            vi.stubGlobal("fetch", fetcher);
+            const progress = vi.fn();
+            const result = await loadBookImage(
+                "/page",
+                new AbortController().signal,
+                progress,
+            );
+            expect(new Uint8Array(await result.arrayBuffer())).toEqual(bytes);
+            expect(progress).toHaveBeenLastCalledWith({
+                received: bytes.length,
+                total: 0,
+                attempt: 1,
+                retrying: false,
+            });
+            expect(fetcher).toHaveBeenCalledOnce();
+        },
+    );
+    it.each([undefined, "identity"])(
+        "still rejects an incomplete response with %s encoding",
+        async (encoding) => {
+            vi.useFakeTimers();
+            const fetcher = vi.fn().mockImplementation(() => {
+                const response = image(new Uint8Array([1, 2, 3]));
+                response.headers.set("Content-Length", "4");
+                if (encoding) response.headers.set("Content-Encoding", encoding);
+                return Promise.resolve(response);
+            });
+            vi.stubGlobal("fetch", fetcher);
+            const result = expect(
+                loadBookImage("/page", new AbortController().signal, vi.fn()),
+            ).rejects.toThrow("The page download was interrupted.");
+            await vi.advanceTimersByTimeAsync(6000);
+            await result;
+            expect(fetcher).toHaveBeenCalledTimes(3);
+        },
+    );
+    it("cancels compressed responses above the decoded image limit without retrying", async () => {
+        const cancel = vi.fn();
+        const chunk = new Uint8Array(1024 * 1024);
+        const response = new Response(
+            new ReadableStream({
+                pull(controller) {
+                    controller.enqueue(chunk);
+                },
+                cancel,
+            }),
+            {
+                headers: {
+                    "Content-Type": "image/png",
+                    "Content-Encoding": "gzip",
+                    "Content-Length": "1",
+                },
+            },
+        );
+        const fetcher = vi.fn().mockResolvedValue(response);
+        vi.stubGlobal("fetch", fetcher);
+        await expect(
+            loadBookImage("/page", new AbortController().signal, vi.fn()),
+        ).rejects.toThrow("64 MiB");
+        expect(cancel).toHaveBeenCalledOnce();
+        expect(fetcher).toHaveBeenCalledOnce();
+    });
+    it("shows permanent server errors without retrying", async () => {
+        const fetcher = vi.fn().mockResolvedValue(
+            new Response(
+                JSON.stringify({
+                    detail: "This resource exceeds the 64 MiB preview limit.",
+                }),
+                { status: 422 },
+            ),
+        );
+        vi.stubGlobal("fetch", fetcher);
+        await expect(
+            loadBookImage("/page", new AbortController().signal, vi.fn()),
+        ).rejects.toThrow("64 MiB");
+        expect(fetcher).toHaveBeenCalledTimes(1);
+    });
+    it("automatically retries transient failures and honors Retry-After", async () => {
+        vi.useFakeTimers();
+        const fetcher = vi
+            .fn()
+            .mockResolvedValueOnce(
+                new Response("{}", {
+                    status: 503,
+                    headers: { "Retry-After": "3" },
+                }),
+            )
+            .mockResolvedValueOnce(image(new Uint8Array([1, 2, 3])));
+        vi.stubGlobal("fetch", fetcher);
+        const promise = loadBookImage(
+            "/page",
+            new AbortController().signal,
+            vi.fn(),
+        );
+        await vi.advanceTimersByTimeAsync(2999);
+        expect(fetcher).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(1);
+        expect((await promise).size).toBe(3);
+        expect(fetcher).toHaveBeenCalledTimes(2);
+    });
+    it("cancels retry work when the reader navigates away", async () => {
+        vi.useFakeTimers();
+        const fetcher = vi
+            .fn()
+            .mockRejectedValue(new TypeError("Network error"));
+        vi.stubGlobal("fetch", fetcher);
+        const controller = new AbortController();
+        const result = expect(
+            loadBookImage("/page", controller.signal, vi.fn()),
+        ).rejects.toThrow();
+        await vi.advanceTimersByTimeAsync(1);
+        controller.abort();
+        await result;
+        await vi.advanceTimersByTimeAsync(10000);
+        expect(fetcher).toHaveBeenCalledTimes(1);
+    });
+    it("rejects active content and oversized originals before buffering", async () => {
+        const cancel = vi.fn();
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({
+                ok: true,
+                headers: new Headers({ "Content-Type": "image/svg+xml" }),
+                body: { cancel },
+            }),
+        );
+        await expect(
+            loadBookImage("/page", new AbortController().signal, vi.fn()),
+        ).rejects.toThrow("supported raster");
+        expect(cancel).toHaveBeenCalledTimes(1);
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue(
+                new Response("", {
+                    headers: {
+                        "Content-Type": "image/png",
+                        "Content-Length": String(MAX_BOOK_IMAGE + 1),
+                    },
+                }),
+            ),
+        );
+        await expect(
+            loadBookImage("/page", new AbortController().signal, vi.fn()),
+        ).rejects.toThrow("64 MiB");
+    });
+});
diff --git a/website/src/features/previews/books/bookImage.ts b/website/src/features/previews/books/bookImage.ts
new file mode 100644
index 00000000..4978084d
--- /dev/null
+++ b/website/src/features/previews/books/bookImage.ts
@@ -0,0 +1,162 @@
+import { readBoundedResponse } from "../previewIO";
+
+export const MAX_BOOK_IMAGE = 64 * 1024 * 1024;
+const rasterTypes = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "image/avif",
+]);
+const transient = new Set([408, 429, 500, 502, 503, 504]);
+export type ImageProgress = {
+    received: number;
+    total: number;
+    attempt: number;
+    retrying: boolean;
+};
+class ImageResponseError extends Error {
+    constructor(
+        message: string,
+        readonly retryable: boolean,
+        readonly delay = 0,
+    ) {
+        super(message);
+    }
+}
+function pause(ms: number, signal: AbortSignal) {
+    return new Promise<void>((resolve, reject) => {
+        signal.throwIfAborted();
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+/** Original raster bytes only: no image conversion, resizing or base64. */
+export async function loadBookImage(
+    url: string,
+    signal: AbortSignal,
+    progress: (value: ImageProgress) => void,
+): Promise<Blob> {
+    for (let attempt = 1; ; attempt++) {
+        let received = 0;
+        let total = 0;
+        progress({ received, total, attempt, retrying: false });
+        try {
+            const active = AbortSignal.any([
+                signal,
+                AbortSignal.timeout(90000),
+            ]);
+            const response = await fetch(url, {
+                credentials: "same-origin",
+                signal: active,
+            });
+            if (!response.ok) {
+                let message =
+                    "The page could not be loaded (" + response.status + ").";
+                try {
+                    const data = JSON.parse(
+                        new TextDecoder().decode(
+                            await readBoundedResponse(response, 65536, active),
+                        ),
+                    );
+                    if (typeof data.detail === "string")
+                        message = data.detail.slice(0, 500);
+                } catch {
+                    /* Keep the HTTP status if the error body is unreadable. */
+                }
+                const retry = response.headers.get("Retry-After") || "";
+                const delay = /^\d+$/.test(retry)
+                    ? Number(retry) * 1000
+                    : Math.max(0, Date.parse(retry) - Date.now());
+                throw new ImageResponseError(
+                    message,
+                    transient.has(response.status),
+                    Number.isFinite(delay) ? delay : 0,
+                );
+            }
+            const mime =
+                response.headers.get("Content-Type")?.split(";")[0].trim() ||
+                "";
+            const encoding = response.headers
+                .get("Content-Encoding")
+                ?.trim()
+                .toLowerCase();
+            // Fetch decodes the body, but Content-Length counts encoded bytes.
+            total =
+                !encoding || encoding === "identity"
+                    ? Number(response.headers.get("Content-Length")) || 0
+                    : 0;
+            if (!rasterTypes.has(mime) || total > MAX_BOOK_IMAGE) {
+                await response.body?.cancel();
+                throw new ImageResponseError(
+                    "This page exceeds the 64 MiB image limit or is not a supported raster image.",
+                    false,
+                );
+            }
+            const reader = response.body?.getReader();
+            if (!reader) throw new TypeError("The page response was empty.");
+            const chunks: BlobPart[] = [];
+            let complete = false;
+            let updated = 0;
+            const abort = () => {
+                void reader.cancel().catch(() => {});
+            };
+            active.addEventListener("abort", abort, { once: true });
+            try {
+                while (true) {
+                    active.throwIfAborted();
+                    const { value, done } = await reader.read();
+                    active.throwIfAborted();
+                    if (done) {
+                        complete = true;
+                        break;
+                    }
+                    received += value.byteLength;
+                    if (received > MAX_BOOK_IMAGE)
+                        throw new ImageResponseError(
+                            "This page exceeds the 64 MiB image limit.",
+                            false,
+                        );
+                    chunks.push(value as Uint8Array<ArrayBuffer>);
+                    if (Date.now() - updated > 200) {
+                        progress({ received, total, attempt, retrying: false });
+                        updated = Date.now();
+                    }
+                }
+                if (total && received !== total)
+                    throw new TypeError("The page download was interrupted.");
+                progress({ received, total, attempt, retrying: false });
+                return new Blob(chunks, { type: mime });
+            } finally {
+                active.removeEventListener("abort", abort);
+                if (!complete) await reader.cancel().catch(() => {});
+                reader.releaseLock();
+            }
+        } catch (cause) {
+            signal.throwIfAborted();
+            if (
+                attempt >= 3 ||
+                (cause instanceof ImageResponseError && !cause.retryable)
+            )
+                throw cause;
+            progress({ received, total, attempt, retrying: true });
+            await pause(
+                Math.min(
+                    30000,
+                    Math.max(
+                        2000 * attempt,
+                        cause instanceof ImageResponseError ? cause.delay : 0,
+                    ),
+                ),
+                signal,
+            );
+        }
+    }
+}
diff --git a/website/src/features/previews/pdf/PdfPreview.css b/website/src/features/previews/pdf/PdfPreview.css
new file mode 100644
index 00000000..3486befc
--- /dev/null
+++ b/website/src/features/previews/pdf/PdfPreview.css
@@ -0,0 +1,142 @@
+/* TextLayer positioning adapted from Mozilla PDF.js (Copyright 2014 Mozilla
+ * Foundation), licensed under Apache License 2.0.
+ * https://www.apache.org/licenses/LICENSE-2.0
+ * Scoped to our bounded visible-page layer. */
+.pdf-password {
+    width: min(24rem, calc(100% - 32px));
+    margin: auto;
+    padding: 24px;
+    color: var(--ink);
+    background: var(--surface);
+    border: 1px solid var(--line);
+    border-radius: 10px;
+}
+.pdf-password h2 {
+    margin: 0 0 8px;
+    font-size: 18px;
+}
+.pdf-password label {
+    display: block;
+    margin-block: 16px 6px;
+}
+.pdf-password input {
+    width: 100%;
+    min-height: 44px;
+    padding: 10px;
+    color: var(--ink);
+    background: var(--canvas);
+    border: 1px solid var(--input-line);
+    border-radius: 6px;
+}
+.pdf-password .inline-actions {
+    justify-content: flex-end;
+    gap: 8px;
+    margin-top: 20px;
+}
+.pdf-password button {
+    min-height: 44px;
+}
+.pdf-text-layer {
+    color-scheme: only light;
+    position: absolute;
+    inset: 0;
+    overflow: clip;
+    text-align: initial;
+    line-height: 1;
+    letter-spacing: normal;
+    word-spacing: normal;
+    text-size-adjust: none;
+    forced-color-adjust: none;
+    transform-origin: 0 0;
+    caret-color: CanvasText;
+    --scale-round-x: 1px;
+    --scale-round-y: 1px;
+    --min-font-size: 1;
+    --text-scale-factor: calc(var(--total-scale-factor) * var(--min-font-size));
+    --min-font-size-inv: calc(1 / var(--min-font-size));
+}
+.pdf-text-layer :is(span, br) {
+    color: transparent;
+    position: absolute;
+    white-space: pre;
+    cursor: text;
+    transform-origin: 0% 0%;
+    user-select: text;
+}
+.pdf-text-layer > :not(.markedContent),
+.pdf-text-layer .markedContent span:not(.markedContent) {
+    --font-height: 0;
+    --scale-x: 1;
+    --rotate: 0deg;
+    z-index: 1;
+    font-size: calc(var(--text-scale-factor) * var(--font-height));
+    transform: rotate(var(--rotate)) scaleX(var(--scale-x))
+        scale(var(--min-font-size-inv));
+}
+.pdf-text-layer .markedContent {
+    display: contents;
+}
+.pdf-text-layer ::selection {
+    background: rgb(50 120 245 / 30%);
+    color: transparent;
+}
+
+.pdf-text-layer[data-main-rotation="90"] {
+    transform: rotate(90deg) translateY(-100%);
+}
+.pdf-text-layer[data-main-rotation="180"] {
+    transform: rotate(180deg) translate(-100%, -100%);
+}
+.pdf-text-layer[data-main-rotation="270"] {
+    transform: rotate(270deg) translateX(-100%);
+}
+
+@media (max-width: 720px), (pointer: coarse) {
+    .file-preview .pdf-options-toggle {
+        display: inline-flex;
+    }
+    .file-preview .pdf-controls .pdf-toolbar {
+        display: none;
+        position: fixed;
+        inset: calc(64px + env(safe-area-inset-top))
+            max(12px, env(safe-area-inset-right)) auto
+            max(12px, env(safe-area-inset-left));
+        width: auto;
+        max-width: none;
+        flex-direction: column;
+        align-items: stretch;
+        z-index: 5;
+        gap: 10px;
+        padding: 8px 12px;
+        border: 1px solid #454b55;
+        border-radius: 10px;
+        background: #25292f;
+        box-shadow: 0 6px 20px #0005;
+        max-height: calc(
+            100dvh - 80px - env(safe-area-inset-top) -
+                env(safe-area-inset-bottom)
+        );
+        overflow: auto;
+        overscroll-behavior: contain;
+    }
+    .file-preview .pdf-controls[data-open="true"] .pdf-toolbar {
+        display: flex;
+    }
+    .file-preview .pdf-toolbar .inline-actions {
+        flex-wrap: wrap;
+        gap: 6px;
+    }
+    .file-preview .pdf-toolbar .pdf-fit {
+        width: auto;
+        gap: 6px;
+        padding: 6px 10px;
+    }
+    .file-preview .pdf-toolbar .pdf-fit-label {
+        display: inline;
+    }
+    .file-preview .pdf-toolbar .icon-button,
+    .file-preview .pdf-toolbar .pdf-fit {
+        min-width: 44px;
+        min-height: 44px;
+    }
+}
diff --git a/website/src/features/previews/pdf/PdfPreview.tsx b/website/src/features/previews/pdf/PdfPreview.tsx
new file mode 100644
index 00000000..76630c27
--- /dev/null
+++ b/website/src/features/previews/pdf/PdfPreview.tsx
@@ -0,0 +1,956 @@
+import {
+    checkPdfSize,
+    PdfRangeReader,
+    PDF_RANGE_CHUNK_BYTES,
+} from "./pdfRange";
+import {
+    useCallback,
+    useEffect,
+    useId,
+    useLayoutEffect,
+    useMemo,
+    useRef,
+    useState,
+    type FormEvent,
+} from "react";
+import {
+    ArrowLeftRight,
+    ChevronLeft,
+    ChevronRight,
+    Minus,
+    Plus,
+    Scan,
+    SlidersHorizontal,
+} from "lucide-react";
+import { createPortal } from "react-dom";
+import {
+    getDocument,
+    PDFDataRangeTransport,
+    GlobalWorkerOptions,
+    TextLayer,
+    PasswordResponses,
+    version as pdfjsVersion,
+    type PDFDocumentLoadingTask,
+    type PDFDocumentProxy,
+    type PDFPageProxy,
+    type RenderTask,
+} from "pdfjs-dist";
+import workerUrl from "pdfjs-dist/build/pdf.worker.mjs?worker&url";
+import { ErrorNotice, Spinner } from "../../../shared/components";
+import { errorMessage } from "../../../shared/api";
+import "./PdfPreview.css";
+
+GlobalWorkerOptions.workerSrc = workerUrl;
+const OVERSCAN_PAGE_TARGET = 5;
+const MAX_PDF_PAGES = 10_000;
+const MAX_PAGE_PIXELS = 2_000_000;
+const MAX_TOTAL_PIXELS = 10_000_000;
+const MAX_CANVAS_SIDE = 4096;
+const MAX_TEXT_RUNS = 2500;
+const MAX_TEXT_CHARACTERS = 100_000;
+const MAX_TOTAL_TEXT_RUNS = 12_500;
+const MAX_TOTAL_TEXT_CHARACTERS = 500_000;
+const PAGE_GAP = 24;
+const PDF_RESOURCE_BASE = `/static/pdfjs/${pdfjsVersion}/`;
+const MIN_ZOOM = 0.25;
+const MAX_ZOOM = 5;
+type PageSize = { width: number; height: number };
+type PageFrame = PageSize & { top: number };
+type Layout = { pages: PageFrame[]; width: number; height: number };
+
+function pageSize(page: PDFPageProxy): PageSize {
+    const { width, height } = page.getViewport({ scale: 1 });
+    if (
+        !Number.isFinite(width) ||
+        !Number.isFinite(height) ||
+        width <= 0 ||
+        height <= 0
+    )
+        throw new Error(
+            "This PDF page has invalid dimensions. Download the original instead.",
+        );
+    return { width, height };
+}
+
+/** Keep selectable text bounded too; file text is handed only to PDF.js textContent. */
+function boundedText(
+    source: ReadableStream,
+    maxRuns: number,
+    maxCharacters: number,
+): ReadableStream {
+    const reader = source.getReader();
+    let runs = 0;
+    let characters = 0;
+    let stopped = false;
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const { value, done } = await reader.read();
+                if (done) {
+                    stopped = true;
+                    controller.close();
+                    return;
+                }
+                const items = [];
+                for (const item of value.items) {
+                    if (typeof item.str !== "string") continue;
+                    if (runs >= maxRuns || characters >= maxCharacters) break;
+                    const str = item.str.slice(0, maxCharacters - characters);
+                    items.push({ ...item, str });
+                    runs += 1;
+                    characters += str.length;
+                }
+                controller.enqueue({ ...value, items });
+                if (runs >= maxRuns || characters >= maxCharacters) {
+                    stopped = true;
+                    controller.close();
+                    await reader.cancel();
+                }
+            } catch (error) {
+                if (!stopped) controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            stopped = true;
+            await reader.cancel(reason);
+        },
+    });
+}
+
+function pageAt(pages: PageFrame[], position: number): number {
+    let low = 0;
+    let high = pages.length - 1;
+    while (low < high) {
+        const middle = Math.floor((low + high + 1) / 2);
+        if (pages[middle].top <= position) low = middle;
+        else high = middle - 1;
+    }
+    return low;
+}
+
+function PdfPage({
+    document,
+    number,
+    name,
+    frame,
+    pixelBudget,
+    textRunBudget,
+    textCharacterBudget,
+    onMeasure,
+    onReady,
+    received,
+}: {
+    document: PDFDocumentProxy;
+    number: number;
+    name: string;
+    frame: PageFrame;
+    pixelBudget: number;
+    textRunBudget: number;
+    textCharacterBudget: number;
+    onMeasure: (number: number, size: PageSize) => void;
+    onReady: () => void;
+    received: number;
+}) {
+    const canvas = useRef<HTMLCanvasElement>(null);
+    const textContainer = useRef<HTMLDivElement>(null);
+    const [busy, setBusy] = useState(true);
+    const [error, setError] = useState("");
+    const [textUnavailable, setTextUnavailable] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        let page: PDFPageProxy | undefined;
+        let render: RenderTask | undefined;
+        let textLayer: TextLayer | undefined;
+        const target = canvas.current;
+        const text = textContainer.current;
+        setBusy(true);
+        setError("");
+        setTextUnavailable(false);
+        void (async () => {
+            page = await document.getPage(number);
+            if (cancelled || !target || !text) {
+                page.cleanup();
+                return;
+            }
+            const base = pageSize(page);
+            onMeasure(number, base);
+            const viewport = page.getViewport({
+                scale: frame.width / base.width,
+            });
+            // Visible pages share ten million backing pixels (40 MB RGBA), with a
+            // two-million-pixel per-page ceiling. More pages may fit at low zoom.
+            // Large zoom levels retain CSS size while reducing backing resolution.
+            const outputScale = Math.min(
+                window.devicePixelRatio || 1,
+                2,
+                Math.sqrt(pixelBudget / (viewport.width * viewport.height)),
+                MAX_CANVAS_SIDE / viewport.width,
+                MAX_CANVAS_SIDE / viewport.height,
+            );
+            target.width = Math.min(
+                pixelBudget,
+                Math.max(1, Math.floor(viewport.width * outputScale)),
+            );
+            target.height = Math.min(
+                Math.floor(pixelBudget / target.width),
+                Math.max(1, Math.floor(viewport.height * outputScale)),
+            );
+            render = page.render({
+                canvas: target,
+                viewport,
+                transform: [
+                    target.width / viewport.width,
+                    0,
+                    0,
+                    target.height / viewport.height,
+                    0,
+                    0,
+                ],
+            });
+            await render.promise;
+            if (cancelled) return;
+            setBusy(false);
+            onReady();
+            text.style.setProperty(
+                "--total-scale-factor",
+                String(viewport.scale * viewport.userUnit),
+            );
+            textLayer = new TextLayer({
+                container: text,
+                viewport,
+                textContentSource: boundedText(
+                    page.streamTextContent(),
+                    textRunBudget,
+                    textCharacterBudget,
+                ),
+            });
+            try {
+                await textLayer.render();
+            } catch {
+                if (!cancelled) setTextUnavailable(true);
+            }
+        })().catch((error) => {
+            if (!cancelled) {
+                setError(errorMessage(error));
+                setBusy(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+            render?.cancel();
+            textLayer?.cancel();
+            text?.replaceChildren();
+            if (target) {
+                target.width = 0;
+                target.height = 0;
+            }
+            // PDF.js defers cleanup if another render of this page is still active.
+            void (render?.promise ?? Promise.resolve())
+                .catch(() => {})
+                .then(() => page?.cleanup());
+        };
+    }, [
+        document,
+        number,
+        frame.width,
+        pixelBudget,
+        textRunBudget,
+        textCharacterBudget,
+        onMeasure,
+        onReady,
+    ]);
+    return (
+        <div
+            className="pdf-page"
+            data-page-number={number}
+            role="group"
+            aria-label={"Page " + number}
+            aria-busy={busy}
+            style={{
+                top: frame.top,
+                width: frame.width,
+                height: frame.height,
+            }}
+        >
+            {busy && (
+                <div className="pdf-page-loading" role="status">
+                    <Spinner /> Loading page {number}…
+                    {received > 0 && (
+                        <span>
+                            {(received / 1024 / 1024).toFixed(1)} MiB received
+                            for this PDF
+                        </span>
+                    )}
+                </div>
+            )}
+            {error && (
+                <div className="pdf-page-error">
+                    <ErrorNotice message={error} />
+                    <p>
+                        Download the original to open this page on your device.
+                    </p>
+                </div>
+            )}
+            {textUnavailable && (
+                <span className="sr-only">
+                    Text selection is unavailable on this page. Download the
+                    original for other reading options.
+                </span>
+            )}
+            <canvas
+                ref={canvas}
+                role="img"
+                aria-label={name + ", page " + number}
+                hidden={busy || !!error}
+            />
+            <div
+                ref={textContainer}
+                className="pdf-text-layer"
+                role="group"
+                aria-label={"Selectable text, page " + number}
+                hidden={busy || !!error}
+            />
+        </div>
+    );
+}
+
+export default function PdfPreview({
+    url,
+    name,
+    size,
+    toolbarTarget,
+}: {
+    url: string;
+    name: string;
+    size: number;
+    toolbarTarget: HTMLElement | null;
+}) {
+    const [toolsOpen, setToolsOpen] = useState(false);
+    const tools = useRef<HTMLDivElement>(null);
+    const toolsToggle = useRef<HTMLButtonElement>(null);
+    const toolsId = useId();
+    useEffect(() => {
+        if (!toolsOpen) return;
+        const dismiss = (event: PointerEvent) => {
+            if (
+                event.target instanceof Node &&
+                !tools.current?.contains(event.target)
+            )
+                setToolsOpen(false);
+        };
+        window.document.addEventListener("pointerdown", dismiss);
+        return () =>
+            window.document.removeEventListener("pointerdown", dismiss);
+    }, [toolsOpen]);
+    const [document, setDocument] = useState<PDFDocumentProxy | null>(null);
+    const [sizes, setSizes] = useState<Map<number, PageSize>>(new Map());
+    const [busy, setBusy] = useState(true);
+    const [received, setReceived] = useState(0);
+    const [firstPaint, setFirstPaint] = useState(false);
+    const onReady = useCallback(() => setFirstPaint(true), []);
+    const [error, setError] = useState("");
+    const [zoom, setZoom] = useState<number | null>(null);
+    const [passwordChallenge, setPasswordChallenge] = useState<{
+        reason: "required" | "incorrect";
+    } | null>(null);
+    const passwordReason = passwordChallenge?.reason ?? null;
+    const [password, setPassword] = useState("");
+    const passwordInput = useRef<HTMLInputElement>(null);
+    const openingError = useRef<HTMLDivElement>(null);
+    const providePassword = useRef<((value: string) => void) | null>(null);
+    const cancelOpening = useRef<(() => void) | null>(null);
+    useEffect(() => {
+        if (passwordChallenge) passwordInput.current?.focus();
+    }, [passwordChallenge]);
+    useEffect(() => {
+        if (error) openingError.current?.focus();
+    }, [error]);
+
+    function unlock(event: FormEvent) {
+        event.preventDefault();
+        const provide = providePassword.current;
+        if (!provide || !password) return;
+        providePassword.current = null;
+        setPasswordChallenge(null);
+        setPassword("");
+        provide(password);
+    }
+    const [fit, setFit] = useState<"width" | "page">("width");
+    const [view, setView] = useState({ top: 0, width: 800, height: 700 });
+    const viewRef = useRef(view);
+    viewRef.current = view;
+    const scroll = useRef<HTMLDivElement>(null);
+    const layoutRef = useRef<Layout>({ pages: [], width: 0, height: 0 });
+    const anchor = useRef<{ index: number; fraction: number } | null>(null);
+    const animation = useRef(0);
+    const syncView = useCallback(() => {
+        const target = scroll.current;
+        if (!target) return;
+        setView((old) => {
+            const next = {
+                top: target.scrollTop,
+                width: target.clientWidth,
+                height: target.clientHeight,
+            };
+            return old.top === next.top &&
+                old.width === next.width &&
+                old.height === next.height
+                ? old
+                : next;
+        });
+    }, []);
+    const rememberAnchor = useCallback(() => {
+        const target = scroll.current;
+        const pages = layoutRef.current.pages;
+        if (!target || !pages.length || anchor.current) return;
+        const index = pageAt(pages, target.scrollTop);
+        anchor.current = {
+            index,
+            fraction:
+                (target.scrollTop - pages[index].top) / pages[index].height,
+        };
+    }, []);
+    const measure = useCallback(
+        (number: number, size: PageSize) => {
+            setSizes((old) => {
+                const previous = old.get(number);
+                if (
+                    previous?.width === size.width &&
+                    previous?.height === size.height
+                )
+                    return old;
+                rememberAnchor();
+                return new Map(old).set(number, size);
+            });
+        },
+        [rememberAnchor],
+    );
+
+    useEffect(() => {
+        const controller = new AbortController();
+        let task: PDFDocumentLoadingTask | undefined;
+        let reader: PdfRangeReader | undefined;
+        const fail = (error: unknown) => {
+            if (controller.signal.aborted) return;
+            setError(errorMessage(error));
+            setBusy(false);
+            setDocument(null);
+            setPasswordChallenge(null);
+            setPassword("");
+            providePassword.current = null;
+            controller.abort();
+            reader?.close();
+            void task
+                ?.destroy()
+                .then(() => TextLayer.cleanup())
+                .catch(() => {});
+        };
+        setBusy(true);
+        setFirstPaint(false);
+        setReceived(0);
+        setError("");
+        setPasswordChallenge(null);
+        setPassword("");
+        providePassword.current = null;
+        cancelOpening.current = () => fail(new Error("PDF opening cancelled."));
+        setDocument(null);
+        setSizes(new Map());
+        setZoom(null);
+        setFit("width");
+        anchor.current = null;
+        if (scroll.current) scroll.current.scrollTop = 0;
+        void (async () => {
+            checkPdfSize(size);
+            reader = new PdfRangeReader(url, size, (value) => {
+                if (!controller.signal.aborted) setReceived(value);
+            });
+            const ranges = reader;
+            const transport = new (class extends PDFDataRangeTransport {
+                requestDataRange(begin: number, end: number) {
+                    void ranges
+                        .read(begin, end)
+                        .then((bytes) => {
+                            if (!controller.signal.aborted)
+                                this.onDataRange(begin, bytes);
+                        })
+                        .catch(fail);
+                }
+                abort() {
+                    ranges.close();
+                }
+            })(size, null);
+            task = getDocument({
+                range: transport,
+                rangeChunkSize: PDF_RANGE_CHUNK_BYTES,
+                disableStream: true,
+                disableAutoFetch: true,
+                enableXfa: false,
+                useWorkerFetch: true,
+                useSystemFonts: false,
+                cMapUrl: PDF_RESOURCE_BASE + "cmaps/",
+                cMapPacked: true,
+                standardFontDataUrl: PDF_RESOURCE_BASE + "standard_fonts/",
+                wasmUrl: PDF_RESOURCE_BASE + "wasm/",
+                iccUrl: PDF_RESOURCE_BASE + "iccs/",
+                maxImageSize: 16777216,
+                canvasMaxAreaInBytes: 16777216,
+            });
+            task.onPassword = (
+                provide: (value: string) => void,
+                reason: number,
+            ) => {
+                if (controller.signal.aborted) return;
+                providePassword.current = provide;
+                setPassword("");
+                setPasswordChallenge({
+                    reason:
+                        reason === PasswordResponses.INCORRECT_PASSWORD
+                            ? "incorrect"
+                            : "required",
+                });
+            };
+            const loaded = await task.promise;
+            if (loaded.numPages > MAX_PDF_PAGES)
+                throw new Error(
+                    "PDF preview is limited to 10,000 pages. Download the original instead.",
+                );
+            const first = await loaded.getPage(1);
+            if (controller.signal.aborted) return;
+            setSizes(new Map([[1, pageSize(first)]]));
+            setDocument(loaded);
+            setBusy(false);
+        })().catch(fail);
+        return () => {
+            controller.abort();
+            providePassword.current = null;
+            cancelOpening.current = null;
+            reader?.close();
+            void task
+                ?.destroy()
+                .then(() => TextLayer.cleanup())
+                .catch(() => {});
+        };
+    }, [url, size]);
+
+    const firstSize = sizes.get(1) ?? { width: 612, height: 792 };
+    const fitWidth = Math.max(64, view.width - 32);
+    const fitHeight = Math.max(64, view.height - 32);
+    const layout = useMemo<Layout>(() => {
+        if (!document) return { pages: [], width: view.width, height: 0 };
+        let top = 16;
+        let width = view.width;
+        const pages = Array.from({ length: document.numPages }, (_, index) => {
+            const base = sizes.get(index + 1) ?? firstSize;
+            const pageScale =
+                zoom ??
+                (fit === "page"
+                    ? Math.min(fitWidth / base.width, fitHeight / base.height)
+                    : fitWidth / base.width);
+            const frame = {
+                top,
+                width: base.width * pageScale,
+                height: Math.max(1, base.height * pageScale),
+            };
+            top += frame.height + PAGE_GAP;
+            width = Math.max(width, frame.width + 32);
+            return frame;
+        });
+        return { pages, width, height: Math.max(0, top - PAGE_GAP + 16) };
+    }, [
+        document,
+        sizes,
+        firstSize,
+        fitWidth,
+        fitHeight,
+        fit,
+        zoom,
+        view.width,
+    ]);
+    layoutRef.current = layout;
+    useLayoutEffect(() => {
+        const target = scroll.current;
+        const remembered = anchor.current;
+        if (target && remembered && layout.pages[remembered.index]) {
+            const page = layout.pages[remembered.index];
+            target.scrollTop = Math.max(
+                0,
+                page.top + remembered.fraction * page.height,
+            );
+            anchor.current = null;
+        }
+        syncView();
+    }, [layout, syncView]);
+
+    useEffect(() => {
+        const target = scroll.current;
+        if (!target) return;
+        const observer = new ResizeObserver(() => {
+            if (target.clientWidth !== viewRef.current.width) rememberAnchor();
+            syncView();
+        });
+        observer.observe(target);
+        syncView();
+        return () => {
+            observer.disconnect();
+            cancelAnimationFrame(animation.current);
+        };
+    }, [rememberAnchor, syncView]);
+
+    const current = layout.pages.length
+        ? pageAt(layout.pages, view.top + 24)
+        : 0;
+    const currentSize = sizes.get(current + 1) ?? firstSize;
+    const scale =
+        zoom ??
+        (fit === "page"
+            ? Math.min(
+                  fitWidth / currentSize.width,
+                  fitHeight / currentSize.height,
+              )
+            : fitWidth / currentSize.width);
+    function fitView(mode: "width" | "page") {
+        rememberAnchor();
+        if (mode === "page") anchor.current = { index: current, fraction: 0 };
+        if (scroll.current) scroll.current.scrollLeft = 0;
+        setFit(mode);
+        setZoom(null);
+    }
+    let firstVisible = layout.pages.length ? pageAt(layout.pages, view.top) : 0;
+    if (
+        firstVisible < layout.pages.length - 1 &&
+        layout.pages[firstVisible].top + layout.pages[firstVisible].height <=
+            view.top
+    )
+        firstVisible += 1;
+    let lastVisible = layout.pages.length
+        ? pageAt(layout.pages, view.top + view.height)
+        : 0;
+    if (
+        lastVisible > firstVisible &&
+        layout.pages[lastVisible].top >= view.top + view.height
+    )
+        lastVisible -= 1;
+    const visibleCount = Math.max(1, lastVisible - firstVisible + 1);
+    // Five is an overscan target, never a cap on pages that intersect the view.
+    const targetCount = Math.max(
+        firstPaint ? OVERSCAN_PAGE_TARGET : 1,
+        visibleCount,
+    );
+    const start = Math.max(
+        0,
+        Math.min(
+            firstVisible - Math.floor((targetCount - visibleCount) / 2),
+            layout.pages.length - targetCount,
+        ),
+    );
+    const activePages = layout.pages.slice(start, start + targetCount);
+    const activeCount = Math.max(1, activePages.length);
+    const pixelBudget = Math.min(
+        MAX_PAGE_PIXELS,
+        Math.floor(MAX_TOTAL_PIXELS / activeCount),
+    );
+    const textRunBudget = Math.min(
+        MAX_TEXT_RUNS,
+        Math.floor(MAX_TOTAL_TEXT_RUNS / activeCount),
+    );
+    const textCharacterBudget = Math.min(
+        MAX_TEXT_CHARACTERS,
+        Math.floor(MAX_TOTAL_TEXT_CHARACTERS / activeCount),
+    );
+    function setScale(next: number | null) {
+        const normalized =
+            next === null ? null : Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, next));
+        if (normalized === zoom) return;
+        rememberAnchor();
+        setZoom(normalized);
+    }
+    return (
+        <div className="pdf-preview">
+            {toolbarTarget &&
+                createPortal(
+                    <div
+                        ref={tools}
+                        className="pdf-controls"
+                        data-open={toolsOpen}
+                        onKeyDown={(event) => {
+                            if (event.key === "Escape" && toolsOpen) {
+                                event.preventDefault();
+                                event.stopPropagation();
+                                setToolsOpen(false);
+                                toolsToggle.current?.focus();
+                            }
+                        }}
+                        onBlur={(event) => {
+                            if (
+                                !event.currentTarget.contains(
+                                    event.relatedTarget,
+                                )
+                            )
+                                setToolsOpen(false);
+                        }}
+                    >
+                        <div
+                            className="reader-navigation"
+                            role="group"
+                            aria-label="Page navigation"
+                        >
+                            <button
+                                className="icon-button"
+                                aria-label="Previous page"
+                                disabled={!document || current === 0}
+                                onClick={() => {
+                                    scroll.current?.scrollTo({
+                                        top:
+                                            layout.pages[current - 1]?.top ?? 0,
+                                    });
+                                    syncView();
+                                }}
+                            >
+                                <ChevronLeft size={20} />
+                            </button>
+                            <label
+                                className="sr-only"
+                                htmlFor={toolsId + "-page"}
+                            >
+                                Page
+                            </label>
+                            <select
+                                id={toolsId + "-page"}
+                                value={current + 1}
+                                disabled={!document}
+                                onChange={(event) => {
+                                    scroll.current?.scrollTo({
+                                        top:
+                                            layout.pages[
+                                                Number(event.target.value) - 1
+                                            ]?.top ?? 0,
+                                    });
+                                    syncView();
+                                }}
+                            >
+                                {document ? (
+                                    Array.from(
+                                        { length: document.numPages },
+                                        (_, i) => (
+                                            <option key={i} value={i + 1}>
+                                                Page {i + 1}
+                                            </option>
+                                        ),
+                                    )
+                                ) : (
+                                    <option value={1}>
+                                        {passwordChallenge
+                                            ? "Password Required"
+                                            : "Loading PDF"}
+                                    </option>
+                                )}
+                            </select>
+                            <span className="book-position" aria-live="polite">
+                                {document
+                                    ? current + 1 + " / " + document.numPages
+                                    : ""}
+                            </span>
+                            <button
+                                className="icon-button"
+                                aria-label="Next page"
+                                disabled={
+                                    !document ||
+                                    current >= document.numPages - 1
+                                }
+                                onClick={() => {
+                                    scroll.current?.scrollTo({
+                                        top:
+                                            layout.pages[current + 1]?.top ?? 0,
+                                    });
+                                    syncView();
+                                }}
+                            >
+                                <ChevronRight size={20} />
+                            </button>
+                        </div>
+                        <button
+                            ref={toolsToggle}
+                            type="button"
+                            className="icon-button pdf-options-toggle"
+                            aria-label="PDF View Options"
+                            aria-expanded={toolsOpen}
+                            aria-controls={toolsId}
+                            onClick={() => setToolsOpen((open) => !open)}
+                        >
+                            <SlidersHorizontal size={20} />
+                        </button>
+                        <div
+                            className="pdf-toolbar"
+                            id={toolsId}
+                            role="group"
+                            aria-label="PDF View Controls"
+                        >
+                            <div className="inline-actions">
+                                <button
+                                    className="icon-button"
+                                    aria-label="Zoom Out"
+                                    disabled={!document || scale <= MIN_ZOOM}
+                                    onClick={() => setScale(scale - 0.25)}
+                                >
+                                    <Minus size={18} />
+                                </button>
+                                <span
+                                    className="pdf-zoom"
+                                    aria-label="PDF zoom"
+                                >
+                                    {document
+                                        ? Math.round(scale * 100) + "%"
+                                        : "—"}
+                                </span>
+                                <button
+                                    className="icon-button"
+                                    aria-label="Zoom in"
+                                    disabled={!document || scale >= MAX_ZOOM}
+                                    onClick={() => setScale(scale + 0.25)}
+                                >
+                                    <Plus size={18} />
+                                </button>
+                                <button
+                                    className="secondary-button pdf-fit"
+                                    aria-label="Fit Width"
+                                    aria-pressed={
+                                        zoom === null && fit === "width"
+                                    }
+                                    disabled={!document}
+                                    onClick={() => fitView("width")}
+                                >
+                                    <ArrowLeftRight size={16} />{" "}
+                                    <span className="pdf-fit-label">
+                                        Fit Width
+                                    </span>
+                                </button>
+                                <button
+                                    className="secondary-button pdf-fit"
+                                    aria-label="Fit Page"
+                                    aria-pressed={
+                                        zoom === null && fit === "page"
+                                    }
+                                    disabled={!document}
+                                    onClick={() => fitView("page")}
+                                >
+                                    <Scan size={16} />{" "}
+                                    <span className="pdf-fit-label">
+                                        Fit Page
+                                    </span>
+                                </button>
+                            </div>
+                        </div>
+                    </div>,
+                    toolbarTarget,
+                )}
+            {passwordReason && (
+                <form
+                    className="pdf-password"
+                    onSubmit={unlock}
+                    aria-labelledby={toolsId + "-password-title"}
+                >
+                    <h2 id={toolsId + "-password-title"}>
+                        Password-Protected PDF
+                    </h2>
+                    <p>Enter the document password to open it.</p>
+                    <label htmlFor={toolsId + "-password"}>PDF Password</label>
+                    <input
+                        ref={passwordInput}
+                        id={toolsId + "-password"}
+                        type="password"
+                        value={password}
+                        autoComplete="off"
+                        required
+                        onChange={(event) => setPassword(event.target.value)}
+                        aria-describedby={
+                            passwordReason === "incorrect"
+                                ? toolsId + "-password-error"
+                                : undefined
+                        }
+                        aria-invalid={passwordReason === "incorrect"}
+                    />
+                    {passwordReason === "incorrect" && (
+                        <p
+                            className="error-notice"
+                            role="alert"
+                            id={toolsId + "-password-error"}
+                        >
+                            Incorrect password. Try again.
+                        </p>
+                    )}
+                    <div className="inline-actions">
+                        <button
+                            type="button"
+                            className="secondary-button"
+                            onClick={() => cancelOpening.current?.()}
+                        >
+                            Cancel
+                        </button>
+                        <button
+                            type="submit"
+                            className="primary-button"
+                            disabled={!password}
+                        >
+                            Open PDF
+                        </button>
+                    </div>
+                </form>
+            )}
+            {busy && !passwordReason && (
+                <div className="preview-loading" role="status">
+                    <Spinner /> Loading PDF…
+                    {received > 0 && (
+                        <span>
+                            {(received / 1024 / 1024).toFixed(1)} MiB received
+                        </span>
+                    )}
+                </div>
+            )}
+            {error && (
+                <div
+                    className="preview-pdf-error"
+                    ref={openingError}
+                    tabIndex={-1}
+                >
+                    <ErrorNotice message={error} />
+                    <p>
+                        Download the original to open this PDF on your device.
+                    </p>
+                </div>
+            )}
+            <div
+                className="pdf-scroll"
+                ref={scroll}
+                tabIndex={0}
+                role="region"
+                aria-label={name + " PDF pages"}
+                hidden={busy || !!error}
+                onScroll={() => {
+                    cancelAnimationFrame(animation.current);
+                    animation.current = requestAnimationFrame(syncView);
+                }}
+            >
+                <div
+                    className="pdf-pages"
+                    style={{ width: layout.width, height: layout.height }}
+                >
+                    {activePages.map((frame, index) => (
+                        <PdfPage
+                            key={start + index + 1}
+                            document={document!}
+                            number={start + index + 1}
+                            name={name}
+                            frame={frame}
+                            pixelBudget={pixelBudget}
+                            textRunBudget={textRunBudget}
+                            textCharacterBudget={textCharacterBudget}
+                            onMeasure={measure}
+                            onReady={onReady}
+                            received={received}
+                        />
+                    ))}
+                </div>
+            </div>
+        </div>
+    );
+}
diff --git a/website/src/features/previews/pdf/pdfRange.test.ts b/website/src/features/previews/pdf/pdfRange.test.ts
new file mode 100644
index 00000000..acb031a7
--- /dev/null
+++ b/website/src/features/previews/pdf/pdfRange.test.ts
@@ -0,0 +1,231 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+    checkPdfSize,
+    PDF_RANGE_BUFFER_BUDGET_BYTES,
+    MAX_PDF_SOURCE_BYTES,
+    PdfRangeReader,
+} from "./pdfRange";
+afterEach(() => vi.unstubAllGlobals());
+
+function ranged(size = 4096) {
+    return vi.fn(async (_url: string, options: RequestInit) => {
+        const range = (options.headers as Record<string, string>).Range;
+        const [, begin, end] = /bytes=(\d+)-(\d+)/.exec(range)!;
+        return new Response(
+            new Uint8Array(Number(end) - Number(begin) + 1).fill(7),
+            {
+                status: 206,
+                headers: { "Content-Range": `bytes ${begin}-${end}/${size}` },
+            },
+        );
+    });
+}
+
+describe("bounded PDF byte ranges", () => {
+    it("uses authenticated no-store ranges without a whole-file fallback", async () => {
+        const fetcher = ranged();
+        vi.stubGlobal("fetch", fetcher);
+        const reader = new PdfRangeReader("/file?auth=share", 4096);
+        expect(await reader.read(17, 49)).toEqual(new Uint8Array(32).fill(7));
+        expect(fetcher.mock.calls[0]).toMatchObject([
+            "/file?auth=share",
+            {
+                credentials: "same-origin",
+                cache: "no-store",
+                headers: { Range: "bytes=17-48" },
+            },
+        ]);
+        reader.close();
+    });
+    it.each([200, 401, 403, 404, 410, 503])(
+        "rejects status %s and cancels its body",
+        async (status) => {
+            const cancel = vi.fn();
+            vi.stubGlobal(
+                "fetch",
+                vi.fn(
+                    async () =>
+                        new Response(new ReadableStream({ cancel }), {
+                            status,
+                        }),
+                ),
+            );
+            const reader = new PdfRangeReader("/file", 4096);
+            await expect(reader.read(0, 32)).rejects.toThrow(
+                status === 200 || status === 503
+                    ? "byte-range"
+                    : "access has expired",
+            );
+            expect(cancel).toHaveBeenCalledOnce();
+            reader.close();
+        },
+    );
+    it("rejects changed source identity/size and short bodies", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(
+                async () =>
+                    new Response(new Uint8Array(32), {
+                        status: 206,
+                        headers: { "Content-Range": "bytes 0-31/5000" },
+                    }),
+            ),
+        );
+        const reader = new PdfRangeReader("/file", 4096);
+        await expect(reader.read(0, 32)).rejects.toThrow(
+            "size or byte range changed",
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(
+                async () =>
+                    new Response(new Uint8Array(4), {
+                        status: 206,
+                        headers: { "Content-Range": "bytes 0-31/4096" },
+                    }),
+            ),
+        );
+        await expect(reader.read(0, 32)).rejects.toThrow("incomplete");
+        reader.close();
+    });
+    it("rejects an equal-sized replacement document using the range ETag", async () => {
+        let identity = "first";
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(
+                async () =>
+                    new Response(new Uint8Array(32), {
+                        status: 206,
+                        headers: {
+                            "Content-Range": "bytes 0-31/4096",
+                            ETag: identity,
+                        },
+                    }),
+            ),
+        );
+        const reader = new PdfRangeReader("/file", 4096);
+        await reader.read(0, 32);
+        identity = "replacement";
+        await expect(reader.read(0, 32)).rejects.toThrow(
+            "changed while reading",
+        );
+        reader.close();
+    });
+    it("splits large worker requests into at most 1 MiB HTTP ranges", async () => {
+        const size = 3 * 1024 ** 2;
+        const fetcher = ranged(size);
+        vi.stubGlobal("fetch", fetcher);
+        const reader = new PdfRangeReader("/file", size);
+        expect((await reader.read(0, size)).byteLength).toBe(size);
+        expect(fetcher).toHaveBeenCalledTimes(3);
+        reader.close();
+    });
+    it("caps simultaneous reads and rejects both active and queued work on close", async () => {
+        const signals: AbortSignal[] = [];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(
+                (_url, options) =>
+                    new Promise((_resolve, reject) => {
+                        const signal = options.signal as AbortSignal;
+                        signals.push(signal);
+                        signal.addEventListener(
+                            "abort",
+                            () => reject(signal.reason),
+                            {
+                                once: true,
+                            },
+                        );
+                    }),
+            ),
+        );
+        const reader = new PdfRangeReader("/file", 4096);
+        const pending = [
+            reader.read(0, 10),
+            reader.read(10, 20),
+            reader.read(20, 30),
+        ];
+        const results = Promise.allSettled(pending);
+        expect(signals).toHaveLength(2);
+        reader.close();
+        expect(
+            (await results).every((result) => result.status === "rejected"),
+        ).toBe(true);
+        expect(signals.every((signal) => signal.aborted)).toBe(true);
+        await expect(reader.read(30, 40)).rejects.toThrow();
+    });
+    it("keeps reading after 64 MiB of cumulative traffic", async () => {
+        const size = 2 * 1024 ** 2;
+        const fetcher = ranged(size);
+        vi.stubGlobal("fetch", fetcher);
+        const reader = new PdfRangeReader("/file", size);
+        for (let index = 0; index < 66; index++)
+            expect((await reader.read(0, 1024 ** 2)).byteLength).toBe(
+                1024 ** 2,
+            );
+        expect(fetcher).toHaveBeenCalledTimes(66);
+        reader.close();
+    });
+    it.each([40 * 1024 ** 2, PDF_RANGE_BUFFER_BUDGET_BYTES + 1])(
+        "queues peers while a %s-byte active buffer owns the budget",
+        async (length) => {
+            const signals: AbortSignal[] = [];
+            vi.stubGlobal(
+                "fetch",
+                vi.fn(
+                    (_url, options) =>
+                        new Promise((_resolve, reject) => {
+                            const signal = options.signal as AbortSignal;
+                            signals.push(signal);
+                            signal.addEventListener(
+                                "abort",
+                                () => reject(signal.reason),
+                                {
+                                    once: true,
+                                },
+                            );
+                        }),
+                ),
+            );
+            const reader = new PdfRangeReader("/file", MAX_PDF_SOURCE_BYTES);
+            const pending = [
+                reader.read(0, length),
+                reader.read(0, 40 * 1024 ** 2),
+            ];
+            const results = Promise.allSettled(pending);
+            expect(signals).toHaveLength(1);
+            reader.close();
+            expect(
+                (await results).every((result) => result.status === "rejected"),
+            ).toBe(true);
+        },
+    );
+    it("releases active buffer claims after failures so queued requests proceed", async () => {
+        const length = 40 * 1024 ** 2;
+        const fetcher = vi.fn(async () => new Response(null, { status: 503 }));
+        vi.stubGlobal("fetch", fetcher);
+        const reader = new PdfRangeReader("/file", MAX_PDF_SOURCE_BYTES);
+        const results = await Promise.allSettled([
+            reader.read(0, length),
+            reader.read(0, length),
+        ]);
+        expect(results.every((result) => result.status === "rejected")).toBe(
+            true,
+        );
+        expect(fetcher).toHaveBeenCalledTimes(2);
+        reader.close();
+    });
+    it("rejects invalid ranges and unbounded source sizes before fetch", async () => {
+        const fetcher = vi.fn();
+        vi.stubGlobal("fetch", fetcher);
+        expect(() => checkPdfSize(MAX_PDF_SOURCE_BYTES + 1)).toThrow("256 MiB");
+        expect(() => checkPdfSize(NaN)).toThrow("invalid size");
+        const reader = new PdfRangeReader("/file", MAX_PDF_SOURCE_BYTES);
+        await expect(reader.read(0, MAX_PDF_SOURCE_BYTES + 1)).rejects.toThrow(
+            "invalid byte range",
+        );
+        await expect(reader.read(-1, 20)).rejects.toThrow("invalid byte range");
+        expect(fetcher).not.toHaveBeenCalled();
+        reader.close();
+    });
+});
diff --git a/website/src/features/previews/pdf/pdfRange.ts b/website/src/features/previews/pdf/pdfRange.ts
new file mode 100644
index 00000000..a7bc6ecd
--- /dev/null
+++ b/website/src/features/previews/pdf/pdfRange.ts
@@ -0,0 +1,165 @@
+import { readBoundedResponse } from "../previewIO";
+
+// PDF.js ChunkedStream allocates new Uint8Array(length), even in range mode.
+// Bound its source buffer as well as fetched data and visible-page rendering.
+export const MAX_PDF_SOURCE_BYTES = 256 * 1024 ** 2;
+// Bound buffers held by active requests, not all bytes read during an opening.
+// PDF.js itself retains its source buffer; a cumulative cap prevents valid large
+// documents from opening even when very few HTTP bytes have arrived.
+export const PDF_RANGE_BUFFER_BUDGET_BYTES = 64 * 1024 ** 2;
+export const PDF_RANGE_CHUNK_BYTES = 64 * 1024;
+const HTTP_RANGE_BYTES = 1024 ** 2;
+// PDF.js can fan out page-tree metadata reads before any pages render.
+// Queue descriptors are tiny; the separate byte budget still bounds payloads.
+const MAX_QUEUED_RANGES = 256;
+
+export function checkPdfSize(size: number): void {
+    if (!Number.isSafeInteger(size) || size <= 0)
+        throw new Error(
+            "This PDF has an invalid size. Download the original instead.",
+        );
+    if (size > MAX_PDF_SOURCE_BYTES)
+        throw new Error(
+            "PDF preview supports files up to 256 MiB to protect browser memory. Download the original to read larger files.",
+        );
+}
+
+type Pending = {
+    begin: number;
+    end: number;
+    resolve: (bytes: Uint8Array) => void;
+    reject: (error: unknown) => void;
+};
+
+/** Only explicit, verified byte ranges; never fall back to a full-file GET. */
+export class PdfRangeReader {
+    private controller = new AbortController();
+    private queue: Pending[] = [];
+    private active = 0;
+    private reserved = 0;
+    private stopped = false;
+    private etag: string | null | undefined;
+    private received = 0;
+
+    constructor(
+        private url: string,
+        private size: number,
+        private onProgress?: (received: number) => void,
+    ) {
+        checkPdfSize(size);
+    }
+
+    read(begin: number, end: number): Promise<Uint8Array> {
+        if (this.stopped) return Promise.reject(this.controller.signal.reason);
+        if (
+            !Number.isSafeInteger(begin) ||
+            !Number.isSafeInteger(end) ||
+            begin < 0 ||
+            end <= begin ||
+            end > this.size
+        )
+            return Promise.reject(
+                new Error("The PDF requested an invalid byte range."),
+            );
+        if (this.queue.length >= MAX_QUEUED_RANGES)
+            return Promise.reject(
+                new Error(
+                    "This PDF requires too many simultaneous reads. Download the original instead.",
+                ),
+            );
+        return new Promise((resolve, reject) => {
+            this.queue.push({ begin, end, resolve, reject });
+            this.pump();
+        });
+    }
+
+    close(): void {
+        if (this.stopped) return;
+        this.stopped = true;
+        this.controller.abort();
+        for (const job of this.queue.splice(0))
+            job.reject(this.controller.signal.reason);
+    }
+
+    private pump(): void {
+        while (!this.stopped && this.active < 2 && this.queue.length) {
+            const job = this.queue[0];
+            const length = job.end - job.begin;
+            // One PDF.js metadata request may span most of a valid document. Run
+            // that request alone rather than rejecting it or allocating peers too.
+            if (
+                this.active > 0 &&
+                this.reserved + length > PDF_RANGE_BUFFER_BUDGET_BYTES
+            )
+                break;
+            this.queue.shift();
+            this.active += 1;
+            this.reserved += length;
+            void this.fetchRange(job.begin, job.end)
+                .then(job.resolve, job.reject)
+                .finally(() => {
+                    this.active -= 1;
+                    this.reserved -= length;
+                    this.pump();
+                });
+        }
+    }
+
+    private async fetchRange(begin: number, end: number): Promise<Uint8Array> {
+        const bytes = new Uint8Array(end - begin);
+        for (let start = begin; start < end; start += HTTP_RANGE_BYTES) {
+            const stop = Math.min(end, start + HTTP_RANGE_BYTES);
+            const signal = AbortSignal.any([
+                this.controller.signal,
+                AbortSignal.timeout(60_000),
+            ]);
+            const response = await fetch(this.url, {
+                credentials: "same-origin",
+                cache: "no-store",
+                headers: { Range: `bytes=${start}-${stop - 1}` },
+                signal,
+            });
+            if (response.status !== 206) {
+                await response.body?.cancel();
+                if ([401, 403, 404, 410].includes(response.status))
+                    throw new Error(
+                        "This PDF is no longer available or access has expired. Close the preview and check the share link or sign in again.",
+                    );
+                throw new Error(
+                    "PDF preview needs byte-range responses. Reload the preview or download the original; the server did not return the requested section.",
+                );
+            }
+            if (
+                response.headers.get("Content-Range") !==
+                `bytes ${start}-${stop - 1}/${this.size}`
+            ) {
+                await response.body?.cancel();
+                throw new Error(
+                    "The PDF size or byte range changed. Close and reopen the preview.",
+                );
+            }
+            const etag = response.headers.get("ETag");
+            if (this.etag === undefined) this.etag = etag;
+            else if (etag !== this.etag) {
+                await response.body?.cancel();
+                throw new Error(
+                    "This PDF changed while reading. Close and reopen the preview.",
+                );
+            }
+            const part = await readBoundedResponse(
+                response,
+                stop - start,
+                signal,
+            );
+            signal.throwIfAborted();
+            if (part.byteLength !== stop - start)
+                throw new Error(
+                    "A PDF section arrived incomplete. Reload the preview or download the original.",
+                );
+            bytes.set(part, start - begin);
+            this.received += part.byteLength;
+            this.onProgress?.(this.received);
+        }
+        return bytes;
+    }
+}
diff --git a/website/src/features/previews/previewIO.test.ts b/website/src/features/previews/previewIO.test.ts
new file mode 100644
index 00000000..aa5063af
--- /dev/null
+++ b/website/src/features/previews/previewIO.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from "vitest";
+import { PreviewLimitError, readBoundedResponse } from "./previewIO";
+describe("bounded preview request cleanup", () => {
+    it("cancels an oversized declared body before reading it", async () => {
+        const cancel = vi.fn();
+        const response = new Response(new ReadableStream({ cancel }), {
+            headers: { "Content-Length": "500" },
+        });
+        await expect(
+            readBoundedResponse(response, 100, new AbortController().signal),
+        ).rejects.toBeInstanceOf(PreviewLimitError);
+        expect(cancel).toHaveBeenCalledOnce();
+    });
+    it("cancels a source that exceeds its declared length", async () => {
+        const cancel = vi.fn();
+        const response = new Response(
+            new ReadableStream({
+                start(controller) {
+                    controller.enqueue(new Uint8Array(101));
+                },
+                cancel,
+            }),
+            { headers: { "Content-Length": "1" } },
+        );
+        await expect(
+            readBoundedResponse(response, 100, new AbortController().signal),
+        ).rejects.toBeInstanceOf(PreviewLimitError);
+        expect(cancel).toHaveBeenCalledOnce();
+    });
+    it("cancels a pending reader when a preview is closed", async () => {
+        const cancel = vi.fn(),
+            controller = new AbortController();
+        const response = new Response(new ReadableStream({ cancel }));
+        const task = readBoundedResponse(response, 100, controller.signal);
+        controller.abort();
+        await expect(task).rejects.toMatchObject({ name: "AbortError" });
+        expect(cancel).toHaveBeenCalledOnce();
+    });
+});
diff --git a/website/src/features/previews/previewIO.ts b/website/src/features/previews/previewIO.ts
new file mode 100644
index 00000000..fc1aba0a
--- /dev/null
+++ b/website/src/features/previews/previewIO.ts
@@ -0,0 +1,50 @@
+export class PreviewLimitError extends Error {}
+/** Read no more than limit bytes, releasing the request on every early exit. */
+export async function readBoundedResponse(
+    response: Response,
+    limit: number,
+    signal: AbortSignal,
+): Promise<Uint8Array> {
+    const declared = Number(response.headers.get("Content-Length"));
+    if (Number.isFinite(declared) && declared > limit) {
+        await response.body?.cancel();
+        throw new PreviewLimitError("Preview exceeds the allowed size.");
+    }
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("The preview response was empty.");
+    const abort = () => {
+        void reader.cancel().catch(() => {});
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    const chunks: Uint8Array[] = [];
+    let size = 0,
+        complete = false;
+    try {
+        signal.throwIfAborted();
+        while (true) {
+            const { done, value } = await reader.read();
+            signal.throwIfAborted();
+            if (done) {
+                complete = true;
+                break;
+            }
+            size += value.byteLength;
+            if (size > limit)
+                throw new PreviewLimitError(
+                    "Preview exceeds the allowed size.",
+                );
+            chunks.push(value);
+        }
+    } finally {
+        signal.removeEventListener("abort", abort);
+        if (!complete) await reader.cancel().catch(() => {});
+        reader.releaseLock();
+    }
+    const data = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        data.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return data;
+}
diff --git a/website/src/features/previews/video/AdvancedVideo.css b/website/src/features/previews/video/AdvancedVideo.css
new file mode 100644
index 00000000..13449316
--- /dev/null
+++ b/website/src/features/previews/video/AdvancedVideo.css
@@ -0,0 +1,250 @@
+.advanced-video {
+    isolation: isolate;
+    background: #080a0d;
+}
+.advanced-player-host {
+    z-index: 0;
+}
+/* Focus may scroll an overflow:hidden host when a settings page changes height.
+   Only the menu should scroll; the video and its controls stay in place. */
+.advanced-video movi-player {
+    overflow: clip;
+}
+.advanced-video movi-player::part(spinner) {
+    visibility: hidden;
+}
+.advanced-state {
+    position: absolute;
+    inset: 0;
+    z-index: 2;
+    display: grid;
+    place-items: center;
+    padding: 20px;
+    background: transparent;
+    color: #f5f5f5;
+    pointer-events: none;
+}
+.advanced-state[data-hidden="true"] {
+    visibility: hidden;
+}
+.advanced-state-content {
+    width: min(100%, 420px);
+    text-align: center;
+}
+.advanced-state h3 {
+    margin: 0;
+    font-size: 18px;
+    font-weight: 500;
+    line-height: 1.4;
+    letter-spacing: normal;
+}
+.advanced-state p {
+    max-width: 38ch;
+    margin: 10px auto 0;
+    color: #c4c7cc;
+    font-size: 14px;
+    line-height: 1.65;
+    overflow-wrap: anywhere;
+}
+.advanced-state-actions {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 10px;
+    margin-top: 10px;
+    pointer-events: auto;
+}
+.advanced-state-actions button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    min-height: 44px;
+    padding: 8px 14px;
+    border: 1px solid #64686e;
+    border-radius: 6px;
+    background: #303236;
+    color: #f5f5f5;
+    font-size: 14px;
+    line-height: 1.4;
+    cursor: pointer;
+}
+.advanced-state-actions button:hover {
+    border-color: #c4c7cc;
+    background: #414449;
+}
+.advanced-state-actions button:focus-visible {
+    outline: 2px solid #b6c9ff;
+    outline-offset: 3px;
+}
+.advanced-state-actions button:disabled {
+    opacity: 0.6;
+    cursor: default;
+}
+.advanced-state-buffering {
+    inset: auto 16px 102px;
+    padding: 0;
+    background: transparent;
+    max-height: calc(100% - 118px);
+    overflow-y: auto;
+    overscroll-behavior: contain;
+}
+.advanced-state-buffering .advanced-state-content {
+    width: fit-content;
+    max-width: 100%;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: center;
+    gap: 4px 12px;
+    padding: 4px 10px;
+    border-radius: 4px;
+    background: rgb(0 0 0 / 68%);
+}
+.advanced-wait-label {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    font-size: 14px;
+    line-height: 1.5;
+}
+.advanced-wait-label [role="progressbar"] {
+    display: flex;
+    flex-shrink: 0;
+}
+.advanced-wait-label svg {
+    animation: advanced-loading 1s linear infinite;
+}
+.advanced-transfer {
+    margin-top: 0;
+    color: #d5d8de;
+    font-size: 12px;
+    line-height: 1.5;
+    font-variant-numeric: tabular-nums;
+}
+.advanced-transfer-network {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 2px 14px;
+}
+.advanced-state-buffering .advanced-state-actions {
+    margin: 0;
+}
+.advanced-state-buffering .advanced-state-actions button {
+    min-height: 36px;
+    padding: 4px 6px;
+    border: 0;
+    background: transparent;
+    font-size: 12px;
+}
+.advanced-state-error .advanced-state-content {
+    max-height: 100%;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    pointer-events: auto;
+    padding: 20px;
+    border-radius: 8px;
+    background: rgb(20 21 23 / 96%);
+}
+@keyframes advanced-loading {
+    to {
+        transform: rotate(360deg);
+    }
+}
+@media (max-width: 720px), (pointer: coarse) {
+    .advanced-state-actions button {
+        min-height: 44px;
+    }
+}
+@media (max-width: 480px) {
+    .advanced-state-buffering {
+        inset-inline: 12px;
+    }
+}
+
+.advanced-video movi-player::part(progress-buffer) {
+    background: #abb7ce;
+    opacity: 0.65;
+}
+.advanced-video movi-player::part(error-screen) {
+    display: none;
+}
+/* Movi's controls-visible blanket rule otherwise makes its collapsed tray
+   interactive. Keep hidden compact controls out of pointer and keyboard paths. */
+@container movi-host (max-width: 720px) {
+    :host .movi-more-btn,
+    :host .movi-gear-btn,
+    :host .movi-mobile-expandable,
+    :host .movi-controls-right .movi-aspect-ratio-btn,
+    :host .movi-controls-right .movi-pip-btn {
+        display: none !important;
+    }
+    :host .movi-controls-right .movi-settings-container,
+    :host .movi-controls-right .movi-settings-btn,
+    :host .movi-controls-right > .movi-fullscreen-btn {
+        display: flex !important;
+    }
+    :host .movi-controls-right .movi-settings-btn,
+    :host .movi-controls-right > .movi-fullscreen-btn {
+        width: 44px !important;
+        height: 44px !important;
+        flex: 0 0 44px;
+    }
+}
+
+/* Keep native menus inside the player and their controls touch-accessible. */
+.movi-settings-menu {
+    max-width: calc(100% - 16px);
+    max-height: min(calc(var(--movi-player-height, 70vh) - 96px), 520px);
+}
+.movi-settings-row,
+.movi-settings-choice {
+    min-height: 44px;
+    padding: 8px 10px;
+    font-size: 14px;
+}
+.advanced-quality-list {
+    display: grid;
+    gap: 2px;
+}
+.advanced-quality-list button {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    width: 100%;
+    min-height: 44px;
+    padding: 10px 12px;
+    border: 0;
+    border-radius: 4px;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    font-size: 14px;
+    text-align: start;
+    cursor: pointer;
+}
+.advanced-quality-list button:hover,
+.advanced-quality-list button[aria-pressed="true"] {
+    background: #303236;
+}
+.advanced-quality-list button span {
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.advanced-quality-list svg {
+    flex-shrink: 0;
+    width: 18px;
+    height: 18px;
+}
+.movi-settings-row:hover,
+.movi-settings-row:active {
+    transform: none;
+}
+@media (prefers-reduced-motion: reduce) {
+    .advanced-wait-label svg {
+        animation: none;
+    }
+}
diff --git a/website/src/features/previews/video/AdvancedVideo.test.ts b/website/src/features/previews/video/AdvancedVideo.test.ts
new file mode 100644
index 00000000..85aef3e3
--- /dev/null
+++ b/website/src/features/previews/video/AdvancedVideo.test.ts
@@ -0,0 +1,251 @@
+import { describe, expect, it } from "vitest";
+import {
+    initialVideoLoadState,
+    unavailableVideoCodec,
+    videoLoadTransition,
+    videoResumeTime,
+    videoIsAdvancing,
+    videoHasChapters,
+    videoBufferSnapshot,
+    type VideoLoadState,
+} from "./AdvancedVideo";
+
+describe("stale buffering recovery", () => {
+    it("accepts advancing playback, but not paused clocks or seek jumps", () => {
+        expect(videoIsAdvancing(12, 12.25, false, false)).toBe(true);
+        expect(videoIsAdvancing(12, 12 + 1 / 120, false, false)).toBe(true);
+        expect(videoIsAdvancing(12, 12, false, false)).toBe(false);
+        expect(videoIsAdvancing(12, 12.25, true, false)).toBe(false);
+        expect(videoIsAdvancing(12, 12.25, false, true)).toBe(false);
+        expect(videoIsAdvancing(12, 90, false, false)).toBe(false);
+        expect(videoIsAdvancing(Number.NaN, 12, false, false)).toBe(false);
+    });
+    it("enables native chapters only for actual in-range chapter metadata", () => {
+        expect(
+            videoHasChapters(
+                [
+                    { start: 0 },
+                    { start: 12.5 },
+                    { start: Number.NaN },
+                    { start: 40 },
+                ],
+                30,
+            ),
+        ).toBe(true);
+        expect(videoHasChapters([], 30)).toBe(false);
+        expect(videoHasChapters([{ start: -1 }, { start: 40 }], 30)).toBe(
+            false,
+        );
+        expect(videoHasChapters([{ start: Number.NaN }], 30)).toBe(false);
+        expect(videoHasChapters([{ start: 12 }], Number.NaN)).toBe(true);
+    });
+});
+
+describe("video startup and buffering states", () => {
+    it("uses actual engine and track events for startup phases", () => {
+        const opening = videoLoadTransition(
+            initialVideoLoadState,
+            "engine-loaded",
+        );
+        expect(opening).toEqual({ phase: "opening", ready: false });
+        expect(videoLoadTransition(opening, "trackschange")).toEqual({
+            phase: "preparing",
+            ready: false,
+        });
+    });
+    it.each(["loadedmetadata", "loadeddata", "canplay", "ready"] as const)(
+        "unlocks controls on %s without requiring playback or autoplay",
+        (event) => {
+            expect(videoLoadTransition(initialVideoLoadState, event)).toEqual({
+                phase: "ready",
+                ready: true,
+            });
+        },
+    );
+    it("keeps a startup wait distinct from a playback stall", () => {
+        expect(videoLoadTransition(initialVideoLoadState, "waiting")).toEqual({
+            phase: "preparing",
+            ready: false,
+        });
+        expect(
+            videoLoadTransition({ phase: "ready", ready: true }, "waiting"),
+        ).toEqual({ phase: "buffering", ready: true });
+    });
+    it("leaves controls available during buffering and seeking", () => {
+        const ready: VideoLoadState = { phase: "ready", ready: true };
+        const buffering = videoLoadTransition(ready, "waiting");
+        const seeking = videoLoadTransition(buffering, "seeking");
+        expect(seeking).toEqual({ phase: "seeking", ready: true });
+        expect(videoLoadTransition(seeking, "seeked")).toEqual(ready);
+        expect(videoLoadTransition(buffering, "pause")).toEqual(ready);
+        expect(videoLoadTransition(buffering, "playing")).toEqual(ready);
+        expect(videoLoadTransition(buffering, "ended")).toEqual(ready);
+    });
+    it("does not mistake pausing before metadata for loaded media", () => {
+        expect(videoLoadTransition(initialVideoLoadState, "pause")).toEqual(
+            initialVideoLoadState,
+        );
+    });
+    it("does not reopen startup when tracks change during playback", () => {
+        const ready: VideoLoadState = { phase: "ready", ready: true };
+        expect(videoLoadTransition(ready, "trackschange")).toBe(ready);
+        expect(videoLoadTransition(ready, "loadstart")).toEqual({
+            phase: "opening",
+            ready: false,
+        });
+        expect(videoLoadTransition(ready, "reset")).toEqual(
+            initialVideoLoadState,
+        );
+    });
+});
+
+describe("saved video position bounds", () => {
+    it("preserves a valid saved position until the new duration is known", () => {
+        expect(videoResumeTime(37.5)).toBe(37.5);
+        expect(videoResumeTime(37.5, 0)).toBe(37.5);
+        expect(videoResumeTime(37.5, Number.NaN)).toBe(37.5);
+        expect(videoResumeTime(37.5, 80)).toBe(37.5);
+    });
+    it("keeps a restored position inside a shorter rendition", () => {
+        expect(videoResumeTime(37.5, 30)).toBe(29.9);
+        expect(videoResumeTime(37.5, 0.05)).toBe(0);
+    });
+    it("normalizes invalid positions without creating an invalid startup seek", () => {
+        expect(videoResumeTime(-1, 30)).toBe(0);
+        expect(videoResumeTime(Number.NaN, 30)).toBe(0);
+        expect(videoResumeTime(Number.POSITIVE_INFINITY, 30)).toBe(0);
+    });
+});
+
+describe("settled video decoder availability", () => {
+    const tracks = [{ type: "video", codec: "msmpeg4v3" }];
+    it("detects an actually rejected decoder rather than trusting a ready clock", () => {
+        expect(
+            unavailableVideoCodec({
+                videoDecoder: { configured: false },
+                getMediaInfo: () => ({ tracks }),
+            }),
+        ).toBe("msmpeg4v3");
+    });
+    it("keeps supported ASF codecs and unrecognized adapter shapes available", () => {
+        expect(
+            unavailableVideoCodec({
+                videoDecoder: { configured: true },
+                getMediaInfo: () => ({ tracks }),
+            }),
+        ).toBeNull();
+        expect(
+            unavailableVideoCodec({ getMediaInfo: () => ({ tracks }) }),
+        ).toBeNull();
+        expect(unavailableVideoCodec(null)).toBeNull();
+    });
+    it("does not reject audio-only media or cover art", () => {
+        for (const mediaTracks of [
+            [{ type: "audio", codec: "aac" }],
+            [{ type: "video", codec: "mjpeg", isAttachedPic: true }],
+        ]) {
+            expect(
+                unavailableVideoCodec({
+                    videoDecoder: { configured: false },
+                    getMediaInfo: () => ({ tracks: mediaTracks }),
+                }),
+            ).toBeNull();
+        }
+    });
+});
+
+describe("measured player buffer", () => {
+    function snapshot(
+        ranges: [number, number][],
+        duration = 100,
+        currentTime = 45,
+    ) {
+        return videoBufferSnapshot({
+            duration,
+            currentTime,
+            buffered: {
+                length: ranges.length,
+                start: (index) => ranges[index][0],
+                end: (index) => ranges[index][1],
+            },
+            player: {
+                getSource: () => ({
+                    getNetworkStats: () => ({
+                        totalBytes: 4194304,
+                        currentSpeed: 524288,
+                    }),
+                }),
+            },
+        });
+    }
+    it("uses engine time ranges and measured delivery, including disjoint regions", () => {
+        expect(
+            snapshot([
+                [0, 10],
+                [40, 60],
+            ]),
+        ).toEqual({
+            ranges: [
+                { start: 0, end: 10 },
+                { start: 40, end: 60 },
+            ],
+            received: 4194304,
+            bytesPerSecond: 524288,
+            measured: true,
+            decodedSeconds: 0,
+            deliveryWaiting: false,
+            decodeBound: false,
+            softwareDecoding: false,
+        });
+    });
+    it("keeps source ranges as estimates without claiming decoded readiness", () => {
+        const result = snapshot([[40, 50]], Number.NaN);
+        expect(result).not.toHaveProperty("percent");
+        expect(result).not.toHaveProperty("ahead");
+        expect(snapshot([], 0).received).toBe(4194304);
+    });
+    it("does not mark an unfetched seek gap as available", () => {
+        const afterSeek = snapshot([[80, 90]], 100, 80);
+        expect(afterSeek.ranges).toEqual([{ start: 80, end: 90 }]);
+        expect(snapshot([[0, 10]], 100, 80).ranges).toEqual([
+            { start: 0, end: 10 },
+        ]);
+    });
+    it("merges overlap, clamps the duration and ignores invalid ranges", () => {
+        const result = snapshot([
+            [40, 60],
+            [50, 120],
+            [90, 80],
+            [NaN, 3],
+        ]);
+        expect(result.ranges).toEqual([{ start: 40, end: 100 }]);
+    });
+    it("keeps network delivery separate from decoded pictures and unknown metrics", () => {
+        const result = videoBufferSnapshot({
+            duration: 100,
+            currentTime: 45,
+            buffered: { length: 1, start: () => 0, end: () => 100 },
+            player: {
+                getSource: () => ({
+                    getNetworkStats: () => ({
+                        totalBytes: NaN,
+                        currentSpeed: Infinity,
+                    }),
+                }),
+                pictureRunwaySeconds: () => 0.75,
+                deliveryStarved: () => false,
+                isDecodeBound: () => true,
+                isSoftwareDecoding: () => true,
+            },
+        });
+        expect(result.ranges).toEqual([{ start: 0, end: 100 }]);
+        expect(result.measured).toBe(false);
+        expect(result.received).toBe(0);
+        expect(result.bytesPerSecond).toBe(0);
+        expect(result.decodedSeconds).toBe(0.75);
+        expect(result.decodeBound).toBe(true);
+        expect(result.softwareDecoding).toBe(true);
+        expect(result.deliveryWaiting).toBe(false);
+        expect(result).not.toHaveProperty("percent");
+    });
+});
diff --git a/website/src/features/previews/video/AdvancedVideo.tsx b/website/src/features/previews/video/AdvancedVideo.tsx
new file mode 100644
index 00000000..4844fbde
--- /dev/null
+++ b/website/src/features/previews/video/AdvancedVideo.tsx
@@ -0,0 +1,922 @@
+import { useEffect, useReducer, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { LoaderCircle, RefreshCw } from "lucide-react";
+import type { MoviElement } from "movi-player/element/slim";
+import wasmUrl from "movi-player/movi.wasm?url";
+import MovTextRenderer, { isMovTextCodec } from "./MovTextRenderer";
+import {
+    attachVideoPresentation,
+    refreshVideoActions,
+    clearVideoQualityControl,
+    installVideoPresentation,
+    setVideoQualityControl,
+    type VideoQualityControl,
+} from "./videoPlayerPresentation";
+import { installVideoPlayerPip } from "./videoPlayerPip";
+import { attachVideoGestures } from "./videoPlayerGestures";
+import { formatBytes } from "../../../shared/types";
+import { videoSourceMemoryBudgetMiB } from "./videoBufferMemory";
+import "./AdvancedVideo.css";
+import advancedStyles from "./AdvancedVideo.css?inline";
+
+let stylesInstalled = false;
+/** Compatibility adapter for pinned 0.4.1: retain strict style CSP and local fonts. */
+function installLocalStyles(constructor: typeof MoviElement) {
+    if (stylesInstalled) return;
+    const prototype = constructor.prototype as unknown as {
+        addStyles: (shadow: ShadowRoot) => void;
+    };
+    const original = prototype.addStyles;
+    if (
+        typeof original !== "function" ||
+        !("adoptedStyleSheets" in ShadowRoot.prototype)
+    )
+        throw new Error("Enhanced playback is unavailable in this browser.");
+    prototype.addStyles = function (shadow: ShadowRoot) {
+        const sheets: CSSStyleSheet[] = [];
+        // The library writes its static stylesheet and optional Google-font import
+        // through these two methods. Never insert either inline stylesheet in the DOM.
+        const target = {
+            querySelector(selector: string) {
+                return selector === "style[data-movi-font]"
+                    ? shadow.host
+                    : shadow.querySelector(selector);
+            },
+            appendChild(node: Node) {
+                if (!(node instanceof HTMLStyleElement))
+                    throw new Error(
+                        "Unexpected enhanced-player style content.",
+                    );
+                const sheet = new CSSStyleSheet();
+                sheet.replaceSync(
+                    (node.textContent || "").replace(/@import[^;]+;/g, ""),
+                );
+                sheets.push(sheet);
+                return node;
+            },
+        };
+        original.call(this, target as unknown as ShadowRoot);
+        const focus = new CSSStyleSheet();
+        focus.replaceSync(
+            "button:focus-visible,input:focus-visible,select:focus-visible,[tabindex]:focus-visible{outline:2px solid #b9c6ff!important;outline-offset:3px!important}" +
+                advancedStyles,
+        );
+        shadow.adoptedStyleSheets = [
+            ...shadow.adoptedStyleSheets,
+            ...sheets,
+            focus,
+        ];
+    };
+    stylesInstalled = true;
+}
+export type VideoLoadState = {
+    phase:
+        "player" | "opening" | "preparing" | "ready" | "buffering" | "seeking";
+    ready: boolean;
+};
+type VideoLoadEvent =
+    | "reset"
+    | "engine-loaded"
+    | "loadstart"
+    | "trackschange"
+    | "loadedmetadata"
+    | "loadeddata"
+    | "canplay"
+    | "ready"
+    | "playing"
+    | "waiting"
+    | "seeking"
+    | "seeked"
+    | "pause"
+    | "ended";
+export const initialVideoLoadState: VideoLoadState = {
+    phase: "player",
+    ready: false,
+};
+/** Metadata readiness and playback intent are distinct: opening never needs autoplay. */
+export function videoLoadTransition(
+    state: VideoLoadState,
+    event: VideoLoadEvent,
+): VideoLoadState {
+    switch (event) {
+        case "reset":
+            return initialVideoLoadState;
+        case "engine-loaded":
+        case "loadstart":
+            return { phase: "opening", ready: false };
+        case "trackschange":
+            return state.ready ? state : { phase: "preparing", ready: false };
+        case "loadedmetadata":
+        case "loadeddata":
+        case "canplay":
+        case "ready":
+        case "playing":
+            return state.phase === "ready"
+                ? state
+                : { phase: "ready", ready: true };
+        case "waiting":
+            return state.ready
+                ? { phase: "buffering", ready: true }
+                : { phase: "preparing", ready: false };
+        case "seeking":
+            return state.ready
+                ? { phase: "seeking", ready: true }
+                : { phase: "preparing", ready: false };
+        case "seeked":
+        case "pause":
+        case "ended":
+            return state.ready ? { phase: "ready", ready: true } : state;
+    }
+}
+/** Only real container chapters should expose the player's chapter timeline. */
+export function videoHasChapters(
+    chapters: { start: number }[],
+    duration: number,
+): boolean {
+    return chapters.some(
+        (chapter) =>
+            Number.isFinite(chapter.start) &&
+            chapter.start >= 0 &&
+            (!Number.isFinite(duration) ||
+                duration <= 0 ||
+                chapter.start < duration),
+    );
+}
+/** Advancing pictures clear a stale buffering event; a seek jump is not playback. */
+export function videoIsAdvancing(
+    previous: number,
+    current: number,
+    paused: boolean,
+    seeking: boolean,
+): boolean {
+    return (
+        !paused &&
+        !seeking &&
+        Number.isFinite(previous) &&
+        Number.isFinite(current) &&
+        current - previous > 0 &&
+        current - previous < 2
+    );
+}
+/** Saved positions can come from a longer rendition; never seek past its end. */
+export function videoResumeTime(time: number, duration?: number): number {
+    const target = Number.isFinite(time) ? Math.max(0, time) : 0;
+    return duration !== undefined && Number.isFinite(duration) && duration > 0
+        ? Math.min(target, Math.max(0, duration - 0.1))
+        : target;
+}
+/** Read-only adapter for pinned Movi 0.4.1, after decoder initialization settles.
+ * That version can announce ready even when its software decoder rejected a codec.
+ * Missing adapter fields are inconclusive; never guess from a filename or a timer.
+ */
+export function unavailableVideoCodec(core: unknown): string | null {
+    const player = core as {
+        videoDecoder?: { configured?: boolean };
+        getMediaInfo?: () => {
+            tracks?: {
+                type?: string;
+                codec?: string;
+                isAttachedPic?: boolean;
+            }[];
+        } | null;
+    } | null;
+    if (player?.videoDecoder?.configured !== false) return null;
+    const video = player
+        .getMediaInfo?.()
+        ?.tracks?.find(
+            (track) => track.type === "video" && !track.isAttachedPic,
+        );
+    if (!video) return null;
+    return video.codec && /^[a-z0-9_.-]{1,48}$/i.test(video.codec)
+        ? video.codec
+        : "unknown";
+}
+export type VideoBufferSnapshot = {
+    ranges: { start: number; end: number }[];
+    received: number;
+    bytesPerSecond: number;
+    measured: boolean;
+    decodedSeconds: number;
+    deliveryWaiting: boolean;
+    decodeBound: boolean;
+    softwareDecoding: boolean;
+};
+/** Movi's source-window time ranges are estimates, not decoded readiness. */
+export function videoBufferSnapshot(player: {
+    duration: number;
+    currentTime: number;
+    buffered: TimeRanges;
+    player?: {
+        getSource?: () => unknown;
+        pictureRunwaySeconds?: () => number;
+        deliveryStarved?: () => boolean;
+        isDecodeBound?: () => boolean;
+        isSoftwareDecoding?: () => boolean;
+    } | null;
+}): VideoBufferSnapshot {
+    const duration = player.duration;
+    const bounded = Number.isFinite(duration) && duration > 0;
+    const ranges: VideoBufferSnapshot["ranges"] = [];
+    for (let index = 0; index < player.buffered.length; index++) {
+        const start = Math.max(0, player.buffered.start(index));
+        const rawEnd = player.buffered.end(index);
+        const end = bounded ? Math.min(duration, rawEnd) : rawEnd;
+        if (Number.isFinite(start) && Number.isFinite(end) && end > start)
+            ranges.push({ start, end });
+    }
+    ranges.sort((left, right) => left.start - right.start);
+    const merged: typeof ranges = [];
+    for (const range of ranges) {
+        const last = merged.at(-1);
+        if (last && range.start <= last.end)
+            last.end = Math.max(last.end, range.end);
+        else merged.push({ ...range });
+    }
+    const source = player.player?.getSource?.() as {
+        getNetworkStats?: () => { totalBytes?: number; currentSpeed?: number };
+    } | null;
+    const stats = source?.getNetworkStats?.();
+    const positive = (value: number | undefined) =>
+        value !== undefined && Number.isFinite(value) && value > 0 ? value : 0;
+    return {
+        ranges: merged,
+        received: positive(stats?.totalBytes),
+        bytesPerSecond: positive(stats?.currentSpeed),
+        measured:
+            Number.isFinite(stats?.totalBytes) &&
+            (stats?.totalBytes ?? -1) >= 0,
+        decodedSeconds: positive(player.player?.pictureRunwaySeconds?.()),
+        deliveryWaiting: player.player?.deliveryStarved?.() === true,
+        decodeBound: player.player?.isDecodeBound?.() === true,
+        softwareDecoding: player.player?.isSoftwareDecoding?.() === true,
+    };
+}
+const phaseCopy = {
+    player: "Loading video…",
+    opening: "Loading video…",
+    preparing: "Loading video…",
+    buffering: "Waiting for video…",
+    seeking: "Loading this part…",
+};
+export default function AdvancedVideo({
+    src,
+    name,
+    playback,
+    qualityControl,
+}: {
+    src: string;
+    name: string;
+    playback: { current: { time: number; playing: boolean } | null };
+    qualityControl?: VideoQualityControl;
+}) {
+    const host = useRef<HTMLDivElement>(null);
+    const activePlayer = useRef<MoviElement | null>(null);
+    const restorePlayerFocus = useRef(false);
+    const qualityControlRef = useRef(qualityControl);
+    qualityControlRef.current = qualityControl;
+    const currentQualityControl = (): VideoQualityControl | undefined => {
+        const control = qualityControlRef.current;
+        if (!control) return;
+        return {
+            ...control,
+            onChange: (value) => {
+                restorePlayerFocus.current = true;
+                const surface = host.current?.parentElement;
+                // Keep the stable player surface fullscreen while replacing its engine.
+                // Request synchronously from the quality button's user activation.
+                if (
+                    document.fullscreenElement === activePlayer.current &&
+                    surface
+                ) {
+                    void surface
+                        .requestFullscreen()
+                        .catch(() => {})
+                        .then(() => {
+                            qualityControlRef.current?.onChange(value);
+                        });
+                } else control.onChange(value);
+            },
+        };
+    };
+    useEffect(() => {
+        if (activePlayer.current)
+            setVideoQualityControl(
+                activePlayer.current,
+                currentQualityControl(),
+            );
+    }, [qualityControl]);
+    const [state, dispatch] = useReducer(
+        videoLoadTransition,
+        initialVideoLoadState,
+    );
+    const [attempt, setAttempt] = useState(0);
+    const [slow, setSlow] = useState(false);
+    const [waitSeconds, setWaitSeconds] = useState(0);
+    const [showStatus, setShowStatus] = useState(false);
+    const [playbackError, setPlaybackError] = useState("");
+    const [transfer, setTransfer] = useState<VideoBufferSnapshot | null>(null);
+    const waitingForVideo = useRef(true);
+    waitingForVideo.current = state.phase !== "ready";
+    const [visible, setVisible] = useState(!document.hidden);
+    const [statusSurface, setStatusSurface] = useState<ShadowRoot | null>(null);
+    useEffect(() => {
+        setShowStatus(false);
+        if (state.phase === "ready") return;
+        // Short startup work stays quiet. Playback waits are already debounced below.
+        const timer = window.setTimeout(
+            () => setShowStatus(true),
+            state.ready ? 0 : 500,
+        );
+        return () => clearTimeout(timer);
+    }, [state.phase, state.ready, attempt]);
+    useEffect(() => {
+        const update = () => setVisible(!document.hidden);
+        document.addEventListener("visibilitychange", update);
+        return () => document.removeEventListener("visibilitychange", update);
+    }, []);
+    useEffect(() => {
+        const update = () => {
+            activePlayer.current?.setHostFullscreen(
+                document.fullscreenElement === host.current?.parentElement,
+            );
+            setStatusSurface(
+                document.fullscreenElement === activePlayer.current
+                    ? activePlayer.current?.shadowRoot || null
+                    : null,
+            );
+        };
+        document.addEventListener("fullscreenchange", update);
+        return () => document.removeEventListener("fullscreenchange", update);
+    }, []);
+    useEffect(() => {
+        setWaitSeconds(0);
+        if (state.phase === "ready") return;
+        const began = performance.now();
+        const timer = window.setInterval(
+            () =>
+                setWaitSeconds(Math.floor((performance.now() - began) / 1000)),
+            1000,
+        );
+        return () => clearInterval(timer);
+    }, [state.phase, attempt]);
+    useEffect(() => {
+        setSlow(false);
+        if (state.phase === "ready") return;
+        // This only offers recovery. A long wait is never proof that playback failed.
+        const timer = window.setTimeout(() => setSlow(true), 8000);
+        return () => clearTimeout(timer);
+    }, [state.phase, attempt]);
+    useEffect(() => {
+        let cancelled = false;
+        let failed = false;
+        let codecRejected = false;
+        let usable = false;
+        let player: MoviElement | null = null;
+        let subtitleRenderer: MovTextRenderer | null = null;
+        let progressTimer: number | undefined;
+        let frameCallback: number | undefined;
+        let frameSource: MoviElement | null = null;
+        let lastPlayback: { time: number; playing: boolean } | null = null;
+        let previousTime = Number.NaN;
+        let latestProgressAt = 0;
+        let hasPresentedFrame = false;
+        let detachPresentation: (() => void) | undefined;
+        let detachPip: (() => void) | undefined;
+        let detachGestures: (() => void) | undefined;
+        const updateChapters = () => {
+            if (!player || cancelled) return;
+            const hasChapters = videoHasChapters(
+                player.player?.getChapters() || [],
+                player.duration,
+            );
+            // The bundled native timeline renders chapter titles/times without
+            // extracting frames when thumb/storyboard are unset. Keep its synthetic
+            // thumbnail timeline unavailable for files with no chapter metadata.
+            const controls = hasChapters ? "nospinner" : "notimeline nospinner";
+            if (player.getAttribute("controlslist") !== controls)
+                player.setAttribute("controlslist", controls);
+            refreshVideoActions(player);
+        };
+        const updateSubtitleRenderer = () => {
+            if (!player || cancelled) return;
+            const track = player.player?.trackManager.getActiveSubtitleTrack();
+            if (isMovTextCodec(track?.codec)) {
+                if (!subtitleRenderer) {
+                    subtitleRenderer = new MovTextRenderer();
+                    player.setSubtitleRenderer(subtitleRenderer);
+                }
+            } else if (subtitleRenderer) {
+                player.setSubtitleRenderer(null);
+                subtitleRenderer.destroy();
+                subtitleRenderer = null;
+            }
+        };
+        let resume: {
+            source: { time: number; playing: boolean };
+            target: number;
+            positionApplied: boolean;
+            playRequested: boolean;
+        } | null = null;
+        let waitingTimer: number | undefined;
+        let pendingSeek = false;
+        let pendingWait: "waiting" | "seeking" = "waiting";
+        const listeners: [string, EventListener][] = [];
+        dispatch("reset");
+        setPlaybackError("");
+        setTransfer(null);
+        let lastTransferAt = 0;
+        let waitReceivedFrom = 0;
+        const clearWaiting = () => {
+            clearTimeout(waitingTimer);
+            waitingTimer = undefined;
+        };
+        const recover = () => {
+            if (!failed || codecRejected) return;
+            failed = false;
+            setPlaybackError("");
+        };
+        const fail = (event?: Event) => {
+            if (cancelled) return;
+            // Movi retries dropped connections itself. A reconnect is a wait, not a
+            // permanent error, and playback can recover without the user's help.
+            if (
+                event?.type === "errordisplay" &&
+                (event as CustomEvent<{ title?: string }>).detail?.title ===
+                    "Reconnecting…"
+            ) {
+                recover();
+                waiting("waiting");
+                return;
+            }
+            if (!cancelled && !failed) {
+                failed = true;
+                clearWaiting();
+                setPlaybackError(
+                    "The video could not play. Try again, or download it to watch on your device.",
+                );
+            }
+        };
+        const updateStartPosition = () => {
+            if (!resume || !player || resume.positionApplied) return;
+            resume.target = videoResumeTime(resume.target, player.duration);
+            // Movi emits ready/loadEnd before its initializer performs its startup seek.
+            // Updating startat here clamps the owned seek without racing a second seek.
+            player.setAttribute("startat", String(resume.target));
+        };
+        const observeResumePosition = () => {
+            if (!usable || !resume || !player || resume.positionApplied) return;
+            if (Math.abs(player.currentTime - resume.target) > 0.05) return;
+            resume.positionApplied = true;
+            if (playback.current === resume.source) playback.current = null;
+        };
+        const rememberPlayback = () => {
+            if (
+                !usable ||
+                !player?.player ||
+                player.player.getState() === "error"
+            )
+                return;
+            lastPlayback = {
+                time: videoResumeTime(player.currentTime, player.duration),
+                playing: !player.paused,
+            };
+        };
+        const updateBuffer = () => {
+            if (!player || cancelled || failed) return;
+            const sample = videoBufferSnapshot(player);
+            // Source counters include repeat/seek reads. They describe delivery to this
+            // player, never whole-file completion or how many pictures can be decoded.
+            if (
+                waitingForVideo.current &&
+                performance.now() - lastTransferAt >= 500
+            ) {
+                lastTransferAt = performance.now();
+                setTransfer({
+                    ...sample,
+                    received: Math.max(0, sample.received - waitReceivedFrom),
+                });
+            }
+            // Pinned Movi 0.4.1 can leave this documented CSS part at zero while
+            // paused, even with a ready buffer. Paint its own public TimeRanges,
+            // including the seek origin, instead of converting server byte offsets.
+            const bar = player.shadowRoot?.querySelector<HTMLElement>(
+                '[part~="progress-buffer"]',
+            );
+            const range = sample.ranges[0]; // This engine exposes one contiguous source window.
+            if (
+                bar &&
+                Number.isFinite(player.duration) &&
+                player.duration > 0
+            ) {
+                bar.title = "Loaded video (approximate)";
+                bar.style.left =
+                    (range ? (range.start / player.duration) * 100 : 0) + "%";
+                bar.style.width =
+                    (range
+                        ? ((range.end - range.start) / player.duration) * 100
+                        : 0) + "%";
+            }
+        };
+        const ready = (
+            event:
+                | "loadedmetadata"
+                | "loadeddata"
+                | "canplay"
+                | "ready"
+                | "playing",
+        ) => {
+            if (cancelled || codecRejected) return;
+            if (
+                failed &&
+                (event === "loadedmetadata" || event === "loadeddata")
+            )
+                return;
+            if (event === "canplay" || event === "ready") {
+                const codec = unavailableVideoCodec(player?.player);
+                if (codec) {
+                    failed = true;
+                    codecRejected = true;
+                    clearWaiting();
+                    setPlaybackError(
+                        "This video’s codec" +
+                            (codec === "unknown" ? "" : " (" + codec + ")") +
+                            " is not supported by the player on this device. Download the original to open it in a video app.",
+                    );
+                    return;
+                }
+            }
+            recover();
+            usable = true;
+            updateBuffer();
+            updateChapters();
+            updateSubtitleRenderer();
+            const engineState = player?.player?.getState();
+            if (
+                event !== "playing" &&
+                (engineState === "buffering" || engineState === "seeking")
+            ) {
+                waiting(engineState === "seeking" ? "seeking" : "waiting");
+                return;
+            }
+            if (event === "playing" && !hasPresentedFrame) {
+                // The engine starts its clock before the first decoded picture arrives.
+                // Preserve loading feedback until successive real frames are presented.
+                waiting("waiting");
+                return;
+            }
+            clearWaiting();
+            pendingSeek = false;
+            dispatch(event);
+
+            updateStartPosition();
+            if (resume && player && !resume.playRequested) {
+                resume.playRequested = true;
+                // During initialization play() queues intent until Movi's startat seek
+                // completes. Fresh previews and previously paused videos stay paused.
+                if (resume.source.playing) void player.play().catch(() => {});
+            }
+            observeResumePosition();
+            rememberPlayback();
+        };
+        const waiting = (kind: "waiting" | "seeking") => {
+            if (cancelled || failed) return;
+            if (!usable) {
+                dispatch("trackschange");
+                return;
+            }
+            if (kind === "waiting" && player?.paused) return;
+            if (kind === "seeking" && player) {
+                if (!pendingSeek)
+                    waitReceivedFrom = videoBufferSnapshot(player).received;
+                pendingSeek = true;
+                previousTime = Number.NaN;
+                latestProgressAt = 0;
+                hasPresentedFrame = false;
+            }
+            pendingWait = pendingSeek ? "seeking" : kind;
+            if (waitingTimer !== undefined) return;
+            waitingTimer = window.setTimeout(() => {
+                waitingTimer = undefined;
+                if (cancelled || failed || !player) return;
+                if (
+                    pendingWait === "waiting" &&
+                    (player.paused ||
+                        performance.now() - latestProgressAt < 500)
+                )
+                    return;
+                hasPresentedFrame = false;
+                dispatch(pendingWait);
+            }, 700);
+        };
+        const settle = (event: "pause" | "seeked" | "ended") => {
+            if (cancelled || failed) return;
+            clearWaiting();
+            if (event !== "seeked") pendingSeek = false;
+            dispatch(event);
+            rememberPlayback();
+        };
+        void import("movi-player/element/slim")
+            .then(({ MoviElement }) => {
+                if (cancelled || !host.current) return;
+                installLocalStyles(MoviElement);
+                installVideoPresentation(MoviElement);
+                player = document.createElement("movi-player");
+                activePlayer.current = player;
+                setVideoQualityControl(player, currentQualityControl());
+                detachPresentation = attachVideoPresentation(player);
+                detachPip = installVideoPlayerPip(player);
+                detachGestures = attachVideoGestures(player);
+                player.setAttribute("wasmurl", wasmUrl);
+                player.setAttribute("engine", "wasm");
+                player.setAttribute("sw", "auto");
+                // This ceiling is separate from decoded pictures. The source allocates
+                // gradually toward its bitrate-aware time goal, rather than reserving
+                // the entire device budget for every video.
+                player.setAttribute(
+                    "buffersize",
+                    String(
+                        videoSourceMemoryBudgetMiB(
+                            (navigator as Navigator & { deviceMemory?: number })
+                                .deviceMemory,
+                        ),
+                    ),
+                );
+                player.setAttribute("persist", "");
+                player.setAttribute("controls", "");
+                player.setAttribute("subtitlepicker", "");
+                player.setAttribute("playsinline", "");
+                player.setAttribute("preload", "metadata");
+                player.setAttribute("theme", "dark");
+                player.setAttribute("themecolor", "#647dff");
+                player.setAttribute("fastseek", "keys gestures");
+                // Enable the native chapter timeline once real metadata is available.
+                // Frame extraction stays disabled: neither thumb nor storyboard is set.
+                player.setAttribute("controlslist", "notimeline nospinner");
+                player.setAttribute(
+                    "aria-label",
+                    "Enhanced video player for " + name,
+                );
+                const saved = playback.current;
+                if (saved) {
+                    resume = {
+                        source: saved,
+                        target: videoResumeTime(saved.time),
+                        positionApplied: false,
+                        playRequested: false,
+                    };
+                    // Establish the library's startup position before connection or src.
+                    player.setAttribute("startat", String(resume.target));
+                }
+                const listen = (type: string, callback: EventListener) => {
+                    player!.addEventListener(type, callback);
+                    listeners.push([type, callback]);
+                };
+                listen("loadstart", () => {
+                    codecRejected = false;
+                    recover();
+                    usable = false;
+                    hasPresentedFrame = false;
+                    clearWaiting();
+                    setTransfer(null);
+                    dispatch("loadstart");
+                });
+                listen("trackschange", () => {
+                    updateChapters();
+                    dispatch("trackschange");
+                });
+                // TrackManager emits this synchronously before choosing the decoder.
+                // Install the public extension in time to receive raw MP4 text packets.
+                listen("subtitletrackchange", updateSubtitleRenderer);
+                listen("loadedmetadata", () => ready("loadedmetadata"));
+                listen("loadeddata", () => ready("loadeddata"));
+                listen("canplay", () => ready("canplay"));
+                listen("playing", () => ready("playing"));
+                listen("play", () => {
+                    // A playing state is an intent; watch actual presented frames below.
+                    latestProgressAt = performance.now();
+                });
+                listen("waiting", () => waiting("waiting"));
+                listen("stalled", () => waiting("waiting"));
+                listen("seeking", () => waiting("seeking"));
+                listen("seeked", () => {
+                    observeResumePosition();
+                    rememberPlayback();
+                    settle("seeked");
+                    // A new position can be available before its audio/video refill is ready.
+                    // Keep the actual engine wait visible instead of treating seeked as play.
+                    if (player?.player?.getState() === "buffering")
+                        waiting("waiting");
+                    else pendingSeek = false;
+                });
+                const observeProgress = () => {
+                    if (!player || cancelled) return;
+                    observeResumePosition();
+                    rememberPlayback();
+                    updateBuffer();
+                    if (
+                        usable &&
+                        !player.paused &&
+                        !player.seeking &&
+                        player.currentTime < player.duration - 0.1 &&
+                        latestProgressAt > 0 &&
+                        performance.now() - latestProgressAt > 1250
+                    )
+                        waiting("waiting");
+                };
+                listen("timeupdate", observeProgress);
+                listen("progress", observeProgress);
+                listen("durationchange", updateStartPosition);
+                listen("pause", () => settle("pause"));
+                listen("ended", () => settle("ended"));
+                listen("statechange", (event) => {
+                    const phase = (event as CustomEvent<string>).detail;
+                    if (
+                        phase === "ready" ||
+                        (phase === "paused" && player!.duration > 0)
+                    )
+                        ready("ready");
+                    else if (phase === "playing") ready("playing");
+                    else if (phase === "buffering") waiting("waiting");
+                    else if (phase === "seeking") waiting("seeking");
+                    else if (phase === "paused") settle("pause");
+                });
+                listen("error", fail);
+                listen("errordisplay", fail);
+                dispatch("engine-loaded");
+                host.current.append(player);
+                player.setHostFullscreen(
+                    document.fullscreenElement === host.current.parentElement,
+                );
+                if (restorePlayerFocus.current) {
+                    restorePlayerFocus.current = false;
+                    player.focus({ preventScroll: true });
+                }
+                player.src = new URL(src, window.location.origin).href;
+                const presentedFrame = (_now: number, metadata: unknown) => {
+                    if (!player || cancelled) return;
+                    const mediaTime = (
+                        metadata as { mediaTime?: number } | null
+                    )?.mediaTime;
+                    // A clock jump or prefetched source range is not proof of moving pictures.
+                    // Reset at every seek and require successive presented frames instead.
+                    if (
+                        !codecRejected &&
+                        videoIsAdvancing(
+                            previousTime,
+                            mediaTime ?? Number.NaN,
+                            player.paused,
+                            player.seeking,
+                        )
+                    ) {
+                        recover();
+                        hasPresentedFrame = true;
+                        pendingSeek = false;
+                        latestProgressAt = performance.now();
+                        clearWaiting();
+                        dispatch("playing");
+                    }
+                    previousTime = mediaTime ?? Number.NaN;
+                    frameCallback =
+                        frameSource?.requestVideoFrameCallback(presentedFrame);
+                };
+                frameSource = player;
+                frameCallback =
+                    frameSource.requestVideoFrameCallback(presentedFrame);
+                progressTimer = window.setInterval(observeProgress, 250);
+            })
+            .catch(fail);
+        return () => {
+            cancelled = true;
+            clearWaiting();
+            clearInterval(progressTimer);
+            detachPresentation?.();
+            detachPip?.();
+            detachGestures?.();
+            if (player) {
+                restorePlayerFocus.current ||=
+                    document.activeElement === player;
+                clearVideoQualityControl(player);
+                if (frameCallback !== undefined)
+                    frameSource?.cancelVideoFrameCallback(frameCallback);
+                if (
+                    lastPlayback &&
+                    (!player.player || player.player.getState() === "error")
+                )
+                    playback.current = lastPlayback;
+                else if (resume && !resume.positionApplied)
+                    playback.current = {
+                        time: resume.target,
+                        playing: usable
+                            ? !player.paused
+                            : resume.source.playing,
+                    };
+                else if (usable && Number.isFinite(player.currentTime))
+                    playback.current = {
+                        time: videoResumeTime(
+                            player.currentTime,
+                            player.duration,
+                        ),
+                        playing: !player.paused,
+                    };
+                for (const [type, callback] of listeners)
+                    player.removeEventListener(type, callback);
+                if (subtitleRenderer) {
+                    player.setSubtitleRenderer(null);
+                    subtitleRenderer.destroy();
+                    subtitleRenderer = null;
+                }
+                player.remove(); // disconnectedCallback aborts requests and destroys its owned engine.
+                if (activePlayer.current === player)
+                    activePlayer.current = null;
+            }
+        };
+    }, [src, name, playback, attempt]);
+    const copy = state.phase !== "ready" ? phaseCopy[state.phase] : null;
+    const loadingStatus =
+        playbackError || (copy && showStatus) ? (
+            <div
+                className={
+                    "advanced-state " +
+                    (playbackError
+                        ? "advanced-state-error"
+                        : "advanced-state-buffering")
+                }
+                data-phase={state.phase}
+                data-hidden={!visible}
+                data-error={Boolean(playbackError)}
+            >
+                <div className="advanced-state-content">
+                    <div
+                        role={playbackError ? "alert" : "status"}
+                        aria-live="polite"
+                        aria-atomic="true"
+                    >
+                        {playbackError ? (
+                            <>
+                                <h3>Can’t play this video</h3>
+                                <p>{playbackError}</p>
+                            </>
+                        ) : (
+                            <div className="advanced-wait-label">
+                                <span
+                                    role="progressbar"
+                                    aria-label="Loading video"
+                                >
+                                    <LoaderCircle
+                                        size={18}
+                                        aria-hidden="true"
+                                    />
+                                </span>
+                                <span>{copy}</span>
+                                {state.ready && waitSeconds > 0 && (
+                                    <span className="advanced-wait-elapsed">
+                                        {waitSeconds}s
+                                    </span>
+                                )}
+                            </div>
+                        )}
+                    </div>
+                    {!playbackError && transfer?.measured && (
+                        <div className="advanced-transfer" aria-live="off">
+                            <div className="advanced-transfer-network">
+                                <span>
+                                    {formatBytes(transfer.received)} received
+                                    {state.phase === "seeking"
+                                        ? " for this seek"
+                                        : ""}
+                                </span>
+                                {transfer.bytesPerSecond > 0 && (
+                                    <span>
+                                        {formatBytes(transfer.bytesPerSecond)}/s
+                                    </span>
+                                )}
+                            </div>
+                        </div>
+                    )}
+                    {(slow || playbackError) && (
+                        <div className="advanced-state-actions">
+                            <button
+                                type="button"
+                                onClick={() => setAttempt((value) => value + 1)}
+                            >
+                                <RefreshCw size={16} aria-hidden="true" /> Try
+                                again
+                            </button>
+                        </div>
+                    )}
+                </div>
+            </div>
+        ) : null;
+    return (
+        <div className="advanced-video" data-phase={state.phase}>
+            <div
+                ref={host}
+                className="advanced-player-host"
+                aria-busy={state.phase !== "ready" && !playbackError}
+            />
+            {statusSurface
+                ? createPortal(loadingStatus, statusSurface)
+                : loadingStatus}
+        </div>
+    );
+}
diff --git a/website/src/features/previews/video/MovTextRenderer.css b/website/src/features/previews/video/MovTextRenderer.css
new file mode 100644
index 00000000..11727bf4
--- /dev/null
+++ b/website/src/features/previews/video/MovTextRenderer.css
@@ -0,0 +1,33 @@
+.tgdrive-movtext-overlay {
+    display: block !important;
+}
+.tgdrive-movtext-renderer {
+    position: absolute;
+    inset: 0;
+    display: flex;
+    align-items: flex-end;
+    justify-content: center;
+    box-sizing: border-box;
+    padding: 5% 4% 7%;
+    pointer-events: none;
+    container-type: inline-size;
+    overflow: hidden;
+}
+.tgdrive-movtext-cue {
+    display: block;
+    max-width: 100%;
+    padding: 0.18em 0.45em;
+    border-radius: 3px;
+    color: #fff;
+    background: rgb(8 10 13 / 84%);
+    font-family: inherit;
+    font-size: clamp(14px, 3.4cqw, 30px);
+    font-weight: 500;
+    line-height: 1.4;
+    text-align: center;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+}
+.tgdrive-movtext-cue[hidden] {
+    display: none;
+}
diff --git a/website/src/features/previews/video/MovTextRenderer.test.ts b/website/src/features/previews/video/MovTextRenderer.test.ts
new file mode 100644
index 00000000..51297d96
--- /dev/null
+++ b/website/src/features/previews/video/MovTextRenderer.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import {
+    decodeMovText,
+    isMovTextCodec,
+    MOVTEXT_LIMITS,
+    MovTextCueBuffer,
+} from "./MovTextRenderer";
+
+function sample(text: string) {
+    const bytes = new TextEncoder().encode(text);
+    return new Uint8Array([bytes.length >> 8, bytes.length & 255, ...bytes]);
+}
+function packet(text: string, timestamp = 0, duration = 2, streamIndex = 3) {
+    return { data: sample(text), timestamp, duration, streamIndex };
+}
+describe("MP4 timed text decoding", () => {
+    it("recognizes only the explicitly handled codecs", () => {
+        expect(isMovTextCodec("mov_text")).toBe(true);
+        expect(isMovTextCodec("tx3g")).toBe(true);
+        for (const codec of ["srt", "ass", "unknown", undefined])
+            expect(isMovTextCodec(codec)).toBe(false);
+    });
+    it("preserves Unicode and inert markup while ignoring trailing style boxes", () => {
+        const source = sample(
+            "資料 résumé <img src=x onerror=alert(1)>\r\nsecond",
+        );
+        const bytes = new Uint8Array([
+            ...source,
+            0,
+            0,
+            0,
+            8,
+            115,
+            116,
+            121,
+            108,
+        ]);
+        expect(decodeMovText(bytes)).toBe(
+            "資料 résumé <img src=x onerror=alert(1)>\nsecond",
+        );
+    });
+    it("decodes both BOM-marked UTF-16 byte orders", () => {
+        expect(
+            decodeMovText(
+                new Uint8Array([0, 6, 0xfe, 0xff, 0, 65, 0x4e, 0x2d]),
+            ),
+        ).toBe("A中");
+        expect(
+            decodeMovText(
+                new Uint8Array([0, 6, 0xff, 0xfe, 65, 0, 0x2d, 0x4e]),
+            ),
+        ).toBe("A中");
+    });
+    it("rejects truncated lengths and malformed Unicode rather than guessing text", () => {
+        for (const bytes of [
+            [],
+            [0],
+            [0, 2, 65],
+            [0, 2],
+            [0, 1, 0xff],
+            [0, 3, 0xfe, 0xff, 0],
+            [0, 4, 0xfe, 0xff, 0xd8, 0],
+        ])
+            expect(decodeMovText(new Uint8Array(bytes))).toBeNull();
+    });
+    it("bounds packet and decoded text while accepting explicit empty markers", () => {
+        expect(decodeMovText(new Uint8Array([0, 0]))).toBe("");
+        expect(
+            decodeMovText(new Uint8Array(MOVTEXT_LIMITS.packetBytes + 1)),
+        ).toBeNull();
+        expect(
+            decodeMovText(sample("x".repeat(MOVTEXT_LIMITS.cueCharacters + 1))),
+        ).toBeNull();
+    });
+});
+describe("bounded timed subtitle state", () => {
+    it("uses packet timing, exclusive cue endings and track identity", () => {
+        const buffer = new MovTextCueBuffer();
+        buffer.configure(3);
+        buffer.pushPacket(packet("wrong", 0, 3, 2));
+        buffer.pushPacket(packet("first", 1, 2));
+        expect(buffer.textAt(0.9)).toBe("");
+        expect(buffer.textAt(1)).toBe("first");
+        expect(buffer.textAt(2.99)).toBe("first");
+        expect(buffer.textAt(3)).toBe("");
+        expect(buffer.queuedCueCount).toBe(1);
+    });
+    it("drops invalid timing and duplicate packets", () => {
+        const buffer = new MovTextCueBuffer();
+        buffer.configure(3);
+        for (const [start, duration] of [
+            [NaN, 2],
+            [0, Infinity],
+            [Infinity, 2],
+            [0, -1],
+            [0, 0],
+            [1e308, 1e308],
+        ])
+            buffer.pushPacket(packet("bad", start, duration));
+        buffer.pushPacket(packet("valid"));
+        buffer.pushPacket(packet("valid"));
+        expect(buffer.queuedCueCount).toBe(1);
+        expect(buffer.textAt(5)).toBe("");
+        buffer.pushPacket(packet("old"));
+        expect(buffer.queuedCueCount).toBe(2);
+    });
+    it("preserves recent ended cues for positive/negative delay adjustments", () => {
+        const buffer = new MovTextCueBuffer();
+        buffer.configure(3);
+        buffer.pushPacket(packet("delayed", 1, 2));
+        expect(buffer.textAt(3.05)).toBe("");
+        buffer.setDelay(0.1);
+        expect(buffer.textAt(3.05)).toBe("delayed");
+        buffer.setDelay(-0.1);
+        expect(buffer.textAt(3.05)).toBe("");
+        buffer.setDelay(2);
+        expect(buffer.textAt(3.1)).toBe("delayed");
+    });
+    it("clears queued and displayed state on seek/track replacement", () => {
+        const buffer = new MovTextCueBuffer();
+        buffer.configure(3);
+        buffer.pushPacket(packet("before"));
+        expect(buffer.textAt(0)).toBe("before");
+        buffer.clear();
+        expect(buffer.textAt(0)).toBe("");
+        buffer.pushPacket(packet("after", 8));
+        expect(buffer.textAt(8)).toBe("after");
+        buffer.configure(null);
+        buffer.pushPacket(packet("off"));
+        expect(buffer.textAt(0)).toBe("");
+    });
+    it("bounds count, character budget and simultaneous visible text", () => {
+        const buffer = new MovTextCueBuffer();
+        buffer.configure(3);
+        for (let index = 0; index < MOVTEXT_LIMITS.queuedCues + 32; index++)
+            buffer.pushPacket(packet(String(index), index, 2000));
+        expect(buffer.queuedCueCount).toBe(MOVTEXT_LIMITS.queuedCues);
+        expect(buffer.textAt(999).split("\n")).toHaveLength(
+            MOVTEXT_LIMITS.visibleCues,
+        );
+        buffer.clear();
+        for (let index = 0; index < 400; index++)
+            buffer.pushPacket(packet("x".repeat(8000), index, 2000));
+        expect(buffer.queuedCharacters).toBeLessThanOrEqual(
+            MOVTEXT_LIMITS.queuedCharacters,
+        );
+        expect(buffer.textAt(99).length).toBeLessThanOrEqual(
+            MOVTEXT_LIMITS.cueCharacters,
+        );
+    });
+});
diff --git a/website/src/features/previews/video/MovTextRenderer.ts b/website/src/features/previews/video/MovTextRenderer.ts
new file mode 100644
index 00000000..b9328d08
--- /dev/null
+++ b/website/src/features/previews/video/MovTextRenderer.ts
@@ -0,0 +1,217 @@
+import type {
+    Packet,
+    SubtitleRenderer,
+    SubtitleTrack,
+} from "movi-player/element/slim";
+import rendererStyles from "./MovTextRenderer.css?inline";
+
+export const MOVTEXT_LIMITS = {
+    packetBytes: 128 * 1024,
+    cueCharacters: 16 * 1024,
+    queuedCues: 4096,
+    queuedCharacters: 2 * 1024 * 1024,
+    visibleCues: 8,
+} as const;
+type TimedPacket = Pick<
+    Packet,
+    "streamIndex" | "timestamp" | "duration" | "data"
+>;
+type Cue = { start: number; end: number; text: string };
+
+export function isMovTextCodec(codec?: string): boolean {
+    return codec === "mov_text" || codec === "tx3g";
+}
+
+/** 3GPP TS 26.245: big-endian byte count, then UTF-8 or BOM-marked UTF-16.
+ * Trailing style/link/font boxes are deliberately ignored: display plain text only.
+ */
+export function decodeMovText(data: Uint8Array): string | null {
+    if (data.byteLength < 2 || data.byteLength > MOVTEXT_LIMITS.packetBytes)
+        return null;
+    const size = data[0] * 256 + data[1];
+    if (size > data.byteLength - 2) return null;
+    if (!size) return "";
+    const text = data.subarray(2, 2 + size);
+    let encoding = "utf-8";
+    let start = 0;
+    if (size >= 2 && text[0] === 0xfe && text[1] === 0xff) {
+        encoding = "utf-16be";
+        start = 2;
+    } else if (size >= 2 && text[0] === 0xff && text[1] === 0xfe) {
+        encoding = "utf-16le";
+        start = 2;
+    }
+    if (encoding !== "utf-8" && (size - start) % 2) return null;
+    try {
+        const value = new TextDecoder(encoding, { fatal: true })
+            .decode(text.subarray(start))
+            .replace(/\r\n?/g, "\n")
+            .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+        return value.length <= MOVTEXT_LIMITS.cueCharacters ? value : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Bounded future-cue window; seeking drops the window before new packets arrive. */
+export class MovTextCueBuffer {
+    private track: number | null = null;
+    private cues: Cue[] = [];
+    private characters = 0;
+    private delay = 0;
+    private mediaTime: number | null = null;
+
+    get queuedCueCount() {
+        return this.cues.length;
+    }
+    get queuedCharacters() {
+        return this.characters;
+    }
+    configure(track: number | null) {
+        this.clear();
+        this.track = Number.isInteger(track) ? track : null;
+    }
+    setDelay(seconds: number) {
+        if (Number.isFinite(seconds)) this.delay = seconds;
+    }
+    clear() {
+        this.cues = [];
+        this.characters = 0;
+        this.mediaTime = null;
+    }
+    pushPacket(packet: TimedPacket) {
+        const { timestamp: start, duration } = packet;
+        const end = start + duration;
+        if (
+            this.track === null ||
+            packet.streamIndex !== this.track ||
+            !Number.isFinite(start) ||
+            !Number.isFinite(duration) ||
+            duration <= 0 ||
+            !Number.isFinite(end) ||
+            end <= start ||
+            !(packet.data instanceof Uint8Array)
+        )
+            return;
+        const text = decodeMovText(packet.data);
+        if (!text) return;
+        if (
+            this.cues.some(
+                (cue) =>
+                    cue.start === start && cue.end === end && cue.text === text,
+            )
+        )
+            return;
+        this.cues.push({ start, end, text });
+        this.characters += text.length;
+        this.cues.sort((a, b) => a.start - b.start || a.end - b.end);
+        while (
+            this.cues.length > MOVTEXT_LIMITS.queuedCues ||
+            this.characters > MOVTEXT_LIMITS.queuedCharacters
+        ) {
+            // Retain recent past cues for subtitle-delay adjustments. Reclaim ended
+            // cues only under pressure; otherwise trim the farthest future packet.
+            const time =
+                this.mediaTime === null ? null : this.mediaTime - this.delay;
+            const expired =
+                time === null
+                    ? -1
+                    : this.cues.findIndex((cue) => cue.end <= time);
+            const removed =
+                expired >= 0
+                    ? this.cues.splice(expired, 1)[0]
+                    : this.cues.pop()!;
+            this.characters -= removed.text.length;
+        }
+    }
+    textAt(mediaTime: number): string {
+        if (!Number.isFinite(mediaTime)) return "";
+        this.mediaTime = mediaTime;
+        const time = mediaTime - this.delay;
+        return this.cues
+            .filter((cue) => cue.start <= time && time < cue.end)
+            .slice(0, MOVTEXT_LIMITS.visibleCues)
+            .map((cue) => cue.text)
+            .join("\n")
+            .slice(0, MOVTEXT_LIMITS.cueCharacters);
+    }
+}
+
+/** Public Movi renderer extension; no WASM decoder or internal player mutation. */
+export default class MovTextRenderer implements SubtitleRenderer {
+    private buffer = new MovTextCueBuffer();
+    private container: HTMLElement | null = null;
+    private node: HTMLDivElement | null = null;
+    private text: HTMLSpanElement | null = null;
+    private sheet: CSSStyleSheet | null = null;
+    private root: ShadowRoot | Document | null = null;
+    private displayed = "";
+    private destroyed = false;
+
+    configure(track: SubtitleTrack) {
+        this.buffer.configure(isMovTextCodec(track.codec) ? track.id : null);
+        this.display("");
+    }
+    mount(container: HTMLElement) {
+        if (this.destroyed) return;
+        this.unmount();
+        this.container = container;
+        // The public mount is shared with Movi's built-in empty-cue renderer,
+        // which writes display:none even while a custom renderer is active.
+        container.classList.add("tgdrive-movtext-overlay");
+        const root = container.getRootNode();
+        if (root instanceof ShadowRoot || root instanceof Document) {
+            this.root = root;
+            this.sheet = new CSSStyleSheet();
+            this.sheet.replaceSync(rendererStyles);
+            root.adoptedStyleSheets = [...root.adoptedStyleSheets, this.sheet];
+        }
+        this.node = document.createElement("div");
+        this.node.className = "tgdrive-movtext-renderer";
+        this.node.setAttribute("aria-label", "Subtitles");
+        this.text = document.createElement("span");
+        this.text.className = "tgdrive-movtext-cue";
+        this.text.hidden = true;
+        this.node.append(this.text);
+        container.append(this.node);
+        this.displayed = "";
+    }
+    pushPacket(packet: Packet) {
+        if (!this.destroyed) this.buffer.pushPacket(packet);
+    }
+    render(mediaTime: number) {
+        if (!this.destroyed) this.display(this.buffer.textAt(mediaTime));
+    }
+    setDelay(seconds: number) {
+        this.buffer.setDelay(seconds);
+    }
+    clear() {
+        this.buffer.clear();
+        this.display("");
+    }
+    private display(value: string) {
+        if (!this.text || value === this.displayed) return;
+        this.displayed = value;
+        this.text.textContent = value;
+        this.text.hidden = !value;
+    }
+    private unmount() {
+        this.container?.classList.remove("tgdrive-movtext-overlay");
+        this.container = null;
+        this.node?.remove();
+        this.node = null;
+        this.text = null;
+        if (this.root && this.sheet)
+            this.root.adoptedStyleSheets = this.root.adoptedStyleSheets.filter(
+                (sheet) => sheet !== this.sheet,
+            );
+        this.root = null;
+        this.sheet = null;
+    }
+    destroy() {
+        if (this.destroyed) return;
+        this.destroyed = true;
+        this.clear();
+        this.unmount();
+    }
+}
diff --git a/website/src/features/previews/video/videoBufferMemory.test.ts b/website/src/features/previews/video/videoBufferMemory.test.ts
new file mode 100644
index 00000000..5ecc6e11
--- /dev/null
+++ b/website/src/features/previews/video/videoBufferMemory.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { videoSourceMemoryBudgetMiB } from "./videoBufferMemory";
+
+describe("compressed video device memory budget", () => {
+    it.each([
+        [0.25, 32],
+        [0.5, 32],
+        [1, 64],
+        [2, 128],
+        [4, 256],
+        [8, 512],
+        [16, 512],
+    ])("uses reported %s GiB to set a %s MiB ceiling", (memory, ceiling) => {
+        expect(videoSourceMemoryBudgetMiB(memory)).toBe(ceiling);
+    });
+    it.each([undefined, 0, -1, Number.NaN, Number.POSITIVE_INFINITY])(
+        "uses a bounded fallback for an unavailable or invalid hint: %s",
+        (memory) => expect(videoSourceMemoryBudgetMiB(memory)).toBe(128),
+    );
+});
diff --git a/website/src/features/previews/video/videoBufferMemory.ts b/website/src/features/previews/video/videoBufferMemory.ts
new file mode 100644
index 00000000..0d9ba8b9
--- /dev/null
+++ b/website/src/features/previews/video/videoBufferMemory.ts
@@ -0,0 +1,12 @@
+/** A coarse device hint, not a measurement of currently free browser memory. */
+export function videoSourceMemoryBudgetMiB(deviceMemoryGiB?: number): number {
+    if (
+        deviceMemoryGiB === undefined ||
+        !Number.isFinite(deviceMemoryGiB) ||
+        deviceMemoryGiB <= 0
+    )
+        return 128;
+    // About 1/16 of reported RAM, bounded to 32–512 MiB. Decoders, GPU
+    // surfaces, WASM, transport and the rest of the application need room too.
+    return Math.min(512, Math.max(32, Math.floor(deviceMemoryGiB * 64)));
+}
diff --git a/website/src/features/previews/video/videoPlayerGestures.ts b/website/src/features/previews/video/videoPlayerGestures.ts
new file mode 100644
index 00000000..7ba037e4
--- /dev/null
+++ b/website/src/features/previews/video/videoPlayerGestures.ts
@@ -0,0 +1,102 @@
+import type { MoviElement } from "movi-player/element/slim";
+
+type GesturePlayer = {
+    isAnyMenuOpen(): boolean;
+    isTimelineOpen(): boolean;
+    toggleTimeline(): void;
+    closeSettingsMenu(): void;
+    closeAllBottomMenus(): void;
+    showControls(): void;
+};
+
+function touchesPicture(event: Event): boolean {
+    const path = event.composedPath();
+    if (
+        path.some(
+            (node) =>
+                node instanceof Element &&
+                node.matches(
+                    "button,input,select,a,label,.movi-controls-bar,.movi-timeline-panel,.movi-overlay-layer",
+                ),
+        )
+    )
+        return false;
+    return path.some(
+        (node) =>
+            node instanceof Element &&
+            node.matches("canvas,video,.movi-controls-overlay"),
+    );
+}
+
+/** Retain Movi's native taps, seeking and mouse gestures. Pinned 0.4.1 checks
+ * for an open menu only after recognizing a double tap, so tapping outside a
+ * menu can seek behind it. Consume that dismissal and its remaining tap burst.
+ */
+export function attachVideoGestures(player: MoviElement): () => void {
+    const gestures = player as unknown as GesturePlayer;
+    let consuming = false;
+    let consumeUntil = 0;
+    const start = (event: TouchEvent) => {
+        if (!touchesPicture(event)) return;
+        const chapters = gestures.isTimelineOpen();
+        const menu = gestures.isAnyMenuOpen() || chapters;
+        consuming = menu || performance.now() < consumeUntil;
+        if (!consuming) return;
+        consumeUntil = performance.now() + 450;
+        if (menu) {
+            gestures.closeSettingsMenu();
+            gestures.closeAllBottomMenus();
+            if (chapters) gestures.toggleTimeline();
+            gestures.showControls();
+        }
+        event.stopPropagation();
+    };
+    const move = (event: TouchEvent) => {
+        if (consuming && touchesPicture(event)) event.stopPropagation();
+    };
+    const end = (event: TouchEvent) => {
+        if (!consuming || !touchesPicture(event)) return;
+        consumeUntil = performance.now() + 450;
+        event.stopPropagation();
+        if (event.cancelable) event.preventDefault();
+        if (!event.touches.length) consuming = false;
+    };
+    const ghostClick = (event: MouseEvent) => {
+        const touch = event as MouseEvent & {
+            pointerType?: string;
+            sourceCapabilities?: { firesTouchEvents?: boolean };
+        };
+        if (
+            performance.now() < consumeUntil &&
+            (touch.pointerType === "touch" ||
+                touch.sourceCapabilities?.firesTouchEvents) &&
+            touchesPicture(event)
+        ) {
+            event.preventDefault();
+            event.stopPropagation();
+        }
+    };
+    player.addEventListener("touchstart", start, {
+        capture: true,
+        passive: true,
+    });
+    player.addEventListener("touchmove", move, {
+        capture: true,
+        passive: true,
+    });
+    player.addEventListener("touchend", end, { capture: true, passive: false });
+    player.addEventListener("touchcancel", end, {
+        capture: true,
+        passive: false,
+    });
+    player.addEventListener("click", ghostClick, true);
+    player.addEventListener("dblclick", ghostClick, true);
+    return () => {
+        player.removeEventListener("touchstart", start, true);
+        player.removeEventListener("touchmove", move, true);
+        player.removeEventListener("touchend", end, true);
+        player.removeEventListener("touchcancel", end, true);
+        player.removeEventListener("click", ghostClick, true);
+        player.removeEventListener("dblclick", ghostClick, true);
+    };
+}
diff --git a/website/src/features/previews/video/videoPlayerPip.css b/website/src/features/previews/video/videoPlayerPip.css
new file mode 100644
index 00000000..b56235ee
--- /dev/null
+++ b/website/src/features/previews/video/videoPlayerPip.css
@@ -0,0 +1,54 @@
+.pip-controls {
+    padding: 8px;
+    gap: 6px;
+}
+.pip-btn-row {
+    gap: 0;
+    justify-content: space-between;
+}
+.pip-btn {
+    min-width: 44px;
+    min-height: 44px;
+    padding: 8px;
+    border-radius: 4px;
+}
+.pip-btn.mute-toggle,
+.pip-btn.back-to-tab {
+    position: static;
+}
+.pip-progress-bar,
+.pip-progress-bar:hover {
+    height: 16px;
+    background: transparent;
+}
+.pip-progress-bar::before {
+    content: "";
+    position: absolute;
+    inset: 6px 0 auto;
+    height: 3px;
+    border-radius: 2px;
+    background: rgb(255 255 255 / 20%);
+}
+.pip-progress-buffer,
+.pip-progress-fill {
+    top: 6px;
+    height: 3px;
+}
+body:focus-within .pip-controls,
+body:focus-within .pip-title {
+    opacity: 1;
+}
+body:is(:hover, :focus-within, .show-controls) .tgdrive-movtext-renderer {
+    padding-bottom: calc(7% + 88px);
+}
+.pip-btn:focus-visible,
+.pip-progress-bar:focus-visible {
+    outline: 2px solid #b9c6ff;
+    outline-offset: 2px;
+}
+@media (prefers-reduced-motion: reduce) {
+    .pip-controls,
+    .pip-title {
+        transition: none;
+    }
+}
diff --git a/website/src/features/previews/video/videoPlayerPip.ts b/website/src/features/previews/video/videoPlayerPip.ts
new file mode 100644
index 00000000..7d5a60bc
--- /dev/null
+++ b/website/src/features/previews/video/videoPlayerPip.ts
@@ -0,0 +1,236 @@
+import pipStyles from "./videoPlayerPip.css?inline";
+import subtitleStyles from "./MovTextRenderer.css?inline";
+
+type PipWindow = Window & typeof globalThis;
+type PipOptions = { width?: number; height?: number };
+type PipController = {
+    requestWindow(options?: PipOptions): Promise<PipWindow>;
+};
+type PipPlayer = HTMLElement & {
+    togglePiP(): Promise<void>;
+    _pipWindow: PipWindow | null;
+    currentTime: number;
+    duration: number;
+    paused: boolean;
+    ended: boolean;
+    muted: boolean;
+};
+
+function timeLabel(seconds: number) {
+    const rounded = Math.floor(Math.max(0, seconds));
+    const minutes = Math.floor(rounded / 60);
+    return minutes + ":" + String(rounded % 60).padStart(2, "0");
+}
+
+function attachPipControls(player: PipPlayer, pip: PipWindow): () => void {
+    const doc = pip.document;
+    const sheet = new pip.CSSStyleSheet();
+    sheet.replaceSync(subtitleStyles + pipStyles);
+    doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, sheet];
+    const controls = doc.querySelector<HTMLElement>(".pip-controls");
+    const position = doc.querySelector<HTMLElement>(".pip-progress-bar");
+    const play = doc.querySelector<HTMLButtonElement>(".play-pause");
+    const mute = doc.querySelector<HTMLButtonElement>(".mute-toggle");
+    for (const [selector, label] of [
+        [".seek-back", "Rewind 10 seconds"],
+        [".seek-fwd", "Forward 10 seconds"],
+        [".back-to-tab", "Back to video"],
+    ]) {
+        const button = doc.querySelector<HTMLButtonElement>(selector);
+        button?.setAttribute("aria-label", label);
+        if (button) button.title = label;
+    }
+    for (const button of doc.querySelectorAll<HTMLButtonElement>(".pip-btn"))
+        button.type = "button";
+    controls?.setAttribute("role", "group");
+    controls?.setAttribute("aria-label", "Video controls");
+    if (position) {
+        position.tabIndex = 0;
+        position.setAttribute("role", "slider");
+        position.setAttribute("aria-label", "Video position");
+        position.setAttribute("aria-orientation", "horizontal");
+        position.setAttribute("aria-valuemin", "0");
+    }
+    const sync = () => {
+        const playLabel = player.paused || player.ended ? "Play" : "Pause";
+        play?.setAttribute("aria-label", playLabel);
+        if (play) play.title = playLabel;
+        const muteLabel = player.muted ? "Unmute" : "Mute";
+        mute?.setAttribute("aria-label", muteLabel);
+        if (mute) mute.title = muteLabel;
+        if (position) {
+            const duration = Number.isFinite(player.duration)
+                ? player.duration
+                : 0;
+            const time = Math.min(
+                duration,
+                Math.max(0, player.currentTime || 0),
+            );
+            position.setAttribute("aria-valuemax", String(duration));
+            position.setAttribute("aria-valuenow", String(time));
+            position.setAttribute(
+                "aria-valuetext",
+                timeLabel(time) + " of " + timeLabel(duration),
+            );
+            position.setAttribute("aria-disabled", String(duration <= 0));
+        }
+    };
+    const seek = (event: KeyboardEvent) => {
+        if (!Number.isFinite(player.duration) || player.duration <= 0) return;
+        let target: number;
+        switch (event.key) {
+            case "ArrowLeft":
+            case "ArrowDown":
+                target = player.currentTime - 5;
+                break;
+            case "ArrowRight":
+            case "ArrowUp":
+                target = player.currentTime + 5;
+                break;
+            case "PageDown":
+                target = player.currentTime - 10;
+                break;
+            case "PageUp":
+                target = player.currentTime + 10;
+                break;
+            case "Home":
+                target = 0;
+                break;
+            case "End":
+                target = player.duration;
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+        // Movi also handles arrow keys on the child document.
+        event.stopPropagation();
+        player.currentTime = Math.min(player.duration, Math.max(0, target));
+        sync();
+    };
+    const events = [
+        "play",
+        "pause",
+        "playing",
+        "ended",
+        "volumechange",
+        "timeupdate",
+        "durationchange",
+    ];
+    const activateButton = (event: KeyboardEvent) => {
+        if (
+            (event.key === " " || event.key === "Enter") &&
+            event.target instanceof pip.Element &&
+            event.target.closest("button")
+        )
+            // Keep the native button action; skip Movi's document-wide play shortcut.
+            event.stopPropagation();
+    };
+    for (const event of events) player.addEventListener(event, sync);
+    position?.addEventListener("keydown", seek);
+    doc.addEventListener("keydown", activateButton, true);
+    sync();
+    const cleanup = () => {
+        for (const event of events) player.removeEventListener(event, sync);
+        position?.removeEventListener("keydown", seek);
+        doc.removeEventListener("keydown", activateButton, true);
+        pip.removeEventListener("pagehide", closed);
+    };
+    const closed = () => {
+        cleanup();
+        if (player.isConnected)
+            requestAnimationFrame(() => player.focus({ preventScroll: true }));
+    };
+    pip.addEventListener("pagehide", closed, { once: true });
+    return cleanup;
+}
+
+/** Adapt the pinned Movi document-PiP surface to strict CSP and keyboard use.
+ * Install on each fresh player and dispose before removing that player.
+ */
+export function installVideoPlayerPip(element: HTMLElement): () => void {
+    const player = element as PipPlayer;
+    const controller = (
+        window as unknown as { documentPictureInPicture?: PipController }
+    ).documentPictureInPicture;
+    if (!controller || typeof player.togglePiP !== "function") return () => {};
+    const original = player.togglePiP;
+    let detachControls: (() => void) | undefined;
+    let restoreRequest: (() => void) | undefined;
+    let disposed = false;
+    let inFlight: Promise<void> | undefined;
+    const runToggle = async () => {
+        if (disposed) return;
+        const previousWindow = player._pipWindow;
+        let restoreHead: (() => void) | undefined;
+        const originalRequest = controller.requestWindow;
+        const requestWindow = async (options?: PipOptions) => {
+            // Call before awaiting to preserve the user's activation. Returning the
+            // window only after adaptation precedes Movi's own await continuation;
+            // Chromium's enter event can arrive after its styles were inserted.
+            const pip = await originalRequest.call(controller, options);
+            if (disposed) {
+                pip.close();
+                throw new DOMException(
+                    "The video preview was closed.",
+                    "AbortError",
+                );
+            }
+            const doc = pip.document;
+            const append = doc.head.appendChild;
+            // Construct sheets in the child realm. Inline <style> insertion would be
+            // blocked by the inherited style-src policy, including subtitle styles.
+            doc.head.appendChild = function <T extends Node>(node: T): T {
+                if (node instanceof pip.HTMLStyleElement) {
+                    const sheet = new pip.CSSStyleSheet();
+                    sheet.replaceSync(
+                        (node.textContent || "").replace(/@import[^;]+;/g, ""),
+                    );
+                    doc.adoptedStyleSheets = [...doc.adoptedStyleSheets, sheet];
+                    return node;
+                }
+                return append.call(this, node) as T;
+            };
+            restoreHead = () => {
+                doc.head.appendChild = append;
+            };
+            return pip;
+        };
+        const restore = () => {
+            if (controller.requestWindow === requestWindow)
+                controller.requestWindow = originalRequest;
+        };
+        controller.requestWindow = requestWindow;
+        restoreRequest = restore;
+        try {
+            await original.call(player);
+        } finally {
+            restore();
+            if (restoreRequest === restore) restoreRequest = undefined;
+            restoreHead?.();
+            detachControls?.();
+            detachControls = undefined;
+            if (!disposed && player._pipWindow && !player._pipWindow.closed)
+                detachControls = attachPipControls(player, player._pipWindow);
+            else if (!disposed && previousWindow && player.isConnected)
+                requestAnimationFrame(() =>
+                    player.focus({ preventScroll: true }),
+                );
+        }
+    };
+    const toggle = () => {
+        if (inFlight) return inFlight;
+        inFlight = runToggle().finally(() => {
+            inFlight = undefined;
+        });
+        return inFlight;
+    };
+    player.togglePiP = toggle;
+    return () => {
+        disposed = true;
+        restoreRequest?.();
+        restoreRequest = undefined;
+        detachControls?.();
+        if (player.togglePiP === toggle) player.togglePiP = original;
+    };
+}
diff --git a/website/src/features/previews/video/videoPlayerPresentation.ts b/website/src/features/previews/video/videoPlayerPresentation.ts
new file mode 100644
index 00000000..f7f8763a
--- /dev/null
+++ b/website/src/features/previews/video/videoPlayerPresentation.ts
@@ -0,0 +1,711 @@
+import type { MoviElement } from "movi-player/element/slim";
+
+type PresentationPlayer = {
+    shadowRoot: ShadowRoot | null;
+    player?: { isSoftwareDecoding?: () => boolean } | null;
+    buildSettingsRoot(): void;
+    syncSettingsRootState(root: ShadowRoot): void;
+    updateAudioTrackMenu(): void;
+    updateSubtitleTrackMenu(): void;
+    updateQualityMenu(): void;
+    generateTimelineStrip(root: ShadowRoot): Promise<void>;
+    updateTimelineCurrent(): void;
+    updateChapterPill(): void;
+    isTimelineOpen(): boolean;
+    toggleTimeline(): void;
+    getMaxAllowedRate?(): number;
+    openSettingsPage(page: string): void;
+    closeSettingsPage(animate?: boolean): void;
+    closeSettingsMenu(): void;
+    _settingsPage: string | null;
+    contextMenuRoot(): ShadowRoot;
+    isAnyMenuOpen(): boolean;
+    isControlAvailable(control: string): boolean;
+    updateAmbientUI(): void;
+    syncTinyLayout(): void;
+    showControls(): void;
+    hideControls(): void;
+    closeAllBottomMenus(): void;
+    focus(options?: FocusOptions): void;
+};
+
+function setText(element: Element | null | undefined, text: string) {
+    if (element && element.textContent !== text) element.textContent = text;
+}
+
+function compactPlayer(player: PresentationPlayer) {
+    const width = player.shadowRoot?.host.clientWidth || 0;
+    return width > 0 && width <= 720;
+}
+
+/** Keep secondary actions behind the same Settings button on small players. */
+function updateCompactActions(player: PresentationPlayer) {
+    const shadow = player.shadowRoot;
+    const root = shadow?.querySelector(".movi-settings-root");
+    if (!shadow || !root) return;
+    const compact = compactPlayer(player);
+    const actions = [
+        ["pip", "Picture in picture", ".movi-pip-btn"],
+        ["chapters", "Chapters", ".movi-chapter-pill"],
+    ];
+    for (const [action, label, selector] of actions) {
+        const control = shadow.querySelector<HTMLButtonElement>(selector);
+        let row = root.querySelector<HTMLButtonElement>(
+            `[data-advanced-action="${action}"]`,
+        );
+        if (
+            !compact ||
+            !control ||
+            control.disabled ||
+            control.style.display === "none"
+        ) {
+            row?.remove();
+            continue;
+        }
+        if (row) continue;
+        row = document.createElement("button");
+        row.type = "button";
+        row.className = "movi-settings-row";
+        row.dataset.advancedAction = action;
+        row.setAttribute("aria-label", label);
+        const icon = control.querySelector("svg")?.cloneNode(true) as
+            SVGElement | undefined;
+        if (icon) {
+            icon.classList.add("movi-settings-icon");
+            icon.setAttribute("aria-hidden", "true");
+            row.append(icon);
+        }
+        const text = document.createElement("span");
+        text.className = "movi-settings-row-label";
+        text.textContent = label;
+        row.append(text);
+        row.addEventListener("click", (event) => {
+            event.stopPropagation();
+            player.closeSettingsMenu();
+            player.focus({ preventScroll: true });
+            control.click();
+        });
+        root.insertBefore(
+            row,
+            root.querySelector(".movi-settings-section-label-secondary"),
+        );
+    }
+}
+
+export function refreshVideoActions(player: MoviElement) {
+    const presentation = player as unknown as PresentationPlayer;
+    presentation.updateChapterPill();
+    updateCompactActions(presentation);
+}
+
+const nativeChoiceClasses = [
+    "movi-speed-item",
+    "movi-audio-track-item",
+    "movi-subtitle-track-item",
+    "movi-quality-item",
+    "movi-timeline-item",
+];
+const nativeChoiceSelector = nativeChoiceClasses
+    .map((name) => "." + name)
+    .join(",");
+const settingsControlSelector =
+    'button:not(:disabled),[role="button"][tabindex="0"]';
+
+function nativeChoiceKey(choice: HTMLElement) {
+    return JSON.stringify([
+        nativeChoiceClasses.find((name) => choice.classList.contains(name)),
+        choice.dataset.speed,
+        choice.dataset.trackId,
+        choice.dataset.audioLang,
+        choice.dataset.subtitleLang,
+        choice.dataset.subtitlePick,
+        choice.dataset.src,
+        choice.dataset.start,
+    ]);
+}
+
+function focusedNativeChoice(player: PresentationPlayer) {
+    const focused = player.shadowRoot?.activeElement;
+    return focused instanceof HTMLElement &&
+        focused.matches(nativeChoiceSelector) &&
+        focused.closest(".movi-settings-page-body")
+        ? nativeChoiceKey(focused)
+        : undefined;
+}
+
+/** Preserve Movi's click handlers while making its native div choices operable. */
+function updateNativeChoices(player: PresentationPlayer, focusedKey?: string) {
+    const shadow = player.shadowRoot;
+    if (!shadow) return;
+    const maximumRate = player.getMaxAllowedRate?.();
+    for (const choice of shadow.querySelectorAll<HTMLElement>(
+        nativeChoiceSelector,
+    )) {
+        const unavailable =
+            choice.style.pointerEvents === "none" ||
+            (choice.dataset.speed !== undefined &&
+                maximumRate !== undefined &&
+                Number(choice.dataset.speed) > maximumRate);
+        const selected = choice.matches(
+            ".movi-speed-active,.movi-audio-track-active,.movi-subtitle-track-active,.movi-quality-active,.movi-timeline-current",
+        );
+        choice.setAttribute("role", "button");
+        choice.tabIndex = unavailable ? -1 : 0;
+        choice.setAttribute("aria-disabled", String(unavailable));
+        if (
+            choice.dataset.subtitlePick ||
+            choice.classList.contains("movi-timeline-item")
+        )
+            choice.removeAttribute("aria-pressed");
+        else choice.setAttribute("aria-pressed", String(selected));
+    }
+    if (!focusedKey || !shadow.querySelector(".movi-settings-menu.is-open"))
+        return;
+    const choices = Array.from(
+        shadow.querySelectorAll<HTMLElement>(
+            '.movi-settings-page-body [role="button"][tabindex="0"]',
+        ),
+    ).filter((choice) => choice.getClientRects().length);
+    (
+        choices.find((choice) => nativeChoiceKey(choice) === focusedKey) ||
+        choices.find(
+            (choice) => choice.getAttribute("aria-pressed") === "true",
+        ) ||
+        choices[0]
+    )?.focus({ preventScroll: true });
+}
+
+const installed = new WeakSet<object>();
+
+export type VideoQualityControl = {
+    variants: { id: string; label: string }[];
+    selected: string;
+    onChange: (id: string) => void;
+};
+const videoQualities = new WeakMap<PresentationPlayer, VideoQualityControl>();
+type QualityView = {
+    list: HTMLElement;
+    nativeList: HTMLElement | null;
+    nativeHidden: HTMLElement["hidden"];
+    signature: string;
+};
+const qualityViews = new WeakMap<PresentationPlayer, QualityView>();
+
+function qualityOptions(control: VideoQualityControl) {
+    const seen = new Set(["original"]);
+    return [
+        { id: "original", label: "Original" },
+        ...control.variants.filter((variant) => {
+            if (seen.has(variant.id)) return false;
+            seen.add(variant.id);
+            return true;
+        }),
+    ];
+}
+
+function updateQualityRow(player: PresentationPlayer) {
+    const root = player.shadowRoot?.querySelector(".movi-settings-root");
+    if (!root) return;
+    const control = videoQualities.get(player);
+    let row = root.querySelector<HTMLElement>('[data-page="quality"]');
+    if (!control?.variants.length) {
+        if (
+            row?.classList.contains("is-static") ||
+            row?.dataset.advancedQuality
+        )
+            row.remove();
+        return;
+    }
+    if (!(row instanceof HTMLButtonElement)) {
+        const button = document.createElement("button");
+        button.type = "button";
+        button.className = "movi-settings-row";
+        button.dataset.page = "quality";
+        if (row) {
+            button.append(...Array.from(row.childNodes));
+            row.replaceWith(button);
+        } else {
+            const icon = player.shadowRoot
+                ?.querySelector(".movi-quality-btn svg")
+                ?.cloneNode(true) as SVGElement | undefined;
+            if (icon) {
+                icon.classList.add("movi-settings-icon");
+                button.append(icon);
+            }
+            const label = document.createElement("span");
+            label.className = "movi-settings-row-label";
+            label.textContent = "Quality";
+            const value = document.createElement("span");
+            value.className = "movi-settings-row-value";
+            button.append(label, value);
+            root.insertBefore(button, root.querySelector(".movi-settings-row"));
+        }
+        row = button;
+    }
+    row.dataset.advancedQuality = "true";
+    row.removeAttribute("aria-disabled");
+    row.setAttribute("aria-label", "Quality");
+    if (!row.querySelector(".movi-settings-chevron")) {
+        const chevron = root.querySelector(
+            '.movi-settings-row[data-page="speed"] .movi-settings-chevron',
+        );
+        if (chevron) row.append(chevron.cloneNode(true));
+    }
+    setText(
+        row.querySelector(".movi-settings-row-value"),
+        qualityOptions(control).find((option) => option.id === control.selected)
+            ?.label || "Original",
+    );
+}
+
+function restoreQualityView(player: PresentationPlayer) {
+    const view = qualityViews.get(player);
+    if (!view) return;
+    view.list.remove();
+    if (view.nativeList) view.nativeList.hidden = view.nativeHidden;
+    qualityViews.delete(player);
+}
+
+function updateQualityChoices(player: PresentationPlayer) {
+    const control = videoQualities.get(player);
+    const body = player.shadowRoot?.querySelector(".movi-settings-page-body");
+    if (!control?.variants.length || !body) return;
+    let view = qualityViews.get(player);
+    if (!view) {
+        const list = document.createElement("div");
+        list.className = "advanced-quality-list";
+        list.setAttribute("role", "group");
+        list.setAttribute("aria-label", "Video quality");
+        const nativeList =
+            body.querySelector<HTMLElement>(".movi-quality-list");
+        view = {
+            list,
+            nativeList,
+            nativeHidden: nativeList?.hidden || false,
+            signature: "",
+        };
+        if (nativeList) nativeList.hidden = true;
+        body.append(list);
+        qualityViews.set(player, view);
+    }
+    const options = qualityOptions(control);
+    const signature = JSON.stringify(options);
+    if (view.signature !== signature) {
+        const focused = player.shadowRoot?.activeElement as HTMLElement | null;
+        const focusedId = view.list.contains(focused)
+            ? focused?.dataset.qualityId
+            : undefined;
+        view.list.replaceChildren();
+        for (const option of options) {
+            const button = document.createElement("button");
+            button.type = "button";
+            button.className = "movi-settings-choice advanced-quality-choice";
+            button.dataset.qualityId = option.id;
+            const label = document.createElement("span");
+            label.textContent = option.label;
+            const check = document.createElementNS(
+                "http://www.w3.org/2000/svg",
+                "svg",
+            );
+            check.classList.add("movi-settings-check");
+            check.setAttribute("viewBox", "0 0 24 24");
+            check.setAttribute("aria-hidden", "true");
+            check.setAttribute("fill", "none");
+            check.setAttribute("stroke", "currentColor");
+            check.setAttribute("stroke-width", "2");
+            const path = document.createElementNS(
+                "http://www.w3.org/2000/svg",
+                "path",
+            );
+            path.setAttribute("d", "m5 12 4 4L19 6");
+            check.append(path);
+            button.append(label, check);
+            button.addEventListener("click", (event) => {
+                event.stopPropagation();
+                const latest = videoQualities.get(player);
+                player.closeSettingsMenu();
+                player.focus({ preventScroll: true });
+                if (latest && latest.selected !== option.id)
+                    latest.onChange(option.id);
+            });
+            view.list.append(button);
+        }
+        view.signature = signature;
+        if (focusedId)
+            Array.from(view.list.querySelectorAll<HTMLButtonElement>("button"))
+                .find((button) => button.dataset.qualityId === focusedId)
+                ?.focus({ preventScroll: true });
+    }
+    for (const button of view.list.querySelectorAll<HTMLButtonElement>(
+        "button",
+    )) {
+        const selected = button.dataset.qualityId === control.selected;
+        button.classList.toggle("is-active", selected);
+        button.setAttribute("aria-pressed", String(selected));
+        button
+            .querySelector<SVGElement>("svg")
+            ?.style.setProperty("visibility", selected ? "visible" : "hidden");
+    }
+}
+
+/** Server variants stay in React; this only presents them in Movi's existing menu. */
+export function setVideoQualityControl(
+    player: MoviElement,
+    control?: VideoQualityControl,
+) {
+    const presentation = player as unknown as PresentationPlayer;
+    if (control?.variants.length) videoQualities.set(presentation, control);
+    else videoQualities.delete(presentation);
+    updateQualityRow(presentation);
+    if (presentation._settingsPage === "quality") {
+        if (control?.variants.length) updateQualityChoices(presentation);
+        else presentation.closeSettingsPage(false);
+    }
+}
+
+export function clearVideoQualityControl(player: MoviElement) {
+    const presentation = player as unknown as PresentationPlayer;
+    videoQualities.delete(presentation);
+    restoreQualityView(presentation);
+    updateQualityRow(presentation);
+}
+
+/** Keep native Movi surfaces, adding TGDrive quality choices and accessibility.
+ */
+export function installVideoPresentation(constructor: typeof MoviElement) {
+    const prototype = constructor.prototype as unknown as PresentationPlayer;
+    if (installed.has(prototype)) return;
+    const buildSettings = prototype.buildSettingsRoot;
+    const syncSettings = prototype.syncSettingsRootState;
+    const openSettings = prototype.openSettingsPage;
+    const closeSettings = prototype.closeSettingsPage;
+    const generateTimeline = prototype.generateTimelineStrip;
+    const controlAvailable = prototype.isControlAvailable;
+    const updateAmbient = prototype.updateAmbientUI;
+    const syncTiny = prototype.syncTinyLayout;
+    const hideControls = prototype.hideControls;
+
+    for (const method of [
+        "updateAudioTrackMenu",
+        "updateSubtitleTrackMenu",
+        "updateQualityMenu",
+    ] as const) {
+        const update = prototype[method];
+        prototype[method] = function () {
+            const focused = focusedNativeChoice(this);
+            update.call(this);
+            updateNativeChoices(this, focused);
+        };
+    }
+
+    prototype.syncTinyLayout = function () {
+        syncTiny.call(this);
+        if (compactPlayer(this)) {
+            const shadow = this.shadowRoot;
+            const right = shadow?.querySelector(".movi-controls-right");
+            const fullscreen = shadow?.querySelector(".movi-fullscreen-btn");
+            if (right && fullscreen && fullscreen.parentElement !== right)
+                right.append(fullscreen);
+            right?.classList.remove("expanded");
+        }
+        updateCompactActions(this);
+    };
+    prototype.hideControls = function () {
+        const focused = this.shadowRoot?.activeElement;
+        // Keyboard users must never lose the control they are operating.
+        if (
+            focused instanceof HTMLElement &&
+            focused.matches(":focus-visible") &&
+            focused.closest(".movi-controls-bar,.movi-top-controls") &&
+            focused.getClientRects().length &&
+            getComputedStyle(focused).visibility !== "hidden"
+        )
+            return;
+        hideControls.call(this);
+    };
+
+    // Movi deliberately suspends glow colour sampling during software decoding.
+    // Keep its settings, context menu and keyboard availability in agreement.
+    prototype.isControlAvailable = function (control) {
+        if (control === "ambient" && this.player?.isSoftwareDecoding?.())
+            return false;
+        return controlAvailable.call(this, control);
+    };
+    prototype.updateAmbientUI = function () {
+        updateAmbient.call(this);
+        if (this.player?.isSoftwareDecoding?.()) {
+            const row = this.contextMenuRoot().querySelector<HTMLElement>(
+                '[data-action="ambient-toggle"]',
+            );
+            if (row) row.style.display = "none";
+        }
+    };
+
+    prototype.buildSettingsRoot = function () {
+        buildSettings.call(this);
+        updateQualityRow(this);
+        updateCompactActions(this);
+    };
+    prototype.syncSettingsRootState = function (root) {
+        syncSettings.call(this, root);
+        updateQualityRow(this);
+    };
+    prototype.openSettingsPage = function (page) {
+        openSettings.call(this, page);
+        updateNativeChoices(this);
+        if (page === "quality" && videoQualities.get(this)?.variants.length)
+            updateQualityChoices(this);
+        // The native root row becomes hidden when a subpage opens. Keep focus in
+        // the menu so keyboard navigation and Escape continue to reach the player.
+        const choices = this.shadowRoot?.querySelectorAll<HTMLElement>(
+            ".movi-settings-page-body :is(" + settingsControlSelector + ")",
+        );
+        const visible = Array.from(choices || []).filter(
+            (button) => button.getClientRects().length,
+        );
+        (
+            visible.find(
+                (button) =>
+                    button.getAttribute("aria-pressed") === "true" ||
+                    button.classList.contains("is-active"),
+            ) ||
+            visible[0] ||
+            this.shadowRoot?.querySelector<HTMLButtonElement>(
+                ".movi-settings-back",
+            )
+        )?.focus({ preventScroll: true });
+    };
+    prototype.closeSettingsPage = function (animate) {
+        const page = this._settingsPage;
+        restoreQualityView(this);
+        closeSettings.call(this, animate);
+        if (page && animate !== false)
+            this.shadowRoot
+                ?.querySelector<HTMLButtonElement>(
+                    `.movi-settings-row[data-page="${page}"]`,
+                )
+                ?.focus({ preventScroll: true });
+    };
+    prototype.generateTimelineStrip = async function (root) {
+        await generateTimeline.call(this, root);
+        this.updateTimelineCurrent();
+        updateNativeChoices(this);
+        if (!this.isTimelineOpen()) return;
+        const panel = root.querySelector<HTMLElement>(".movi-timeline-panel");
+        panel?.setAttribute("role", "region");
+        panel?.setAttribute("aria-label", "Chapters");
+        (
+            root.querySelector<HTMLElement>(".movi-timeline-current") ||
+            root.querySelector<HTMLElement>(".movi-timeline-item")
+        )?.focus({ preventScroll: true });
+    };
+    installed.add(prototype);
+}
+
+/** Keep native button activation out of the player's global Space shortcut. */
+export function attachVideoPresentation(player: MoviElement): () => void {
+    const presentation = player as unknown as PresentationPlayer;
+    let disposed = false;
+    const guard = (event: KeyboardEvent) => {
+        const openSettings = player.shadowRoot?.querySelector(
+            ".movi-settings-menu.is-open",
+        );
+        const openTimeline = presentation.isTimelineOpen()
+            ? player.shadowRoot?.querySelector(".movi-timeline-panel")
+            : null;
+        const openMenu =
+            openSettings ||
+            player.shadowRoot?.querySelector(
+                ".movi-speed-menu.is-open,.movi-audio-track-menu.is-open,.movi-subtitle-track-menu.is-open,.movi-quality-menu.is-open",
+            ) ||
+            openTimeline;
+        const timelineMenu = openTimeline && openMenu === openTimeline;
+        if (openMenu && (event.key === " " || event.key === "Enter")) {
+            const choice = event
+                .composedPath()
+                .find(
+                    (node): node is HTMLElement =>
+                        node instanceof HTMLElement &&
+                        node.matches(nativeChoiceSelector),
+                );
+            if (choice && openMenu.contains(choice)) {
+                event.preventDefault();
+                event.stopPropagation();
+                if (
+                    choice.getAttribute("aria-disabled") !== "true" &&
+                    choice.style.pointerEvents !== "none"
+                ) {
+                    choice.click();
+                    if (!choice.classList.contains("movi-timeline-item"))
+                        player.focus({ preventScroll: true });
+                }
+                return;
+            }
+        }
+        if (
+            openMenu &&
+            (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key) ||
+                (timelineMenu &&
+                    ["ArrowLeft", "ArrowRight"].includes(event.key)))
+        ) {
+            const buttons = Array.from(
+                openMenu.querySelectorAll<HTMLElement>(
+                    timelineMenu
+                        ? ".movi-timeline-close,.movi-timeline-item"
+                        : settingsControlSelector,
+                ),
+            ).filter(
+                (button) =>
+                    button.getClientRects().length &&
+                    getComputedStyle(button).visibility !== "hidden",
+            );
+            if (buttons.length) {
+                event.preventDefault();
+                event.stopPropagation();
+                const current = buttons.indexOf(
+                    player.shadowRoot?.activeElement as HTMLElement,
+                );
+                const target =
+                    event.key === "Home"
+                        ? 0
+                        : event.key === "End"
+                          ? buttons.length - 1
+                          : current < 0
+                            ? event.key === "ArrowDown" ||
+                              event.key === "ArrowRight"
+                                ? 0
+                                : buttons.length - 1
+                            : (current +
+                                  (event.key === "ArrowDown" ||
+                                  event.key === "ArrowRight"
+                                      ? 1
+                                      : -1) +
+                                  buttons.length) %
+                              buttons.length;
+                buttons[target].focus({ preventScroll: true });
+                buttons[target].scrollIntoView({ block: "nearest" });
+            }
+            return;
+        }
+        if (event.key === "Escape") {
+            const settings = player.shadowRoot?.querySelector(
+                ".movi-settings-menu.is-open",
+            );
+            if (settings || presentation.isAnyMenuOpen() || openTimeline) {
+                event.preventDefault();
+                event.stopPropagation();
+                if (settings && presentation._settingsPage) {
+                    const page = presentation._settingsPage;
+                    presentation.closeSettingsPage();
+                    player.shadowRoot
+                        ?.querySelector<HTMLButtonElement>(
+                            `.movi-settings-row[data-page="${page}"]`,
+                        )
+                        ?.focus({ preventScroll: true });
+                } else {
+                    presentation.closeAllBottomMenus();
+                    if (openTimeline) presentation.toggleTimeline();
+                    player.shadowRoot
+                        ?.querySelector<HTMLButtonElement>(".movi-settings-btn")
+                        ?.focus({ preventScroll: true });
+                }
+                return;
+            }
+        }
+        if (
+            (event.key === " " || event.key === "Enter") &&
+            event
+                .composedPath()
+                .some((node) => node instanceof HTMLButtonElement)
+        )
+            event.stopPropagation();
+    };
+    const retainPictureSampling = () => {
+        const engine = player.player as unknown as {
+            videoRenderer?: {
+                enableAmbientMirror?: () => void;
+                disableAmbientMirror?: () => void;
+            };
+        } | null;
+        // The two Movi 0.4.1 switches share this renderer resource, but either
+        // switch can release it while the other is still on. Reacquire the same
+        // mirror without toggling the setting or resetting its current crop.
+        if (player.cropbars || player.ambientMode)
+            engine?.videoRenderer?.enableAmbientMirror?.();
+        else engine?.videoRenderer?.disableAmbientMirror?.();
+    };
+    player.addEventListener("keydown", guard, true);
+    const settings = player.shadowRoot?.querySelector<HTMLElement>(
+        ".movi-settings-menu",
+    );
+    const settingsButton =
+        player.shadowRoot?.querySelector(".movi-settings-btn");
+    const timeline = player.shadowRoot?.querySelector<HTMLElement>(
+        ".movi-timeline-panel",
+    );
+    const chapterButton =
+        player.shadowRoot?.querySelector(".movi-chapter-pill");
+    let timelineWasOpen = false;
+    const syncPopup = () => {
+        if (settings) {
+            settings.id = "tgdrive-player-settings";
+            settingsButton?.setAttribute("aria-controls", settings.id);
+            settingsButton?.setAttribute(
+                "aria-expanded",
+                String(settings.classList.contains("is-open")),
+            );
+        }
+        if (timeline) {
+            const open = presentation.isTimelineOpen();
+            timeline.id = "tgdrive-player-chapters";
+            chapterButton?.setAttribute("aria-controls", timeline.id);
+            chapterButton?.setAttribute("aria-expanded", String(open));
+            if (open && !timelineWasOpen)
+                (
+                    timeline.querySelector<HTMLElement>(
+                        ".movi-timeline-current",
+                    ) ||
+                    timeline.querySelector<HTMLElement>(".movi-timeline-item")
+                )?.focus({ preventScroll: true });
+            timelineWasOpen = open;
+        }
+    };
+    const menuObserver = new MutationObserver(syncPopup);
+    if (settings)
+        menuObserver.observe(settings, {
+            attributes: true,
+            attributeFilter: ["class"],
+        });
+    if (timeline)
+        menuObserver.observe(timeline, {
+            attributes: true,
+            attributeFilter: ["style"],
+        });
+    syncPopup();
+    const resumeAutoHide = () =>
+        queueMicrotask(() => {
+            if (!disposed && player.isConnected) presentation.showControls();
+        });
+    player.addEventListener("focusin", resumeAutoHide);
+    player.addEventListener("focusout", resumeAutoHide);
+    const shadow = player.shadowRoot;
+    shadow?.addEventListener("focusin", resumeAutoHide);
+    shadow?.addEventListener("focusout", resumeAutoHide);
+    const resize = new ResizeObserver(() => presentation.syncTinyLayout());
+    resize.observe(player);
+    const pictureEvents = ["ambientchange", "cropbarschange", "loadeddata"];
+    for (const event of pictureEvents)
+        player.addEventListener(event, retainPictureSampling);
+    return () => {
+        disposed = true;
+        player.removeEventListener("keydown", guard, true);
+        player.removeEventListener("focusin", resumeAutoHide);
+        player.removeEventListener("focusout", resumeAutoHide);
+        shadow?.removeEventListener("focusin", resumeAutoHide);
+        shadow?.removeEventListener("focusout", resumeAutoHide);
+        menuObserver.disconnect();
+        resize.disconnect();
+        for (const event of pictureEvents)
+            player.removeEventListener(event, retainPictureSampling);
+    };
+}
diff --git a/website/src/features/settings/BotModeSettings.css b/website/src/features/settings/BotModeSettings.css
new file mode 100644
index 00000000..13b00d8a
--- /dev/null
+++ b/website/src/features/settings/BotModeSettings.css
@@ -0,0 +1,18 @@
+#bot-mode {
+    scroll-margin-top: 20px;
+}
+.bot-upload-destination {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    margin: 16px 0;
+    overflow-wrap: anywhere;
+}
+.bot-upload-destination > span {
+    color: var(--muted);
+    font-size: 13px;
+}
+.bot-upload-destination > strong {
+    font-size: 14px;
+    font-weight: 500;
+}
diff --git a/website/src/features/settings/BotModeSettings.tsx b/website/src/features/settings/BotModeSettings.tsx
new file mode 100644
index 00000000..9abfe220
--- /dev/null
+++ b/website/src/features/settings/BotModeSettings.tsx
@@ -0,0 +1,291 @@
+import { useCallback, useEffect, useState } from "react";
+import { Button, Paper } from "@mantine/core";
+import { ChevronRight, Folder } from "lucide-react";
+import { api, errorMessage, type BotUploadSettings } from "../../shared/api";
+import { ErrorNotice, Modal, Spinner } from "../../shared/components";
+import { itemPath, type DriveItem } from "../../shared/types";
+import {
+    useManualRefresh,
+    type RefreshNotice,
+} from "../../shared/useManualRefresh";
+import "./BotModeSettings.css";
+
+export default function BotModeSettings({
+    onNotice,
+    demoMode = false,
+}: { onNotice?: RefreshNotice; demoMode?: boolean } = {}) {
+    const [saved, setSaved] = useState<BotUploadSettings | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [busy, setBusy] = useState(false);
+    const [picking, setPicking] = useState(false);
+    const [error, setError] = useState("");
+    const [notice, setNotice] = useState("");
+    const manual = useManualRefresh(onNotice);
+    const load = useCallback(async (signal?: AbortSignal, explicit = false) => {
+        setLoading(true);
+        setError("");
+        try {
+            const value = await api.botUploadSettings(signal);
+            if (signal?.aborted) return false;
+            setSaved(value);
+            return true;
+        } catch (cause) {
+            if (!signal?.aborted) setError(errorMessage(cause));
+            if (explicit) throw cause;
+            return false;
+        } finally {
+            if (!signal?.aborted) setLoading(false);
+        }
+    }, []);
+    useEffect(() => {
+        const controller = new AbortController();
+        void load(controller.signal);
+        return () => controller.abort();
+    }, [load]);
+    useEffect(() => {
+        if (saved && window.location.hash === "#bot-mode")
+            document
+                .getElementById("bot-mode")
+                ?.scrollIntoView({ block: "start" });
+    }, [saved]);
+    const save = async (path: string | null) => {
+        if (demoMode) return;
+        setBusy(true);
+        setError("");
+        setNotice("");
+        try {
+            setSaved(await api.saveBotUploadSettings(path));
+            setPicking(false);
+            setNotice(
+                "Bot upload folder saved. Applies to the next file you send.",
+            );
+        } catch (cause) {
+            setError(errorMessage(cause));
+        } finally {
+            setBusy(false);
+        }
+    };
+    return (
+        <Paper
+            component="section"
+            id="bot-mode"
+            className="settings-section preference-section"
+            aria-labelledby="bot-mode-heading"
+        >
+            <h2 id="bot-mode-heading">Bot uploads</h2>
+            <p className="settings-help">
+                Files you send or forward to the Telegram bot are saved in this
+                folder.
+            </p>
+            {loading ? (
+                <p role="status">
+                    <Spinner /> Loading bot settings…
+                </p>
+            ) : (
+                saved && (
+                    <>
+                        <p className="bot-upload-destination">
+                            <span>Upload folder</span>
+                            <strong>{saved.folder_label}</strong>
+                        </p>
+                        {!saved.available && (
+                            <ErrorNotice message="This folder is no longer available. Choose another before sending more files to the bot." />
+                        )}
+                        {!saved.enabled && (
+                            <p className="settings-help">
+                                Bot mode is not enabled on this installation.
+                                You can still choose its upload folder.
+                            </p>
+                        )}
+                        <div className="upload-settings-actions">
+                            <Button
+                                className="secondary-button"
+                                disabled={demoMode || busy}
+                                onClick={() => {
+                                    setPicking(true);
+                                    setError("");
+                                    setNotice("");
+                                }}
+                            >
+                                Change folder
+                            </Button>
+                            <Button
+                                variant="subtle"
+                                className="text-button"
+                                disabled={demoMode || busy}
+                                onClick={() => void save(null)}
+                            >
+                                Use default folder
+                            </Button>
+                        </div>
+                        <p className="settings-help">
+                            Default: My Files / TGDriveBotModeFiles. Created
+                            automatically on the first bot upload. Changes apply
+                            without restarting.
+                        </p>
+                    </>
+                )
+            )}
+            {!picking && <ErrorNotice message={error} />}
+            {!saved && (!loading || manual.refreshing) && (
+                <Button
+                    variant="subtle"
+                    disabled={loading || manual.refreshing}
+                    aria-busy={manual.refreshing}
+                    onClick={() =>
+                        void manual.run(
+                            (signal) => load(signal, true),
+                            "Bot settings refreshed.",
+                        )
+                    }
+                >
+                    {manual.refreshing && <Spinner />}
+                    {manual.refreshing ? "Refreshing…" : "Try again"}
+                </Button>
+            )}
+            {notice && <p role="status">{notice}</p>}
+            {picking && (
+                <FolderPicker
+                    busy={busy}
+                    error={error}
+                    onSave={save}
+                    onClose={() => {
+                        if (!busy) setPicking(false);
+                    }}
+                />
+            )}
+        </Paper>
+    );
+}
+
+function FolderPicker({
+    busy,
+    error,
+    onSave,
+    onClose,
+}: {
+    busy: boolean;
+    error: string;
+    onSave: (path: string) => Promise<void>;
+    onClose: () => void;
+}) {
+    const [trail, setTrail] = useState([{ path: "/", name: "My Files" }]);
+    const [folders, setFolders] = useState<DriveItem[]>([]);
+    const [loading, setLoading] = useState(true);
+    const [loadError, setLoadError] = useState("");
+    const [retry, setRetry] = useState(0);
+    const path = trail[trail.length - 1].path;
+    useEffect(() => {
+        const controller = new AbortController();
+        setLoading(true);
+        setLoadError("");
+        setFolders([]);
+        void api
+            .directory(path, "", controller.signal)
+            .then((result) => {
+                if (!controller.signal.aborted)
+                    setFolders(
+                        Object.values(result.data.contents)
+                            .filter((item) => item.type === "folder")
+                            .sort((a, b) => a.name.localeCompare(b.name)),
+                    );
+            })
+            .catch((cause) => {
+                if (!controller.signal.aborted)
+                    setLoadError(errorMessage(cause));
+            })
+            .finally(() => {
+                if (!controller.signal.aborted) setLoading(false);
+            });
+        return () => controller.abort();
+    }, [path, retry]);
+    return (
+        <Modal title="Choose bot upload folder" onClose={onClose}>
+            <p className="muted">
+                Open a folder, then choose Use this folder. All bot uploads will
+                go there.
+            </p>
+            <nav
+                className="move-breadcrumbs"
+                aria-label="Bot upload folder breadcrumb"
+            >
+                {trail.map((crumb, index) => (
+                    <button
+                        type="button"
+                        key={crumb.path}
+                        className="text-button"
+                        disabled={busy}
+                        onClick={() => setTrail(trail.slice(0, index + 1))}
+                    >
+                        {index > 0 && (
+                            <ChevronRight size={13} aria-hidden="true" />
+                        )}
+                        {crumb.name}
+                    </button>
+                ))}
+            </nav>
+            <div className="folder-picker" aria-busy={loading}>
+                {loading ? (
+                    <p role="status">
+                        <Spinner /> Loading folders…
+                    </p>
+                ) : loadError ? (
+                    <>
+                        <ErrorNotice message={loadError} />
+                        <button
+                            type="button"
+                            className="text-button"
+                            onClick={() => setRetry(retry + 1)}
+                        >
+                            Try again
+                        </button>
+                    </>
+                ) : folders.length ? (
+                    folders.map((folder) => (
+                        <button
+                            type="button"
+                            key={folder.id}
+                            disabled={busy}
+                            onClick={() =>
+                                setTrail([
+                                    ...trail,
+                                    {
+                                        path: itemPath(folder),
+                                        name: folder.name,
+                                    },
+                                ])
+                            }
+                        >
+                            <Folder size={19} aria-hidden="true" />
+                            <span>{folder.name}</span>
+                            <ChevronRight size={16} aria-hidden="true" />
+                        </button>
+                    ))
+                ) : (
+                    <p className="muted">
+                        No subfolders here. You can use this folder.
+                    </p>
+                )}
+            </div>
+            <ErrorNotice message={error} />
+            <div className="dialog-actions">
+                <button
+                    type="button"
+                    className="secondary-button"
+                    disabled={busy}
+                    onClick={onClose}
+                >
+                    Cancel
+                </button>
+                <button
+                    type="button"
+                    className="primary-button"
+                    disabled={busy || loading || Boolean(loadError)}
+                    onClick={() => void onSave(path)}
+                >
+                    {busy ? "Saving…" : "Use this folder"}
+                </button>
+            </div>
+        </Modal>
+    );
+}
diff --git a/website/src/features/settings/PremiumConnection.tsx b/website/src/features/settings/PremiumConnection.tsx
new file mode 100644
index 00000000..96bca957
--- /dev/null
+++ b/website/src/features/settings/PremiumConnection.tsx
@@ -0,0 +1,303 @@
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import { Check, ShieldCheck } from "lucide-react";
+import { api, ApiError, errorMessage } from "../../shared/api";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import type { ManagementSettings, PremiumChallenge } from "../../shared/types";
+
+export default function PremiumConnection({
+    revision,
+    blockedReason,
+    onComplete,
+    onCancel,
+    onRefresh,
+}: {
+    revision: number;
+    blockedReason: string;
+    onComplete: (value: ManagementSettings) => void;
+    onCancel: () => void;
+    onRefresh: () => void;
+}) {
+    const [stage, setStage] = useState<"phone" | "code" | "password">("phone");
+    const [label, setLabel] = useState("My Premium account");
+    const [phone, setPhone] = useState("");
+    const [code, setCode] = useState("");
+    const [password, setPassword] = useState("");
+    const [error, setError] = useState("");
+    const [busy, setBusy] = useState(false);
+    const [waitUntil, setWaitUntil] = useState(0);
+    const [remaining, setRemaining] = useState(0);
+    const challenge = useRef<PremiumChallenge | null>(null);
+    const mounted = useRef(true);
+    const focusField = useRef<HTMLInputElement>(null);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            const active = challenge.current;
+            challenge.current = null;
+            if (active)
+                void api
+                    .cancelPremiumLogin(active.challenge_id)
+                    .catch(() => {});
+        };
+    }, []);
+    useEffect(() => {
+        focusField.current?.focus();
+    }, [stage]);
+    useEffect(() => {
+        if (!waitUntil) return;
+        const tick = () => {
+            const seconds = Math.max(
+                0,
+                Math.ceil((waitUntil - Date.now()) / 1000),
+            );
+            setRemaining(seconds);
+            if (!seconds) setWaitUntil(0);
+        };
+        tick();
+        const timer = setInterval(tick, 1000);
+        return () => clearInterval(timer);
+    }, [waitUntil]);
+    const submit = async (event: FormEvent) => {
+        event.preventDefault();
+        if (busy || remaining || blockedReason) return;
+        setError("");
+        const normalizedPhone = phone.replace(/[ ()-]/g, "").trim();
+        if (
+            stage === "phone" &&
+            !/^\+[1-9][0-9]{6,14}$/.test(normalizedPhone)
+        ) {
+            setError(
+                "Enter your phone number with its country code, such as +441234567890.",
+            );
+            return;
+        }
+        setBusy(true);
+        try {
+            if (stage === "phone") {
+                const value = await api.startPremiumLogin(
+                    revision,
+                    normalizedPhone,
+                    label.trim(),
+                );
+                if (!mounted.current) {
+                    void api
+                        .cancelPremiumLogin(value.challenge_id)
+                        .catch(() => {});
+                    return;
+                }
+                challenge.current = value;
+                setStage("code");
+            } else {
+                const active = challenge.current;
+                if (!active)
+                    throw new Error(
+                        "This connection request expired. Start again.",
+                    );
+                const result = await api.verifyPremiumLogin(
+                    active.challenge_id,
+                    stage === "code"
+                        ? { code: code.replace(/\s/g, "") }
+                        : { password },
+                );
+                if (!mounted.current) return;
+                if (result.stage === "complete") {
+                    challenge.current = null;
+                    onComplete(result.settings);
+                } else {
+                    challenge.current = result;
+                    setStage(result.stage);
+                }
+            }
+        } catch (cause) {
+            if (!mounted.current) return;
+            if (
+                cause instanceof ApiError &&
+                cause.status === 429 &&
+                cause.retryAfter > 0
+            ) {
+                const seconds = Math.ceil(cause.retryAfter);
+                setRemaining(seconds);
+                setWaitUntil(Date.now() + seconds * 1000);
+            }
+            if (
+                cause instanceof ApiError &&
+                (cause.status === 410 ||
+                    cause.status === 502 ||
+                    cause.code === "TELEGRAM_PREMIUM_REQUIRED" ||
+                    cause.code.startsWith("SETTINGS_") ||
+                    (cause.status === 429 &&
+                        cause.code === "TELEGRAM_LOGIN_FAILED"))
+            ) {
+                const active = challenge.current;
+                challenge.current = null;
+                if (active)
+                    void api
+                        .cancelPremiumLogin(active.challenge_id)
+                        .catch(() => {});
+                setStage("phone");
+                if (cause.code.startsWith("SETTINGS_")) onRefresh();
+            }
+            setError(errorMessage(cause));
+            focusField.current?.focus();
+        } finally {
+            setCode("");
+            setPassword("");
+            if (mounted.current) setBusy(false);
+        }
+    };
+    return (
+        <form
+            className="management-form premium-connection"
+            onSubmit={(event) => void submit(event)}
+            aria-labelledby="premium-connect-heading"
+        >
+            <h3 id="premium-connect-heading">
+                <ShieldCheck size={18} /> Connect a Premium Account
+            </h3>
+            <ol className="premium-steps" aria-label="Connection progress">
+                <li
+                    aria-current={stage === "phone" ? "step" : undefined}
+                    data-complete={stage !== "phone"}
+                >
+                    Account
+                </li>
+                <li
+                    aria-current={stage === "code" ? "step" : undefined}
+                    data-complete={stage === "password"}
+                >
+                    Login code
+                </li>
+                <li aria-current={stage === "password" ? "step" : undefined}>
+                    Verification
+                </li>
+            </ol>
+            <p>
+                Your account must already have Telegram Premium and access to
+                this drive’s channel. Login happens here; your code and two-step
+                password are not saved.
+            </p>
+            <fieldset disabled={busy || Boolean(blockedReason)}>
+                {stage === "phone" ? (
+                    <>
+                        <label htmlFor="premium-account-label">
+                            Account Name
+                        </label>
+                        <input
+                            id="premium-account-label"
+                            required
+                            maxLength={80}
+                            value={label}
+                            autoComplete="off"
+                            onChange={(event) => setLabel(event.target.value)}
+                        />
+                        <label htmlFor="premium-phone">Phone Number</label>
+                        <input
+                            id="premium-phone"
+                            ref={focusField}
+                            type="tel"
+                            autoComplete="tel"
+                            required
+                            maxLength={32}
+                            placeholder="+441234567890"
+                            value={phone}
+                            aria-describedby="premium-phone-help"
+                            onChange={(event) => setPhone(event.target.value)}
+                        />
+                        <p
+                            id="premium-phone-help"
+                            className="management-caption"
+                        >
+                            Include the + country code. Telegram will send a
+                            login code for this account.
+                        </p>
+                    </>
+                ) : stage === "code" ? (
+                    <>
+                        <label htmlFor="premium-code">
+                            Telegram Login Code
+                        </label>
+                        <input
+                            id="premium-code"
+                            ref={focusField}
+                            inputMode="numeric"
+                            autoComplete="one-time-code"
+                            required
+                            maxLength={16}
+                            value={code}
+                            aria-describedby="premium-code-help"
+                            onChange={(event) => setCode(event.target.value)}
+                        />
+                        <p
+                            id="premium-code-help"
+                            className="management-caption"
+                        >
+                            Enter the code from Telegram. This request expires
+                            after five minutes.
+                        </p>
+                    </>
+                ) : (
+                    <>
+                        <label htmlFor="premium-2fa">
+                            Telegram Two-Step Password
+                        </label>
+                        <input
+                            id="premium-2fa"
+                            ref={focusField}
+                            type="password"
+                            autoComplete="off"
+                            required
+                            maxLength={512}
+                            value={password}
+                            onChange={(event) =>
+                                setPassword(event.target.value)
+                            }
+                        />
+                        <p className="management-caption">
+                            This account has two-step verification. Enter its
+                            Telegram password.
+                        </p>
+                    </>
+                )}
+            </fieldset>
+            {blockedReason && <p className="settings-help">{blockedReason}</p>}
+            <ErrorNotice message={error} />
+            {busy && (
+                <p role="status">
+                    <Spinner />
+                    {stage === "phone"
+                        ? "Requesting a Telegram Login Code…"
+                        : "Verifying your Telegram account…"}
+                </p>
+            )}
+            <div className="management-actions">
+                <button
+                    className="primary-button"
+                    disabled={busy || remaining > 0 || Boolean(blockedReason)}
+                >
+                    {busy ? <Spinner /> : <Check size={17} />}
+                    {remaining
+                        ? `Try Again in ${remaining}s`
+                        : stage === "phone"
+                          ? "Send Login Code"
+                          : stage === "code"
+                            ? "Verify Code"
+                            : "Connect Account"}
+                </button>
+                <button
+                    type="button"
+                    className="secondary-button"
+                    disabled={busy}
+                    onClick={onCancel}
+                >
+                    Cancel Connection
+                </button>
+            </div>
+            <p className="management-caption">
+                After verification, the account is saved privately for this
+                installation. Restart TGDrive to use it. Treat the saved session
+                as an account credential.
+            </p>
+        </form>
+    );
+}
diff --git a/website/src/features/settings/SettingsManagement.css b/website/src/features/settings/SettingsManagement.css
new file mode 100644
index 00000000..64f9dcce
--- /dev/null
+++ b/website/src/features/settings/SettingsManagement.css
@@ -0,0 +1,482 @@
+.page-body {
+    max-width: 1024px;
+}
+.settings-section {
+    padding-block: 4px 28px;
+    margin-bottom: 28px;
+    border-bottom: 1px solid var(--line-subtle);
+}
+.settings-section:last-child {
+    border-bottom: 0;
+}
+.settings-section h2 {
+    margin: 0 0 7px;
+    font-size: 16px;
+    line-height: 24px;
+    font-weight: 600;
+}
+.settings-section p {
+    max-width: 70ch;
+    margin: 0 0 14px;
+    color: var(--muted);
+    font-size: 14px;
+    line-height: 1.6;
+}
+.settings-section-title {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    gap: 20px;
+    margin-bottom: 20px;
+}
+.settings-section-title > div:first-child {
+    flex: 1;
+    min-width: 180px;
+}
+.connection-management .settings-section-title {
+    align-items: center;
+}
+.connection-management .connection-summary {
+    margin-top: 10px;
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+}
+.managed-client-columns {
+    display: grid;
+    grid-template-columns: minmax(130px, 1fr) minmax(130px, 1fr) 96px;
+    gap: 12px;
+    padding: 12px 10px 12px 58px;
+    color: var(--muted);
+    font-size: 12px;
+}
+.settings-section-title p {
+    margin: 0;
+}
+.management-actions {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin: 0;
+}
+.management-notice,
+.management-pending {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    margin: 0 0 24px;
+}
+.management-notice {
+    color: var(--success);
+    font-size: 13px;
+}
+.management-pending {
+    padding: 16px;
+    border-radius: 10px;
+    background: var(--surface-subtle);
+}
+.management-pending > div {
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.management-pending > svg {
+    flex-shrink: 0;
+    color: var(--warning);
+    margin-top: 2px;
+}
+.management-pending strong {
+    font-size: 14px;
+    font-weight: 600;
+}
+.management-pending p {
+    font-size: 13px;
+    line-height: 1.6;
+    color: var(--muted);
+    margin: 4px 0 8px;
+}
+.management-pending details,
+.management-running,
+.connection-advanced {
+    font-size: 12px;
+}
+.management-pending summary,
+.management-running summary,
+.connection-advanced summary {
+    cursor: pointer;
+    color: var(--muted);
+    list-style: none;
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    width: max-content;
+}
+.management-pending summary:hover,
+.management-running summary:hover,
+.connection-advanced summary:hover {
+    color: var(--ink);
+}
+.management-pending code {
+    display: block;
+    margin-top: 12px;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+    user-select: text;
+}
+.managed-client-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    border-block-start: 1px solid var(--line-subtle);
+}
+.managed-client-list > li {
+    border-block-end: 1px solid var(--line-subtle);
+}
+.managed-client-list > .is-editing {
+    background: var(--surface-subtle);
+    border-radius: 12px;
+}
+.managed-client-row {
+    display: grid;
+    grid-template-columns: 36px minmax(130px, 1fr) minmax(130px, 1fr) 96px;
+    align-items: center;
+    gap: 12px;
+    min-height: 88px;
+    padding: 18px 10px;
+}
+.managed-client-icon {
+    display: grid;
+    place-items: center;
+    width: 36px;
+    height: 36px;
+    color: var(--icon);
+    background: var(--surface-subtle);
+    border-radius: 8px;
+}
+.managed-client-info,
+.managed-client-state {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+}
+.managed-client-info strong {
+    font-size: 14px;
+    font-weight: 600;
+    overflow-wrap: anywhere;
+}
+.managed-client-info > span,
+.managed-client-state > span {
+    font-size: 12px;
+    color: var(--muted);
+    overflow-wrap: anywhere;
+}
+.managed-client-state .client-health {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+    color: var(--muted);
+}
+.client-health > span {
+    width: 6px;
+    height: 6px;
+    flex: 0 0 6px;
+    border-radius: 50%;
+    background: var(--muted);
+}
+.managed-client-state .is-connected {
+    color: var(--success);
+}
+.client-health.is-connected > span {
+    background: var(--success);
+}
+.connection-management .management-caption {
+    font-size: 12px;
+    color: var(--muted);
+    line-height: 1.65;
+    margin: 8px 0 0;
+}
+.connection-readiness {
+    padding-block: 10px;
+}
+.inline-link {
+    color: var(--action);
+    padding: 0 3px;
+    font-size: inherit;
+    text-decoration: underline;
+    text-underline-offset: 3px;
+}
+.connection-editor {
+    padding: 24px;
+    margin: 0;
+    background: var(--surface-subtle);
+    border-radius: 12px;
+}
+.connection-editor fieldset,
+.premium-connection fieldset {
+    margin: 0;
+    padding: 0;
+    border: 0;
+    min-width: 0;
+}
+.connection-editor label,
+.premium-connection label {
+    font-size: 13px;
+}
+.management-fields {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) minmax(0, 1.5fr);
+    gap: 20px;
+}
+.management-fields > div {
+    min-width: 0;
+}
+.connection-editor input:not([type="checkbox"]),
+.premium-connection input {
+    background: var(--surface);
+}
+.connection-editor-options {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: 12px;
+    margin-block: 18px 0;
+}
+.management-checkbox {
+    display: inline-flex;
+    align-items: center;
+    gap: 9px;
+    margin: 0;
+    font-weight: 400;
+}
+.connection-editor-footer {
+    margin-top: 22px;
+}
+.connection-editor-footer .management-actions {
+    margin-top: 14px;
+}
+.new-client-editor > h3 {
+    padding: 20px 20px 0;
+    margin: 0;
+    font-size: 14px;
+}
+.client-removal {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    gap: 12px;
+}
+.client-removal p {
+    margin: 0;
+}
+.management-running {
+    margin-top: 18px;
+}
+.management-running ul {
+    list-style: none;
+    padding: 10px 0;
+    margin: 0;
+}
+.management-running li {
+    display: flex;
+    justify-content: space-between;
+    gap: 16px;
+    padding-block: 8px;
+    color: var(--muted);
+}
+.management-running li > span {
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.connection-api-summary {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 20px 48px;
+    margin: 0 0 20px;
+}
+.connection-api-summary dt {
+    color: var(--muted);
+    font-size: 12px;
+    margin-bottom: 7px;
+}
+.connection-api-summary > div {
+    min-width: 0;
+    max-width: 100%;
+    overflow-wrap: anywhere;
+}
+.connection-api-summary dd {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 7px;
+    margin: 0;
+    font-size: 14px;
+    user-select: text;
+}
+.connection-api-summary dd small {
+    color: var(--muted);
+    width: 100%;
+    font-size: 11px;
+}
+.connection-advanced {
+    margin-top: 20px;
+}
+.connection-advanced p {
+    margin-top: 16px;
+}
+.connection-footer-note {
+    max-width: 75ch;
+}
+.premium-connection {
+    margin: 18px 0 0;
+    padding: 24px;
+    border-radius: 12px;
+    background: var(--surface-subtle);
+}
+.premium-connection h3 {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 15px;
+    font-weight: 600;
+    margin: 0 0 10px;
+}
+.premium-steps {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px 20px;
+    list-style: none;
+    padding: 0 0 14px;
+    margin: 18px 0;
+    border-bottom: 1px solid var(--line-subtle);
+    font-size: 12px;
+    color: var(--muted);
+}
+.premium-steps li[aria-current="step"] {
+    color: var(--ink);
+    font-weight: 600;
+    text-decoration: underline;
+    text-decoration-color: var(--action);
+    text-underline-offset: 8px;
+}
+.premium-steps li[data-complete="true"] {
+    color: var(--success);
+}
+.premium-connection input {
+    max-width: 420px;
+    margin-bottom: 14px;
+}
+.premium-connection .management-actions {
+    margin-top: 20px;
+}
+.restart-required-banner {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+    padding: 14px 16px;
+    margin-bottom: 22px;
+    background: var(--surface-subtle);
+    border-radius: 8px;
+}
+.restart-required-banner > svg {
+    color: var(--warning);
+    margin-top: 2px;
+}
+.restart-required-banner > div {
+    flex: 1;
+    min-width: 0;
+}
+.restart-required-banner strong {
+    font-size: 13px;
+    font-weight: 600;
+}
+.restart-required-banner p {
+    margin: 4px 0 0;
+    font-size: 12px;
+    color: var(--muted);
+}
+@media (max-width: 620px) {
+    .management-pending summary,
+    .management-running summary,
+    .connection-advanced summary {
+        min-height: 44px;
+        max-width: 100%;
+    }
+    .managed-client-columns {
+        display: none;
+    }
+    .settings-section-title {
+        gap: 14px;
+    }
+    .settings-section-title > .management-actions {
+        width: 100%;
+    }
+    .connection-management .settings-section-title > .management-actions {
+        display: grid;
+        grid-template-columns: auto minmax(0, 1fr);
+        gap: 10px;
+    }
+    .connection-management .settings-section-title .primary-button {
+        grid-column: 1 / -1;
+        grid-row: 1;
+    }
+    .connection-management .settings-section-title .secondary-button {
+        justify-self: end;
+    }
+    .settings-section-title .primary-button,
+    .settings-section-title .secondary-button {
+        font-size: 12px;
+        padding-inline: 12px;
+    }
+    .managed-client-row {
+        grid-template-columns: 32px minmax(0, 1fr) auto;
+        gap: 10px;
+        padding: 16px 0;
+    }
+    .managed-client-state {
+        grid-column: 2;
+        grid-row: 2;
+    }
+    .managed-client-row > .text-button {
+        grid-column: 3;
+        grid-row: 1 / span 2;
+        padding-inline: 7px;
+    }
+    .managed-client-icon {
+        width: 32px;
+        height: 32px;
+    }
+    .managed-client-row .text-button > span {
+        display: inline;
+    }
+    .managed-client-row > .text-button {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .managed-client-row > .text-button svg {
+        display: none;
+    }
+    .management-fields {
+        grid-template-columns: minmax(0, 1fr);
+        gap: 18px;
+    }
+    .connection-editor,
+    .premium-connection {
+        padding: 16px;
+    }
+    .connection-editor input,
+    .premium-connection input {
+        font-size: 16px;
+    }
+    .connection-api-summary {
+        gap: 22px 30px;
+    }
+    .restart-required-banner {
+        flex-wrap: wrap;
+    }
+    .restart-required-banner > .text-button {
+        margin-inline-start: 32px;
+    }
+}
diff --git a/website/src/features/settings/SettingsManagement.tsx b/website/src/features/settings/SettingsManagement.tsx
new file mode 100644
index 00000000..995e87ba
--- /dev/null
+++ b/website/src/features/settings/SettingsManagement.tsx
@@ -0,0 +1,1002 @@
+import {
+    useCallback,
+    useEffect,
+    useRef,
+    useState,
+    useSyncExternalStore,
+    type FormEvent,
+} from "react";
+import {
+    AlertCircle,
+    Bot,
+    Check,
+    ChevronDown,
+    KeyRound,
+    Pencil,
+    Plus,
+    RefreshCw,
+    Undo2,
+    UserRound,
+    X,
+} from "lucide-react";
+import { api, ApiError, errorMessage } from "../../shared/api";
+import { useManualRefresh } from "../../shared/useManualRefresh";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import type { ManagedClient, ManagementSettings } from "../../shared/types";
+import {
+    clientConnectionLabel,
+    clientDisplayName,
+    createConnectionDraft,
+    isCredentialRepair,
+    MAX_STORAGE_CLIENTS,
+    prepareConnectionUpdate,
+    type ClientDraft,
+    type ConnectionDraft,
+} from "./settingsManagement";
+import { transfers, uploadBackupState } from "../transfers/transfers";
+import PremiumConnection from "./PremiumConnection";
+import DemoModeNotice from "../../shared/DemoModeNotice";
+import "./SettingsManagement.css";
+
+function announceSaved(value: ManagementSettings) {
+    window.dispatchEvent(
+        new CustomEvent("tgdrive:settings-saved", {
+            detail: {
+                admission_paused: value.admission_paused,
+                restart_required: value.restart_required,
+            },
+        }),
+    );
+}
+function ClientHealth({ client }: { client: ManagedClient }) {
+    const label = clientConnectionLabel(client);
+    return (
+        <span
+            className={
+                "client-health " +
+                (client.enabled &&
+                client.connected &&
+                client.healthy &&
+                !["queued", "checking", "waiting", "failed"].includes(
+                    client.connection_check ?? "",
+                )
+                    ? "is-connected"
+                    : "")
+            }
+        >
+            <span aria-hidden="true" />
+            {label}
+        </span>
+    );
+}
+export default function SettingsManagement({
+    onNotice,
+    demoMode = false,
+}: {
+    onNotice?: (message: string, error?: boolean) => void;
+    demoMode?: boolean;
+}) {
+    const [settings, setSettings] = useState<ManagementSettings | null>(null);
+    const [draft, setDraft] = useState<ConnectionDraft | null>(null);
+    const [target, setTarget] = useState<string | null>(null);
+    const [premiumOpen, setPremiumOpen] = useState(false);
+    const [error, setError] = useState("");
+    const [formError, setFormError] = useState("");
+    const [notice, setNotice] = useState("");
+    const [loading, setLoading] = useState(true);
+    const [saving, setSaving] = useState(false);
+    const { refreshing: refreshingConnections, run } =
+        useManualRefresh(onNotice);
+    const manualPending = useRef(false);
+    const checksBusy = Boolean(
+        settings?.clients.some((client) =>
+            ["queued", "checking", "waiting"].includes(
+                client.connection_check ?? "",
+            ),
+        ),
+    );
+    const checksPending = Boolean(
+        settings?.clients.some(
+            (client) =>
+                ["queued", "checking"].includes(
+                    client.connection_check ?? "",
+                ) ||
+                (client.connection_check === "waiting" &&
+                    (!client.connection_retry_at ||
+                        client.connection_retry_at * 1000 <= Date.now())),
+        ),
+    );
+    const generation = useRef(0);
+    const mounted = useRef(true);
+    const editBase = useRef<ManagementSettings | null>(null);
+    const firstField = useRef<HTMLInputElement>(null);
+    const load = useCallback(async (signal?: AbortSignal, manual = false) => {
+        if (manualPending.current && !manual) return false;
+        const requestId = ++generation.current;
+        try {
+            const value = await api.settings(signal);
+            if (
+                mounted.current &&
+                !signal?.aborted &&
+                requestId === generation.current
+            ) {
+                setSettings(value);
+                setError("");
+                return true;
+            }
+            return false;
+        } catch (cause) {
+            if (
+                mounted.current &&
+                requestId === generation.current &&
+                !signal?.aborted
+            ) {
+                setSettings(null);
+                setError(errorMessage(cause));
+            }
+            if (manual) throw cause;
+            return false;
+        } finally {
+            if (mounted.current && requestId === generation.current)
+                setLoading(false);
+        }
+    }, []);
+    useEffect(() => {
+        mounted.current = true;
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            await load(controller.signal);
+            if (!controller.signal.aborted) timer = setTimeout(poll, 10000);
+        };
+        void poll();
+        return () => {
+            mounted.current = false;
+            ++generation.current;
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [load]);
+    useEffect(() => {
+        if (!checksPending) return;
+        const controller = new AbortController();
+        const timer = setTimeout(() => void load(controller.signal), 1000);
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [checksPending, settings, load]);
+    const refreshSettings = () =>
+        run(async (signal) => {
+            manualPending.current = true;
+            try {
+                return await load(signal, true);
+            } finally {
+                manualPending.current = false;
+            }
+        }, "Connection status refreshed.");
+    const refreshConnections = () => {
+        if (demoMode) return;
+        return run(async (signal) => {
+            manualPending.current = true;
+            const requestId = ++generation.current;
+            try {
+                const value = await api.refreshConnections(signal);
+                if (
+                    !mounted.current ||
+                    signal.aborted ||
+                    requestId !== generation.current
+                )
+                    return false;
+                setSettings(value);
+                setError("");
+                return true;
+            } catch (cause) {
+                if (
+                    mounted.current &&
+                    !signal.aborted &&
+                    requestId === generation.current
+                )
+                    setError(errorMessage(cause));
+                throw cause;
+            } finally {
+                manualPending.current = false;
+            }
+        }, "Connection checks requested.");
+    };
+    useEffect(() => {
+        firstField.current?.focus();
+    }, [target]);
+    const uploadItems = useSyncExternalStore(
+        transfers.subscribe,
+        transfers.snapshot,
+    );
+    const unfinished = uploadBackupState(uploadItems);
+    const recovery = settings?.recovery;
+    const cleanRepair = Boolean(
+        recovery?.state === "error" &&
+        !recovery.recovery_required &&
+        recovery.protected_revision === recovery.metadata_revision,
+    );
+    const jobsPending = Boolean(
+        settings &&
+        (settings.stats.active_jobs ||
+            settings.stats.queued_jobs ||
+            settings.stats.failed_jobs),
+    );
+    const blocked =
+        !settings ||
+        Boolean(unfinished) ||
+        jobsPending ||
+        !recovery ||
+        (recovery.state !== "protected" && !cleanRepair) ||
+        recovery.recovery_required === true ||
+        recovery.protected_revision < recovery.metadata_revision;
+    const blockedReason =
+        unfinished || jobsPending
+            ? "Finish or cancel pending transfers before saving connection changes."
+            : "Restore the database connection before saving connection changes.";
+    const credentialRepair = isCredentialRepair(draft, settings);
+    const closeEditor = () => {
+        setDraft(null);
+        setTarget(null);
+        setFormError("");
+        editBase.current = null;
+    };
+    const beginEdit = (id: string) => {
+        if (demoMode || !settings) return;
+        editBase.current = settings;
+        setDraft(createConnectionDraft(settings));
+        setTarget(id);
+        setNotice("");
+        setFormError("");
+    };
+    const addClient = (kind: "bot" | "user") => {
+        if (demoMode || !settings) return;
+        const next = createConnectionDraft(settings);
+        const key = crypto.randomUUID();
+        next.clients.push({
+            key,
+            label: kind === "bot" ? "Storage Bot" : "My Premium account",
+            kind,
+            enabled: true,
+            credential: "",
+            removed: false,
+        });
+        editBase.current = settings;
+        setDraft(next);
+        setTarget(key);
+        setPremiumOpen(false);
+        setNotice("");
+        setFormError("");
+    };
+    const changeClient = (key: string, patch: Partial<ClientDraft>) =>
+        setDraft(
+            (current) =>
+                current && {
+                    ...current,
+                    clients: current.clients.map((row) =>
+                        row.key === key ? { ...row, ...patch } : row,
+                    ),
+                },
+        );
+    const dirty = Boolean(
+        draft &&
+        editBase.current &&
+        (draft.apiId !== String(editBase.current.api_id) ||
+            draft.apiHash.trim() ||
+            draft.clients.some((row) => {
+                const prior = editBase.current!.clients.find(
+                    (client) => client.id === row.id,
+                );
+                return (
+                    !prior ||
+                    row.removed ||
+                    row.credential.trim() ||
+                    row.label !== prior.label ||
+                    row.enabled !== prior.enabled
+                );
+            })),
+    );
+    const save = async (event: FormEvent) => {
+        event.preventDefault();
+        if (demoMode || !draft || saving || !dirty) return;
+        if (blocked && !credentialRepair) {
+            setFormError(blockedReason);
+            return;
+        }
+        let payload;
+        try {
+            payload = prepareConnectionUpdate(draft);
+        } catch (cause) {
+            setFormError(errorMessage(cause));
+            return;
+        }
+        setSaving(true);
+        setFormError("");
+        setNotice("");
+        ++generation.current;
+        try {
+            const value = await api.saveSettings(payload);
+            if (!mounted.current) return;
+            ++generation.current;
+            setSettings(value);
+            announceSaved(value);
+            setError("");
+            closeEditor();
+            setNotice(
+                value.restart_required
+                    ? "Verified and saved. Restart TGDrive to apply your connection changes."
+                    : "Connection verified and saved.",
+            );
+        } catch (cause) {
+            if (!mounted.current) return;
+            if (
+                cause instanceof ApiError &&
+                cause.code === "SETTINGS_CONFLICT"
+            ) {
+                closeEditor();
+                setFormError(
+                    "Connection settings changed elsewhere. Review the latest configuration and try again.",
+                );
+                await load();
+            } else setFormError(errorMessage(cause));
+        } finally {
+            if (mounted.current) setSaving(false);
+        }
+    };
+    const footer = () => (
+        <div className="connection-editor-footer">
+            {blocked && (
+                <p className="management-caption">
+                    {credentialRepair
+                        ? "You can repair a token or session for the same Telegram account while keeping pending transfers. Other connection changes must wait."
+                        : blockedReason}{" "}
+                    <button
+                        type="button"
+                        className="inline-link"
+                        disabled={refreshingConnections}
+                        onClick={() => void refreshSettings()}
+                    >
+                        {refreshingConnections && <Spinner />} Check Again
+                    </button>
+                </p>
+            )}
+            {settings && draft && settings.revision !== draft.revision && (
+                <ErrorNotice message="The saved configuration changed. Cancel and reopen this editor before saving." />
+            )}
+            <ErrorNotice message={formError} />
+            <div className="management-actions">
+                {dirty && (
+                    <button
+                        className="primary-button"
+                        disabled={
+                            demoMode ||
+                            saving ||
+                            (blocked && !credentialRepair) ||
+                            Boolean(
+                                settings &&
+                                draft &&
+                                settings.revision !== draft.revision,
+                            )
+                        }
+                    >
+                        {saving ? <Spinner /> : <Check size={17} />}
+                        {saving ? "Verifying…" : "Verify and Save"}
+                    </button>
+                )}
+                <button
+                    type="button"
+                    className="secondary-button"
+                    disabled={saving}
+                    onClick={closeEditor}
+                >
+                    {dirty ? "Cancel Changes" : "Done"}
+                </button>
+            </div>
+            {saving && (
+                <p role="status" className="management-caption">
+                    Checking accounts and channel access. Your current
+                    connection stays active.
+                </p>
+            )}
+        </div>
+    );
+    const editor = (row: ClientDraft) => (
+        <form
+            className="connection-editor"
+            onSubmit={(event) => void save(event)}
+        >
+            <fieldset disabled={demoMode || saving}>
+                {row.removed ? (
+                    <div className="client-removal">
+                        <p>
+                            {row.label} will be removed after you save and
+                            restart.
+                        </p>
+                        <button
+                            type="button"
+                            className="text-button"
+                            onClick={() =>
+                                changeClient(row.key, { removed: false })
+                            }
+                        >
+                            <Undo2 size={16} /> Undo Removal
+                        </button>
+                    </div>
+                ) : (
+                    <>
+                        <div className="management-fields">
+                            <div>
+                                <label htmlFor={"client-label-" + row.key}>
+                                    Local Label
+                                </label>
+                                <input
+                                    ref={firstField}
+                                    id={"client-label-" + row.key}
+                                    required
+                                    maxLength={80}
+                                    value={row.label}
+                                    onChange={(event) =>
+                                        changeClient(row.key, {
+                                            label: event.target.value,
+                                        })
+                                    }
+                                />
+                            </div>
+                            <div>
+                                <label htmlFor={"client-credential-" + row.key}>
+                                    {row.id ? "Replace " : ""}
+                                    {row.kind === "bot"
+                                        ? "Bot Token"
+                                        : "Telethon Session"}
+                                </label>
+                                <input
+                                    id={"client-credential-" + row.key}
+                                    type="password"
+                                    autoComplete="new-password"
+                                    maxLength={8192}
+                                    required={!row.id}
+                                    value={row.credential}
+                                    aria-describedby={
+                                        "credential-help-" + row.key
+                                    }
+                                    onChange={(event) =>
+                                        changeClient(row.key, {
+                                            credential: event.target.value,
+                                        })
+                                    }
+                                />
+                                <p
+                                    id={"credential-help-" + row.key}
+                                    className="management-caption"
+                                >
+                                    {row.id
+                                        ? "Leave blank to keep the saved credential."
+                                        : row.kind === "bot"
+                                          ? "Paste the token from BotFather. It stays hidden after saving."
+                                          : "Import a Telethon StringSession generated locally. Treat it as an account credential."}
+                                </p>
+                            </div>
+                        </div>
+                        <div className="connection-editor-options">
+                            <label className="management-checkbox">
+                                <input
+                                    type="checkbox"
+                                    checked={row.enabled}
+                                    onChange={(event) =>
+                                        changeClient(row.key, {
+                                            enabled: event.target.checked,
+                                        })
+                                    }
+                                />{" "}
+                                Enabled after restart
+                            </label>
+                            {row.id && (
+                                <button
+                                    type="button"
+                                    className="text-button danger-text"
+                                    onClick={() =>
+                                        changeClient(row.key, {
+                                            removed: true,
+                                            credential: "",
+                                        })
+                                    }
+                                >
+                                    <X size={16} /> Remove Client
+                                </button>
+                            )}
+                        </div>
+                        {row.kind === "bot" && (
+                            <p className="management-caption">
+                                The bot needs channel administrator permission
+                                to post and delete messages.
+                            </p>
+                        )}
+                    </>
+                )}
+            </fieldset>
+            {footer()}
+        </form>
+    );
+    const selected = draft?.clients.find((row) => row.key === target);
+    const connectedClients =
+        settings?.clients.filter(
+            (client) => clientConnectionLabel(client) === "Connected",
+        ).length ?? 0;
+    return (
+        <div
+            className="connection-management page-body"
+            aria-busy={saving || refreshingConnections}
+        >
+            {demoMode && <DemoModeNotice />}
+            {loading && (
+                <div className="loading-state" role="status">
+                    <Spinner /> Loading connections…
+                </div>
+            )}
+            {error && (
+                <div className="management-load-error">
+                    <ErrorNotice message={error} />
+                    <button
+                        className="secondary-button"
+                        type="button"
+                        disabled={refreshingConnections}
+                        onClick={() => void refreshSettings()}
+                    >
+                        {refreshingConnections ? (
+                            <Spinner />
+                        ) : (
+                            <RefreshCw size={16} />
+                        )}{" "}
+                        Try Again
+                    </button>
+                </div>
+            )}
+            {notice && (
+                <p className="management-notice" role="status">
+                    <Check size={18} />
+                    {notice}
+                </p>
+            )}
+            {settings?.storage_channel_error && (
+                <div className="management-pending" role="alert">
+                    <AlertCircle size={20} aria-hidden="true" />
+                    <div>
+                        <strong>Storage channel needs attention</strong>
+                        <p>{settings.storage_channel_error}</p>
+                        <p>
+                            Resolve the issue above, then restart TGDrive to
+                            check the channel again. Keep the same storage
+                            channel for this drive.
+                        </p>
+                    </div>
+                </div>
+            )}
+            {settings?.restart_required && (
+                <div className="management-pending" role="status">
+                    <AlertCircle size={20} />
+                    <div>
+                        <strong>Saved changes need a restart</strong>
+                        <p>
+                            New file changes are paused. Your running connection
+                            is still available for browsing and downloads.
+                        </p>
+                        <details>
+                            <summary>How to Restart</summary>
+                            <code>docker compose restart app</code>
+                            <p>
+                                Run this in the installation folder, using the
+                                existing Compose project name if you selected
+                                one.
+                            </p>
+                        </details>
+                    </div>
+                </div>
+            )}
+            {settings && (
+                <>
+                    <section
+                        className="settings-section"
+                        aria-labelledby="storage-clients-heading"
+                    >
+                        <div className="settings-section-title">
+                            <div>
+                                <h2 id="storage-clients-heading">
+                                    Storage Clients
+                                </h2>
+                                <p>
+                                    Bots store your files. Available Premium
+                                    accounts are preferred for upload and
+                                    download speed. All accounts use the same
+                                    file split size, capped at 2000 MiB per
+                                    document.
+                                </p>
+                                <p className="connection-summary">
+                                    {connectedClients} connected ·{" "}
+                                    {settings.clients.length} configured
+                                </p>
+                            </div>
+                            <div className="management-actions">
+                                <button
+                                    type="button"
+                                    className="text-button"
+                                    disabled={
+                                        demoMode ||
+                                        refreshingConnections ||
+                                        checksBusy ||
+                                        Boolean(draft) ||
+                                        premiumOpen
+                                    }
+                                    title="Check saved credentials and storage channel access"
+                                    onClick={() => void refreshConnections()}
+                                >
+                                    {refreshingConnections || checksPending ? (
+                                        <Spinner />
+                                    ) : (
+                                        <RefreshCw size={16} />
+                                    )}
+                                    {refreshingConnections || checksPending
+                                        ? "Checking…"
+                                        : checksBusy
+                                          ? "Waiting to retry…"
+                                          : "Refresh"}
+                                </button>
+                                <button
+                                    type="button"
+                                    className="primary-button"
+                                    disabled={
+                                        demoMode ||
+                                        Boolean(draft) ||
+                                        premiumOpen ||
+                                        settings.clients.length >=
+                                            MAX_STORAGE_CLIENTS
+                                    }
+                                    onClick={() => addClient("bot")}
+                                >
+                                    <Plus size={17} /> Add Storage Bot
+                                </button>
+                                <button
+                                    type="button"
+                                    className="secondary-button"
+                                    disabled={
+                                        demoMode ||
+                                        Boolean(draft) ||
+                                        premiumOpen ||
+                                        blocked ||
+                                        settings.clients.length >=
+                                            MAX_STORAGE_CLIENTS
+                                    }
+                                    onClick={() => {
+                                        setPremiumOpen(true);
+                                        setNotice("");
+                                    }}
+                                >
+                                    <Plus size={17} /> Connect Premium Account
+                                </button>
+                            </div>
+                        </div>
+                        <div
+                            className="managed-client-columns"
+                            aria-hidden="true"
+                        >
+                            <span>Account</span>
+                            <span>Connection & activity</span>
+                            <span />
+                        </div>
+                        <ul
+                            className="managed-client-list"
+                            aria-label="Configured storage clients"
+                        >
+                            {settings.clients.map((client) => (
+                                <li
+                                    key={client.id}
+                                    className={
+                                        target === client.id ? "is-editing" : ""
+                                    }
+                                >
+                                    <div className="managed-client-row">
+                                        <span className="managed-client-icon">
+                                            {client.kind === "bot" ? (
+                                                <Bot size={20} />
+                                            ) : (
+                                                <UserRound size={20} />
+                                            )}
+                                        </span>
+                                        <div className="managed-client-info">
+                                            <strong>
+                                                {clientDisplayName(client)}
+                                            </strong>
+                                            <span>
+                                                {client.username && (
+                                                    <>@{client.username} · </>
+                                                )}
+                                                {client.kind === "bot"
+                                                    ? "Storage Bot"
+                                                    : "Premium account"}
+                                            </span>
+                                        </div>
+                                        <div className="managed-client-state">
+                                            <ClientHealth client={client} />
+                                            <span>
+                                                {client.connection_check ===
+                                                    "passed" &&
+                                                client.active_leases === 0 ? (
+                                                    client.kind === "bot" ? (
+                                                        "Token and channel verified"
+                                                    ) : (
+                                                        "Account and channel verified"
+                                                    )
+                                                ) : (
+                                                    <>
+                                                        {client.active_leases}{" "}
+                                                        active{" "}
+                                                        {client.active_leases ===
+                                                        1
+                                                            ? "operation"
+                                                            : "operations"}
+                                                    </>
+                                                )}
+                                            </span>
+                                            {(client.connection_check_error ||
+                                                client.error) && (
+                                                <span
+                                                    className="danger-text"
+                                                    role="status"
+                                                >
+                                                    {client.connection_check_error ||
+                                                        client.error}
+                                                </span>
+                                            )}
+                                        </div>
+                                        <button
+                                            type="button"
+                                            className="text-button"
+                                            aria-label={
+                                                "Manage " +
+                                                clientDisplayName(client)
+                                            }
+                                            disabled={
+                                                demoMode ||
+                                                saving ||
+                                                Boolean(
+                                                    draft &&
+                                                    target !== client.id,
+                                                ) ||
+                                                premiumOpen
+                                            }
+                                            onClick={() =>
+                                                target === client.id
+                                                    ? closeEditor()
+                                                    : beginEdit(client.id)
+                                            }
+                                        >
+                                            <Pencil size={16} />
+                                            <span>Manage</span>
+                                        </button>
+                                    </div>
+                                    {target === client.id &&
+                                        selected &&
+                                        editor(selected)}
+                                </li>
+                            ))}
+                            {selected && !selected.id && (
+                                <li className="is-editing new-client-editor">
+                                    <h3>
+                                        {selected.kind === "bot"
+                                            ? "Add Storage Bot"
+                                            : "Import Premium Session"}
+                                    </h3>
+                                    {editor(selected)}
+                                </li>
+                            )}
+                        </ul>
+                        {!demoMode && premiumOpen && (
+                            <PremiumConnection
+                                revision={settings.revision}
+                                blockedReason={blocked ? blockedReason : ""}
+                                onCancel={() => setPremiumOpen(false)}
+                                onRefresh={() => void load()}
+                                onComplete={(value) => {
+                                    ++generation.current;
+                                    setSettings(value);
+                                    announceSaved(value);
+                                    setPremiumOpen(false);
+                                    setNotice(
+                                        "Premium account verified and saved. Restart TGDrive to use it.",
+                                    );
+                                }}
+                            />
+                        )}
+                        {!draft && !premiumOpen && blocked && (
+                            <p className="management-caption connection-readiness">
+                                {blockedReason}{" "}
+                                <button
+                                    type="button"
+                                    className="inline-link"
+                                    disabled={refreshingConnections}
+                                    onClick={() => void refreshSettings()}
+                                >
+                                    {refreshingConnections && <Spinner />} Check
+                                    Readiness
+                                </button>
+                            </p>
+                        )}
+                        {cleanRepair && (
+                            <p className="management-caption">
+                                The last confirmed catalog is current. You can
+                                repair a failed connection; backup needs
+                                attention until the repaired service restarts
+                                and verifies it.
+                            </p>
+                        )}
+                        {settings.restart_required &&
+                            settings.active_clients?.length > 0 && (
+                                <details className="management-running">
+                                    <summary>
+                                        Currently running clients{" "}
+                                        <ChevronDown size={15} />
+                                    </summary>
+                                    <ul>
+                                        {settings.active_clients.map(
+                                            (client) => (
+                                                <li key={client.id}>
+                                                    <span>
+                                                        {clientDisplayName(
+                                                            client,
+                                                        )}
+                                                    </span>
+                                                    <span>
+                                                        {clientConnectionLabel({
+                                                            ...client,
+                                                            enabled: true,
+                                                        })}
+                                                    </span>
+                                                </li>
+                                            ),
+                                        )}
+                                    </ul>
+                                </details>
+                            )}
+                    </section>
+                    <section
+                        className="settings-section"
+                        aria-labelledby="telegram-api-heading"
+                    >
+                        <div className="settings-section-title">
+                            <div>
+                                <h2 id="telegram-api-heading">Telegram API</h2>
+                                <p>
+                                    Application credentials for connecting this
+                                    installation to Telegram.
+                                </p>
+                            </div>
+                            <button
+                                type="button"
+                                className="text-button"
+                                disabled={
+                                    demoMode ||
+                                    saving ||
+                                    Boolean(draft && target !== "api") ||
+                                    premiumOpen
+                                }
+                                onClick={() =>
+                                    target === "api"
+                                        ? closeEditor()
+                                        : beginEdit("api")
+                                }
+                            >
+                                <Pencil size={16} /> Edit API Credentials
+                            </button>
+                        </div>
+                        <dl className="connection-api-summary">
+                            <div>
+                                <dt>API ID</dt>
+                                <dd>{settings.api_id}</dd>
+                            </div>
+                            <div>
+                                <dt>API Hash</dt>
+                                <dd>
+                                    <KeyRound size={15} />
+                                    {settings.api_hash_configured
+                                        ? "Saved · hidden"
+                                        : "Not Configured"}
+                                </dd>
+                            </div>
+                            <div>
+                                <dt>Storage Channel</dt>
+                                <dd>
+                                    {settings.storage_channel}
+                                    <small>Fixed for this drive</small>
+                                </dd>
+                            </div>
+                        </dl>
+                        {target === "api" && draft && (
+                            <form
+                                className="connection-editor"
+                                onSubmit={(event) => void save(event)}
+                            >
+                                <fieldset disabled={demoMode || saving}>
+                                    <div className="management-fields">
+                                        <div>
+                                            <label htmlFor="telegram-api-id">
+                                                API ID
+                                            </label>
+                                            <input
+                                                id="telegram-api-id"
+                                                ref={firstField}
+                                                inputMode="numeric"
+                                                autoComplete="off"
+                                                required
+                                                maxLength={10}
+                                                value={draft.apiId}
+                                                onChange={(event) =>
+                                                    setDraft({
+                                                        ...draft,
+                                                        apiId: event.target
+                                                            .value,
+                                                    })
+                                                }
+                                            />
+                                        </div>
+                                        <div>
+                                            <label htmlFor="telegram-api-hash">
+                                                Replace API Hash
+                                            </label>
+                                            <input
+                                                id="telegram-api-hash"
+                                                type="password"
+                                                autoComplete="new-password"
+                                                maxLength={32}
+                                                value={draft.apiHash}
+                                                onChange={(event) =>
+                                                    setDraft({
+                                                        ...draft,
+                                                        apiHash:
+                                                            event.target.value,
+                                                    })
+                                                }
+                                            />
+                                            <p className="management-caption">
+                                                Leave blank to keep the saved
+                                                hash.
+                                            </p>
+                                        </div>
+                                    </div>
+                                </fieldset>
+                                {footer()}
+                            </form>
+                        )}
+                        <details className="connection-advanced">
+                            <summary>Advanced Connection Options</summary>
+                            <p>
+                                Already have an authorized Telethon
+                                StringSession?
+                            </p>
+                            <button
+                                type="button"
+                                className="secondary-button"
+                                disabled={
+                                    demoMode ||
+                                    Boolean(draft) ||
+                                    premiumOpen ||
+                                    settings.clients.length >=
+                                        MAX_STORAGE_CLIENTS
+                                }
+                                onClick={() => addClient("user")}
+                            >
+                                Import session (advanced)
+                            </button>
+                        </details>
+                    </section>
+                    <p className="management-caption connection-footer-note">
+                        Credentials are saved privately in MongoDB and encrypted
+                        in Telegram database backups. Keep at least one enabled
+                        bot. Verified changes apply after restart.
+                    </p>
+                </>
+            )}
+            {!draft && <ErrorNotice message={formError} />}
+        </div>
+    );
+}
diff --git a/website/src/features/settings/StorageView.css b/website/src/features/settings/StorageView.css
new file mode 100644
index 00000000..f9c0ceb1
--- /dev/null
+++ b/website/src/features/settings/StorageView.css
@@ -0,0 +1,229 @@
+.storage-page {
+    max-width: 1024px;
+}
+.storage-protection {
+    padding-top: 4px;
+}
+.storage-protection-heading {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    margin-bottom: 18px;
+}
+.storage-protection-heading > div:nth-child(2) {
+    min-width: 0;
+    flex: 1;
+}
+.storage-protection-heading h2 {
+    margin-bottom: 3px;
+}
+.storage-protection-heading > .secondary-button {
+    margin-inline-start: auto;
+}
+.storage-protection-icon {
+    display: grid;
+    place-items: center;
+    width: 48px;
+    height: 48px;
+    flex: 0 0 48px;
+    color: var(--action);
+    background: var(--surface-subtle);
+    border-radius: 12px;
+}
+.storage-protection-icon.is-protected {
+    color: var(--success);
+}
+.storage-protection-icon.is-attention {
+    color: var(--danger);
+}
+.storage-protection .drive-backup-state {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+    font-size: 13px;
+    margin: 0;
+}
+.storage-protection .backup-confirmation-date {
+    margin: 0 0 8px;
+    font-size: 12px;
+}
+.backup-confirmation-date strong {
+    color: var(--ink);
+    font-weight: 500;
+    user-select: text;
+}
+.storage-protection .backup-safety-note {
+    margin-bottom: 0;
+}
+.storage-catalog {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    margin: 0;
+    padding-block: 5px 8px;
+}
+.storage-catalog > div {
+    min-width: 0;
+    padding-inline: 22px;
+    border-inline-end: 1px solid var(--line-subtle);
+}
+.storage-catalog > div:first-child {
+    padding-inline-start: 0;
+}
+.storage-catalog > div:last-child {
+    border: 0;
+}
+.storage-catalog dt {
+    font-size: 13px;
+    color: var(--muted);
+    margin-bottom: 8px;
+}
+.storage-catalog dd {
+    margin: 0;
+    font-size: 22px;
+    line-height: 30px;
+    font-weight: 500;
+    font-variant-numeric: tabular-nums;
+    user-select: text;
+    overflow-wrap: anywhere;
+}
+.storage-catalog dd > span {
+    display: block;
+    margin-top: 5px;
+    font-size: 13px;
+    line-height: 20px;
+    font-weight: 400;
+    color: var(--muted);
+}
+.storage-count-link {
+    font: inherit;
+    padding: 0;
+}
+.storage-count-link:focus-visible {
+    outline: 2px solid var(--action);
+    outline-offset: 4px;
+}
+.storage-count-link:hover {
+    color: var(--action);
+}
+.staging-usage {
+    max-width: 700px;
+    padding-top: 3px;
+}
+.staging-meter-label,
+.storage-secondary-facts {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    font-size: 12px;
+    color: var(--muted);
+    font-variant-numeric: tabular-nums;
+}
+.staging-meter-label {
+    color: var(--ink);
+}
+.staging-meter {
+    display: block;
+    appearance: none;
+    width: 100%;
+    height: 7px;
+    overflow: hidden;
+    border: 0;
+    border-radius: 4px;
+    background: var(--line-subtle);
+    margin-block: 12px;
+}
+.staging-meter::-webkit-progress-bar {
+    background: var(--line-subtle);
+}
+.staging-meter::-webkit-progress-value {
+    background: var(--action);
+    border-radius: 4px;
+}
+.staging-meter::-moz-progress-bar {
+    background: var(--action);
+}
+.storage-jobs {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: 16px;
+}
+.storage-jobs p {
+    margin: 0;
+}
+.drive-recovery-help {
+    padding-block: 0 24px;
+}
+.drive-recovery-help summary {
+    display: list-item;
+    font-size: 14px;
+    font-weight: 500;
+    padding-block: 8px;
+    cursor: pointer;
+}
+.drive-recovery-help > p {
+    color: var(--muted);
+    max-width: 70ch;
+    font-size: 14px;
+    line-height: 1.65;
+}
+.drive-recovery-help > .inline-link {
+    display: inline-flex;
+    align-items: center;
+    gap: 5px;
+    padding-inline: 0;
+}
+@media (max-width: 620px) {
+    .storage-protection-heading {
+        display: grid;
+        grid-template-columns: 48px minmax(0, 1fr);
+        gap: 12px;
+    }
+    .storage-protection-heading > .secondary-button {
+        grid-column: 2;
+        justify-self: start;
+        margin-inline-start: 0;
+    }
+    .storage-catalog > div {
+        padding-inline: 12px;
+    }
+    .storage-catalog dd {
+        font-size: 20px;
+    }
+    .storage-catalog dd > span {
+        font-size: 12px;
+    }
+}
+@media (max-width: 480px) {
+    .storage-catalog {
+        grid-template-columns: minmax(0, 1fr);
+        gap: 16px;
+    }
+    .storage-catalog > div {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) minmax(0, 1.5fr);
+        gap: 12px;
+        align-items: baseline;
+        padding-inline: 0;
+        border-inline-end: 0;
+    }
+    .storage-catalog dt {
+        margin-bottom: 0;
+    }
+    .storage-catalog dd {
+        text-align: end;
+    }
+    .storage-catalog .storage-count-link {
+        text-align: end;
+    }
+}
+
+.backup-guide-link {
+    display: inline-flex;
+    align-items: center;
+    min-height: 44px;
+    margin-inline-end: 20px;
+}
diff --git a/website/src/features/settings/StorageView.tsx b/website/src/features/settings/StorageView.tsx
new file mode 100644
index 00000000..70e78f6b
--- /dev/null
+++ b/website/src/features/settings/StorageView.tsx
@@ -0,0 +1,455 @@
+import {
+    useCallback,
+    useEffect,
+    useRef,
+    useState,
+    useSyncExternalStore,
+} from "react";
+import {
+    AlertCircle,
+    ExternalLink,
+    RefreshCw,
+    ShieldCheck,
+} from "lucide-react";
+import { api, errorMessage } from "../../shared/api";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import DemoModeNotice from "../../shared/DemoModeNotice";
+import {
+    formatBytes,
+    formatTimestamp,
+    type ManagementStats,
+    type ServerStatus,
+} from "../../shared/types";
+import {
+    useManualRefresh,
+    type RefreshNotice,
+} from "../../shared/useManualRefresh";
+import ChannelBackup from "../backup/ChannelBackup";
+import DatabaseRestore, {
+    type DatabaseRestoreState,
+} from "../backup/DatabaseRestore";
+import { transfers, uploadBackupState } from "../transfers/transfers";
+import "./StorageView.css";
+
+export default function StorageView({
+    config,
+    demoMode = false,
+    onTransfers,
+    onTrash,
+    onNotice,
+    onRestoreStateChange,
+}: {
+    config: { max_file_size: number };
+    demoMode?: boolean;
+    onTransfers: () => void;
+    onTrash: () => void;
+    onNotice?: RefreshNotice;
+    onRestoreStateChange?: (state: DatabaseRestoreState) => void;
+}) {
+    const [status, setStatus] = useState<ServerStatus | null>(null);
+    const [usage, setUsage] = useState<ManagementStats | null>(null);
+    const [error, setError] = useState("");
+    const [usageError, setUsageError] = useState("");
+    const [loading, setLoading] = useState(true);
+    const [backingUp, setBackingUp] = useState(false);
+    const [backupError, setBackupError] = useState("");
+    const [restoringDatabase, setRestoringDatabase] = useState(false);
+    const generation = useRef(0);
+    const mounted = useRef(true);
+    const manualPending = useRef(false);
+    const refreshAction = useManualRefresh(onNotice);
+    const load = useCallback(async (signal?: AbortSignal, manual = false) => {
+        if (manualPending.current && !manual) return false;
+        const current = ++generation.current;
+        const [health, management] = await Promise.allSettled([
+            api.status(signal),
+            api.settings(signal),
+        ]);
+        if (
+            !mounted.current ||
+            signal?.aborted ||
+            current !== generation.current
+        )
+            return false;
+        if (health.status === "fulfilled") {
+            setStatus(health.value);
+            setError("");
+        } else {
+            setStatus(null);
+            setError(errorMessage(health.reason));
+        }
+        if (management.status === "fulfilled") {
+            setUsage(management.value.stats);
+            setUsageError("");
+        } else {
+            setUsage(null);
+            setUsageError(
+                "Usage figures could not be loaded. Check Again to retry.",
+            );
+        }
+        setLoading(false);
+        if (manual) {
+            if (health.status === "rejected") throw health.reason;
+            if (management.status === "rejected") throw management.reason;
+        }
+        return true;
+    }, []);
+    const refreshStorage = () =>
+        refreshAction.run(async (signal) => {
+            manualPending.current = true;
+            try {
+                return await load(signal, true);
+            } finally {
+                manualPending.current = false;
+            }
+        }, "Storage refreshed.");
+    useEffect(() => {
+        mounted.current = true;
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            await load(controller.signal);
+            if (!controller.signal.aborted) timer = setTimeout(poll, 5000);
+        };
+        if (!restoringDatabase) void poll();
+        return () => {
+            mounted.current = false;
+            ++generation.current;
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [load, restoringDatabase]);
+    const uploadItems = useSyncExternalStore(
+        transfers.subscribe,
+        transfers.snapshot,
+    );
+    const uploadProtection = uploadBackupState(uploadItems);
+    const recovery = status?.recovery;
+    const protectedDrive =
+        !error &&
+        !uploadProtection &&
+        recovery?.state === "protected" &&
+        !recovery.recovery_required &&
+        recovery.protected_revision >= recovery.metadata_revision;
+    const attention = Boolean(
+        error ||
+        recovery?.state === "error" ||
+        uploadProtection === "attention",
+    );
+    const lastBackup = recovery?.last_success_at
+        ? new Date(recovery.last_success_at)
+        : null;
+    const label = loading
+        ? "Checking storage…"
+        : protectedDrive
+          ? "Saved to MongoDB"
+          : recovery?.state === "error"
+            ? "Database Needs Attention"
+            : uploadProtection === "attention"
+              ? "Uploads Need Attention"
+              : uploadProtection
+                ? "Uploads Still in Progress"
+                : recovery?.state === "pending"
+                  ? "Backing up your latest changes"
+                  : "Backup Status Unavailable";
+    const backUp = async () => {
+        if (demoMode || restoringDatabase) return;
+        setBackingUp(true);
+        setBackupError("");
+        try {
+            await api.backup();
+        } catch (cause) {
+            if (mounted.current) setBackupError(errorMessage(cause));
+        } finally {
+            if (mounted.current) {
+                await load();
+                setBackingUp(false);
+            }
+        }
+    };
+    const databaseRestoreState = useCallback(
+        (state: DatabaseRestoreState) => {
+            if (mounted.current) setRestoringDatabase(state.phase !== "idle");
+            onRestoreStateChange?.(state);
+        },
+        [onRestoreStateChange],
+    );
+    return (
+        <div className="storage-page page-body">
+            {demoMode && <DemoModeNotice />}
+            <section
+                className="settings-section storage-protection"
+                aria-labelledby="drive-backup-heading"
+            >
+                <div className="storage-protection-heading">
+                    <div
+                        className={
+                            "storage-protection-icon " +
+                            (protectedDrive
+                                ? "is-protected"
+                                : attention
+                                  ? "is-attention"
+                                  : "")
+                        }
+                    >
+                        {protectedDrive ? (
+                            <ShieldCheck size={25} />
+                        ) : attention ? (
+                            <AlertCircle size={25} />
+                        ) : (
+                            <RefreshCw size={25} />
+                        )}
+                    </div>
+                    <div>
+                        <h2 id="drive-backup-heading">Cloud Database</h2>
+                        <p
+                            className={
+                                "drive-backup-state " +
+                                (protectedDrive
+                                    ? "connection-ready"
+                                    : attention
+                                      ? "danger-text"
+                                      : "")
+                            }
+                            role="status"
+                        >
+                            {(backingUp || (!protectedDrive && !attention)) && (
+                                <Spinner />
+                            )}
+                            {label}
+                        </p>
+                    </div>
+                    <button
+                        className="secondary-button"
+                        disabled={
+                            demoMode ||
+                            restoringDatabase ||
+                            backingUp ||
+                            loading ||
+                            refreshAction.refreshing ||
+                            !status
+                        }
+                        onClick={() => void backUp()}
+                    >
+                        {backingUp ? <Spinner /> : <RefreshCw size={16} />}
+                        {backingUp ? "Backing up…" : "Back Up Now"}
+                    </button>
+                </div>
+                <p className="backup-confirmation-date">
+                    Last Telegram Safety Copy:{" "}
+                    <strong>
+                        {lastBackup && !Number.isNaN(lastBackup.getTime())
+                            ? formatTimestamp(recovery?.last_success_at)
+                            : "Scheduled Automatically"}
+                    </strong>
+                </p>
+                <p className="backup-safety-note">
+                    Your catalog is saved in MongoDB; files stay in Telegram.
+                    Encrypted database backups run separately. Unfinished
+                    uploads still need their local files.
+                </p>
+                <ErrorNotice
+                    message={
+                        backupError ||
+                        error ||
+                        (typeof recovery?.error === "string"
+                            ? recovery.error
+                            : "") ||
+                        (typeof recovery?.backup_error === "string"
+                            ? recovery.backup_error
+                            : "")
+                    }
+                />
+                <a
+                    className="inline-link backup-guide-link"
+                    href="https://github.com/TechShreyash/TGDrive/blob/main/docs/backup-recovery.md"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                >
+                    Backup &amp; recovery guide
+                </a>
+                {recovery?.backup_key_configured &&
+                    (demoMode ? (
+                        <button type="button" className="text-button" disabled>
+                            Save Recovery Key
+                        </button>
+                    ) : (
+                        <a
+                            className="text-button"
+                            href="/api/v1/backup/recovery-key"
+                            download
+                        >
+                            Save Recovery Key
+                        </a>
+                    ))}
+            </section>
+            <ChannelBackup demoMode={demoMode} onNotice={onNotice} />
+            <section
+                className="settings-section"
+                aria-labelledby="drive-usage-heading"
+            >
+                <div className="settings-section-title">
+                    <div>
+                        <h2 id="drive-usage-heading">Files in This Drive</h2>
+                        <p>
+                            Your cataloged files and folders. Telegram does not
+                            provide a storage quota here.
+                        </p>
+                    </div>
+                    <button
+                        className="text-button"
+                        aria-label="Check Again"
+                        disabled={
+                            loading ||
+                            backingUp ||
+                            restoringDatabase ||
+                            refreshAction.refreshing
+                        }
+                        onClick={() => void refreshStorage()}
+                        aria-busy={refreshAction.refreshing}
+                    >
+                        {refreshAction.refreshing ? (
+                            <Spinner />
+                        ) : (
+                            <RefreshCw size={16} />
+                        )}
+                        {refreshAction.refreshing
+                            ? "Refreshing…"
+                            : "Check Again"}
+                    </button>
+                </div>
+                <ErrorNotice message={usageError} />
+                {usage ? (
+                    <dl className="storage-catalog">
+                        <div>
+                            <dt>Files</dt>
+                            <dd>
+                                {usage.files.toLocaleString()}
+                                <span>
+                                    {formatBytes(usage.total_bytes)} stored
+                                </span>
+                            </dd>
+                        </div>
+                        <div>
+                            <dt>Folders</dt>
+                            <dd>
+                                {usage.folders.toLocaleString()}
+                                <span>Across your drive</span>
+                            </dd>
+                        </div>
+                        <div>
+                            <dt>In Trash</dt>
+                            <dd>
+                                <button
+                                    className="storage-count-link"
+                                    onClick={onTrash}
+                                >
+                                    {usage.trashed_files.toLocaleString()}
+                                </button>
+                                <span>
+                                    {formatBytes(usage.trashed_bytes)} ·{" "}
+                                    <button
+                                        className="inline-link"
+                                        onClick={onTrash}
+                                    >
+                                        Open Trash
+                                    </button>
+                                </span>
+                            </dd>
+                        </div>
+                    </dl>
+                ) : (
+                    !usageError && (
+                        <p role="status">
+                            <Spinner /> Loading usage…
+                        </p>
+                    )
+                )}
+            </section>
+            <section
+                className="settings-section"
+                aria-labelledby="staging-heading"
+            >
+                <h2 id="staging-heading">Temporary Storage</h2>
+                <p>
+                    Reserved space for browser uploads before Telegram confirms
+                    them.
+                </p>
+                {usage && (
+                    <div className="staging-usage">
+                        <div className="staging-meter-label">
+                            <span>
+                                {formatBytes(usage.staging_reserved_bytes)}{" "}
+                                reserved
+                            </span>
+                            <span>
+                                {formatBytes(usage.staging_budget_bytes)} budget
+                            </span>
+                        </div>
+                        <progress
+                            className="staging-meter"
+                            value={usage.staging_reserved_bytes}
+                            max={Math.max(1, usage.staging_budget_bytes)}
+                            aria-label="Reserved Upload Staging"
+                        />
+                        <div className="storage-secondary-facts">
+                            <span>
+                                {usage.free_disk_bytes == null
+                                    ? "Free Disk Unavailable"
+                                    : formatBytes(usage.free_disk_bytes) +
+                                      " free on the staging disk"}
+                            </span>
+                            <span>
+                                File limit:{" "}
+                                {formatBytes(
+                                    typeof status?.max_file_size === "number"
+                                        ? status.max_file_size
+                                        : config.max_file_size,
+                                )}
+                            </span>
+                        </div>
+                    </div>
+                )}
+            </section>
+            {usage && (
+                <section
+                    className="settings-section storage-jobs"
+                    aria-labelledby="storage-transfers-heading"
+                >
+                    <div>
+                        <h2 id="storage-transfers-heading">
+                            Current Transfers
+                        </h2>
+                        <p>
+                            {usage.active_jobs} active · {usage.queued_jobs}{" "}
+                            queued · {usage.failed_jobs} need attention
+                        </p>
+                    </div>
+                    <button className="secondary-button" onClick={onTransfers}>
+                        Open Transfers
+                    </button>
+                </section>
+            )}
+            <details className="drive-recovery-help">
+                <summary>Recover on a New Installation</summary>
+                <p>
+                    Use the same MongoDB connection to reopen this drive on a
+                    new installation. A catalog restore is only needed if the
+                    database itself is lost.
+                </p>
+                <DatabaseRestore
+                    demoMode={demoMode}
+                    onRestoreStateChange={databaseRestoreState}
+                />
+                <a
+                    className="inline-link"
+                    href="https://github.com/TechShreyash/TGDrive/blob/main/docs/backup-recovery.md"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                >
+                    Read the Recovery Guide <ExternalLink size={13} />
+                </a>
+            </details>
+        </div>
+    );
+}
diff --git a/website/src/features/settings/UploadSettings.css b/website/src/features/settings/UploadSettings.css
new file mode 100644
index 00000000..adbf117e
--- /dev/null
+++ b/website/src/features/settings/UploadSettings.css
@@ -0,0 +1,60 @@
+.preference-description p {
+    margin-bottom: 0;
+}
+.preference-controls {
+    min-width: 0;
+}
+
+.upload-limit-setting {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 24px;
+    margin-block: 24px 12px;
+}
+.upload-limit-setting label {
+    font-weight: 500;
+}
+.upload-limit-setting p {
+    margin: 5px 0 0;
+    font-size: 13px;
+}
+.upload-limit-stepper {
+    display: flex;
+    align-items: center;
+    flex-shrink: 0;
+    padding: 4px;
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    background: var(--surface);
+}
+.upload-limit-stepper input {
+    appearance: textfield;
+    width: 46px;
+    padding: 8px 0;
+    border: 0;
+    background: transparent;
+    color: var(--ink);
+    text-align: center;
+    font-size: 16px;
+    font-variant-numeric: tabular-nums;
+}
+.upload-limit-stepper input::-webkit-inner-spin-button,
+.upload-limit-stepper input::-webkit-outer-spin-button {
+    appearance: none;
+    margin: 0;
+}
+.upload-settings-actions {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 16px;
+    margin-top: 20px;
+}
+@media (max-width: 480px) {
+    .upload-limit-setting {
+        align-items: flex-start;
+        flex-direction: column;
+        gap: 12px;
+    }
+}
diff --git a/website/src/features/settings/UploadSettings.tsx b/website/src/features/settings/UploadSettings.tsx
new file mode 100644
index 00000000..51762804
--- /dev/null
+++ b/website/src/features/settings/UploadSettings.tsx
@@ -0,0 +1,230 @@
+import { Button, Paper } from "@mantine/core";
+import { useCallback, useEffect, useState, type FormEvent } from "react";
+import { Minus, Plus } from "lucide-react";
+import { api, errorMessage, type UploadPreferences } from "../../shared/api";
+import { ErrorNotice, Spinner } from "../../shared/components";
+import {
+    useManualRefresh,
+    type RefreshNotice,
+} from "../../shared/useManualRefresh";
+import "./UploadSettings.css";
+
+export default function UploadSettings({
+    onNotice,
+    demoMode = false,
+}: { onNotice?: RefreshNotice; demoMode?: boolean } = {}) {
+    const [saved, setSaved] = useState<UploadPreferences | null>(null);
+    const [value, setValue] = useState(1);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    const [notice, setNotice] = useState("");
+    const [loading, setLoading] = useState(true);
+    const refreshAction = useManualRefresh(onNotice);
+    const load = useCallback(async (signal?: AbortSignal, manual = false) => {
+        setLoading(true);
+        setError("");
+        try {
+            const preferences = await api.uploadPreferences(signal);
+            if (!signal?.aborted) {
+                setSaved(preferences);
+                setValue(preferences.uploads_per_bot);
+            }
+            return !signal?.aborted;
+        } catch (cause) {
+            if (!signal?.aborted) setError(errorMessage(cause));
+            if (manual) throw cause;
+            return false;
+        } finally {
+            if (!signal?.aborted) setLoading(false);
+        }
+    }, []);
+    useEffect(() => {
+        const controller = new AbortController();
+        void load(controller.signal);
+        return () => controller.abort();
+    }, [load]);
+    const save = async (event: FormEvent) => {
+        event.preventDefault();
+        if (demoMode) return;
+        setBusy(true);
+        setError("");
+        setNotice("");
+        try {
+            const preferences = await api.saveUploadPreferences(value);
+            setSaved(preferences);
+            setValue(preferences.uploads_per_bot);
+            setNotice("Upload settings saved.");
+        } catch (cause) {
+            setError(errorMessage(cause));
+        } finally {
+            setBusy(false);
+        }
+    };
+    return (
+        <Paper
+            component="section"
+            className="settings-section preference-section"
+            aria-labelledby="upload-settings-heading"
+        >
+            <h2 id="upload-settings-heading" className="sr-only">
+                Parallel uploads
+            </h2>
+            <div className="preference-controls">
+                {loading ? (
+                    <Spinner />
+                ) : saved ? (
+                    <form onSubmit={(event) => void save(event)}>
+                        <div className="upload-limit-setting">
+                            <div>
+                                <label
+                                    id="upload-limit-label"
+                                    htmlFor="uploads-per-bot"
+                                >
+                                    Simultaneous Uploads per Bot
+                                </label>
+                                <p id="upload-limit-help">
+                                    Start with 1; add bots before increasing.
+                                </p>
+                            </div>
+                            <div className="upload-limit-stepper">
+                                <Button
+                                    type="button"
+                                    className="icon-button"
+                                    aria-label="Fewer Uploads per Bot"
+                                    disabled={
+                                        demoMode ||
+                                        busy ||
+                                        !Number.isInteger(value) ||
+                                        value <= 1
+                                    }
+                                    onClick={() => {
+                                        setValue(value - 1);
+                                        setNotice("");
+                                    }}
+                                >
+                                    <Minus size={16} />
+                                </Button>
+                                <input
+                                    id="uploads-per-bot"
+                                    type="number"
+                                    min="1"
+                                    max="4"
+                                    step="1"
+                                    required
+                                    aria-describedby="upload-limit-help"
+                                    value={value}
+                                    disabled={demoMode || busy}
+                                    onChange={(event) => {
+                                        setValue(event.target.valueAsNumber);
+                                        setNotice("");
+                                    }}
+                                />
+                                <Button
+                                    type="button"
+                                    className="icon-button"
+                                    aria-label="More Uploads per Bot"
+                                    disabled={
+                                        demoMode ||
+                                        busy ||
+                                        !Number.isInteger(value) ||
+                                        value >= 4
+                                    }
+                                    onClick={() => {
+                                        setValue(value + 1);
+                                        setNotice("");
+                                    }}
+                                >
+                                    <Plus size={16} />
+                                </Button>
+                            </div>
+                        </div>
+                        <p className="settings-help">
+                            {saved.connected_bots} connected{" "}
+                            {saved.connected_bots === 1 ? "bot" : "bots"} ·{" "}
+                            {saved.connected_bots *
+                                (Number.isInteger(value)
+                                    ? value
+                                    : saved.uploads_per_bot)}{" "}
+                            upload{" "}
+                            {saved.connected_bots *
+                                (Number.isInteger(value)
+                                    ? value
+                                    : saved.uploads_per_bot) ===
+                            1
+                                ? "slot"
+                                : "slots"}
+                            .
+                        </p>
+                        <div className="upload-settings-actions">
+                            <Button
+                                className="primary-button"
+                                type="submit"
+                                disabled={
+                                    demoMode ||
+                                    busy ||
+                                    !Number.isInteger(value) ||
+                                    value < 1 ||
+                                    value > 4 ||
+                                    value === saved.uploads_per_bot
+                                }
+                            >
+                                {busy ? "Saving…" : "Save Changes"}
+                            </Button>
+                            <Button
+                                type="button"
+                                className="text-button"
+                                variant="subtle"
+                                disabled={demoMode || busy}
+                                onClick={() => {
+                                    setValue(1);
+                                    setError("");
+                                    setNotice(
+                                        "Default loaded: 1 upload per bot. Save Changes to apply.",
+                                    );
+                                }}
+                            >
+                                Restore upload defaults
+                            </Button>
+                            <Button
+                                type="button"
+                                className="text-button"
+                                variant="subtle"
+                                disabled={
+                                    demoMode ||
+                                    busy ||
+                                    value === saved.uploads_per_bot
+                                }
+                                hidden={value === saved.uploads_per_bot}
+                                onClick={() => {
+                                    setValue(saved.uploads_per_bot);
+                                    setError("");
+                                    setNotice("");
+                                }}
+                            >
+                                Discard upload changes
+                            </Button>
+                            <span role="status" className="settings-help">
+                                {notice}
+                            </span>
+                        </div>
+                    </form>
+                ) : (
+                    <Button
+                        className="secondary-button"
+                        disabled={refreshAction.refreshing || loading}
+                        onClick={() =>
+                            void refreshAction.run(
+                                (signal) => load(signal, true),
+                                "Upload settings refreshed.",
+                            )
+                        }
+                    >
+                        {refreshAction.refreshing && <Spinner />}
+                        {refreshAction.refreshing ? "Refreshing…" : "Try Again"}
+                    </Button>
+                )}
+                <ErrorNotice message={error} />
+            </div>
+        </Paper>
+    );
+}
diff --git a/website/src/features/settings/settingsManagement.test.ts b/website/src/features/settings/settingsManagement.test.ts
new file mode 100644
index 00000000..7451cb24
--- /dev/null
+++ b/website/src/features/settings/settingsManagement.test.ts
@@ -0,0 +1,298 @@
+import { describe, expect, it } from "vitest";
+import {
+    clientConnectionLabel,
+    clientDisplayName,
+    createConnectionDraft,
+    isCredentialRepair,
+    MAX_STORAGE_CLIENTS,
+    prepareConnectionUpdate,
+} from "./settingsManagement";
+import type { ManagementSettings } from "../../shared/types";
+
+const snapshot = (): ManagementSettings => ({
+    revision: 3,
+    applied_revision: 3,
+    restart_required: false,
+    application_mode: "restart",
+    admission_paused: false,
+    api_id: 12345,
+    api_hash_configured: true,
+    storage_channel: -1001234567890,
+    clients: [
+        {
+            id: "configured-bot",
+            label: "Storage Bot",
+            kind: "bot",
+            enabled: true,
+            configured: true,
+            connected: true,
+            healthy: true,
+            premium: null,
+            active_leases: 2,
+            error: null,
+        },
+    ],
+    active_clients: [],
+    stats: {
+        files: 1,
+        folders: 2,
+        total_bytes: 3,
+        trashed_files: 0,
+        trashed_bytes: 0,
+        active_jobs: 1,
+        queued_jobs: 2,
+        failed_jobs: 0,
+        staging_budget_bytes: 1000,
+        staging_reserved_bytes: 10,
+        free_disk_bytes: 2000,
+    },
+});
+
+it("permits credential repair without treating account removal as repair", () => {
+    const settings = snapshot();
+    const draft = createConnectionDraft(settings);
+    expect(isCredentialRepair(draft, settings)).toBe(false);
+    draft.clients[0].credential = "123456:replacement";
+    expect(isCredentialRepair(draft, settings)).toBe(true);
+    draft.clients[0].removed = true;
+    expect(isCredentialRepair(draft, settings)).toBe(false);
+    draft.clients[0].removed = false;
+    draft.clients[0].enabled = false;
+    expect(isCredentialRepair(draft, settings)).toBe(false);
+    draft.clients[0].enabled = true;
+    draft.apiId = "99999";
+    expect(isCredentialRepair(draft, settings)).toBe(false);
+});
+
+describe("write-only connection settings", () => {
+    it("never prepopulates a credential from health/configuration", () => {
+        const draft = createConnectionDraft(snapshot());
+        expect(draft.apiHash).toBe("");
+        expect(draft.clients[0].credential).toBe("");
+        expect(draft.clients[0]).not.toHaveProperty("connected");
+        expect(draft.clients[0]).not.toHaveProperty("active_leases");
+    });
+    it("preserves existing secrets by omission and sends only writable fields", () => {
+        const update = prepareConnectionUpdate(
+            createConnectionDraft(snapshot()),
+        );
+        expect(update).toEqual({
+            expected_revision: 3,
+            api_id: 12345,
+            clients: [
+                {
+                    id: "configured-bot",
+                    label: "Storage Bot",
+                    kind: "bot",
+                    enabled: true,
+                },
+            ],
+        });
+        expect(update).not.toHaveProperty("api_hash");
+        expect(update).not.toHaveProperty("storage_channel");
+        expect(update.clients?.[0]).not.toHaveProperty("credential");
+    });
+    it("uses a write-only replacement without leaking it into validation errors", () => {
+        const draft = createConnectionDraft(snapshot());
+        draft.apiHash = " a".trim().repeat(32);
+        draft.clients[0].credential = "12345:" + "x".repeat(25);
+        const update = prepareConnectionUpdate(draft);
+        expect(update.api_hash).toBe("a".repeat(32));
+        expect(update.clients?.[0].credential).toBe("12345:" + "x".repeat(25));
+        draft.clients[0].credential = "very-private-invalid-value";
+        expect(() => prepareConnectionUpdate(draft)).toThrow(
+            "valid Telegram bot token",
+        );
+        try {
+            prepareConnectionUpdate(draft);
+        } catch (error) {
+            expect(String(error)).not.toContain("very-private-invalid-value");
+        }
+    });
+    it.each(["0", "-1", "1.5", "2147483648", "1e5", "NaN"])(
+        "rejects invalid API ID %s",
+        (value) => {
+            const draft = createConnectionDraft(snapshot());
+            draft.apiId = value;
+            expect(() => prepareConnectionUpdate(draft)).toThrow("API ID");
+        },
+    );
+    it("requires a credential for new clients and does not send their local key as an ID", () => {
+        const draft = createConnectionDraft(snapshot());
+        draft.clients.push({
+            key: "browser-only-key",
+            label: "My Premium account",
+            kind: "user",
+            enabled: true,
+            credential: "",
+            removed: false,
+        });
+        expect(() => prepareConnectionUpdate(draft)).toThrow(
+            "Telethon Session",
+        );
+        draft.clients[1].credential = "a-session-to-be-validated-by-the-server";
+        const client = prepareConnectionUpdate(draft).clients?.[1];
+        expect(client).not.toHaveProperty("id");
+        expect(client).not.toHaveProperty("key");
+    });
+    it("omits removed rows but allows undo before saving", () => {
+        const draft = createConnectionDraft(snapshot());
+        draft.clients.push({
+            ...draft.clients[0],
+            key: "second",
+            id: "second",
+            label: "Second bot",
+        });
+        draft.clients[1].removed = true;
+        expect(prepareConnectionUpdate(draft).clients).toHaveLength(1);
+        draft.clients[1].removed = false;
+        expect(prepareConnectionUpdate(draft).clients).toHaveLength(2);
+    });
+    it("requires an enabled bot even if Premium accounts exist", () => {
+        const draft = createConnectionDraft(snapshot());
+        draft.clients[0].enabled = false;
+        draft.clients.push({
+            key: "user",
+            id: "user",
+            label: "Premium",
+            kind: "user",
+            enabled: true,
+            credential: "",
+            removed: false,
+        });
+        expect(() => prepareConnectionUpdate(draft)).toThrow(
+            "enabled storage bot",
+        );
+        draft.clients[0].removed = true;
+        expect(() => prepareConnectionUpdate(draft)).toThrow(
+            "enabled storage bot",
+        );
+    });
+    it("bounds the saved client count and validates hidden disabled-new credentials too", () => {
+        const draft = createConnectionDraft(snapshot());
+        draft.clients = Array.from(
+            { length: MAX_STORAGE_CLIENTS + 1 },
+            (_, i) => ({
+                ...draft.clients[0],
+                key: String(i),
+                id: String(i),
+            }),
+        );
+        expect(() => prepareConnectionUpdate(draft)).toThrow(
+            "50 storage clients",
+        );
+        draft.clients = draft.clients.slice(0, MAX_STORAGE_CLIENTS);
+        expect(prepareConnectionUpdate(draft).clients).toHaveLength(
+            MAX_STORAGE_CLIENTS,
+        );
+        draft.clients = draft.clients.slice(0, MAX_STORAGE_CLIENTS - 1);
+        draft.clients.push({
+            key: "new",
+            kind: "bot",
+            label: "Disabled bot",
+            enabled: false,
+            credential: "",
+            removed: false,
+        });
+        expect(() => prepareConnectionUpdate(draft)).toThrow("bot token");
+    });
+    it("validates names and API Hashes without echoing values", () => {
+        const draft = createConnectionDraft(snapshot());
+        draft.apiHash = "secret-invalid-hash";
+        expect(() => prepareConnectionUpdate(draft)).toThrow("32 hexadecimal");
+        draft.apiHash = "";
+        draft.clients[0].label = "line\nbreak";
+        expect(() => prepareConnectionUpdate(draft)).toThrow(
+            "control characters",
+        );
+    });
+    it("distinguishes disabled saved intent from connected runtime health", () => {
+        expect(
+            clientConnectionLabel({
+                enabled: false,
+                connected: true,
+                healthy: true,
+            }),
+        ).toBe("Disabled in saved configuration");
+        expect(
+            clientConnectionLabel({
+                enabled: true,
+                connected: false,
+                healthy: true,
+            }),
+        ).toBe("Disconnected");
+        expect(
+            clientConnectionLabel({
+                enabled: true,
+                connected: null,
+                healthy: false,
+            }),
+        ).toBe("Not connected");
+        expect(
+            clientConnectionLabel({
+                enabled: true,
+                connected: true,
+                healthy: false,
+            }),
+        ).toBe("Connected · needs attention");
+        expect(
+            clientConnectionLabel({
+                enabled: true,
+                connected: true,
+                healthy: true,
+            }),
+        ).toBe("Connected");
+    });
+});
+
+describe("Telegram connection names", () => {
+    it("prefers the Telegram name without changing the saved local label", () => {
+        const client = {
+            ...snapshot().clients[0],
+            display_name: "Drive · संग्रह",
+            username: "drive_bot",
+        };
+        expect(clientDisplayName(client)).toBe("Drive · संग्रह");
+        const value = snapshot();
+        value.clients[0] = client;
+        expect(
+            prepareConnectionUpdate(createConnectionDraft(value)).clients?.[0]
+                .label,
+        ).toBe("Storage Bot");
+    });
+    it("uses the username then local label when a Telegram name is unavailable", () => {
+        expect(
+            clientDisplayName({
+                label: "Backup",
+                display_name: null,
+                username: "drive_bot",
+            }),
+        ).toBe("@drive_bot");
+        expect(clientDisplayName({ label: "Backup" })).toBe("Backup");
+    });
+});
+
+describe("manual connection verification status", () => {
+    it("shows verification failures even while an existing socket is connected", () => {
+        const client = { enabled: true, connected: true, healthy: true };
+        expect(
+            clientConnectionLabel({ ...client, connection_check: "checking" }),
+        ).toBe("Checking connection…");
+        expect(
+            clientConnectionLabel({ ...client, connection_check: "failed" }),
+        ).toBe("Check failed");
+        expect(
+            clientConnectionLabel({ ...client, connection_check: "waiting" }),
+        ).toBe("Waiting to retry…");
+        expect(
+            clientConnectionLabel({ ...client, connection_check: "passed" }),
+        ).toBe("Connected");
+        expect(
+            clientConnectionLabel({
+                ...client,
+                connected: false,
+                connection_check: "passed",
+            }),
+        ).toBe("Verified · runtime disconnected");
+    });
+});
diff --git a/website/src/features/settings/settingsManagement.ts b/website/src/features/settings/settingsManagement.ts
new file mode 100644
index 00000000..d621e57b
--- /dev/null
+++ b/website/src/features/settings/settingsManagement.ts
@@ -0,0 +1,167 @@
+import type {
+    ManagedClient,
+    ManagementSettings,
+    ManagementUpdate,
+} from "../../shared/types";
+
+export const MAX_STORAGE_CLIENTS = 50;
+
+export interface ClientDraft {
+    key: string;
+    id?: string;
+    label: string;
+    kind: "bot" | "user";
+    enabled: boolean;
+    credential: string;
+    removed: boolean;
+}
+export interface ConnectionDraft {
+    revision: number;
+    apiId: string;
+    apiHash: string;
+    clients: ClientDraft[];
+}
+export function isCredentialRepair(
+    draft: ConnectionDraft | null,
+    settings: ManagementSettings | null,
+): boolean {
+    if (
+        !draft ||
+        !settings ||
+        draft.apiId.trim() !== String(settings.api_id) ||
+        draft.apiHash.trim() ||
+        draft.clients.length !== settings.clients.length
+    )
+        return false;
+    return (
+        draft.clients.some((row) => row.credential.trim()) &&
+        draft.clients.every((row, index) => {
+            const prior = settings.clients[index];
+            return (
+                row.id === prior.id &&
+                !row.removed &&
+                row.kind === prior.kind &&
+                row.enabled === prior.enabled
+            );
+        })
+    );
+}
+
+export function createConnectionDraft(
+    settings: ManagementSettings,
+): ConnectionDraft {
+    return {
+        revision: settings.revision,
+        apiId: String(settings.api_id),
+        apiHash: "",
+        clients: settings.clients.map((client) => ({
+            key: client.id,
+            id: client.id,
+            label: client.label,
+            kind: client.kind,
+            enabled: client.enabled,
+            credential: "",
+            removed: false,
+        })),
+    };
+}
+export function prepareConnectionUpdate(
+    draft: ConnectionDraft,
+): ManagementUpdate {
+    if (
+        !/^[1-9]\d*$/.test(draft.apiId.trim()) ||
+        !Number.isSafeInteger(Number(draft.apiId.trim())) ||
+        Number(draft.apiId.trim()) > 2147483647
+    ) {
+        throw new Error("Enter a Telegram API ID between 1 and 2147483647.");
+    }
+    const apiHash = draft.apiHash.trim();
+    if (apiHash && !/^[a-fA-F0-9]{32}$/.test(apiHash)) {
+        throw new Error(
+            "The API Hash must contain exactly 32 hexadecimal characters.",
+        );
+    }
+    if (
+        draft.clients.filter((client) => !client.removed).length >
+        MAX_STORAGE_CLIENTS
+    )
+        throw new Error(
+            `You can configure up to ${MAX_STORAGE_CLIENTS} storage clients.`,
+        );
+    const clients = draft.clients
+        .filter((client) => !client.removed)
+        .map((client) => {
+            const label = client.label.trim();
+            if (
+                !label ||
+                label.length > 80 ||
+                /[\u0000-\u001f\u007f-\u009f]/.test(label)
+            )
+                throw new Error(
+                    "Give each client a name of 1–80 characters without control characters.",
+                );
+            const credential = client.credential.trim();
+            if (!client.id && !credential)
+                throw new Error(
+                    `Enter the ${client.kind === "bot" ? "bot token" : "Telethon Session"} for ${label}.`,
+                );
+            if (credential.length > 8192)
+                throw new Error(
+                    `The credential for ${label} is too long. Check the copied value.`,
+                );
+            if (
+                credential &&
+                client.kind === "bot" &&
+                !/^[1-9][0-9]{4,14}:[A-Za-z0-9_-]{20,}$/.test(credential)
+            ) {
+                throw new Error(
+                    `Enter a valid Telegram bot token for ${label}.`,
+                );
+            }
+            return {
+                ...(client.id ? { id: client.id } : {}),
+                label,
+                kind: client.kind,
+                enabled: client.enabled,
+                ...(credential ? { credential } : {}),
+            };
+        });
+    if (!clients.some((client) => client.kind === "bot" && client.enabled))
+        throw new Error("Keep at least one enabled storage bot.");
+    return {
+        expected_revision: draft.revision,
+        api_id: Number(draft.apiId.trim()),
+        ...(apiHash ? { api_hash: apiHash } : {}),
+        clients,
+    };
+}
+export function clientConnectionLabel(client: {
+    enabled: boolean;
+    connected: boolean | null;
+    healthy: boolean;
+    connection_check?: ManagedClient["connection_check"];
+}): string {
+    if (!client.enabled) return "Disabled in saved configuration";
+    if (client.connection_check === "queued") return "Waiting to check";
+    if (client.connection_check === "checking") return "Checking connection…";
+    if (client.connection_check === "waiting") return "Waiting to retry…";
+    if (client.connection_check === "failed") return "Check failed";
+    if (
+        client.connection_check === "passed" &&
+        !(client.connected && client.healthy)
+    )
+        return "Verified · runtime disconnected";
+    if (client.connected === false) return "Disconnected";
+    if (client.connected === true && client.healthy) return "Connected";
+    if (client.connected === true) return "Connected · needs attention";
+    return "Not connected";
+}
+
+export function clientDisplayName(
+    client: Pick<ManagedClient, "label" | "display_name" | "username">,
+): string {
+    return (
+        client.display_name?.trim() ||
+        (client.username ? "@" + client.username : client.label)
+    );
+}
diff --git a/website/src/features/shares/SharesView.css b/website/src/features/shares/SharesView.css
new file mode 100644
index 00000000..42858f6c
--- /dev/null
+++ b/website/src/features/shares/SharesView.css
@@ -0,0 +1,277 @@
+.shares-page {
+    container-type: inline-size;
+}
+.shares-toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 12px;
+    padding-bottom: 14px;
+    border-bottom: 1px solid var(--line-subtle);
+}
+.shares-filters {
+    display: flex;
+    gap: 4px;
+    flex-wrap: wrap;
+}
+.shares-filters button {
+    gap: 8px;
+    padding: 9px 13px;
+    border-radius: 8px;
+    color: var(--muted);
+}
+.shares-filters button[aria-pressed="true"] {
+    background: var(--selected);
+    color: var(--on-action-soft);
+}
+.shares-filters button span {
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+}
+.share-columns {
+    display: none;
+    color: var(--muted);
+    font-size: 12px;
+}
+.shares-rows {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+}
+.share-row {
+    display: grid;
+    grid-template-columns: 24px minmax(0, 1fr);
+    gap: 8px 12px;
+    padding: 12px 0;
+    border-bottom: 1px solid var(--line-subtle);
+    align-items: center;
+}
+.share-row:hover {
+    background: var(--hover);
+}
+.share-row > .file-icon {
+    grid-column: 1;
+    grid-row: 1;
+}
+.share-item {
+    grid-column: 2;
+    grid-row: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+.share-name {
+    padding: 0;
+    text-align: left;
+    background: none;
+    border: 0;
+    font: inherit;
+    font-weight: 550;
+    color: var(--ink);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    cursor: pointer;
+    line-height: 20px;
+    width: fit-content;
+    max-width: 100%;
+}
+.share-name:hover {
+    color: var(--action);
+    text-decoration: underline;
+    text-underline-offset: 3px;
+}
+.share-name:focus-visible,
+.share-expiry time:focus-visible {
+    outline: 2px solid var(--action);
+    outline-offset: 3px;
+    border-radius: 3px;
+}
+.share-location {
+    font-size: 13px;
+    line-height: 18px;
+    color: var(--muted);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.share-dates {
+    grid-column: 2;
+    grid-row: 2;
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    min-width: 0;
+}
+.share-expiry,
+.share-created {
+    font-size: 12px;
+    line-height: 18px;
+    color: var(--muted);
+    min-width: 0;
+    font-variant-numeric: tabular-nums;
+}
+.share-expiry time {
+    position: relative;
+    display: inline-flex;
+    gap: 4px;
+    flex-wrap: wrap;
+    cursor: help;
+}
+.share-expiry-label {
+    font-size: inherit;
+}
+.share-expiry-tooltip,
+.share-copy-explanation {
+    display: none;
+    position: absolute;
+    z-index: 5;
+    padding: 8px 10px;
+    width: max-content;
+    max-width: 230px;
+    border: 1px solid var(--line-subtle);
+    border-radius: 6px;
+    background: var(--surface-raised);
+    color: var(--ink);
+    box-shadow: 0 4px 16px #0003;
+    line-height: 1.5;
+}
+.share-expiry-tooltip {
+    top: calc(100% + 8px);
+    left: 0;
+}
+.share-expiry time:hover .share-expiry-tooltip,
+.share-expiry time:focus .share-expiry-tooltip {
+    display: block;
+}
+.share-row-actions {
+    grid-column: 2;
+    grid-row: 3;
+    display: flex;
+    gap: 4px;
+    align-items: center;
+    min-width: 0;
+}
+.share-copy[aria-disabled="true"] {
+    opacity: 0.55;
+    cursor: help;
+}
+.share-copy[aria-disabled="true"]:hover {
+    background: none;
+}
+.share-copy-control {
+    position: relative;
+    display: inline-flex;
+    flex-shrink: 0;
+}
+.share-copy-control[data-unavailable="true"] {
+    cursor: help;
+}
+.share-copy-control[data-unavailable="true"] .share-copy {
+    pointer-events: none;
+}
+.share-copy-control:focus-visible {
+    outline: 2px solid var(--action);
+    outline-offset: 2px;
+    border-radius: 8px;
+}
+.share-copy-explanation {
+    bottom: 100%;
+    left: 0;
+    width: 230px;
+    max-width: calc(100vw - 48px);
+    white-space: normal;
+}
+.share-copy-control:hover .share-copy-explanation,
+.share-copy-control:focus .share-copy-explanation {
+    display: block;
+}
+.share-row-actions .icon-button {
+    width: 40px;
+    min-width: 40px;
+    height: 40px;
+}
+.file-share-indicator {
+    color: var(--muted);
+    display: inline-flex;
+    align-items: center;
+    flex-shrink: 0;
+}
+.share-created {
+    display: block;
+    overflow-wrap: anywhere;
+}
+.share-dialog-identity {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    margin-block: 4px 16px;
+    color: var(--muted);
+    font-size: 13px;
+    line-height: 20px;
+    overflow-wrap: anywhere;
+}
+.share-dialog-identity strong {
+    color: var(--ink);
+    font-size: 14px;
+}
+@container (min-width: 700px) {
+    .share-copy-explanation {
+        left: auto;
+        right: 0;
+    }
+    .share-columns {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) 210px 172px;
+        gap: 16px;
+        padding: 14px 8px 12px 48px;
+        border-bottom: 1px solid var(--line-subtle);
+    }
+    .share-columns > :last-child {
+        text-align: right;
+    }
+    .share-row {
+        grid-template-columns: 24px minmax(0, 1fr) 210px 172px;
+        column-gap: 16px;
+        padding: var(--list-row-padding, 8px) 8px;
+        min-height: var(--list-row-min-height, 56px);
+    }
+    .share-item {
+        grid-column: 2;
+    }
+    .share-dates {
+        grid-column: 3;
+        grid-row: 1;
+    }
+    .share-row-actions {
+        grid-column: 4;
+        grid-row: 1;
+        justify-content: flex-end;
+    }
+}
+@container (max-width: 699px) {
+    .shares-filters button {
+        min-height: 44px;
+        padding-inline: 10px;
+    }
+    .share-name {
+        min-height: 44px;
+    }
+    .share-row-actions .icon-button {
+        min-width: 44px;
+        min-height: 44px;
+    }
+    .share-row-actions {
+        gap: 8px;
+        flex-wrap: wrap;
+    }
+}
+
+.share-link-label {
+    color: var(--ink);
+    font-weight: 500;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
diff --git a/website/src/features/shares/SharesView.tsx b/website/src/features/shares/SharesView.tsx
new file mode 100644
index 00000000..e000e4bf
--- /dev/null
+++ b/website/src/features/shares/SharesView.tsx
@@ -0,0 +1,829 @@
+import { useEffect, useRef, useState } from "react";
+import {
+    Link,
+    Copy,
+    FolderOpen,
+    RefreshCw,
+    X,
+    Check,
+    Pencil,
+} from "lucide-react";
+import { api, errorMessage, request } from "../../shared/api";
+import { useManualRefresh } from "../../shared/useManualRefresh";
+import {
+    formatDate,
+    formatTimestamp,
+    getTimezone,
+    type Share,
+} from "../../shared/types";
+import { FileIcon, Spinner, ErrorNotice, Modal } from "../../shared/components";
+import "./SharesView.css";
+
+export function shareExpired(share: Share) {
+    return (
+        share.expires_at != null &&
+        new Date(
+            typeof share.expires_at === "number"
+                ? share.expires_at * 1000
+                : share.expires_at,
+        ).getTime() <= Date.now()
+    );
+}
+export function shareCopyIssue(share: Share) {
+    if (!share.id) return "Refresh Shared Links before managing this entry.";
+    if (shareExpired(share)) return "This link has expired.";
+    if (!share.copyable)
+        return "Original link is unavailable; existing copies still work.";
+    return "";
+}
+function createdTime(share: Share) {
+    const date = new Date(share.created_at);
+    return Number.isNaN(date.getTime())
+        ? "—"
+        : new Intl.DateTimeFormat(undefined, {
+              dateStyle: "medium",
+              timeStyle: "medium",
+              timeZone: getTimezone(),
+          }).format(date);
+}
+function expiryDescription(share: Share) {
+    return share.expires_at == null
+        ? "No expiry"
+        : `${shareExpired(share) ? "Expired" : "Expires"} ${formatTimestamp(share.expires_at)}`;
+}
+function shareDescription(share: Share) {
+    return [
+        share.name || "Shared Item",
+        share.label,
+        expiryDescription(share),
+        "Created " + formatTimestamp(share.created_at),
+    ]
+        .filter(Boolean)
+        .join(". ");
+}
+export function shareUrl(auth: string, nodeId: string, folder: boolean) {
+    return (
+        window.location.origin +
+        (folder ? "/" : "/file") +
+        "?" +
+        new URLSearchParams({
+            path: folder ? "/share_" + nodeId : "/" + nodeId,
+            auth,
+        })
+    );
+}
+export default function SharesView({
+    refresh,
+    onError,
+    onChange,
+    onLocate,
+    onNotice,
+    query = "",
+}: {
+    refresh: number;
+    onError: (message: string) => void;
+    onChange: () => void;
+    onLocate: (share: Share) => void;
+    onNotice?: (message: string, error?: boolean) => void;
+    query?: string;
+}) {
+    const [shares, setShares] = useState<Share[]>([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState("");
+    const [filter, setFilter] = useState<"active" | "expired" | "all">(
+        "active",
+    );
+    const generation = useRef(0);
+    const manualPending = useRef(false);
+    const { refreshing, run } = useManualRefresh(onNotice);
+    const [busy, setBusy] = useState<{
+        id: string;
+        action: "copy" | "revoke";
+    } | null>(null);
+    const [copied, setCopied] = useState("");
+    const [confirm, setConfirm] = useState<Share | null>(null);
+    const [revokeError, setRevokeError] = useState("");
+    const [manualLink, setManualLink] = useState("");
+    const [editing, setEditing] = useState<Share | null>(null);
+    // Expiry changes while this page is open, without a database refresh.
+    const [, tick] = useState(0);
+    useEffect(() => {
+        const timer = setInterval(() => tick((n) => n + 1), 30000);
+        return () => clearInterval(timer);
+    }, []);
+    useEffect(() => {
+        if (manualPending.current) return;
+        const controller = new AbortController();
+        const requestId = ++generation.current;
+        setLoading(true);
+        void request<{ shares: Share[] }>("/api/v1/shares", undefined, {
+            signal: controller.signal,
+        })
+            .then((result) => {
+                if (
+                    !controller.signal.aborted &&
+                    requestId === generation.current
+                ) {
+                    setShares(result.shares);
+                    setError("");
+                }
+            })
+            .catch((cause) => {
+                if (
+                    !controller.signal.aborted &&
+                    requestId === generation.current
+                )
+                    setError(errorMessage(cause));
+            })
+            .finally(() => {
+                if (
+                    !controller.signal.aborted &&
+                    requestId === generation.current
+                )
+                    setLoading(false);
+            });
+        return () => controller.abort();
+    }, [refresh]);
+    const refreshShares = () =>
+        run(async (signal) => {
+            manualPending.current = true;
+            const requestId = ++generation.current;
+            try {
+                const result = await request<{ shares: Share[] }>(
+                    "/api/v1/shares",
+                    undefined,
+                    {
+                        signal,
+                    },
+                );
+                if (signal.aborted || requestId !== generation.current)
+                    return false;
+                setShares(result.shares);
+                setError("");
+                setLoading(false);
+                return true;
+            } catch (cause) {
+                if (!signal.aborted && requestId === generation.current)
+                    setError(errorMessage(cause));
+                throw cause;
+            } finally {
+                manualPending.current = false;
+            }
+        }, "Shared links refreshed.");
+    useEffect(() => {
+        if (!copied) return;
+        const timer = setTimeout(() => setCopied(""), 2500);
+        return () => clearTimeout(timer);
+    }, [copied]);
+    const matching = shares.filter((share) =>
+        ((share.name || "Shared Item") + " " + (share.label || ""))
+            .normalize("NFC")
+            .toLocaleLowerCase()
+            .includes(query.normalize("NFC").toLocaleLowerCase()),
+    );
+    const active = matching.filter((share) => !shareExpired(share));
+    const expired = matching.filter(shareExpired);
+    const visible = (
+        filter === "active" ? active : filter === "expired" ? expired : matching
+    )
+        .slice()
+        .sort(
+            (a, b) =>
+                Number(shareExpired(a)) - Number(shareExpired(b)) ||
+                Date.parse(b.created_at) - Date.parse(a.created_at),
+        );
+    const revoke = async (share: Share) => {
+        if (busy) return;
+        if (!share.id) {
+            onError("Refresh Shared Links before managing this entry.");
+            return;
+        }
+        setBusy({ id: share.id, action: "revoke" });
+        setRevokeError("");
+        try {
+            await api.revoke(share.path, share.id);
+            setConfirm(null);
+            onChange();
+        } catch (cause) {
+            if (confirm) setRevokeError(errorMessage(cause));
+            else onError(errorMessage(cause));
+        } finally {
+            setBusy(null);
+        }
+    };
+    const copy = async (share: Share) => {
+        if (busy) return;
+        const issue = shareCopyIssue(share);
+        if (issue) return;
+        setBusy({ id: share.id!, action: "copy" });
+        setCopied("");
+        try {
+            const result = await api.shareLink(share.path, share.id);
+            const url = shareUrl(
+                result.auth,
+                result.node_id,
+                result.type === "folder",
+            );
+            try {
+                await navigator.clipboard.writeText(url);
+                setCopied(share.id!);
+            } catch {
+                setManualLink(url);
+            }
+        } catch (cause) {
+            onError(errorMessage(cause));
+        } finally {
+            setBusy(null);
+        }
+    };
+    const locate = async (share: Share) => {
+        try {
+            if (!share.id)
+                throw new Error(
+                    "Refresh Shared Links before managing this entry.",
+                );
+            const latest = (await api.shares()).shares.find(
+                (row) => row.id === share.id,
+            );
+            if (!latest)
+                throw new Error(
+                    "This shared item is no longer available. Refresh the list.",
+                );
+            onLocate(latest);
+        } catch (cause) {
+            onError(errorMessage(cause));
+        }
+    };
+    const copiedShare = shares.find((share) => share.id === copied);
+    return (
+        <div className="shares-page" aria-busy={loading || refreshing}>
+            <div className="shares-toolbar">
+                <div
+                    className="shares-filters"
+                    role="group"
+                    aria-label="Filter Shared Links"
+                >
+                    {(["active", "expired", "all"] as const).map((value) => (
+                        <button
+                            key={value}
+                            className="text-button"
+                            aria-pressed={filter === value}
+                            onClick={() => setFilter(value)}
+                        >
+                            {
+                                {
+                                    active: "Active",
+                                    expired: "Expired",
+                                    all: "All",
+                                }[value]
+                            }
+                            <span>
+                                {value === "all"
+                                    ? matching.length
+                                    : value === "active"
+                                      ? active.length
+                                      : expired.length}
+                            </span>
+                        </button>
+                    ))}
+                </div>
+                <button
+                    className="icon-button"
+                    aria-label="Refresh Shared Links"
+                    title="Refresh"
+                    disabled={loading || refreshing}
+                    onClick={() => void refreshShares()}
+                >
+                    {refreshing ? <Spinner /> : <RefreshCw size={18} />}
+                </button>
+            </div>
+            {error && (
+                <div className="page-load-error">
+                    <ErrorNotice message={error} />
+                    <button
+                        className="secondary-button"
+                        disabled={refreshing}
+                        onClick={() => void refreshShares()}
+                    >
+                        {refreshing && <Spinner />} Try Again
+                    </button>
+                </div>
+            )}
+            {loading && !shares.length ? (
+                <div className="loading-state" role="status">
+                    <Spinner /> Loading shared links…
+                </div>
+            ) : error && !shares.length ? null : !visible.length ? (
+                <div className="empty-state">
+                    <Link size={36} />
+                    <h2>
+                        {query
+                            ? "No Matching Shared Links"
+                            : filter === "expired"
+                              ? "No Expired Links"
+                              : filter === "all"
+                                ? "No Shared Links"
+                                : "No Active Shared Links"}
+                    </h2>
+                    <p>
+                        {query
+                            ? "Try another name or clear the search."
+                            : filter === "expired"
+                              ? "Links that reach their expiry date will appear here."
+                              : "Use an item’s Share Link action in My Files to share it."}
+                    </p>
+                </div>
+            ) : (
+                <>
+                    <div className="share-columns" aria-hidden="true">
+                        <span>Shared item</span>
+                        <span>Link dates</span>
+                        <span>Actions</span>
+                    </div>
+                    <ul className="shares-rows" aria-label="Shared Links">
+                        {visible.map((share) => {
+                            const ended = shareExpired(share);
+                            const name = share.name || "Shared Item";
+                            const copyIssue = shareCopyIssue(share);
+                            const copying =
+                                busy?.id === share.id &&
+                                busy?.action === "copy";
+                            const revoking =
+                                busy?.id === share.id &&
+                                busy?.action === "revoke";
+                            const wasCopied = !!share.id && copied === share.id;
+                            const detailsId = share.id
+                                ? `share-details-${share.id}`
+                                : undefined;
+                            const description = shareDescription(share);
+                            const copyTitle = copying
+                                ? "Copying link"
+                                : wasCopied
+                                  ? "Link copied"
+                                  : "Copy link";
+                            const expiryDate = new Date(
+                                typeof share.expires_at === "number"
+                                    ? share.expires_at * 1000
+                                    : (share.expires_at ?? ""),
+                            );
+                            return (
+                                <li
+                                    key={
+                                        share.id ||
+                                        `${share.path}:${share.created_at}`
+                                    }
+                                    className="share-row"
+                                    data-share-id={share.id}
+                                    data-status={ended ? "expired" : "active"}
+                                    onDoubleClick={(event) => {
+                                        if (
+                                            !(
+                                                event.target as HTMLElement
+                                            ).closest("button,a")
+                                        )
+                                            void locate(share);
+                                    }}
+                                >
+                                    <FileIcon
+                                        name={name}
+                                        folder={share.type === "folder"}
+                                    />
+                                    <div className="share-item">
+                                        <button
+                                            className="share-name"
+                                            title={name}
+                                            aria-describedby={detailsId}
+                                            onClick={() => void locate(share)}
+                                        >
+                                            {name}
+                                        </button>
+                                        <span
+                                            className="share-location"
+                                            title={[
+                                                share.label,
+                                                share.folder_label ||
+                                                    "My Files",
+                                            ]
+                                                .filter(Boolean)
+                                                .join(" · ")}
+                                        >
+                                            {share.label && (
+                                                <>
+                                                    <span className="share-link-label">
+                                                        {share.label}
+                                                    </span>
+                                                    {" · "}
+                                                </>
+                                            )}
+                                            {share.folder_label || "My Files"}
+                                        </span>
+                                        <span
+                                            className="sr-only"
+                                            id={detailsId}
+                                        >
+                                            {description}
+                                        </span>
+                                    </div>
+                                    <div className="share-dates">
+                                        <div
+                                            className={
+                                                "share-expiry" +
+                                                (ended ? " ended" : "")
+                                            }
+                                        >
+                                            {share.expires_at ? (
+                                                <time
+                                                    dateTime={
+                                                        Number.isFinite(
+                                                            expiryDate.getTime(),
+                                                        )
+                                                            ? expiryDate.toISOString()
+                                                            : undefined
+                                                    }
+                                                    tabIndex={0}
+                                                    aria-label={`${ended ? "Expired" : "Expires"} ${formatTimestamp(share.expires_at)}`}
+                                                >
+                                                    <span className="share-expiry-label">
+                                                        {ended
+                                                            ? "Expired"
+                                                            : "Expires"}
+                                                    </span>
+                                                    {formatDate(
+                                                        share.expires_at,
+                                                    )}
+                                                    <span
+                                                        className="share-expiry-tooltip"
+                                                        role="tooltip"
+                                                    >
+                                                        {formatTimestamp(
+                                                            share.expires_at,
+                                                        )}
+                                                    </span>
+                                                </time>
+                                            ) : (
+                                                "No expiry"
+                                            )}
+                                        </div>
+                                        <time
+                                            className="share-created"
+                                            dateTime={share.created_at}
+                                            title={
+                                                "Created " +
+                                                formatTimestamp(
+                                                    share.created_at,
+                                                )
+                                            }
+                                        >
+                                            Created {createdTime(share)}
+                                        </time>
+                                    </div>
+                                    <div className="share-row-actions">
+                                        <span
+                                            className="share-copy-control"
+                                            data-unavailable={!!copyIssue}
+                                            role={
+                                                copyIssue ? "group" : undefined
+                                            }
+                                            tabIndex={copyIssue ? 0 : undefined}
+                                            aria-label={
+                                                copyIssue
+                                                    ? `Copy link unavailable for ${share.label || name}. ${copyIssue}`
+                                                    : undefined
+                                            }
+                                            aria-describedby={
+                                                copyIssue
+                                                    ? detailsId
+                                                    : undefined
+                                            }
+                                            onClick={
+                                                copyIssue
+                                                    ? (event) =>
+                                                          event.currentTarget.focus()
+                                                    : undefined
+                                            }
+                                            onKeyDown={(event) => {
+                                                if (event.key === "Escape")
+                                                    event.currentTarget.blur();
+                                            }}
+                                        >
+                                            <button
+                                                className="icon-button share-copy"
+                                                disabled={!!busy || !!copyIssue}
+                                                aria-disabled={!!copyIssue}
+                                                aria-busy={copying}
+                                                aria-label={`${copyTitle} for ${share.label || name}${copyIssue ? ". " + copyIssue : ""}`}
+                                                aria-describedby={detailsId}
+                                                title={
+                                                    copyIssue
+                                                        ? undefined
+                                                        : copyTitle
+                                                }
+                                                onClick={() => void copy(share)}
+                                            >
+                                                {copying ? (
+                                                    <Spinner />
+                                                ) : wasCopied ? (
+                                                    <Check
+                                                        size={18}
+                                                        aria-hidden="true"
+                                                    />
+                                                ) : (
+                                                    <Copy
+                                                        size={18}
+                                                        aria-hidden="true"
+                                                    />
+                                                )}
+                                            </button>
+                                            {copyIssue && (
+                                                <span
+                                                    className="share-copy-explanation"
+                                                    role="tooltip"
+                                                >
+                                                    {copyIssue}
+                                                </span>
+                                            )}
+                                        </span>
+                                        {share.id && (
+                                            <button
+                                                className="icon-button"
+                                                disabled={!!busy}
+                                                title="Edit link"
+                                                aria-label={
+                                                    "Edit link " +
+                                                    (share.label ||
+                                                        "for " + name)
+                                                }
+                                                aria-describedby={detailsId}
+                                                onClick={() =>
+                                                    setEditing(share)
+                                                }
+                                            >
+                                                <Pencil
+                                                    size={18}
+                                                    aria-hidden="true"
+                                                />
+                                            </button>
+                                        )}
+                                        <button
+                                            className="icon-button share-locate"
+                                            title="Show in folder"
+                                            aria-label={
+                                                "Show " + name + " in folder"
+                                            }
+                                            aria-describedby={detailsId}
+                                            onClick={() => void locate(share)}
+                                        >
+                                            <FolderOpen
+                                                size={18}
+                                                aria-hidden="true"
+                                            />
+                                        </button>
+                                        <button
+                                            className="icon-button"
+                                            disabled={!!busy || !share.id}
+                                            aria-busy={revoking}
+                                            title={
+                                                ended
+                                                    ? "Remove expired link"
+                                                    : "Revoke link"
+                                            }
+                                            aria-label={
+                                                (ended
+                                                    ? "Remove Expired Link for "
+                                                    : "Revoke Link for ") + name
+                                            }
+                                            aria-describedby={detailsId}
+                                            onClick={() => (
+                                                setRevokeError(""),
+                                                setConfirm(share)
+                                            )}
+                                        >
+                                            {revoking ? (
+                                                <Spinner />
+                                            ) : (
+                                                <X
+                                                    size={18}
+                                                    aria-hidden="true"
+                                                />
+                                            )}
+                                        </button>
+                                    </div>
+                                </li>
+                            );
+                        })}
+                    </ul>
+                </>
+            )}
+            <span className="sr-only" role="status">
+                {busy?.action === "copy"
+                    ? "Copying share link"
+                    : copiedShare
+                      ? "Share link copied. " + shareDescription(copiedShare)
+                      : ""}
+            </span>
+            {confirm && (
+                <Modal
+                    title={
+                        shareExpired(confirm)
+                            ? "Remove Expired Link?"
+                            : "Revoke This Link?"
+                    }
+                    onClose={() => {
+                        if (!busy) setConfirm(null);
+                    }}
+                >
+                    <ShareIdentity share={confirm} />
+                    <p>
+                        {shareExpired(confirm)
+                            ? "Remove this expired entry from Shared Links."
+                            : "People with this link will lose access."}{" "}
+                        Other links are unaffected.
+                    </p>
+                    <ErrorNotice message={revokeError} />
+                    <div className="dialog-actions">
+                        <button
+                            className="secondary-button"
+                            disabled={!!busy}
+                            onClick={() => setConfirm(null)}
+                        >
+                            Cancel
+                        </button>
+                        <button
+                            className="danger-button"
+                            disabled={!!busy}
+                            onClick={() => void revoke(confirm)}
+                        >
+                            {busy ? (
+                                <Spinner />
+                            ) : (
+                                <X size={16} aria-hidden="true" />
+                            )}
+                            {shareExpired(confirm)
+                                ? "Remove Entry"
+                                : "Revoke Link"}
+                        </button>
+                    </div>
+                </Modal>
+            )}
+            {editing && (
+                <EditShare
+                    share={editing}
+                    onClose={() => setEditing(null)}
+                    onSaved={() => {
+                        setEditing(null);
+                        onChange();
+                    }}
+                />
+            )}
+            {manualLink && (
+                <Modal
+                    title="Copy Share Link"
+                    onClose={() => setManualLink("")}
+                >
+                    <p>Select and copy the link below.</p>
+                    <label htmlFor="existing-share-url">Share Link</label>
+                    <input
+                        id="existing-share-url"
+                        readOnly
+                        value={manualLink}
+                        onFocus={(event) => event.target.select()}
+                    />
+                    <div className="dialog-actions">
+                        <button
+                            className="primary-button"
+                            onClick={() => setManualLink("")}
+                        >
+                            Done
+                        </button>
+                    </div>
+                </Modal>
+            )}
+        </div>
+    );
+}
+
+function ShareIdentity({ share }: { share: Share }) {
+    return (
+        <div className="share-dialog-identity">
+            <strong>{share.name || "Shared Item"}</strong>
+            {share.label && <span>{share.label}</span>}
+            <span>{expiryDescription(share)}</span>
+            <span>Created {formatTimestamp(share.created_at)}</span>
+        </div>
+    );
+}
+
+function EditShare({
+    share,
+    onClose,
+    onSaved,
+}: {
+    share: Share;
+    onClose: () => void;
+    onSaved: () => void;
+}) {
+    const [label, setLabel] = useState(share.label || "");
+    const date = share.expires_at
+        ? new Date(
+              typeof share.expires_at === "number"
+                  ? share.expires_at * 1000
+                  : share.expires_at,
+          )
+        : null;
+    const localDate = date
+        ? new Date(date.getTime() - date.getTimezoneOffset() * 60000)
+              .toISOString()
+              .slice(0, 16)
+        : "";
+    const [expiry, setExpiry] = useState(localDate);
+    const [never, setNever] = useState(!share.expires_at);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    const save = async () => {
+        if (busy) return;
+        setBusy(true);
+        setError("");
+        try {
+            const changes: {
+                share_id: string;
+                label?: string;
+                expires_at?: string | null;
+            } = { share_id: share.id! };
+            if (label !== (share.label || "")) changes.label = label;
+            if (never !== !share.expires_at || (!never && expiry !== localDate))
+                changes.expires_at = never
+                    ? null
+                    : new Date(expiry).toISOString();
+            await request("/api/v1/shares", changes, { method: "PATCH" });
+            onSaved();
+        } catch (cause) {
+            setError(errorMessage(cause));
+        } finally {
+            setBusy(false);
+        }
+    };
+    return (
+        <Modal
+            title="Edit share link"
+            onClose={() => {
+                if (!busy) onClose();
+            }}
+        >
+            <form
+                onSubmit={(event) => {
+                    event.preventDefault();
+                    void save();
+                }}
+            >
+                <ShareIdentity share={share} />
+                <label htmlFor="edit-share-label">Link label</label>
+                <input
+                    id="edit-share-label"
+                    maxLength={80}
+                    value={label}
+                    onChange={(event) => setLabel(event.target.value)}
+                />
+                <label className="checkbox-label">
+                    <input
+                        type="checkbox"
+                        checked={never}
+                        onChange={(event) => setNever(event.target.checked)}
+                    />
+                    No expiry
+                </label>
+                {!never && (
+                    <>
+                        <label htmlFor="edit-share-expiry">
+                            Expiry date and time
+                        </label>
+                        <input
+                            id="edit-share-expiry"
+                            type="datetime-local"
+                            required
+                            value={expiry}
+                            onChange={(event) => setExpiry(event.target.value)}
+                        />
+                    </>
+                )}
+                <p className="muted">
+                    Changes apply only to this link. Anyone with the link can
+                    use it.
+                </p>
+                <ErrorNotice message={error} />
+                <div className="dialog-actions">
+                    <button
+                        className="secondary-button"
+                        type="button"
+                        disabled={busy}
+                        onClick={onClose}
+                    >
+                        Cancel
+                    </button>
+                    <button className="primary-button" disabled={busy}>
+                        {busy && <Spinner />}Save changes
+                    </button>
+                </div>
+            </form>
+        </Modal>
+    );
+}
diff --git a/website/src/features/shares/shares.test.ts b/website/src/features/shares/shares.test.ts
new file mode 100644
index 00000000..b08a95d4
--- /dev/null
+++ b/website/src/features/shares/shares.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { shareExpired } from "./SharesView";
+
+describe("shared link expiry", () => {
+    const base = { path: "/file", created_at: "2026-01-01T00:00:00Z" };
+
+    it("treats numeric expiry values as Unix seconds, like date formatting", () => {
+        expect(
+            shareExpired({ ...base, expires_at: Date.now() / 1000 + 86400 }),
+        ).toBe(false);
+        expect(
+            shareExpired({ ...base, expires_at: Date.now() / 1000 - 86400 }),
+        ).toBe(true);
+    });
+
+    it("preserves ISO expiry dates and links without an expiry", () => {
+        expect(
+            shareExpired({
+                ...base,
+                expires_at: new Date(Date.now() + 86400000).toISOString(),
+            }),
+        ).toBe(false);
+        expect(
+            shareExpired({ ...base, expires_at: "2020-01-01T00:00:00Z" }),
+        ).toBe(true);
+        expect(shareExpired({ ...base, expires_at: null })).toBe(false);
+    });
+});
diff --git a/website/src/features/transfers/DeletionNotice.css b/website/src/features/transfers/DeletionNotice.css
new file mode 100644
index 00000000..ac65aca1
--- /dev/null
+++ b/website/src/features/transfers/DeletionNotice.css
@@ -0,0 +1,50 @@
+.deletion-notice {
+    margin: 0 0 20px;
+    padding: 12px 16px;
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    color: var(--ink);
+    background: var(--surface);
+}
+.deletion-summary {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+}
+.deletion-summary > span {
+    flex: 1;
+    min-width: 0;
+    overflow-wrap: anywhere;
+}
+.deletion-summary > svg {
+    flex-shrink: 0;
+}
+.deletion-errors {
+    margin-top: 10px;
+}
+.deletion-progress-detail {
+    margin: 10px 0 0;
+}
+.deletion-errors summary {
+    cursor: pointer;
+    text-underline-offset: 3px;
+}
+.deletion-errors p {
+    max-width: 70ch;
+    margin: 12px 0;
+}
+.deletion-errors ul {
+    max-height: 180px;
+    overflow: auto;
+    overflow-wrap: anywhere;
+    padding-left: 22px;
+}
+.deletion-errors li {
+    margin: 8px 0;
+}
+@media (max-width: 720px) {
+    .deletion-errors summary {
+        min-height: 44px;
+        padding-block: 10px;
+    }
+}
diff --git a/website/src/features/transfers/DeletionNotice.tsx b/website/src/features/transfers/DeletionNotice.tsx
new file mode 100644
index 00000000..8093079f
--- /dev/null
+++ b/website/src/features/transfers/DeletionNotice.tsx
@@ -0,0 +1,98 @@
+import { useState } from "react";
+import { RefreshCw, Trash2 } from "lucide-react";
+import { Spinner } from "../../shared/components";
+import { transfers } from "./transfers";
+import { errorMessage } from "../../shared/api";
+import type { Job } from "../../shared/types";
+import "./DeletionNotice.css";
+
+const failedStates = new Set(["error", "failed", "interrupted"]);
+const terminalStates = new Set(["completed", "cancelled", ...failedStates]);
+
+/** Deletion is one operation notice; per-file details are useful only on failure. */
+export default function DeletionNotice({
+    jobs,
+    completed,
+    progressError,
+}: {
+    jobs: Job[];
+    completed: number;
+    progressError: string;
+}) {
+    const active = jobs.filter((job) => !terminalStates.has(job.status));
+    const failed = jobs.filter((job) => failedStates.has(job.status));
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState("");
+    if (!active.length && !failed.length) return null;
+    return (
+        <section className="deletion-notice" aria-label="File Deletion">
+            <div className="deletion-summary" role="status" aria-live="polite">
+                {active.length ? <Spinner /> : <Trash2 size={18} />}
+                <span>
+                    {active.length
+                        ? "Deleting " +
+                          active.length +
+                          (active.length === 1 ? " item…" : " items…")
+                        : failed.length +
+                          (failed.length === 1
+                              ? " item could not be deleted."
+                              : " items could not be deleted.")}
+                </span>
+            </div>
+            {active.length > 0 && (
+                <p className="deletion-progress-detail">
+                    {completed > 0 ? completed + " completed. " : ""}
+                    {active.some((job) => job.phase === "checking_backup")
+                        ? "Checking backup protection before deletion. "
+                        : active.some(
+                                (job) => job.phase === "waiting_for_uploads",
+                            )
+                          ? "Waiting for uploads into these items to stop. "
+                          : ""}
+                    Items stay in Trash until deletion finishes.
+                </p>
+            )}
+            {progressError && <p role="alert">{progressError}</p>}
+            {failed.length > 0 && (
+                <details className="deletion-errors">
+                    <summary>View Failed Items ({failed.length})</summary>
+                    <p>
+                        These items remain in Trash. You can retry their
+                        deletion.
+                    </p>
+                    <ul>
+                        {failed.map((job) => (
+                            <li key={job.id}>
+                                <strong>{job.name || "Item"}</strong>:{" "}
+                                {job.error ||
+                                    "TGDrive could not remove this item."}
+                            </li>
+                        ))}
+                    </ul>
+                    <button
+                        className="secondary-button"
+                        disabled={busy}
+                        onClick={() => {
+                            setBusy(true);
+                            setError("");
+                            void (async () => {
+                                try {
+                                    for (const job of failed)
+                                        await transfers.retryDeletion(job.id);
+                                } catch (problem) {
+                                    setError(errorMessage(problem));
+                                } finally {
+                                    setBusy(false);
+                                }
+                            })();
+                        }}
+                    >
+                        {busy ? <Spinner /> : <RefreshCw size={16} />} Retry
+                        Failed deletions
+                    </button>
+                    {error && <p role="alert">{error}</p>}
+                </details>
+            )}
+        </section>
+    );
+}
diff --git a/website/src/features/transfers/FolderUpload.css b/website/src/features/transfers/FolderUpload.css
new file mode 100644
index 00000000..cf7ce8b9
--- /dev/null
+++ b/website/src/features/transfers/FolderUpload.css
@@ -0,0 +1,68 @@
+.folder-upload-summary {
+    display: flex;
+    align-items: center;
+    gap: 14px;
+    margin: 4px 0 20px;
+    color: var(--ink);
+}
+.folder-upload-summary > svg {
+    flex: 0 0 auto;
+    color: var(--action);
+}
+.folder-upload-summary > div {
+    display: flex;
+    flex-direction: column;
+    gap: 5px;
+    min-width: 0;
+}
+.folder-upload-summary strong {
+    overflow-wrap: anywhere;
+}
+.folder-upload-summary span,
+.folder-upload-note {
+    color: var(--muted);
+    font-size: 13px;
+    line-height: 1.65;
+}
+.folder-upload-skipped {
+    margin: 16px 0;
+    padding: 12px;
+    border: 1px solid var(--line);
+    border-radius: 8px;
+    font-size: 13px;
+    line-height: 1.6;
+}
+.folder-upload-skipped summary {
+    cursor: pointer;
+    font-weight: 600;
+}
+.folder-upload-skipped ul {
+    max-height: 150px;
+    overflow: auto;
+    padding-inline-start: 20px;
+}
+.folder-upload-skipped li {
+    margin-block: 7px;
+    overflow-wrap: anywhere;
+}
+.folder-upload-progress {
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    margin: 20px 0;
+    padding-block: 8px;
+}
+.folder-upload-action {
+    white-space: nowrap;
+}
+.transfer-item-path {
+    display: block;
+    color: var(--muted);
+    font-size: 12px;
+    overflow-wrap: anywhere;
+}
+
+.folder-upload-destination {
+    margin: 0 0 12px;
+    overflow-wrap: anywhere;
+}
diff --git a/website/src/features/transfers/FolderUpload.test.ts b/website/src/features/transfers/FolderUpload.test.ts
new file mode 100644
index 00000000..49440d24
--- /dev/null
+++ b/website/src/features/transfers/FolderUpload.test.ts
@@ -0,0 +1,220 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import FolderUpload from "./FolderUpload";
+import {
+    folderTreeRequest,
+    planFolderUpload,
+    prepareFolderUpload,
+} from "./FolderUpload";
+function picked(path: string, contents = "data") {
+    const file = new File([contents], path.split("/").at(-1)!);
+    Object.defineProperty(file, "webkitRelativePath", { value: path });
+    return file;
+}
+afterEach(() => vi.unstubAllGlobals());
+describe("folder selection validation", () => {
+    it("preserves the selected root and ancestors while keeping duplicate basenames separate", () => {
+        const plan = planFolderUpload(
+            [
+                picked("Project/readme.txt"),
+                picked("Project/alpha/notes.txt"),
+                picked("Project/beta/deep/notes.txt"),
+            ],
+            100,
+        );
+        expect(plan.rootName).toBe("Project");
+        expect(plan.folders).toEqual([["alpha"], ["beta"], ["beta", "deep"]]);
+        expect(
+            plan.files.map(({ relativePath, parent }) => [
+                relativePath,
+                parent,
+            ]),
+        ).toEqual([
+            ["Project/readme.txt", ""],
+            ["Project/alpha/notes.txt", "alpha"],
+            ["Project/beta/deep/notes.txt", "beta/deep"],
+        ]);
+    });
+    it("normalizes relative folder keys to the backend NFC contract", () => {
+        const plan = planFolderUpload([picked("資料/Cafe\u0301/a.txt")], 100);
+        expect(plan.folders).toEqual([["Café"]]);
+        expect(plan.files[0].parent).toBe("Café");
+    });
+    it.each([
+        "Project/../a",
+        "Project//a",
+        "/Project/a",
+        "Project/a\\b",
+        "Project/ bad/a",
+        "Project/\u0001/a",
+    ])("rejects unsafe relative paths: %s", (path) =>
+        expect(() => planFolderUpload([picked(path)], 100)).toThrow(),
+    );
+    it("does not flatten a browser selection that omitted folder paths", () => {
+        expect(() =>
+            planFolderUpload([new File(["ok"], "file.txt")], 100),
+        ).toThrow("did not provide folder paths");
+    });
+    it("rejects sibling collisions and file-versus-folder conflicts", () => {
+        expect(() =>
+            planFolderUpload([picked("Root/A/a"), picked("Root/a/b")], 100),
+        ).toThrow("conflicting");
+        expect(() =>
+            planFolderUpload([picked("Root/a"), picked("Root/a/b")], 100),
+        ).toThrow("conflicting");
+        expect(() =>
+            planFolderUpload([picked("Root/a"), picked("Root/a")], 100),
+        ).toThrow("conflicting");
+    });
+    it("lists unsupported files explicitly without creating their otherwise-empty ancestors", () => {
+        const plan = planFolderUpload(
+            [
+                picked("Root/a", "ok"),
+                picked("Root/empty/zero", ""),
+                picked("Root/large/file", "x".repeat(200)),
+            ],
+            100,
+        );
+        expect(plan.files).toHaveLength(1);
+        expect(plan.skipped).toHaveLength(2);
+        expect(plan.folders).toEqual([]);
+        expect(plan.totalSize).toBe(2);
+    });
+    it("bounds admission and actual UTF-8 metadata payload bytes", () => {
+        expect(() =>
+            planFolderUpload(
+                Array.from({ length: 1001 }, (_, i) => picked("Root/" + i)),
+                100,
+            ),
+        ).toThrow("1,000 files");
+        expect(() =>
+            planFolderUpload(
+                [picked(["Root", ...Array(63).fill("a"), "file"].join("/"))],
+                100,
+            ),
+        ).toThrow("64 levels");
+        const plan = planFolderUpload([picked("Root/a")], 100);
+        plan.folders = Array.from({ length: 300 }, () => ["界".repeat(255)]);
+        expect(() => folderTreeRequest(plan, "/", "id")).toThrow(
+            "preparation limit",
+        );
+    });
+});
+describe("confirmed atomic folder preparation", () => {
+    const response = {
+        root: { id: "root-id", name: "Project (1)", path: "/", type: "folder" },
+        folders: { "": "/root-id", alpha: "/root-id/alpha-id" },
+    };
+    it("resolves opaque destinations only after a confirmed response and never sends file bytes", async () => {
+        const fetcher = vi.fn(async () =>
+            Response.json(response, { status: 201 }),
+        );
+        vi.stubGlobal("fetch", fetcher);
+        const plan = planFolderUpload([picked("Project/alpha/a.txt")], 100);
+        const result = await prepareFolderUpload(
+            plan,
+            "/",
+            "stable-key",
+            new AbortController().signal,
+        );
+        expect(result.root.name).toBe("Project (1)");
+        expect(result.entries[0].destination).toBe("/root-id/alpha-id");
+        expect(result.entries[0].relativePath).toBe("Project/alpha/a.txt");
+        expect(fetcher).toHaveBeenCalledTimes(1);
+        const [url, options] = fetcher.mock.calls[0] as unknown as [
+            string,
+            RequestInit,
+        ];
+        expect(url).toBe("/api/v1/folders/tree");
+        expect(JSON.parse(options.body as string)).toEqual({
+            destination: "/",
+            root_name: "Project",
+            folders: [["alpha"]],
+            client_request_id: "stable-key",
+        });
+    });
+    it("replays the same idempotency key and manifest after an unknown response outcome", async () => {
+        const calls: string[] = [];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (_url: string, options: RequestInit) => {
+                calls.push(options.body as string);
+                if (calls.length === 1) throw new TypeError("response lost");
+                return Response.json(response);
+            }),
+        );
+        const plan = planFolderUpload([picked("Project/alpha/a.txt")], 100);
+        await expect(
+            prepareFolderUpload(
+                plan,
+                "/",
+                "stable-key",
+                new AbortController().signal,
+            ),
+        ).rejects.toThrow();
+        await prepareFolderUpload(
+            plan,
+            "/",
+            "stable-key",
+            new AbortController().signal,
+        );
+        expect(calls[0]).toBe(calls[1]);
+    });
+    it("rejects missing or foreign destination mappings", async () => {
+        const plan = planFolderUpload([picked("Project/alpha/a")], 100);
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    ...response,
+                    folders: { "": "/root-id", alpha: "/unrelated" },
+                }),
+            ),
+        );
+        await expect(
+            prepareFolderUpload(plan, "/", "key", new AbortController().signal),
+        ).rejects.toThrow("incomplete");
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json(response)),
+        );
+        await expect(
+            prepareFolderUpload(
+                plan,
+                "/another",
+                "key",
+                new AbortController().signal,
+            ),
+        ).rejects.toThrow("invalid");
+    });
+});
+
+describe("folder confirmation", () => {
+    it("shows only the selection, destination and necessary upload controls", () => {
+        const html = renderToStaticMarkup(
+            createElement(FolderUpload, {
+                files: [
+                    picked("Project/readme.txt"),
+                    picked("Project/sub/notes.txt"),
+                ],
+                destination: "/",
+                destinationName: "My Files",
+                maxSize: 100,
+                supported: true,
+                onClose: () => {},
+                onQueued: () => {},
+                onFilesFallback: () => {},
+                onChanged: () => {},
+            }),
+        );
+        expect(html).toContain("<strong>Project</strong>");
+        expect(html).toContain("2 files · 8 B");
+        expect(html).toContain("To <strong>My Files</strong>");
+        expect(html).not.toContain("folder-upload-help");
+        expect(html).toContain(">Upload</button>");
+        expect(html).not.toContain("resumable upload queue");
+        expect(html).not.toContain("Keep this tab open");
+        expect(html).not.toContain("preparation request");
+    });
+});
diff --git a/website/src/features/transfers/FolderUpload.tsx b/website/src/features/transfers/FolderUpload.tsx
new file mode 100644
index 00000000..2e23daf5
--- /dev/null
+++ b/website/src/features/transfers/FolderUpload.tsx
@@ -0,0 +1,438 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { FolderUp, RefreshCw } from "lucide-react";
+import { api, errorMessage } from "../../shared/api";
+import { ErrorNotice, Modal, Spinner } from "../../shared/components";
+import { transfers } from "./transfers";
+import {
+    formatBytes,
+    itemPath,
+    type DriveItem,
+    type FolderTreeRequest,
+} from "../../shared/types";
+import "./FolderUpload.css";
+
+export const MAX_FOLDER_FILES = 1000;
+const MAX_FOLDERS = 1000;
+const MAX_PATH_SEGMENTS = 64;
+type FolderFile = { file: File; relativePath: string; parent: string };
+export interface FolderUploadPlan {
+    rootName: string;
+    folders: string[][];
+    files: FolderFile[];
+    skipped: { path: string; reason: string }[];
+    totalSize: number;
+}
+function segment(value: string): string {
+    const normalized = value.normalize("NFC");
+    if (
+        !normalized ||
+        normalized !== normalized.trim() ||
+        normalized === "." ||
+        normalized === ".." ||
+        /[/\\\p{Cc}\p{Cs}]/u.test(normalized) ||
+        [...normalized].length > 255
+    )
+        throw new Error(
+            "A folder or file has an unsupported name. Rename it on your device and choose the folder again.",
+        );
+    return normalized;
+}
+export function planFolderUpload(
+    files: File[],
+    maxSize: number,
+): FolderUploadPlan {
+    if (!files.length)
+        throw new Error(
+            "The selected folder has no files this browser can provide.",
+        );
+    if (files.length > MAX_FOLDER_FILES)
+        throw new Error("Choose a folder containing at most 1,000 files.");
+    const plan: FolderUploadPlan = {
+        rootName: "",
+        folders: [],
+        files: [],
+        skipped: [],
+        totalSize: 0,
+    };
+    const folders = new Map<string, string[]>();
+    const names = new Map<string, { path: string; kind: "file" | "folder" }>();
+    const reserve = (path: string, kind: "file" | "folder") => {
+        const key = path.toLowerCase();
+        const existing = names.get(key);
+        if (
+            existing &&
+            (kind === "file" ||
+                existing.path !== path ||
+                existing.kind !== kind)
+        )
+            throw new Error(
+                "This folder contains duplicate or conflicting names. Rename them on your device before uploading.",
+            );
+        names.set(key, { path, kind });
+    };
+    for (const file of files) {
+        const relative = file.webkitRelativePath;
+        if (!relative || !relative.includes("/"))
+            throw new Error(
+                "This browser did not provide folder paths. Use Upload Files instead.",
+            );
+        const parts = relative.split("/").map(segment);
+        if (parts.length > MAX_PATH_SEGMENTS)
+            throw new Error(
+                "Folder paths can contain at most 64 levels, including the file.",
+            );
+        if (segment(file.name) !== parts.at(-1))
+            throw new Error(
+                "A selected file has an invalid folder path. Choose the folder again.",
+            );
+        if (!plan.rootName) plan.rootName = parts[0];
+        if (parts[0] !== plan.rootName)
+            throw new Error("Choose one folder at a time.");
+        const path = parts.join("/");
+        if (
+            !Number.isSafeInteger(file.size) ||
+            file.size <= 0 ||
+            file.size > maxSize
+        ) {
+            plan.skipped.push({
+                path,
+                reason:
+                    file.size > maxSize
+                        ? "Exceeds the per-file upload limit"
+                        : "Empty files are not supported",
+            });
+            continue;
+        }
+        for (let index = 1; index < parts.length - 1; index++) {
+            const folder = parts.slice(1, index + 1);
+            const key = folder.join("/");
+            reserve(key, "folder");
+            folders.set(key, folder);
+        }
+        const withoutRoot = parts.slice(1).join("/");
+        reserve(withoutRoot, "file");
+        plan.files.push({
+            file,
+            relativePath: path,
+            parent: parts.slice(1, -1).join("/"),
+        });
+        plan.totalSize += file.size;
+        if (!Number.isSafeInteger(plan.totalSize))
+            throw new Error(
+                "This selection is too large to track safely. Choose a smaller folder.",
+            );
+    }
+    if (!plan.files.length)
+        throw new Error(
+            "No supported files were found. Empty files and files above the upload limit cannot be uploaded.",
+        );
+    if (folders.size + 1 > MAX_FOLDERS)
+        throw new Error("Choose a folder containing at most 1,000 folders.");
+    plan.folders = [...folders.values()].sort(
+        (a, b) => a.length - b.length || a.join("/").localeCompare(b.join("/")),
+    );
+    return plan;
+}
+export function folderTreeRequest(
+    plan: FolderUploadPlan,
+    destination: string,
+    requestId: string,
+): FolderTreeRequest {
+    const payload = {
+        destination,
+        root_name: plan.rootName,
+        folders: plan.folders,
+        client_request_id: requestId,
+    };
+    if (new TextEncoder().encode(JSON.stringify(payload)).length > 64 * 1024)
+        throw new Error(
+            "The folder names exceed the preparation limit. Choose a smaller folder.",
+        );
+    return payload;
+}
+export async function prepareFolderUpload(
+    plan: FolderUploadPlan,
+    destination: string,
+    requestId: string,
+    signal: AbortSignal,
+) {
+    const result = await api.prepareFolderTree(
+        folderTreeRequest(plan, destination, requestId),
+        signal,
+    );
+    const rootPath = result.folders?.[""];
+    if (
+        !result.root ||
+        result.root.type !== "folder" ||
+        typeof result.root.id !== "string" ||
+        typeof result.root.path !== "string" ||
+        typeof rootPath !== "string" ||
+        !rootPath.startsWith("/") ||
+        !result.root.id ||
+        typeof result.root.name !== "string" ||
+        !rootPath.startsWith(
+            (destination === "/" ? "" : destination.replace(/\/$/, "")) + "/",
+        ) ||
+        rootPath
+            .slice(
+                (destination === "/" ? "" : destination.replace(/\/$/, ""))
+                    .length + 1,
+            )
+            .includes("/") ||
+        rootPath === "/" ||
+        itemPath(result.root) !== rootPath
+    )
+        throw new Error(
+            "The server returned invalid folder preparation information. Retry Preparation.",
+        );
+    for (const parts of plan.folders) {
+        const path = result.folders[parts.join("/")];
+        const parent = result.folders[parts.slice(0, -1).join("/")];
+        if (
+            typeof path !== "string" ||
+            typeof parent !== "string" ||
+            !path.startsWith(parent + "/") ||
+            path.slice(parent.length + 1).includes("/") ||
+            path === parent + "/"
+        )
+            throw new Error(
+                "The server returned an incomplete folder tree. Retry Preparation.",
+            );
+    }
+    return {
+        root: result.root,
+        entries: plan.files.map((entry) => ({
+            file: entry.file,
+            destination: result.folders[entry.parent],
+            relativePath: entry.relativePath,
+        })),
+    };
+}
+
+export default function FolderUpload({
+    files,
+    destination,
+    destinationName,
+    maxSize,
+    supported,
+    onClose,
+    onQueued,
+    onFilesFallback,
+    onChanged,
+}: {
+    files: File[];
+    destination: string;
+    destinationName: string;
+    maxSize: number;
+    supported: boolean;
+    onClose: () => void;
+    onQueued: (root: DriveItem, count: number) => void;
+    onFilesFallback: () => void;
+    onChanged: () => void;
+}) {
+    const planned = useMemo(() => {
+        if (!supported) return { plan: null, error: "" };
+        try {
+            return { plan: planFolderUpload(files, maxSize), error: "" };
+        } catch (error) {
+            return { plan: null, error: errorMessage(error) };
+        }
+    }, [files, maxSize, supported]);
+    const [requestId] = useState(() => crypto.randomUUID());
+    const [state, setState] = useState<
+        "review" | "preparing" | "cancelled" | "error"
+    >("review");
+    const [error, setError] = useState("");
+    const controller = useRef<AbortController | null>(null);
+    const prepared = useRef<Awaited<
+        ReturnType<typeof prepareFolderUpload>
+    > | null>(null);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            controller.current?.abort();
+        };
+    }, []);
+    const close = () => {
+        if (state === "preparing") {
+            controller.current?.abort();
+            return;
+        }
+        onClose();
+    };
+    const start = async () => {
+        const plan = planned.plan;
+        if (!plan || state === "preparing") return;
+        if (!transfers.canQueue(plan.files.length)) {
+            setError(
+                "The upload queue is full. Wait for existing device transfers or cancel some, then retry.",
+            );
+            setState("error");
+            return;
+        }
+        const active = new AbortController();
+        controller.current = active;
+        setState("preparing");
+        setError("");
+        try {
+            const result =
+                prepared.current ||
+                (await prepareFolderUpload(
+                    plan,
+                    destination,
+                    requestId,
+                    active.signal,
+                ));
+            prepared.current = result;
+            if (active.signal.aborted || !mounted.current) return;
+            const rejected = transfers.addEntries(
+                result.entries,
+                maxSize,
+                true,
+                {
+                    name: result.root.name,
+                    folderUpload: {
+                        id: requestId,
+                        name: result.root.name,
+                        root_path: itemPath(result.root),
+                        created_at: Date.now() / 1000,
+                    },
+                },
+            );
+            if (rejected.length) throw new Error(rejected.join("; "));
+            onChanged();
+            onQueued(result.root, result.entries.length);
+        } catch (error) {
+            if (!mounted.current) return;
+            if (active.signal.aborted) setState("cancelled");
+            else {
+                setState("error");
+                setError(errorMessage(error));
+            }
+        } finally {
+            if (mounted.current && active.signal.aborted) setState("cancelled");
+            if (controller.current === active) controller.current = null;
+            onChanged();
+        }
+    };
+    const fallback = () => {
+        onClose();
+        onFilesFallback();
+    };
+    if (!supported)
+        return (
+            <Modal title="Upload Folder" onClose={onClose}>
+                <p>
+                    Folder selection is not available in this browser. You can
+                    upload files instead, or use a browser that supports
+                    choosing folders.
+                </p>
+                <div className="dialog-actions">
+                    <button className="secondary-button" onClick={onClose}>
+                        Close
+                    </button>
+                    <button className="primary-button" onClick={fallback}>
+                        Upload Files
+                    </button>
+                </div>
+            </Modal>
+        );
+    const plan = planned.plan;
+    return (
+        <Modal title="Upload Folder" onClose={close}>
+            <ErrorNotice message={planned.error || error} />
+            {plan && (
+                <>
+                    <div className="folder-upload-summary">
+                        <FolderUp size={27} aria-hidden="true" />
+                        <div>
+                            <strong>{plan.rootName}</strong>
+                            <span>
+                                {plan.files.length.toLocaleString()}{" "}
+                                {plan.files.length === 1 ? "file" : "files"} ·{" "}
+                                {formatBytes(plan.totalSize)}
+                            </span>
+                        </div>
+                    </div>
+                    <p className="folder-upload-destination">
+                        To <strong>{destinationName}</strong>
+                    </p>
+                    {plan.skipped.length > 0 && (
+                        <details className="folder-upload-skipped" open>
+                            <summary>
+                                {plan.skipped.length}{" "}
+                                {plan.skipped.length === 1 ? "file" : "files"}{" "}
+                                will be skipped
+                            </summary>
+                            <ul>
+                                {plan.skipped
+                                    .slice(0, 20)
+                                    .map((entry, index) => (
+                                        <li key={index}>
+                                            <span>{entry.path}</span> —{" "}
+                                            {entry.reason}
+                                        </li>
+                                    ))}
+                            </ul>
+                            {plan.skipped.length > 20 && (
+                                <p>
+                                    And {plan.skipped.length - 20} more
+                                    unsupported files.
+                                </p>
+                            )}
+                        </details>
+                    )}
+                    {state === "preparing" && (
+                        <div className="folder-upload-progress" role="status">
+                            <Spinner />
+                            <strong>Preparing folders…</strong>
+                        </div>
+                    )}
+                    {state === "cancelled" && (
+                        <p role="status" className="folder-upload-note">
+                            Preparation cancelled. No files were queued. An
+                            empty folder may remain.
+                        </p>
+                    )}
+                    {state === "error" && (
+                        <p className="folder-upload-note">
+                            No files were queued. Retry Preparation, or close
+                            this dialog to choose the folder again.
+                        </p>
+                    )}
+                </>
+            )}
+            <div className="dialog-actions">
+                <button className="secondary-button" onClick={close}>
+                    {state === "preparing" ? "Cancel Preparation" : "Close"}
+                </button>
+                {plan ? (
+                    <button
+                        className="primary-button"
+                        disabled={state === "preparing"}
+                        onClick={() => void start()}
+                    >
+                        {state === "preparing" ? (
+                            <Spinner />
+                        ) : state === "review" ? (
+                            <FolderUp size={17} />
+                        ) : (
+                            <RefreshCw size={17} />
+                        )}
+                        {state === "review"
+                            ? "Upload"
+                            : state === "preparing"
+                              ? "Preparing folders…"
+                              : "Retry Preparation"}
+                    </button>
+                ) : (
+                    <button className="primary-button" onClick={fallback}>
+                        Upload Files
+                    </button>
+                )}
+            </div>
+        </Modal>
+    );
+}
diff --git a/website/src/features/transfers/TransferDeviceNotice.test.ts b/website/src/features/transfers/TransferDeviceNotice.test.ts
new file mode 100644
index 00000000..05b8cf79
--- /dev/null
+++ b/website/src/features/transfers/TransferDeviceNotice.test.ts
@@ -0,0 +1,587 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import TransferPanel, { BatchTransfer } from "./TransferPanel";
+import { summarizeBatches } from "./transferBatches";
+import type { Transfer } from "./transfers";
+import { getTimezone, setTimezone } from "../../shared/types";
+
+const local = (change: Partial<Transfer> = {}): Transfer => ({
+    key: "device-file",
+    name: "Photo.jpg",
+    size: 100,
+    total: 100,
+    current: 0,
+    lastModified: 0,
+    destination: "/",
+    initiatedHere: true,
+    state: "queued",
+    phase: "Waiting to send from this device",
+    folderUpload: change.relativePath
+        ? {
+              id: change.batchId || "folder",
+              name: change.relativePath.split("/")[0],
+              root_path: "/" + change.relativePath.split("/")[0],
+              created_at: 1,
+          }
+        : undefined,
+    ...change,
+});
+
+beforeEach(() => {
+    vi.stubGlobal("window", {
+        history: { state: null },
+        matchMedia: () => ({ matches: false }),
+    });
+    vi.stubGlobal("document", { createElement: () => ({}) });
+});
+afterEach(() => vi.unstubAllGlobals());
+
+function render(items: Transfer[], expandedPage = true) {
+    return renderToStaticMarkup(
+        createElement(TransferPanel, {
+            items,
+            expandedPage,
+            onError: () => {},
+        }),
+    );
+}
+
+function renderExpandedBatches(items: Transfer[]) {
+    const batches = summarizeBatches(items, 10000);
+    const deviceUploadsPending = batches.some((batch) => batch.device.pending);
+    return renderToStaticMarkup(
+        createElement(
+            "div",
+            null,
+            ...batches.map((batch) =>
+                createElement(BatchTransfer, {
+                    key: batch.id,
+                    batch,
+                    deviceUploadsPending,
+                    expanded: true,
+                    onToggleExpanded: () => {},
+                    now: 10000,
+                    run: () => {},
+                    onChooseFile: () => {},
+                    onChooseBatch: () => {},
+                    folderPickerSupported: true,
+                }),
+            ),
+        ),
+    );
+}
+
+describe("visible device receipt feedback", () => {
+    it("uses the instance timezone for finished file and folder dates", () => {
+        const previousTimezone = getTimezone();
+        const finishedAt = Date.parse("2026-01-02T00:30:00Z");
+        const items = [
+            local({ state: "completed", finishedAt }),
+            local({
+                key: "folder-file",
+                state: "completed",
+                finishedAt,
+                relativePath: "Pictures/Photo.jpg",
+            }),
+        ];
+        const views: string[] = [];
+        try {
+            for (const timezone of ["Pacific/Honolulu", "Pacific/Kiritimati"]) {
+                setTimezone(timezone);
+                const html = render(items);
+                const full = new Intl.DateTimeFormat(undefined, {
+                    dateStyle: "full",
+                    timeStyle: "short",
+                    timeZone: timezone,
+                }).format(finishedAt);
+                const compact = new Intl.DateTimeFormat(undefined, {
+                    dateStyle: "medium",
+                    timeStyle: "short",
+                    timeZone: timezone,
+                }).format(finishedAt);
+                expect(html.split(`title="${full}"`)).toHaveLength(3);
+                expect(html.split(`>${compact}</time>`)).toHaveLength(3);
+                views.push(html);
+            }
+            expect(views[0]).not.toBe(views[1]);
+        } finally {
+            setTimezone(previousTimezone);
+        }
+    });
+
+    it("keeps separate standalone uploads in the device phase until all are accepted", () => {
+        const accepted = local({
+            batchId: "accepted-file",
+            jobId: "first-job",
+            state: "uploading",
+            stage: "uploading",
+            phase: "Uploading to Telegram",
+            current: 25,
+            speedBytesPerSecond: 10,
+            progressUpdatedAt: 9,
+            serverObservedAt: 9000,
+        });
+        const sending = local({
+            key: "second",
+            batchId: "sending-file",
+            state: "receiving",
+            phase: "Uploading from your device",
+            current: 40,
+            meter: {
+                stage: "receipt",
+                bytes: 40,
+                at: 9000,
+                advancedAt: 9000,
+                rate: 20,
+            },
+        });
+        const pending = renderExpandedBatches([accepted, sending]);
+        expect(pending).toContain('class="transfer-phase">Received');
+        expect(pending).toContain("40 / 100 B");
+        expect(pending).toContain("20 B/s");
+        expect(pending).not.toContain("Telegram");
+        expect(pending).not.toContain("25 / 100 B");
+        expect(pending).not.toContain("10 B/s");
+
+        const complete = renderExpandedBatches([
+            accepted,
+            {
+                ...sending,
+                jobId: "second-job",
+                state: "uploading",
+                stage: "uploading",
+                phase: "Uploading to Telegram",
+                current: 50,
+                speedBytesPerSecond: 30,
+                progressUpdatedAt: 9,
+                serverObservedAt: 9000,
+            },
+        ]);
+        expect(complete).toContain("25 / 100 B");
+        expect(complete).toContain("50 / 100 B");
+        expect(complete).toContain("10 B/s");
+        expect(complete).toContain("30 B/s");
+        expect(complete).not.toContain("Uploading from your device");
+        expect(complete).not.toContain('class="transfer-phase">Received');
+    });
+
+    it("keeps accepted folders and their children received while another folder sends", () => {
+        const first = local({
+            batchId: "accepted-folder",
+            relativePath: "First/Photo.jpg",
+            jobId: "first-job",
+            state: "uploading",
+            stage: "uploading",
+            phase: "Uploading to Telegram",
+            current: 25,
+            speedBytesPerSecond: 10,
+            progressUpdatedAt: 9,
+            serverObservedAt: 9000,
+        });
+        const second = local({
+            key: "second",
+            batchId: "sending-folder",
+            relativePath: "Second/Photo.jpg",
+            state: "receiving",
+            phase: "Uploading from your device",
+            current: 40,
+            meter: {
+                stage: "receipt",
+                bytes: 40,
+                at: 9000,
+                advancedAt: 9000,
+                rate: 20,
+            },
+        });
+        const pending = renderExpandedBatches([first, second]);
+        expect(pending.match(/data-stage="device"/g)).toHaveLength(2);
+        expect(pending.match(/<progress/g)).toHaveLength(2);
+        expect(pending).toContain(
+            'class="transfer-batch-status" aria-live="polite">Received',
+        );
+        expect(pending).toContain('class="transfer-phase">Received');
+        expect(pending).toContain("20 B/s");
+        expect(pending).not.toContain("Telegram");
+        expect(pending).not.toContain("25 / 100 B");
+        expect(pending).not.toContain("10 B/s");
+        expect(pending).not.toContain("0 of 1");
+
+        const complete = renderExpandedBatches([
+            first,
+            {
+                ...second,
+                jobId: "second-job",
+                state: "uploading",
+                stage: "uploading",
+                phase: "Uploading to Telegram",
+                current: 50,
+                speedBytesPerSecond: 30,
+                progressUpdatedAt: 9,
+                serverObservedAt: 9000,
+            },
+        ]);
+        expect(complete.match(/data-stage="telegram"/g)).toHaveLength(2);
+        expect(complete).toContain("25 / 100 B");
+        expect(complete).toContain("50 / 100 B");
+        expect(complete).toContain("10 B/s");
+        expect(complete).toContain("30 B/s");
+        expect(complete).not.toContain("Uploading from device");
+        expect(complete).not.toContain('class="transfer-phase">Received');
+    });
+
+    it("keeps discovered upload jobs received while local device work is pending", () => {
+        const server = local({
+            batchId: "server:job",
+            initiatedHere: false,
+            jobId: "server-job",
+            state: "uploading",
+            stage: "uploading",
+            phase: "Uploading to Telegram",
+            current: 25,
+            speedBytesPerSecond: 10,
+            progressUpdatedAt: 9,
+            serverObservedAt: 9000,
+        });
+        const pending = local({ key: "pending", batchId: "device" });
+        const html = renderExpandedBatches([server, pending]);
+        expect(html).toContain('class="transfer-phase">Received');
+        expect(html).not.toContain("Telegram");
+        expect(html).not.toContain("25 / 100 B");
+        expect(html).not.toContain("10 B/s");
+
+        const complete = renderExpandedBatches([server]);
+        expect(complete).toContain("Uploading to Telegram");
+        expect(complete).toContain("25 / 100 B");
+        expect(complete).toContain("10 B/s");
+    });
+
+    it("keeps single-file folder summaries free of redundant completion counts", () => {
+        const folder = local({
+            batchId: "single-folder",
+            relativePath: "Pictures/Photo.jpg",
+            state: "receiving",
+            phase: "Uploading from your device",
+        });
+        const receiving = render([folder]);
+        expect(receiving).toContain("Uploading from device");
+        expect(receiving).not.toContain("0 of 1");
+        expect(receiving).not.toContain("Uploading to Telegram");
+
+        const accepted = render([
+            {
+                ...folder,
+                jobId: "accepted",
+                state: "uploading",
+                phase: "Uploading to Telegram",
+                stage: "uploading",
+            },
+        ]);
+        expect(accepted).toContain("Uploading to Telegram");
+        expect(accepted).not.toContain("0 of 1");
+        expect(accepted).not.toContain("Uploading from device");
+
+        const ordinary = render([
+            { ...folder, relativePath: undefined, folderUpload: undefined },
+        ]);
+        expect(ordinary).not.toContain("0 of 1");
+        expect(ordinary).toContain("Uploading from your device");
+        expect(ordinary).not.toContain("transfer-batch-status");
+    });
+
+    it("preserves attention and recovery actions for a single-file folder", () => {
+        vi.stubGlobal("document", {
+            createElement: () => ({ webkitdirectory: "" }),
+        });
+        const html = render([
+            local({
+                batchId: "single-folder",
+                relativePath: "Pictures/Photo.jpg",
+                state: "error",
+                error: "Connection interrupted",
+            }),
+        ]);
+        expect(html).toContain("Uploading from device · 1 failed");
+        expect(html).toContain("Choose Folder");
+        expect(html).not.toContain("0 of 1");
+    });
+
+    it("shows server receipt counts in a folder summary before its files are expanded", () => {
+        const first = local({
+            batchId: "folder",
+            relativePath: "Pictures/Photo.jpg",
+            jobId: "accepted",
+            state: "uploading",
+        });
+        const second = local({
+            batchId: "folder",
+            key: "second",
+            relativePath: "Pictures/Second.jpg",
+        });
+        const html = render([first, second]);
+        expect(html).toContain("Uploading from device · 1 of 2 received");
+        expect(html).toContain("Keep this tab open");
+        expect(html).not.toContain("You can close this tab");
+        expect(html).not.toContain("transfer-child");
+    });
+
+    it("offers to close the tab only after every standalone upload is accepted", () => {
+        const accepted = local({ jobId: "accepted", state: "uploading" });
+        const pending = local({ key: "second", name: "Second.jpg" });
+        expect(render([accepted, pending])).not.toContain(
+            "You can close this tab",
+        );
+        expect(render([accepted, pending])).toContain(
+            "Keep this tab open for other uploads",
+        );
+        expect(
+            render([
+                accepted,
+                { ...pending, jobId: "second-job", state: "uploading" },
+            ]),
+        ).toContain("You can close this tab");
+    });
+
+    it("does not show a device receipt for server-discovered or URL transfers", () => {
+        expect(
+            render([
+                local({
+                    initiatedHere: false,
+                    jobId: "server-job",
+                    state: "uploading",
+                }),
+            ]),
+        ).not.toContain("transfer-device-status");
+        expect(
+            render([
+                local({ kind: "remote", jobId: "url-job", state: "uploading" }),
+            ]),
+        ).not.toContain("transfer-device-status");
+    });
+
+    it("keeps collapsed readiness in the original header without adding an overlay row", () => {
+        vi.stubGlobal("window", {
+            history: { state: { tgdriveReveal: true } },
+            matchMedia: () => ({ matches: false }),
+        });
+        const pending = render([local()], false);
+        expect(pending).toContain(
+            'class="transfer-collapsed-status" role="status">Keep this tab open',
+        );
+        expect(pending).not.toContain('class="transfer-notice"');
+        const accepted = render(
+            [local({ jobId: "accepted", state: "uploading" })],
+            false,
+        );
+        expect(accepted).toContain(
+            'class="transfer-collapsed-status" role="status">You can close this tab',
+        );
+        expect(accepted).toContain('title="You can close this tab"');
+        expect(accepted).not.toContain('class="transfer-notice"');
+    });
+
+    it("shows only device bytes, rates and received child states before handoff", () => {
+        const first = local({
+            batchId: "folder",
+            relativePath: "Pictures/Photo.jpg",
+            jobId: "accepted",
+            state: "uploading",
+            stage: "uploading",
+            phase: "Uploading to Telegram",
+            current: 25,
+            speedBytesPerSecond: 10,
+            progressUpdatedAt: 9,
+            serverObservedAt: 9000,
+        });
+        const second = local({
+            batchId: "folder",
+            key: "second",
+            relativePath: "Pictures/Second.jpg",
+            state: "receiving",
+            phase: "Uploading from your device",
+            current: 20,
+            sentCurrent: 40,
+            meter: {
+                stage: "receipt",
+                bytes: 40,
+                at: 9000,
+                advancedAt: 9000,
+                rate: 20,
+            },
+        });
+        const batch = summarizeBatches([first, second], 10000)[0];
+        const html = renderToStaticMarkup(
+            createElement(BatchTransfer, {
+                batch,
+                deviceUploadsPending: true,
+                expanded: true,
+                onToggleExpanded: () => {},
+                now: 10000,
+                run: () => {},
+                onChooseFile: () => {},
+                onChooseBatch: () => {},
+                folderPickerSupported: true,
+            }),
+        );
+        expect(html).toContain('data-stage="device"');
+        expect(html).toContain("140 / 200 B");
+        expect(html).toContain("70%");
+        expect(html).toContain("20 B/s");
+        expect(html).toContain('class="transfer-phase">Received');
+        expect(html).not.toContain("Telegram");
+        expect(html).not.toContain("10 B/s");
+        expect(html).not.toContain("25 / 100 B");
+        expect(html).not.toContain("Done");
+
+        const accepted = render([
+            first,
+            {
+                ...second,
+                jobId: "second-job",
+                state: "uploading",
+                stage: "queued",
+                current: 0,
+            },
+        ]);
+        expect(accepted).toContain('data-stage="telegram"');
+        expect(accepted).toContain("Uploading to Telegram");
+        expect(accepted).toContain("25 / 200 B");
+        expect(accepted).not.toContain("Uploading from device");
+    });
+
+    it("counts a running folder as one task while keeping its file total", () => {
+        const html = render([
+            local({
+                batchId: "folder",
+                relativePath: "Pictures/Photo.jpg",
+                state: "completed",
+                jobId: "first",
+            }),
+            local({
+                key: "second",
+                batchId: "folder",
+                relativePath: "Pictures/Second.jpg",
+                state: "receiving",
+            }),
+        ]);
+        expect(html).toMatch(/Running<span>1<\/span>/);
+        expect(html).toContain("2 files");
+    });
+
+    it("renders files from one ordinary selection as separate tasks", () => {
+        const selected = ["First.jpg", "Second.jpg", "Third.jpg"].map(
+            (name, index) =>
+                local({
+                    key: "selected-" + index,
+                    batchId: "selected-" + index,
+                    batchName: "3 files",
+                    name,
+                    state: "receiving",
+                }),
+        );
+        const html = render(selected);
+        expect(html).toContain("3 transfers shown");
+        expect(html).toMatch(/Running<span>3<\/span>/);
+        expect(html.match(/class="transfer-item"/g)).toHaveLength(3);
+        expect(html).not.toContain('class="transfer-batch"');
+        expect(html).not.toContain('aria-label="Show Files"');
+        for (const item of selected) expect(html).toContain(item.name);
+        expect(render(selected, false)).toContain("3 uploads in progress");
+    });
+
+    it("counts a 72-file folder and two ordinary files as three tasks", () => {
+        const folder = Array.from({ length: 72 }, (_, index) =>
+            local({
+                key: "folder-" + index,
+                name: index + ".jpg",
+                batchId: "folder",
+                batchName: "Pictures",
+                relativePath: "Pictures/" + index + ".jpg",
+                state: "receiving",
+            }),
+        );
+        const ordinary = ["First.jpg", "Second.jpg"].map((name, index) =>
+            local({
+                key: "ordinary-" + index,
+                batchId: "selection",
+                name,
+                state: "receiving",
+            }),
+        );
+        const html = render([...folder, ...ordinary]);
+        expect(html).toContain("3 transfers shown");
+        expect(html).toMatch(/Running<span>3<\/span>/);
+        expect(html.match(/class="transfer-batch"/g)).toHaveLength(1);
+        expect(html.match(/class="transfer-item"/g)).toHaveLength(2);
+        expect(html).toContain("72 files");
+    });
+
+    it("keeps a one-file folder grouped using server folder metadata alone", () => {
+        const html = render([
+            local({
+                folderUpload: {
+                    id: "folder-task",
+                    name: "Pictures",
+                    root_path: "/Pictures",
+                    created_at: 1,
+                },
+                state: "receiving",
+            }),
+        ]);
+        expect(html).toContain('class="transfer-batch"');
+        expect(html).toContain('data-folder="true"');
+        expect(html).toContain('aria-label="Show Files"');
+        expect(html).toContain("Pictures");
+        expect(html).toContain("1 file");
+        expect(html).toMatch(/Running<span>1<\/span>/);
+    });
+
+    it("uses the uploaded folder root for a nested server history member", () => {
+        const html = render([
+            local({
+                folderUpload: {
+                    id: "folder-task",
+                    name: "Pictures",
+                    root_path: "/Pictures",
+                    created_at: 1,
+                },
+                destination: "/Pictures/Nested",
+                state: "completed",
+                jobId: "server-file",
+                historyOnly: true,
+                location: {
+                    available: true,
+                    folder_label: "My Files / Pictures / Nested",
+                    folder_path: "/Pictures/Nested",
+                },
+            }),
+        ]);
+        expect(html).toContain('title="My Files / Pictures"');
+        expect(html).not.toContain('title="My Files / Pictures / Nested"');
+    });
+
+    it("counts finished folders and ordinary files by task", () => {
+        const items = [
+            local({
+                batchId: "folder",
+                relativePath: "Pictures/Photo.jpg",
+                state: "completed",
+                jobId: "first",
+            }),
+            local({
+                key: "folder-second",
+                batchId: "folder",
+                relativePath: "Pictures/Second.jpg",
+                state: "completed",
+                jobId: "second",
+            }),
+            local({
+                key: "ordinary",
+                name: "Readme.txt",
+                state: "completed",
+                jobId: "third",
+            }),
+        ];
+        expect(render(items)).toMatch(/Finished<span>2<\/span>/);
+    });
+});
diff --git a/website/src/features/transfers/TransferHistory.css b/website/src/features/transfers/TransferHistory.css
new file mode 100644
index 00000000..b2411778
--- /dev/null
+++ b/website/src/features/transfers/TransferHistory.css
@@ -0,0 +1,93 @@
+.transfer-history-filters {
+    margin: 4px 0 16px;
+}
+.transfer-history-toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    gap: 8px 16px;
+    margin: 4px 0 16px;
+}
+.transfer-history-toolbar .transfer-history-filters {
+    min-width: 0;
+    margin: 0;
+}
+.transfer-history-clear {
+    min-height: 44px;
+    flex-shrink: 0;
+}
+.transfer-history .transfer-history-filters {
+    display: flex;
+    flex-wrap: nowrap;
+    overflow-x: auto;
+}
+.transfer-history-pagination {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+    padding: 20px 0;
+    border-top: 1px solid var(--line);
+    margin-top: 16px;
+}
+.transfer-history-pagination > span {
+    color: var(--muted);
+    font-size: 13px;
+    font-variant-numeric: tabular-nums;
+}
+.transfer-history-page-controls,
+.transfer-history-page-numbers {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+}
+.transfer-history-page-controls {
+    flex-wrap: wrap;
+    justify-content: flex-end;
+}
+.transfer-history-page-numbers {
+    flex-wrap: wrap;
+    justify-content: center;
+}
+.transfer-history-page-numbers > span {
+    color: var(--muted);
+    padding-inline: 4px;
+}
+.transfer-history-pagination button {
+    min-width: 40px;
+    min-height: 40px;
+    padding: 8px;
+    font-variant-numeric: tabular-nums;
+}
+.transfer-history-pagination button[aria-current="page"] {
+    border-color: var(--action);
+    background: var(--action-soft);
+    color: var(--on-action-soft);
+    font-weight: 600;
+}
+@media (max-width: 360px) {
+    .transfer-history-page-numbers {
+        gap: 2px;
+    }
+}
+.transfer-history .transfer-category[data-category="finished"] > .empty-state {
+    padding-block: 40px;
+}
+@media (max-width: 540px) {
+    .transfer-history-pagination {
+        flex-wrap: wrap;
+    }
+    .transfer-history-page-controls {
+        width: 100%;
+        justify-content: center;
+    }
+    .transfer-history-page-numbers {
+        order: -1;
+        width: 100%;
+    }
+    .transfer-history-pagination button {
+        min-width: 36px;
+        min-height: 44px;
+    }
+}
diff --git a/website/src/features/transfers/TransferHistory.tsx b/website/src/features/transfers/TransferHistory.tsx
new file mode 100644
index 00000000..a375a168
--- /dev/null
+++ b/website/src/features/transfers/TransferHistory.tsx
@@ -0,0 +1,419 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { ChevronLeft, ChevronRight, Trash2, Upload } from "lucide-react";
+import { errorMessage } from "../../shared/api";
+import { ErrorNotice, Modal, Spinner } from "../../shared/components";
+import TransferPanel from "./TransferPanel";
+import {
+    loadTaskHistoryPage,
+    liveHistoryRows,
+    matchHistoryTasks,
+    visibleHistory,
+    type HistoryFilter,
+} from "./transferHistory";
+import type { Job, TransferTaskHistoryPage } from "../../shared/types";
+import { transfers, type Transfer } from "./transfers";
+import {
+    useManualRefresh,
+    type RefreshNotice,
+} from "../../shared/useManualRefresh";
+import "./TransferHistory.css";
+
+const filters: { key: HistoryFilter; label: string }[] = [
+    { key: "all", label: "All" },
+    { key: "completed", label: "Successful" },
+    { key: "error", label: "Failed" },
+    { key: "cancelled", label: "Cancelled" },
+];
+export default function TransferHistory({
+    items,
+    onError,
+    onLocate,
+    onNotice,
+    query = "",
+}: {
+    items: Transfer[];
+    onLocate: (item: Transfer, folder?: boolean) => void;
+    onError: (message: string) => void;
+    onNotice?: RefreshNotice;
+    query?: string;
+}) {
+    const [filter, setFilter] = useState<HistoryFilter>("all");
+    const [pageNumber, setPageNumber] = useState(1);
+    const [jobs, setJobs] = useState<Job[]>([]);
+    const [localItems, setLocalItems] = useState<Transfer[]>([]);
+    const [page, setPage] = useState<TransferTaskHistoryPage | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState("");
+    const [confirmClear, setConfirmClear] = useState(false);
+    const [clearing, setClearing] = useState(false);
+    const [clearError, setClearError] = useState("");
+    const [historyVersion, setHistoryVersion] = useState(0);
+    const clearingRef = useRef(false);
+    const generation = useRef(0);
+    const currentItems = useRef(items);
+    currentItems.current = items;
+    const manual = useManualRefresh(onNotice);
+    const context = JSON.stringify([filter, pageNumber, query]);
+    const manualContext = useRef<string | null>(null);
+    const load = useCallback(
+        async (signal: AbortSignal, explicit = false) => {
+            if (clearingRef.current) return false;
+            const version = ++generation.current;
+            let redirected = false;
+            try {
+                const response = await loadTaskHistoryPage(
+                    currentItems.current,
+                    filter,
+                    pageNumber,
+                    signal,
+                    query,
+                );
+                if (signal.aborted || generation.current !== version)
+                    return false;
+                if (response.page !== pageNumber) {
+                    redirected = true;
+                    setJobs([]);
+                    setLocalItems([]);
+                    setPage(response);
+                    setLoading(true);
+                    setPageNumber(response.page);
+                    return true;
+                }
+                setJobs(response.jobs);
+                setLocalItems(response.localItems);
+                setPage(response);
+                setError("");
+                return true;
+            } catch (cause) {
+                if (signal.aborted || generation.current !== version)
+                    return false;
+                setError(errorMessage(cause));
+                if (explicit) throw cause;
+                return false;
+            } finally {
+                if (
+                    !redirected &&
+                    !signal.aborted &&
+                    generation.current === version
+                )
+                    setLoading(false);
+            }
+        },
+        [filter, pageNumber, query],
+    );
+    useEffect(() => {
+        move(1, true);
+    }, [query]);
+    useEffect(() => {
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout>;
+        const poll = async () => {
+            if (manualContext.current !== context)
+                await load(controller.signal);
+            if (!controller.signal.aborted)
+                timer = setTimeout(poll, document.hidden ? 30000 : 10000);
+        };
+        void poll();
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [load, context, historyVersion]);
+    const clearHistory = async () => {
+        if (clearingRef.current) return;
+        clearingRef.current = true;
+        setClearing(true);
+        setClearError("");
+        generation.current++;
+        try {
+            await transfers.clearHistory();
+            generation.current++;
+            setJobs([]);
+            setLocalItems([]);
+            setPage(null);
+            setPageNumber(1);
+            setLoading(true);
+            setError("");
+            setConfirmClear(false);
+            onNotice?.("Transfer history cleared.");
+        } catch (cause) {
+            setClearError(errorMessage(cause));
+        } finally {
+            clearingRef.current = false;
+            setClearing(false);
+            setHistoryVersion((version) => version + 1);
+        }
+    };
+    const retry = () =>
+        manual.run(async (signal) => {
+            manualContext.current = context;
+            setLoading(true);
+            try {
+                return await load(signal, true);
+            } finally {
+                if (manualContext.current === context)
+                    manualContext.current = null;
+            }
+        }, "Transfer history refreshed.");
+    const move = (next: number, resetTotals = false) => {
+        if (next === pageNumber && !resetTotals) return;
+        generation.current++;
+        setLoading(true);
+        setError("");
+        setJobs([]);
+        setLocalItems([]);
+        if (resetTotals) setPage(null);
+        setPageNumber(next);
+    };
+    const latest = new Map(items.map((item) => [item.key, item]));
+    const pageItems = new Map(
+        localItems.map((item) => [item.key, latest.get(item.key) || item]),
+    );
+    for (const item of matchHistoryTasks(liveHistoryRows(items), query))
+        pageItems.set(item.key, item);
+    const visible = visibleHistory(
+        jobs,
+        [...pageItems.values()],
+        filter,
+        true,
+        true,
+    );
+    const controls = (
+        <div className="transfer-history-toolbar">
+            <div
+                className="transfer-history-filters transfer-filters"
+                role="group"
+                aria-label="Filter Finished Transfers"
+            >
+                {filters.map((entry) => (
+                    <button
+                        type="button"
+                        key={entry.key}
+                        aria-pressed={filter === entry.key}
+                        onClick={() => {
+                            if (entry.key !== filter) {
+                                move(1, true);
+                                setFilter(entry.key);
+                            }
+                        }}
+                    >
+                        {entry.label}
+                    </button>
+                ))}
+            </div>
+            <button
+                type="button"
+                className="secondary-button transfer-history-clear"
+                disabled={clearing || manual.refreshing}
+                onClick={() => {
+                    setClearError("");
+                    setConfirmClear(true);
+                }}
+            >
+                <Trash2 size={16} aria-hidden="true" /> Clear history
+            </button>
+        </div>
+    );
+    const empty = loading ? (
+        <p className="transfer-history-loading" role="status">
+            <Spinner /> Loading finished transfers…
+        </p>
+    ) : !error ? (
+        <div className="empty-state">
+            <Upload size={32} />
+            <h2>
+                {query
+                    ? "No Matching Finished Transfers"
+                    : filter === "all"
+                      ? pageNumber === 1
+                          ? "No Finished Transfers Yet"
+                          : "No More Finished Transfers"
+                      : "No " +
+                        filters.find((entry) => entry.key === filter)!.label +
+                        " Transfers"}
+            </h2>
+            <p>
+                {query
+                    ? "Try another name or clear the search."
+                    : filter === "all"
+                      ? "Successful, failed and cancelled uploads appear here."
+                      : "Try another filter to see other finished uploads."}
+            </p>
+        </div>
+    ) : null;
+    return (
+        <section className="transfer-history" aria-label="Transfer History">
+            <TransferPanel
+                items={visible}
+                onError={onError}
+                onLocate={onLocate}
+                expandedPage
+                finishedControls={
+                    <>
+                        {controls}
+                        {error && (
+                            <div className="page-load-error">
+                                <ErrorNotice message={error} />
+                                <button
+                                    className="secondary-button"
+                                    disabled={loading || manual.refreshing}
+                                    aria-busy={manual.refreshing}
+                                    onClick={() => void retry()}
+                                >
+                                    {manual.refreshing && <Spinner />}
+                                    {manual.refreshing
+                                        ? "Refreshing…"
+                                        : "Try Again"}
+                                </button>
+                            </div>
+                        )}
+                    </>
+                }
+                finishedEmpty={empty}
+            />
+            {page && page.total_tasks > 0 && (
+                <HistoryPagination
+                    page={pageNumber}
+                    totalPages={page.total_pages}
+                    totalTasks={page.total_tasks}
+                    loading={loading}
+                    onPageChange={move}
+                />
+            )}
+            {confirmClear && (
+                <Modal
+                    title="Clear transfer history?"
+                    initialFocus="#keep-transfer-history"
+                    onClose={() => {
+                        if (!clearingRef.current) setConfirmClear(false);
+                    }}
+                >
+                    <p>
+                        Remove successful, failed and cancelled transfers from
+                        all history pages, including entries for deleted files?
+                        This applies to every filter and search result and
+                        cannot be undone.
+                    </p>
+                    <p>
+                        Your files, active uploads and transfers waiting for a
+                        file will be kept. Folders with unfinished uploads keep
+                        their history until the remaining uploads finish.
+                    </p>
+                    <ErrorNotice message={clearError} />
+                    <div className="dialog-actions">
+                        <button
+                            id="keep-transfer-history"
+                            type="button"
+                            className="secondary-button"
+                            disabled={clearing}
+                            onClick={() => setConfirmClear(false)}
+                        >
+                            Keep history
+                        </button>
+                        <button
+                            type="button"
+                            className="danger-button"
+                            disabled={clearing}
+                            aria-busy={clearing}
+                            onClick={() => void clearHistory()}
+                        >
+                            {clearing && <Spinner />}
+                            {clearing ? "Clearing…" : "Clear history"}
+                        </button>
+                    </div>
+                </Modal>
+            )}
+        </section>
+    );
+}
+
+function numberedPages(page: number, total: number): (number | "gap")[] {
+    if (total <= 7)
+        return Array.from({ length: total }, (_, index) => index + 1);
+    const start = page <= 3 ? 2 : Math.max(2, Math.min(page - 1, total - 4));
+    const end =
+        page >= total - 2
+            ? total - 1
+            : Math.min(total - 1, Math.max(page + 1, 5));
+    const pages: (number | "gap")[] = [1];
+    if (start > 2) pages.push("gap");
+    for (let number = start; number <= end; number++) pages.push(number);
+    if (end < total - 1) pages.push("gap");
+    pages.push(total);
+    return pages;
+}
+
+export function HistoryPagination({
+    page,
+    totalPages,
+    totalTasks,
+    loading,
+    onPageChange,
+}: {
+    page: number;
+    totalPages: number;
+    totalTasks: number;
+    loading: boolean;
+    onPageChange: (page: number) => void;
+}) {
+    return (
+        <nav
+            className="transfer-history-pagination"
+            aria-label="Finished transfer pages"
+            aria-busy={loading}
+        >
+            <span role="status" aria-live="polite" aria-atomic="true">
+                Page {page} of {totalPages} · {totalTasks}{" "}
+                {totalTasks === 1 ? "task" : "tasks"}
+                {loading ? " · Loading…" : ""}
+            </span>
+            <div className="transfer-history-page-controls">
+                <button
+                    type="button"
+                    className="secondary-button"
+                    aria-label="Previous page of finished transfers"
+                    title="Previous page"
+                    disabled={loading || page <= 1}
+                    onClick={() => onPageChange(page - 1)}
+                >
+                    <ChevronLeft size={16} aria-hidden="true" />
+                </button>
+                <div className="transfer-history-page-numbers">
+                    {numberedPages(page, totalPages).map((number, index) =>
+                        number === "gap" ? (
+                            <span key={"gap-" + index} aria-hidden="true">
+                                …
+                            </span>
+                        ) : (
+                            <button
+                                type="button"
+                                key={number}
+                                className="secondary-button"
+                                aria-label={
+                                    "Page " + number + " of finished transfers"
+                                }
+                                aria-current={
+                                    number === page ? "page" : undefined
+                                }
+                                disabled={loading}
+                                onClick={() => onPageChange(number)}
+                            >
+                                {number}
+                            </button>
+                        ),
+                    )}
+                </div>
+                <button
+                    type="button"
+                    className="secondary-button"
+                    aria-label="Next page of finished transfers"
+                    title="Next page"
+                    disabled={loading || page >= totalPages}
+                    onClick={() => onPageChange(page + 1)}
+                >
+                    <ChevronRight size={16} aria-hidden="true" />
+                </button>
+            </div>
+        </nav>
+    );
+}
diff --git a/website/src/features/transfers/TransferHistoryPagination.test.ts b/website/src/features/transfers/TransferHistoryPagination.test.ts
new file mode 100644
index 00000000..71f4a604
--- /dev/null
+++ b/website/src/features/transfers/TransferHistoryPagination.test.ts
@@ -0,0 +1,102 @@
+import {
+    Children,
+    createElement,
+    isValidElement,
+    type ReactElement,
+    type ReactNode,
+} from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { HistoryPagination } from "./TransferHistory";
+
+function render(page = 1, totalPages = 3, loading = false) {
+    return renderToStaticMarkup(
+        createElement(HistoryPagination, {
+            page,
+            totalPages,
+            totalTasks: (totalPages - 1) * 20 + 1,
+            loading,
+            onPageChange: () => {},
+        }),
+    );
+}
+
+type ButtonProps = {
+    children?: ReactNode;
+    "aria-label"?: string;
+    onClick?: () => void;
+};
+function findButton(
+    node: ReactNode,
+    label: string,
+): ReactElement<ButtonProps> | undefined {
+    for (const child of Children.toArray(node)) {
+        if (!isValidElement<ButtonProps>(child)) continue;
+        if (child.type === "button" && child.props["aria-label"] === label)
+            return child;
+        const nested = findButton(child.props.children, label);
+        if (nested) return nested;
+    }
+}
+
+describe("numbered transfer task pages", () => {
+    it("shows direct numbered pages with the current page identified", () => {
+        const html = render(2);
+        expect(html).toContain('aria-label="Finished transfer pages"');
+        expect(html).toContain("Page 2 of 3 · 41 tasks");
+        expect(html).toContain('aria-label="Page 1 of finished transfers"');
+        expect(html).toContain(
+            'aria-label="Page 2 of finished transfers" aria-current="page"',
+        );
+        expect(html).toContain('aria-label="Page 3 of finished transfers"');
+        expect(html).not.toContain("Latest");
+    });
+
+    it("disables the previous and next controls at the respective ends", () => {
+        expect(render(1)).toMatch(
+            /aria-label="Previous page of finished transfers"[^>]*disabled=""/,
+        );
+        expect(render(3)).toMatch(
+            /aria-label="Next page of finished transfers"[^>]*disabled=""/,
+        );
+        expect(render(2)).not.toContain('disabled=""');
+    });
+
+    it("keeps large histories compact while exposing first, current and last pages", () => {
+        const html = render(40, 100);
+        for (const page of [1, 39, 40, 41, 100])
+            expect(html).toContain(
+                'aria-label="Page ' + page + ' of finished transfers"',
+            );
+        expect(html).not.toContain(
+            'aria-label="Page 20 of finished transfers"',
+        );
+        expect(html.match(/aria-hidden="true">…<\/span>/g)).toHaveLength(2);
+    });
+
+    it("disables every page action while loading without hiding page positions", () => {
+        const html = render(2, 3, true);
+        expect(html).toContain('aria-busy="true"');
+        expect(html).toContain("Loading…");
+        expect(html.match(/disabled=""/g)).toHaveLength(5);
+        expect(html).toContain('aria-current="page"');
+    });
+
+    it("opens a selected numbered page directly and moves one page at a time", () => {
+        const onPageChange = vi.fn();
+        const view = HistoryPagination({
+            page: 2,
+            totalPages: 5,
+            totalTasks: 81,
+            loading: false,
+            onPageChange,
+        });
+        findButton(view, "Page 5 of finished transfers")?.props.onClick?.();
+        findButton(
+            view,
+            "Previous page of finished transfers",
+        )?.props.onClick?.();
+        findButton(view, "Next page of finished transfers")?.props.onClick?.();
+        expect(onPageChange.mock.calls).toEqual([[5], [1], [3]]);
+    });
+});
diff --git a/website/src/features/transfers/TransferMetrics.test.ts b/website/src/features/transfers/TransferMetrics.test.ts
new file mode 100644
index 00000000..48b43b38
--- /dev/null
+++ b/website/src/features/transfers/TransferMetrics.test.ts
@@ -0,0 +1,63 @@
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { TransferMetrics } from "./TransferPanel";
+import type { Transfer } from "./transfers";
+
+const item: Transfer = {
+    key: "sample",
+    initiatedHere: true,
+    name: "Video.mp4",
+    size: 1024 * 1024,
+    lastModified: 0,
+    destination: "/",
+    state: "uploading",
+    phase: "Uploading to Telegram",
+    stage: "uploading",
+    current: 512 * 1024,
+    total: 1024 * 1024,
+    speedBytesPerSecond: 128 * 1024,
+    serverObservedAt: 2000,
+    progressUpdatedAt: 2,
+};
+function render(change: Partial<Transfer> = {}, now = 2100) {
+    return renderToStaticMarkup(
+        createElement(TransferMetrics, { item: { ...item, ...change }, now }),
+    );
+}
+describe("visible transfer timing", () => {
+    it("shows throughput and estimated remaining time together", () => {
+        const html = render();
+        expect(html).toContain("128 KB/s");
+        expect(html).toContain("About 4s remaining");
+        expect(html).toContain(
+            'title="Estimated upload time for this stage. Verification and publishing may take longer."',
+        );
+        expect(html).not.toContain("Telegram");
+        expect(html).not.toContain("Calculating");
+        expect(render({ stage: "downloading" })).toContain("128 KB/s");
+    });
+    it("leaves unknown timing quiet and reports meaningful waits without fabricated speed", () => {
+        const initial = render({ speedBytesPerSecond: null });
+        expect(initial).not.toContain("Calculating speed");
+        expect(initial).not.toContain("Estimating time");
+        const stalled = render({}, 18000);
+        expect(stalled).toContain("No recent progress");
+        expect(stalled).not.toContain("Time estimate unavailable");
+        expect(stalled).not.toContain("128 KB/s");
+        expect(stalled).not.toContain("About");
+        expect(render({ total: 0 })).not.toContain("Time remaining unknown");
+        expect(render({ stage: "retry_wait" })).toContain(
+            "Waiting for Telegram",
+        );
+        expect(render({ stage: "source_retry_wait" })).toContain(
+            "Waiting to retry source",
+        );
+        expect(render({ stage: "source_retry_wait" })).not.toContain(
+            "No recent progress",
+        );
+        expect(render({ stage: "finalizing" })).toContain(
+            "Finishing this stage",
+        );
+    });
+});
diff --git a/website/src/features/transfers/TransferPanel.css b/website/src/features/transfers/TransferPanel.css
new file mode 100644
index 00000000..ba7b994c
--- /dev/null
+++ b/website/src/features/transfers/TransferPanel.css
@@ -0,0 +1,168 @@
+.transfer-center .transfer-bytes,
+.transfer-center .transfer-batch-percent,
+.transfer-center .transfer-metrics {
+    font-variant-numeric: tabular-nums;
+}
+
+.transfer-center .transfer-batch-percent {
+    min-inline-size: 3ch;
+    text-align: end;
+}
+
+.transfer-center .transfer-speed,
+.transfer-center .transfer-eta {
+    white-space: nowrap;
+}
+
+.transfer-center .transfer-timing-state {
+    overflow-wrap: anywhere;
+}
+
+.transfer-precheck-progress {
+    grid-column: 1 / -1;
+    block-size: 4px;
+    overflow: hidden;
+    border-radius: 6px;
+    background: var(--line);
+    margin-block: 5px;
+}
+
+.transfer-precheck-progress > span {
+    display: block;
+    inline-size: 30%;
+    block-size: 100%;
+    background: var(--action);
+}
+
+.transfer-source-wait {
+    grid-column: 1 / -1;
+    color: var(--muted);
+    font-size: 12px;
+    line-height: 1.5;
+    overflow-wrap: anywhere;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    .transfer-precheck-progress > span {
+        animation: transfer-checking 1.4s ease-in-out infinite alternate;
+    }
+    @keyframes transfer-checking {
+        to {
+            transform: translateX(233%);
+        }
+    }
+}
+
+.transfer-heading:has(.transfer-collapsed-status) h2 {
+    min-width: 0;
+}
+
+.transfer-collapsed-status {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.transfer-center .transfer-device-status {
+    display: block;
+    grid-column: 1 / -1;
+    min-width: 0;
+    color: var(--ink);
+    font-size: 11px;
+    line-height: 1.5;
+    overflow-wrap: anywhere;
+}
+
+.transfer-page .transfer-device-status {
+    font-size: 12px;
+}
+
+.transfer-center .transfer-batch-status .transfer-device-status {
+    display: inline-block;
+    max-inline-size: 100%;
+    color: inherit;
+    font-size: inherit;
+}
+
+/* One metadata baseline for the current transfer, above its progress bar. */
+.transfer-center
+    .transfer-item[data-live-metrics="true"]
+    .transfer-row-details {
+    display: flex;
+    align-items: baseline;
+    gap: 4px 14px;
+    color: var(--muted);
+    font-size: 12px;
+}
+
+.transfer-center
+    .transfer-item[data-live-metrics="true"]
+    .transfer-row-details
+    .transfer-metrics {
+    display: contents;
+    font-size: inherit;
+}
+
+.transfer-center
+    .transfer-item[data-live-metrics="true"]
+    .transfer-row-details
+    > .transfer-bytes {
+    white-space: nowrap;
+}
+
+@container (min-width: 600px) {
+    .transfer-page .transfer-item[data-live-metrics="true"] .transfer-copy {
+        grid-template-columns: minmax(0, 1fr) minmax(0, 1.5fr);
+        column-gap: 24px;
+    }
+
+    .transfer-page
+        .transfer-item[data-live-metrics="true"]
+        .transfer-copy
+        > .transfer-item-title {
+        grid-column: 1;
+        grid-row: 1;
+    }
+
+    .transfer-page .transfer-item[data-live-metrics="true"] .transfer-phase {
+        grid-column: 1;
+        grid-row: 2;
+    }
+
+    .transfer-page .transfer-item[data-live-metrics="true"] .transfer-location,
+    .transfer-page
+        .transfer-item[data-live-metrics="true"]
+        .transfer-relative-path {
+        grid-column: 1;
+        grid-row: 3;
+    }
+
+    .transfer-page
+        .transfer-item[data-live-metrics="true"]
+        .transfer-row-details {
+        grid-column: 2;
+        grid-row: 1 / 4;
+        justify-content: flex-end;
+        align-self: center;
+    }
+
+    .transfer-page
+        .transfer-item[data-live-metrics="true"]
+        .transfer-copy
+        > progress {
+        grid-column: 1 / -1;
+        grid-row: 4;
+    }
+
+    .transfer-page
+        .transfer-item[data-live-metrics="true"]
+        .transfer-item-actions {
+        align-self: center;
+    }
+}
+
+@container (min-width: 900px) {
+    .transfer-page .transfer-item[data-live-metrics="true"] .transfer-copy {
+        grid-template-columns: minmax(0, 1fr) auto;
+    }
+}
diff --git a/website/src/features/transfers/TransferPanel.tsx b/website/src/features/transfers/TransferPanel.tsx
new file mode 100644
index 00000000..1be9d3bc
--- /dev/null
+++ b/website/src/features/transfers/TransferPanel.tsx
@@ -0,0 +1,1375 @@
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import {
+    Upload,
+    ChevronDown,
+    ChevronRight,
+    ChevronUp,
+    X,
+    RotateCcw,
+    Check,
+    Pause,
+    AlertCircle,
+    Folder,
+    FolderOpen,
+    Clock3,
+    FileUp,
+} from "lucide-react";
+import {
+    transfers,
+    isTransferActive,
+    canCancelTransfer,
+    type Transfer,
+} from "./transfers";
+import { historyStatus } from "./transferHistory";
+import { deviceUploadMessage, needsDeviceUpload } from "./deviceUploadStatus";
+import {
+    summarizeBatches,
+    batchCategory,
+    type TransferBatch,
+} from "./transferBatches";
+import {
+    formatBytes,
+    formatByteProgress,
+    remainingBytesHint,
+    getTimezone,
+} from "../../shared/types";
+import { errorMessage } from "../../shared/api";
+import { Modal, Spinner } from "../../shared/components";
+import {
+    transferDetails,
+    transferProgress,
+    formatDuration,
+    formatProgressPercent,
+} from "./progress";
+import "./TransferPanel.css";
+
+export default function TransferPanel({
+    items,
+    onError,
+    expandedPage = false,
+    onLocate,
+    pageContext = "files",
+    finishedControls,
+    finishedEmpty,
+}: {
+    items: Transfer[];
+    onError: (message: string) => void;
+    expandedPage?: boolean;
+    pageContext?: string;
+    onLocate?: (item: Transfer, folder?: boolean) => void;
+    finishedControls?: ReactNode;
+    finishedEmpty?: ReactNode;
+}) {
+    // The Transfers page is global; the floating receipt belongs to this browser.
+    items = expandedPage
+        ? items
+        : items.filter((item) => item.initiatedHere === true);
+    const [collapsed, setCollapsed] = useState(
+        () =>
+            !!window.history.state?.tgdriveReveal ||
+            window.matchMedia("(max-width: 720px)").matches ||
+            pageContext !== "files",
+    );
+    const [notice, setNotice] = useState("");
+    const [expandedBatches, setExpandedBatches] = useState<Set<string>>(
+        new Set(),
+    );
+    const [cancelKeys, setCancelKeys] = useState<string[] | null>(null);
+    const input = useRef<HTMLInputElement>(null);
+    const bulkInput = useRef<HTMLInputElement>(null);
+    const folderInput = useRef<HTMLInputElement>(null);
+    const resumeKey = useRef("");
+    const resumeBatch = useRef("");
+    const active = items.filter(isTransferActive).length;
+    const unresolved =
+        active > 0 || items.some((item) => item.state === "error");
+    const [floatingVisible, setFloatingVisible] = useState(unresolved);
+    useEffect(() => {
+        if (expandedPage) return;
+        if (unresolved) {
+            setFloatingVisible(true);
+            return;
+        }
+        // A recent upload may show its completion briefly; fetched history stays quiet.
+        const timer = setTimeout(() => setFloatingVisible(false), 5000);
+        return () => clearTimeout(timer);
+    }, [unresolved, expandedPage]);
+    useEffect(() => {
+        if (!expandedPage && pageContext !== "files") setCollapsed(true);
+    }, [pageContext, expandedPage]);
+    const [now, setNow] = useState(Date.now);
+    useEffect(() => {
+        if (!active) return;
+        const timer = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(timer);
+    }, [active]);
+    const batches = summarizeBatches(
+        items,
+        now,
+        transfers.batchProgressSnapshot(),
+    );
+    const deviceUploadsPending =
+        items.some(needsDeviceUpload) ||
+        transfers.snapshot().some(needsDeviceUpload);
+    const deviceMessage = deviceUploadMessage(items, deviceUploadsPending);
+    const collapsedDeviceLabel =
+        !expandedPage && collapsed && deviceMessage
+            ? deviceUploadsPending
+                ? "Keep this tab open"
+                : "You can close this tab"
+            : null;
+    const categories = expandedPage
+        ? [
+              { key: "running", label: "Running" },
+              { key: "queued", label: "Queued" },
+              { key: "finished", label: "Finished" },
+          ]
+        : [
+              { key: "running", label: "Running" },
+              { key: "queued", label: "Queued" },
+              { key: "error", label: "Needs Attention" },
+              { key: "completed", label: "Completed" },
+              { key: "cancelled", label: "Cancelled" },
+          ];
+    const groups = categories
+        .map((category) => {
+            const groupedBatches = batches.filter((batch) =>
+                category.key === "finished"
+                    ? !["running", "queued"].includes(batchCategory(batch))
+                    : batchCategory(batch) === category.key,
+            );
+            if (category.key === "finished") {
+                const created = (batch: TransferBatch) =>
+                    Math.min(
+                        ...batch.items.map(
+                            (item) =>
+                                item.batchCreatedAt || item.createdAt || 0,
+                        ),
+                    );
+                groupedBatches.sort(
+                    (a, b) =>
+                        created(b) - created(a) || a.id.localeCompare(b.id),
+                );
+            }
+            return {
+                ...category,
+                batches: groupedBatches,
+                count: groupedBatches.length,
+            };
+        })
+        .filter(
+            (group) =>
+                group.count > 0 ||
+                (group.key === "finished" && finishedControls),
+        );
+
+    const cancellable = items.filter(canCancelTransfer);
+    const cancelCount = cancelKeys
+        ? batches.filter((batch) =>
+              batch.items.some(
+                  (item) =>
+                      canCancelTransfer(item) && cancelKeys.includes(item.key),
+              ),
+          ).length
+        : 0;
+    const pending = batches.filter((batch) => batch.pending).length;
+    const heading = batches.some((batch) => batch.active > 0)
+        ? pending +
+          (pending === 1 ? " upload in progress" : " uploads in progress")
+        : batches.some((batch) => batch.queued > 0)
+          ? pending + (pending === 1 ? " upload waiting" : " uploads waiting")
+          : batches.some((batch) => batch.failed || batch.awaiting)
+            ? "Uploads Need Attention"
+            : "Transfers";
+    const folderPickerSupported =
+        "webkitdirectory" in document.createElement("input");
+    const run = (task: Promise<unknown>) => {
+        void task.catch((error) => onError(errorMessage(error)));
+    };
+    const reselect = async (files: File[]) => {
+        const result = await transfers.resumeBatchFiles(
+            resumeBatch.current,
+            files,
+        );
+        setNotice(
+            result.matched +
+                (result.matched === 1 ? " file" : " files") +
+                " queued for verification." +
+                (result.remaining
+                    ? " " +
+                      result.remaining +
+                      " still need their original files."
+                    : "") +
+                (result.unmatched
+                    ? " " +
+                      result.unmatched +
+                      " selected files did not match this upload."
+                    : "") +
+                (result.errors.length ? " " + result.errors[0] : ""),
+        );
+    };
+    if (!expandedPage && !floatingVisible) return null;
+    if (!items.length && !finishedControls)
+        return expandedPage ? (
+            <div className="empty-state">
+                <Upload size={40} />
+                <h2>No Transfers Yet</h2>
+                <p>Uploads started from a folder in My Files appear here.</p>
+            </div>
+        ) : null;
+    return (
+        <section
+            id="transfer-dialog"
+            className={
+                "transfer-center " + (expandedPage ? "transfer-page" : "")
+            }
+            aria-label="Transfers"
+        >
+            <header
+                className="transfer-heading"
+                hidden={expandedPage && !cancellable.length}
+            >
+                <h2
+                    id="transfer-summary"
+                    className={expandedPage ? "sr-only" : undefined}
+                    title={
+                        collapsedDeviceLabel
+                            ? deviceMessage || undefined
+                            : undefined
+                    }
+                >
+                    <Upload size={18} />
+                    {expandedPage ? (
+                        batches.length +
+                        (batches.length === 1
+                            ? " transfer shown"
+                            : " transfers shown")
+                    ) : collapsedDeviceLabel ? (
+                        <span
+                            className="transfer-collapsed-status"
+                            role="status"
+                        >
+                            {collapsedDeviceLabel}
+                        </span>
+                    ) : (
+                        heading
+                    )}
+                </h2>
+                <div className="inline-actions">
+                    {cancellable.length > 0 && (
+                        <button
+                            className="text-button"
+                            onClick={() =>
+                                setCancelKeys(
+                                    cancellable.map((item) => item.key),
+                                )
+                            }
+                        >
+                            Cancel All
+                        </button>
+                    )}
+                    {!expandedPage && (
+                        <button
+                            id="transfer-toggle"
+                            className="text-button"
+                            onClick={() => setCollapsed(!collapsed)}
+                            aria-expanded={!collapsed}
+                            aria-controls="transfer-list"
+                            aria-label={
+                                collapsed
+                                    ? "Show Transfer Details"
+                                    : "Hide Transfer Details"
+                            }
+                            title={
+                                collapsed
+                                    ? "Show Transfer Details"
+                                    : "Hide details; uploads keep running"
+                            }
+                        >
+                            {collapsed ? "Show" : "Hide"}
+                            {collapsed ? (
+                                <ChevronUp size={15} />
+                            ) : (
+                                <ChevronDown size={15} />
+                            )}
+                        </button>
+                    )}
+                </div>
+            </header>
+            {notice && (
+                <p className="transfer-notice" role="status">
+                    {notice}
+                </p>
+            )}
+            <div
+                id="transfer-list"
+                className="transfer-list"
+                hidden={collapsed && !expandedPage}
+            >
+                {groups.map((group) => (
+                    <section
+                        className="transfer-category"
+                        data-category={group.key}
+                        key={group.key}
+                        aria-label={group.label}
+                    >
+                        <h3
+                            className="transfer-category-title"
+                            hidden={!expandedPage && groups.length === 1}
+                        >
+                            {group.label}
+                            <span>{group.count}</span>
+                        </h3>
+                        {group.key === "finished" && finishedControls}
+                        {group.key === "finished" &&
+                            !group.count &&
+                            finishedEmpty}
+                        <div role="list">
+                            {group.batches.map((batch) => (
+                                <BatchTransfer
+                                    key={batch.id}
+                                    batch={batch}
+                                    deviceUploadsPending={deviceUploadsPending}
+                                    expanded={expandedBatches.has(batch.id)}
+                                    onToggleExpanded={() =>
+                                        setExpandedBatches((previous) => {
+                                            const next = new Set(
+                                                [...previous].filter((id) =>
+                                                    batches.some(
+                                                        (current) =>
+                                                            current.id === id,
+                                                    ),
+                                                ),
+                                            );
+                                            if (next.has(batch.id))
+                                                next.delete(batch.id);
+                                            else next.add(batch.id);
+                                            return next;
+                                        })
+                                    }
+                                    onLocate={
+                                        onLocate
+                                            ? (item, folder) => {
+                                                  setCollapsed(true);
+                                                  onLocate(item, folder);
+                                              }
+                                            : undefined
+                                    }
+                                    showTimestamp={expandedPage}
+                                    now={now}
+                                    run={run}
+                                    onChooseFile={(key) => {
+                                        resumeKey.current = key;
+                                        input.current?.click();
+                                    }}
+                                    onChooseBatch={() => {
+                                        resumeBatch.current = batch.id;
+                                        if (batch.folder)
+                                            folderInput.current?.click();
+                                        else bulkInput.current?.click();
+                                    }}
+                                    folderPickerSupported={
+                                        folderPickerSupported
+                                    }
+                                />
+                            ))}
+                        </div>
+                    </section>
+                ))}
+            </div>
+            {!expandedPage &&
+                !collapsed &&
+                batches.some((batch) => !batch.pending) && (
+                    <div className="transfer-footer">
+                        <button
+                            id="transfer-clear"
+                            className="text-button"
+                            onClick={() => transfers.clearFinished()}
+                            title="Remove completed and cancelled uploads from this list"
+                        >
+                            Clear Finished
+                        </button>
+                    </div>
+                )}
+            {cancelKeys !== null && (
+                <Modal
+                    title="Cancel All Uploads?"
+                    initialFocus="[data-keep-uploading]"
+                    onClose={() => setCancelKeys(null)}
+                >
+                    <p>
+                        Cancel {cancelCount} unfinished{" "}
+                        {cancelCount === 1 ? "upload" : "uploads"}? Files
+                        already in your drive will be kept.
+                    </p>
+                    <div className="dialog-actions">
+                        <button
+                            className="secondary-button"
+                            data-keep-uploading
+                            onClick={() => setCancelKeys(null)}
+                        >
+                            Keep Uploading
+                        </button>
+                        <button
+                            className="danger-button"
+                            disabled={!cancelCount}
+                            onClick={() => {
+                                const keys = cancelKeys;
+                                setCancelKeys(null);
+                                run(transfers.cancelAll(keys));
+                            }}
+                        >
+                            Cancel Uploads
+                        </button>
+                    </div>
+                </Modal>
+            )}
+            {transfers.recoveryWarning && (
+                <p
+                    className="transfer-help transfer-storage-warning"
+                    role="status"
+                >
+                    {transfers.recoveryWarning}
+                </p>
+            )}
+            <input
+                ref={input}
+                type="file"
+                hidden
+                aria-label="Choose Original File to Resume"
+                onChange={(event) => {
+                    const file = event.target.files?.[0];
+                    if (file) run(transfers.resume(resumeKey.current, file));
+                    event.target.value = "";
+                }}
+            />
+            <input
+                ref={bulkInput}
+                type="file"
+                multiple
+                hidden
+                aria-label="Choose Original Files to Resume"
+                onChange={(event) => {
+                    const files = Array.from(event.target.files || []);
+                    if (files.length) run(reselect(files));
+                    event.target.value = "";
+                }}
+            />
+            <input
+                ref={(node) => {
+                    folderInput.current = node;
+                    node?.setAttribute("webkitdirectory", "");
+                }}
+                type="file"
+                multiple
+                hidden
+                aria-label="Choose Original Folder to Resume"
+                onChange={(event) => {
+                    const files = Array.from(event.target.files || []);
+                    if (files.length) run(reselect(files));
+                    event.target.value = "";
+                }}
+            />
+        </section>
+    );
+}
+
+function batchStatus(batch: TransferBatch, deviceStage: boolean) {
+    const counts = [
+        deviceStage
+            ? batch.device.pending
+                ? "Uploading from device"
+                : "Received"
+            : "Uploading to Telegram",
+    ];
+    if (batch.count > 1 && (!deviceStage || batch.device.pending))
+        counts.push(
+            deviceStage
+                ? batch.device.received +
+                      " of " +
+                      batch.device.count +
+                      " received"
+                : batch.completed + " of " + batch.count + " uploaded",
+        );
+    const attention = batch.device.pending
+        ? batch.items.filter(needsDeviceUpload)
+        : batch.items;
+    const failed = attention.filter((item) => item.state === "error").length;
+    const awaiting = attention.filter(
+        (item) => item.state === "awaiting_file",
+    ).length;
+    if (failed) counts.push(failed + " failed");
+    if (awaiting) counts.push(awaiting + " need originals");
+    if (batch.cancelled) counts.push(batch.cancelled + " cancelled");
+    return counts.join(" · ");
+}
+
+export function BatchTransfer({
+    batch,
+    deviceUploadsPending,
+    expanded,
+    onToggleExpanded,
+    now,
+    run,
+    onChooseFile,
+    onChooseBatch,
+    folderPickerSupported,
+    showTimestamp = false,
+    onLocate,
+}: {
+    onLocate?: (item: Transfer, folder?: boolean) => void;
+    batch: TransferBatch;
+    deviceUploadsPending: boolean;
+    expanded: boolean;
+    onToggleExpanded: () => void;
+    showTimestamp?: boolean;
+    now: number;
+    run: (task: Promise<unknown>) => void;
+    onChooseFile: (key: string) => void;
+    onChooseBatch: () => void;
+    folderPickerSupported: boolean;
+}) {
+    const [filter, setFilter] = useState("all");
+    const [limit, setLimit] = useState(20);
+    const listId = useId();
+    const hasFolder = batch.folder;
+    const deviceMessage = deviceUploadMessage(
+        batch.items,
+        deviceUploadsPending,
+    );
+    // Keep the browser's pending uploads in one visible phase, even when a
+    // different batch has already handed its files to the server.
+    const deviceStage =
+        batch.device.pending ||
+        (deviceUploadsPending &&
+            batch.pending &&
+            batch.items.some(
+                (item) =>
+                    !item.historyOnly &&
+                    !["remote", "delete"].includes(item.kind || ""),
+            ));
+    const receiptComplete = deviceStage && !batch.device.pending;
+    if (!hasFolder)
+        return (
+            <>
+                {batch.items.map((item) => (
+                    <TransferRow
+                        key={item.key}
+                        item={item}
+                        deviceUploadsPending={deviceUploadsPending}
+                        deviceStage={deviceStage}
+                        onLocate={onLocate}
+                        showTimestamp={showTimestamp}
+                        now={now}
+                        run={run}
+                        onChooseFile={onChooseFile}
+                    />
+                ))}
+            </>
+        );
+    const folderItem = batch.items.find((item) => item.state === "completed");
+    const canShowFolder =
+        hasFolder &&
+        !!onLocate &&
+        !!folderItem &&
+        batch.items.every((item) => item.state === "completed");
+    const finishedTimes = batch.items
+        .map((item) => item.finishedAt)
+        .filter(
+            (value): value is number =>
+                typeof value === "number" &&
+                Number.isFinite(value) &&
+                value > 0 &&
+                value <= 8.64e15,
+        );
+    const finishedAt =
+        !batch.pending && finishedTimes.length === batch.count
+            ? Math.max(...finishedTimes)
+            : undefined;
+    const locations = [
+        ...new Set(
+            batch.items
+                .map((item) =>
+                    item.location?.available
+                        ? item.location.folder_label
+                        : undefined,
+                )
+                .filter((label): label is string => !!label),
+        ),
+    ];
+    let locationLabel =
+        locations.length === 1
+            ? locations[0]
+            : locations.length > 1
+              ? locations.length + " folders"
+              : batch.items.every((item) => item.destination === "/")
+                ? "My Files"
+                : "";
+    if (hasFolder) {
+        const source = batch.items.find(
+            (item) => item.location?.available && item.location.folder_label,
+        );
+        if (source?.location?.folder_label) {
+            const root = source.folderUpload?.root_path
+                .split("/")
+                .filter(Boolean);
+            const destination = source.destination.split("/").filter(Boolean);
+            const depth = source.relativePath
+                ? Math.max(0, source.relativePath.split("/").length - 2)
+                : root &&
+                    root.every((name, index) => destination[index] === name)
+                  ? destination.length - root.length
+                  : 0;
+            const names = source.location.folder_label.split(" / ");
+            locationLabel = names
+                .slice(0, Math.max(1, names.length - depth))
+                .join(" / ");
+        }
+    }
+    if (batch.cancelled === batch.count) locationLabel = "";
+    const showProgress =
+        batch.pending && batch.active + batch.queued > 0 && !receiptComplete;
+    const displayTotal =
+        deviceStage && batch.device.count > 0
+            ? batch.device.total
+            : batch.totalBytes;
+    const displayRate = receiptComplete ? undefined : batch.displayRate;
+    const displayEta = receiptComplete ? undefined : batch.displayEta;
+    const received = (item: Transfer) =>
+        !needsDeviceUpload(item) && item.state !== "cancelled";
+    const activeFile = (item: Transfer) =>
+        isTransferActive(item) &&
+        item.state !== "awaiting_file" &&
+        (!deviceStage || needsDeviceUpload(item));
+    const activeCount = batch.items.filter(activeFile).length;
+    const receivedCount = batch.items.filter(received).length;
+    const mixedStatuses =
+        [
+            activeCount,
+            batch.failed + batch.awaiting,
+            deviceStage ? receivedCount : batch.completed,
+            batch.cancelled,
+        ].filter((count) => count > 0).length > 1;
+    const canCancel = batch.items.some(
+        (item) =>
+            canCancelTransfer(item) &&
+            (isTransferActive(item) || item.state === "error"),
+    );
+    const needsFiles = batch.items.some(
+        (item) =>
+            item.state === "awaiting_file" ||
+            (item.state === "error" && !item.jobId && !item.file),
+    );
+    const filtered = batch.items.filter(
+        (item) =>
+            !mixedStatuses ||
+            filter === "all" ||
+            (filter === "active" && activeFile(item)) ||
+            (filter === "attention" &&
+                (item.state === "error" || item.state === "awaiting_file")) ||
+            (filter === "completed" &&
+                (deviceStage ? received(item) : item.state === "completed")) ||
+            (filter === "cancelled" && item.state === "cancelled"),
+    );
+    const filters = [
+        { key: "all", label: "All", count: batch.count },
+        { key: "active", label: "Active", count: activeCount },
+        {
+            key: "attention",
+            label: "Needs Attention",
+            count: batch.failed + batch.awaiting,
+        },
+        {
+            key: "completed",
+            label: deviceStage ? "Received" : "Done",
+            count: deviceStage ? receivedCount : batch.completed,
+        },
+        { key: "cancelled", label: "Cancelled", count: batch.cancelled },
+    ].filter(
+        (entry) =>
+            entry.key === "all" || entry.count > 0 || entry.key === filter,
+    );
+    return (
+        <article
+            className="transfer-batch"
+            role="listitem"
+            data-batch-id={batch.id}
+            data-cancelled={batch.cancelled === batch.count || undefined}
+            data-folder={hasFolder || undefined}
+            data-expanded={expanded}
+            data-stage={deviceStage ? "device" : "telegram"}
+            data-status={
+                !batch.pending
+                    ? "finished"
+                    : batch.failed || batch.awaiting
+                      ? "attention"
+                      : "active"
+            }
+        >
+            <div className="transfer-batch-summary">
+                <div className="transfer-batch-title">
+                    <button
+                        type="button"
+                        className="transfer-batch-toggle"
+                        aria-label={expanded ? "Hide Files" : "Show Files"}
+                        aria-describedby={listId + "-name"}
+                        aria-expanded={expanded}
+                        aria-controls={listId}
+                        onClick={onToggleExpanded}
+                        onDoubleClick={(event) => {
+                            event.preventDefault();
+                            event.stopPropagation();
+                        }}
+                    >
+                        {expanded ? (
+                            <ChevronDown size={15} />
+                        ) : (
+                            <ChevronRight size={15} />
+                        )}
+                        <span
+                            className="transfer-group-icon"
+                            aria-hidden="true"
+                        >
+                            <Folder size={20} />
+                        </span>
+                        <strong
+                            id={listId + "-name"}
+                            className="transfer-batch-name"
+                            title={batch.name}
+                        >
+                            {batch.name}
+                        </strong>
+                        {hasFolder && (
+                            <span className="transfer-batch-count">
+                                {batch.count}{" "}
+                                {batch.count === 1 ? "file" : "files"}
+                            </span>
+                        )}
+                    </button>
+                    {showProgress && batch.progress !== undefined && (
+                        <span className="transfer-batch-percent">
+                            {formatProgressPercent(batch.progress)}
+                        </span>
+                    )}
+                </div>
+                {locationLabel && (
+                    <span
+                        className="transfer-batch-location"
+                        title={locationLabel}
+                    >
+                        {locationLabel}
+                    </span>
+                )}
+                {batch.pending && (
+                    <p className="transfer-batch-status" aria-live="polite">
+                        {batchStatus(batch, deviceStage)}
+                        {deviceMessage && (
+                            <span className="transfer-device-status">
+                                {" "}
+                                · {deviceMessage}
+                            </span>
+                        )}
+                    </p>
+                )}
+                {showTimestamp && finishedAt && (
+                    <time
+                        className="transfer-batch-time"
+                        dateTime={new Date(finishedAt).toISOString()}
+                        title={new Intl.DateTimeFormat(undefined, {
+                            dateStyle: "full",
+                            timeStyle: "short",
+                            timeZone: getTimezone(),
+                        }).format(finishedAt)}
+                    >
+                        {new Intl.DateTimeFormat(undefined, {
+                            dateStyle: "medium",
+                            timeStyle: "short",
+                            timeZone: getTimezone(),
+                        }).format(finishedAt)}
+                    </time>
+                )}
+                {canShowFolder && folderItem && onLocate && (
+                    <button
+                        className="icon-button transfer-batch-locate"
+                        aria-label={"Show " + batch.name + " folder"}
+                        title="Show Folder"
+                        onClick={() => onLocate(folderItem, true)}
+                    >
+                        <FolderOpen size={18} />
+                    </button>
+                )}
+                {canCancel && (
+                    <button
+                        className="icon-button transfer-batch-cancel"
+                        aria-label="Cancel Upload"
+                        title="Cancel Upload"
+                        onClick={() => run(transfers.cancelBatch(batch.id))}
+                    >
+                        <X size={18} />
+                    </button>
+                )}
+                {showProgress && (
+                    <progress
+                        aria-label={
+                            (deviceStage
+                                ? "Device upload"
+                                : "Telegram upload") +
+                            " progress for " +
+                            batch.name
+                        }
+                        max={1}
+                        value={batch.progress}
+                    />
+                )}
+                <div className="transfer-batch-metrics">
+                    {displayTotal !== undefined && (
+                        <span className="transfer-batch-size">
+                            {batch.pending && !receiptComplete
+                                ? formatByteProgress(
+                                      batch.displayBytes,
+                                      displayTotal,
+                                  )
+                                : formatBytes(displayTotal)}
+                        </span>
+                    )}
+                    <span className="transfer-batch-throughput">
+                        {displayRate && (
+                            <span>{formatBytes(displayRate)}/s</span>
+                        )}
+                        {displayEta !== undefined && (
+                            <span
+                                title={
+                                    deviceStage
+                                        ? "Estimated upload time from your device. Server verification may take longer."
+                                        : "Estimated upload time to Telegram. Publishing and retries may take longer."
+                                }
+                            >
+                                About{" "}
+                                {formatDuration(
+                                    Math.max(1, Math.ceil(displayEta)),
+                                )}{" "}
+                                remaining
+                            </span>
+                        )}
+                    </span>
+                </div>
+                {(needsFiles ||
+                    batch.items.some(
+                        (item) =>
+                            item.state === "error" &&
+                            !item.historyOnly &&
+                            (item.jobId || item.file),
+                    )) && (
+                    <div className="transfer-batch-actions">
+                        {needsFiles &&
+                            (!hasFolder || folderPickerSupported) && (
+                                <button
+                                    type="button"
+                                    className="secondary-button transfer-recovery-button"
+                                    onClick={onChooseBatch}
+                                >
+                                    <FileUp size={15} />
+                                    {hasFolder
+                                        ? "Choose Folder"
+                                        : "Choose Files"}
+                                </button>
+                            )}
+                        {batch.items.some(
+                            (item) =>
+                                item.state === "error" &&
+                                !item.historyOnly &&
+                                (item.jobId || item.file),
+                        ) && (
+                            <button
+                                type="button"
+                                className="text-button"
+                                onClick={() =>
+                                    run(transfers.retryBatch(batch.id))
+                                }
+                            >
+                                <RotateCcw size={14} />
+                                Retry Failed
+                            </button>
+                        )}
+                    </div>
+                )}
+            </div>
+            {expanded && (
+                <div className="transfer-batch-files" id={listId}>
+                    {mixedStatuses && (
+                        <div className="transfer-files-toolbar">
+                            <div
+                                className="transfer-filters"
+                                role="group"
+                                aria-label={"Files shown for " + batch.name}
+                            >
+                                {filters.map((entry) => (
+                                    <button
+                                        key={entry.key}
+                                        type="button"
+                                        data-filter={entry.key}
+                                        aria-pressed={filter === entry.key}
+                                        onClick={() => {
+                                            setFilter(entry.key);
+                                            setLimit(20);
+                                        }}
+                                    >
+                                        {entry.label} <span>{entry.count}</span>
+                                    </button>
+                                ))}
+                            </div>
+                        </div>
+                    )}
+                    <div role="list">
+                        {filtered.slice(0, limit).map((item) => (
+                            <TransferRow
+                                key={item.key}
+                                item={item}
+                                onLocate={onLocate}
+                                compactChild
+                                deviceStage={deviceStage}
+                                groupLocation={
+                                    hasFolder ? locationLabel : undefined
+                                }
+                                showTimestamp={false}
+                                now={now}
+                                run={run}
+                                onChooseFile={onChooseFile}
+                            />
+                        ))}
+                    </div>
+                    {!filtered.length && (
+                        <p className="transfer-no-files">
+                            No files in this view.
+                        </p>
+                    )}
+                    {filtered.length > limit && (
+                        <button
+                            type="button"
+                            className="text-button transfer-show-more"
+                            onClick={() => setLimit((value) => value + 20)}
+                        >
+                            Show more ({filtered.length - limit} remaining)
+                        </button>
+                    )}
+                </div>
+            )}
+        </article>
+    );
+}
+
+function TransferRow({
+    item,
+    deviceUploadsPending,
+    now,
+    showTimestamp = false,
+    compactChild = false,
+    deviceStage = false,
+    groupLocation,
+    onLocate,
+    run,
+    onChooseFile,
+}: {
+    compactChild?: boolean;
+    deviceStage?: boolean;
+    groupLocation?: string;
+    onLocate?: (item: Transfer, folder?: boolean) => void;
+    item: Transfer;
+    deviceUploadsPending?: boolean;
+    now: number;
+    showTimestamp?: boolean;
+    run: (task: Promise<unknown>) => void;
+    onChooseFile: (key: string) => void;
+}) {
+    const fullLocation = item.location?.available
+        ? item.location.folder_label || ""
+        : item.location?.reason || "";
+    const displayLocation =
+        groupLocation && fullLocation === groupLocation
+            ? ""
+            : groupLocation && fullLocation.startsWith(groupLocation + " / ")
+              ? fullLocation.slice(groupLocation.length + 3)
+              : fullLocation;
+    const relativeDirectory = item.relativePath
+        ?.split("/")
+        .slice(1, -1)
+        .join(" / ");
+    const meter = usePresentedProgress(item);
+    const status = historyStatus(item);
+    const finished = status === "completed" || status === "cancelled";
+    const received =
+        deviceStage && !needsDeviceUpload(item) && item.state !== "cancelled";
+    const checkingSource =
+        item.kind === "remote" &&
+        ["checking_source", "source_retry_wait"].includes(item.stage || "") &&
+        item.state === "uploading";
+    const sourceWaiting =
+        checkingSource &&
+        ["Checking source…", "Starting URL import…"].includes(item.phase) &&
+        item.serverStatus !== "queued" &&
+        now - (item.startedAt || item.createdAt || now) >= 5000;
+    const deviceMessage =
+        !compactChild && deviceUploadMessage([item], deviceUploadsPending);
+    const liveMetrics =
+        !received &&
+        !finished &&
+        status !== "queued" &&
+        !["error", "awaiting_file"].includes(item.state);
+    const showPercent =
+        !received &&
+        !finished &&
+        status !== "queued" &&
+        meter.fraction !== undefined;
+    const needsOriginal =
+        item.kind !== "remote" &&
+        (item.state === "awaiting_file" ||
+            (item.state === "error" && !item.jobId && !item.file));
+    const canLocate =
+        !!onLocate &&
+        item.state === "completed" &&
+        item.location?.available !== false;
+    const recordedAt = item.finishedAt || item.createdAt;
+    const validRecordedAt =
+        typeof recordedAt === "number" &&
+        Number.isFinite(recordedAt) &&
+        recordedAt > 0 &&
+        recordedAt <= 8.64e15;
+    return (
+        <article
+            className={
+                "transfer-item" + (compactChild ? " transfer-child" : "")
+            }
+            role="listitem"
+            data-status={item.state}
+            data-live-metrics={liveMetrics || undefined}
+            onDoubleClick={(event) => {
+                if (
+                    canLocate &&
+                    !(event.target as HTMLElement).closest("button,input,a")
+                )
+                    onLocate?.(item);
+            }}
+        >
+            <div className="transfer-state-icon">
+                {item.state === "error" ? (
+                    <AlertCircle size={19} />
+                ) : received || item.state === "completed" ? (
+                    <Check size={19} />
+                ) : item.state === "awaiting_file" ? (
+                    <Pause size={19} />
+                ) : item.state === "cancelled" ? (
+                    <X size={19} />
+                ) : status === "queued" ? (
+                    <Clock3 size={19} />
+                ) : (
+                    <Upload size={19} />
+                )}
+            </div>
+            <div className="transfer-copy">
+                <div className="transfer-item-title">
+                    <strong className="transfer-item-name" title={item.name}>
+                        {item.name}
+                    </strong>
+                    {showPercent && !liveMetrics && (
+                        <span className="transfer-batch-percent">
+                            {formatProgressPercent(meter.fraction!)}
+                        </span>
+                    )}
+                </div>
+                {item.relativePath &&
+                    !item.location?.available &&
+                    (!compactChild || !!relativeDirectory) && (
+                        <span
+                            className="transfer-relative-path"
+                            title={item.relativePath}
+                        >
+                            {compactChild
+                                ? relativeDirectory
+                                : item.relativePath}
+                        </span>
+                    )}
+                {needsOriginal ? (
+                    <div className="transfer-recovery">
+                        <span className="transfer-recovery-message">
+                            Choose the original file to resume
+                        </span>
+                        <button
+                            className="secondary-button transfer-recovery-button"
+                            onClick={() => onChooseFile(item.key)}
+                        >
+                            <FileUp size={16} aria-hidden="true" /> Choose File
+                        </button>
+                    </div>
+                ) : (
+                    (received || !finished) && (
+                        <span
+                            className={
+                                "transfer-phase" +
+                                (item.state === "verifying" || checkingSource
+                                    ? " transfer-verification"
+                                    : "")
+                            }
+                            role={checkingSource ? "status" : undefined}
+                        >
+                            {!received &&
+                                (item.state === "verifying" ||
+                                    checkingSource) && <Spinner />}
+                            {received ? "Received" : item.phase}
+                        </span>
+                    )
+                )}
+                {item.state !== "cancelled" &&
+                    item.location &&
+                    displayLocation && (
+                        <span
+                            className="transfer-location"
+                            title={
+                                item.location.display_path ||
+                                item.location.reason
+                            }
+                        >
+                            {displayLocation}
+                        </span>
+                    )}
+                {!checkingSource && (
+                    <div className="transfer-row-details">
+                        {liveMetrics && (
+                            <TransferMetrics item={item} now={now} />
+                        )}
+                        {showPercent && liveMetrics && (
+                            <span className="transfer-batch-percent">
+                                {formatProgressPercent(meter.fraction!)}
+                            </span>
+                        )}
+                        <span
+                            className="transfer-bytes"
+                            title={
+                                !received && item.state === "receiving"
+                                    ? "Bytes sent by this browser. Resume positions are saved only after the server confirms each chunk."
+                                    : !received &&
+                                        item.jobId &&
+                                        ["uploading", "finalizing"].includes(
+                                            item.stage || "",
+                                        ) &&
+                                        !finished
+                                      ? "Bytes sent to Telegram, including parts still uploading. Each part appears in the channel after it finishes."
+                                      : undefined
+                            }
+                        >
+                            {received || finished || status === "queued"
+                                ? formatBytes(item.size || item.total)
+                                : formatByteProgress(
+                                      meter.current,
+                                      meter.total,
+                                  )}
+                        </span>
+                        {!received &&
+                            !liveMetrics &&
+                            !finished &&
+                            status !== "queued" && (
+                                <TransferMetrics item={item} now={now} />
+                            )}
+                        {showTimestamp && finished && validRecordedAt && (
+                            <time
+                                className="transfer-history-time"
+                                dateTime={new Date(recordedAt).toISOString()}
+                                title={new Intl.DateTimeFormat(undefined, {
+                                    dateStyle: "full",
+                                    timeStyle: "short",
+                                    timeZone: getTimezone(),
+                                }).format(recordedAt)}
+                            >
+                                {new Intl.DateTimeFormat(undefined, {
+                                    dateStyle: "medium",
+                                    timeStyle: "short",
+                                    timeZone: getTimezone(),
+                                }).format(recordedAt)}
+                            </time>
+                        )}
+                    </div>
+                )}
+                {checkingSource && (
+                    <div
+                        className="transfer-precheck-progress"
+                        role="progressbar"
+                        aria-label={item.phase + " for " + item.name}
+                    >
+                        <span />
+                    </div>
+                )}
+                {liveMetrics && !checkingSource && (
+                    <progress
+                        aria-label={item.phase + " for " + item.name}
+                        max={1}
+                        value={meter.fraction}
+                    />
+                )}
+                {sourceWaiting && (
+                    <span className="transfer-source-wait">
+                        {item.jobId
+                            ? "The source is taking longer to respond. You can keep browsing."
+                            : "Waiting for server confirmation. You can keep browsing."}
+                    </span>
+                )}
+                {deviceMessage && (
+                    <span className="transfer-device-status" role="status">
+                        {deviceMessage}
+                    </span>
+                )}
+                {item.state !== "cancelled" && item.error && (
+                    <span className="transfer-error">{item.error}</span>
+                )}
+            </div>
+            <div className="transfer-item-actions">
+                {canLocate && (
+                    <button
+                        className="icon-button"
+                        aria-label={"Show " + item.name + " in folder"}
+                        title="Show in Folder"
+                        onClick={() => onLocate?.(item)}
+                    >
+                        <FolderOpen size={18} />
+                    </button>
+                )}
+                {item.state === "error" &&
+                    !item.historyOnly &&
+                    !needsOriginal && (
+                        <button
+                            className="icon-button"
+                            aria-label={"Retry " + item.name}
+                            onClick={() => run(transfers.retry(item.key))}
+                        >
+                            <RotateCcw size={17} />
+                        </button>
+                    )}
+                {canCancelTransfer(item) &&
+                    (isTransferActive(item) || item.state === "error") && (
+                        <button
+                            className="icon-button"
+                            aria-label={"Cancel " + item.name}
+                            onClick={() => run(transfers.cancel(item.key))}
+                        >
+                            <X size={18} />
+                        </button>
+                    )}
+            </div>
+        </article>
+    );
+}
+
+/** Ease toward measured bytes only; a stalled transport never advances on a timer. */
+function usePresentedProgress(item: Transfer) {
+    const measured = transferProgress(item);
+    const stage = item.state + ":" + (item.stage || "");
+    const [display, setDisplay] = useState(() => ({
+        stage,
+        total: measured.total,
+        current: measured.current,
+    }));
+    const shown = useRef(display);
+    useEffect(() => {
+        const target = {
+            stage,
+            total: measured.total,
+            current: measured.current,
+        };
+        const previous = shown.current;
+        if (
+            previous.stage !== stage ||
+            previous.total !== target.total ||
+            target.current <= previous.current ||
+            window.matchMedia("(prefers-reduced-motion: reduce)").matches
+        ) {
+            shown.current = target;
+            setDisplay(target);
+            return;
+        }
+        const start = performance.now();
+        let frame = 0;
+        const tick = (now: number) => {
+            const elapsed = Math.min(1, (now - start) / 180);
+            const fraction = 1 - (1 - elapsed) ** 3;
+            const next = {
+                ...target,
+                current:
+                    elapsed === 1
+                        ? target.current
+                        : previous.current +
+                          (target.current - previous.current) * fraction,
+            };
+            shown.current = next;
+            setDisplay(next);
+            if (elapsed < 1) frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frame);
+    }, [stage, measured.current, measured.total]);
+    // Stage changes and retries never show bytes carried over from the previous stage.
+    if (display.stage !== stage || display.total !== measured.total)
+        return measured;
+    return transferProgress({
+        ...item,
+        current: Math.min(display.current, measured.current),
+        sentCurrent: undefined,
+    });
+}
+
+export function TransferMetrics({
+    item,
+    now,
+}: {
+    item: Transfer;
+    now: number;
+}) {
+    const details = transferDetails(item, now);
+    const meter = transferProgress(item);
+    const remaining =
+        ["receiving", "uploading"].includes(item.state) &&
+        ![
+            "queued",
+            "retry_wait",
+            "source_retry_wait",
+            "waiting_for_telegram",
+        ].includes(item.stage || "")
+            ? remainingBytesHint(meter.current, meter.total)
+            : "";
+    return (
+        <span className="transfer-metrics" data-timing={details.timing}>
+            {remaining && <span>{remaining}</span>}
+            {details.rate ? (
+                <span
+                    className="transfer-speed"
+                    title="Speed during this stage"
+                >
+                    {formatBytes(details.rate)}/s
+                </span>
+            ) : null}
+            {details.eta !== undefined && (
+                <span
+                    className="transfer-eta"
+                    title="Estimated upload time for this stage. Verification and publishing may take longer."
+                >
+                    About {formatDuration(Math.max(1, Math.ceil(details.eta)))}{" "}
+                    remaining
+                </span>
+            )}
+            {details.timing === "stalled" && (
+                <span className="transfer-timing-state">
+                    No recent progress
+                </span>
+            )}
+            {details.timing === "waiting" && (
+                <span className="transfer-timing-state">
+                    {item.stage === "source_retry_wait"
+                        ? "Waiting to retry source"
+                        : "Waiting for Telegram"}
+                </span>
+            )}
+            {details.timing === "finishing" && (
+                <span className="transfer-timing-state">
+                    Finishing this stage…
+                </span>
+            )}
+        </span>
+    );
+}
diff --git a/website/src/features/transfers/adaptiveUploadScheduling.test.ts b/website/src/features/transfers/adaptiveUploadScheduling.test.ts
new file mode 100644
index 00000000..5e9f3a39
--- /dev/null
+++ b/website/src/features/transfers/adaptiveUploadScheduling.test.ts
@@ -0,0 +1,335 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TransferManager } from "./transfers";
+import type { UploadChunkTransport } from "./uploadTransport";
+
+const FILE_SIZE = 8 * 1024 * 1024;
+const managers: TransferManager[] = [];
+
+interface PendingChunk {
+    sent: number;
+    progress: (bytes: number) => void;
+    succeed: () => void;
+    fail: (error: unknown) => void;
+    respond: (response: Response) => void;
+    signal: AbortSignal;
+}
+
+/** Real manager scheduling with controllable browser byte events and responses. */
+async function runningUploads(count = 10, resumeFirstFile = false) {
+    const chunks = new Map<string, PendingChunk>();
+    const started: string[] = [];
+    const aborted: string[] = [];
+    const sendChunk: UploadChunkTransport = (url, options, progress) =>
+        new Promise<Response>((resolve, reject) => {
+            const id = decodeURIComponent(url.split("/")[4]);
+            let settled = false;
+            const settle = (response?: Response, error?: unknown) => {
+                if (settled) return;
+                settled = true;
+                options.signal.removeEventListener("abort", abort);
+                chunks.delete(id);
+                if (error !== undefined) reject(error);
+                else resolve(response!);
+            };
+            const abort = () => {
+                aborted.push(id);
+                settle(
+                    undefined,
+                    new DOMException("Upload paused", "AbortError"),
+                );
+            };
+            chunks.set(id, {
+                sent: 0,
+                progress,
+                succeed: () =>
+                    settle(
+                        new Response(null, {
+                            status: 204,
+                            headers: { "Upload-Offset": String(FILE_SIZE) },
+                        }),
+                    ),
+                fail: (error) => settle(undefined, error),
+                respond: (response) => settle(response),
+                signal: options.signal,
+            });
+            started.push(id);
+            options.signal.addEventListener("abort", abort, { once: true });
+            if (options.signal.aborted) abort();
+        });
+    const receipt = (id: string) =>
+        Response.json({
+            id,
+            offset: resumeFirstFile && id === "file-0.bin" ? 4 : 0,
+            total_size: FILE_SIZE,
+            chunk_size: FILE_SIZE,
+            checksums:
+                resumeFirstFile && id === "file-0.bin"
+                    ? [
+                          {
+                              offset: 0,
+                              size: 4,
+                              sha256: "unused-before-digest-fails",
+                          },
+                      ]
+                    : [],
+        });
+    vi.stubGlobal(
+        "fetch",
+        vi.fn(async (url: string, options: RequestInit = {}) => {
+            if (url === "/api/v1/jobs") return Response.json({ jobs: [] });
+            if (url === "/api/v1/uploads") {
+                const { name } = JSON.parse(String(options.body)) as {
+                    name: string;
+                };
+                return receipt(name);
+            }
+            const id = decodeURIComponent(url.split("/")[4]);
+            if (url.endsWith("/cancel"))
+                return Response.json({ state: "cancelled" });
+            if (options.method === "HEAD")
+                return new Response(null, {
+                    headers: {
+                        "Upload-Offset":
+                            resumeFirstFile && id === "file-0.bin" ? "4" : "0",
+                        "Upload-Length": String(FILE_SIZE),
+                    },
+                });
+            if (url.endsWith("/complete")) return Response.json({ id });
+            return receipt(id);
+        }),
+    );
+    const manager = new TransferManager(sendChunk);
+    managers.push(manager);
+    const contents = new Uint8Array(FILE_SIZE);
+    manager.add(
+        Array.from(
+            { length: count },
+            (_, index) => new File([contents], `file-${index}.bin`),
+        ),
+        "/",
+        FILE_SIZE,
+    );
+    if (resumeFirstFile)
+        Object.assign(manager.snapshot()[0], {
+            uploadId: "file-0.bin",
+            current: 4,
+        });
+    manager.setEnabled(true);
+    await vi.advanceTimersByTimeAsync(0);
+    const flush = () => vi.advanceTimersByTimeAsync(0);
+    const observedConcurrency: number[] = [chunks.size];
+    const flow = async (
+        seconds: number,
+        bytesPerStream: (active: number) => number,
+    ) => {
+        for (let second = 0; second < seconds; second++) {
+            await vi.advanceTimersByTimeAsync(1000);
+            const bytes = bytesPerStream(chunks.size);
+            for (const chunk of [...chunks.values()]) {
+                chunk.sent = Math.min(FILE_SIZE - 1, chunk.sent + bytes);
+                chunk.progress(chunk.sent);
+            }
+            await flush();
+            observedConcurrency.push(chunks.size);
+        }
+    };
+    return {
+        manager,
+        chunks,
+        started,
+        aborted,
+        flush,
+        flow,
+        observedConcurrency,
+    };
+}
+
+beforeEach(() => {
+    vi.useFakeTimers();
+    const values = new Map<string, string>();
+    vi.stubGlobal("localStorage", {
+        get length() {
+            return values.size;
+        },
+        key: (index: number) => [...values.keys()][index] ?? null,
+        removeItem: (key: string) => values.delete(key),
+        getItem: (key: string) => values.get(key) || null,
+        setItem: (key: string, value: string) => values.set(key, value),
+    });
+    vi.stubGlobal("window", new EventTarget());
+});
+
+afterEach(async () => {
+    for (const manager of managers.splice(0)) manager.setEnabled(false);
+    await vi.advanceTimersByTimeAsync(0);
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+});
+
+describe("adaptive device scheduling integration", () => {
+    it("starts two requests and does not grow just because files remain queued", async () => {
+        const upload = await runningUploads();
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.started).toHaveLength(2);
+
+        await vi.advanceTimersByTimeAsync(90_000);
+        expect(upload.started).toHaveLength(2);
+    });
+
+    it("probes three then four only while more streams improve aggregate byte throughput", async () => {
+        const upload = await runningUploads();
+        await upload.flow(40, () => 64 * 1024);
+
+        expect(upload.observedConcurrency).toContain(3);
+        expect(upload.observedConcurrency).toContain(4);
+        expect(upload.observedConcurrency.indexOf(3)).toBeLessThan(
+            upload.observedConcurrency.indexOf(4),
+        );
+        expect(Math.max(...upload.observedConcurrency)).toBe(4);
+        expect(upload.started).toHaveLength(4);
+        expect(upload.aborted).toEqual([]);
+    });
+
+    it("rolls back a probe that merely divides the same total bandwidth", async () => {
+        const upload = await runningUploads();
+        await upload.flow(30, (active) => Math.floor((128 * 1024) / active));
+
+        expect(upload.observedConcurrency).toContain(3);
+        expect(upload.observedConcurrency).not.toContain(4);
+        // An admission reduction leaves the three already-started requests alone.
+        expect(upload.chunks.size).toBe(3);
+        expect(upload.aborted).toEqual([]);
+        const first = [...upload.chunks.values()][0];
+        first.succeed();
+        await upload.flush();
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.started).toHaveLength(3);
+        [...upload.chunks.values()][0].succeed();
+        await upload.flush();
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.started).toHaveLength(4);
+    });
+
+    it("replaces a cancelled request without reducing the healthy device limit", async () => {
+        const upload = await runningUploads();
+        const cancelled = upload.manager.snapshot()[0];
+        await upload.manager.cancel(cancelled.key);
+        await upload.flush();
+
+        expect(upload.manager.snapshot()[0].state).toBe("cancelled");
+        expect(upload.started).toHaveLength(3);
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.aborted).toEqual([cancelled.name]);
+        expect(
+            [...upload.chunks.values()].every((chunk) => !chunk.signal.aborted),
+        ).toBe(true);
+    });
+
+    it.each(["network", "server"])(
+        "reduces new admissions after a %s error while leaving other requests running",
+        async (failure) => {
+            const upload = await runningUploads();
+            const [failed, remaining] = [...upload.chunks.values()];
+            if (failure === "network")
+                failed.fail(new TypeError("Network interrupted"));
+            else
+                failed.respond(
+                    Response.json({ detail: "Busy" }, { status: 503 }),
+                );
+            await upload.flush();
+
+            expect(upload.started).toHaveLength(2);
+            expect(upload.chunks.size).toBe(1);
+            expect(remaining.signal.aborted).toBe(false);
+            expect(upload.aborted).toEqual([]);
+
+            remaining.succeed();
+            await upload.flush();
+            expect(upload.started).toHaveLength(3);
+            expect(upload.chunks.size).toBe(1);
+            expect(upload.manager.snapshot()[1].jobId).toBe("file-1.bin");
+        },
+    );
+
+    it("keeps device capacity available for smaller files when a receipt hits staging pressure", async () => {
+        const upload = await runningUploads();
+        [...upload.chunks.values()][0].respond(
+            Response.json({ detail: "Staging is full" }, { status: 507 }),
+        );
+        await upload.flush();
+
+        expect(upload.manager.snapshot()[0]).toMatchObject({
+            state: "queued",
+            phase: "Waiting for server space",
+        });
+        expect(upload.started).toHaveLength(3);
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.aborted).toEqual([]);
+    });
+
+    it("does not classify a resume verification runtime failure as network pressure", async () => {
+        const digest = vi
+            .spyOn(crypto.subtle, "digest")
+            .mockRejectedValueOnce(new TypeError("Checksum runtime error"));
+        const upload = await runningUploads(10, true);
+        await upload.flush();
+
+        expect(digest).toHaveBeenCalledOnce();
+        expect(upload.manager.snapshot()[0]).toMatchObject({
+            state: "error",
+            error: "Checksum runtime error",
+        });
+        expect(upload.started).toEqual(["file-1.bin", "file-2.bin"]);
+        expect(upload.chunks.size).toBe(2);
+
+        upload.chunks.get("file-1.bin")!.succeed();
+        await upload.flush();
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.started).toEqual([
+            "file-1.bin",
+            "file-2.bin",
+            "file-3.bin",
+        ]);
+        expect(upload.aborted).toEqual([]);
+    });
+
+    it("discards background byte and timer samples and starts a fresh visible window", async () => {
+        const visibility = { visibilityState: "visible" };
+        vi.stubGlobal("document", visibility);
+        const upload = await runningUploads();
+        await upload.flow(4, () => 64 * 1024);
+
+        visibility.visibilityState = "hidden";
+        await upload.flow(40, () => 64 * 1024);
+        await vi.advanceTimersByTimeAsync(30_000);
+        expect(upload.started).toHaveLength(2);
+        expect(upload.aborted).toEqual([]);
+
+        visibility.visibilityState = "visible";
+        await upload.flow(1, () => 64 * 1024);
+        expect(upload.started).toHaveLength(2);
+
+        // A new request still fills the healthy two-file limit, proving the hidden
+        // no-progress interval did not count as a network stall and reduce it.
+        [...upload.chunks.values()][0].succeed();
+        await upload.flush();
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.started).toHaveLength(3);
+        await upload.flow(3, () => 64 * 1024);
+        expect(upload.started).toHaveLength(3);
+    });
+
+    it("does not treat a fully sent body waiting for acknowledgement as a device stall", async () => {
+        const upload = await runningUploads();
+        for (const chunk of upload.chunks.values()) chunk.progress(FILE_SIZE);
+        await vi.advanceTimersByTimeAsync(60_000);
+        expect(upload.started).toHaveLength(2);
+        expect(upload.aborted).toEqual([]);
+
+        [...upload.chunks.values()][0].succeed();
+        await upload.flush();
+        expect(upload.chunks.size).toBe(2);
+        expect(upload.started).toHaveLength(3);
+    });
+});
diff --git a/website/src/features/transfers/batchProgress.test.ts b/website/src/features/transfers/batchProgress.test.ts
new file mode 100644
index 00000000..deeec647
--- /dev/null
+++ b/website/src/features/transfers/batchProgress.test.ts
@@ -0,0 +1,160 @@
+import { describe, expect, it } from "vitest";
+import { BatchProgressTracker } from "./batchProgress";
+import { currentRate } from "./progress";
+import { summarizeBatches } from "./transferBatches";
+import type { Transfer } from "./transfers";
+
+function item(key: string, overrides: Partial<Transfer> = {}): Transfer {
+    return {
+        key,
+        initiatedHere: true,
+        name: key + ".bin",
+        size: 100,
+        total: 100,
+        current: 0,
+        lastModified: 0,
+        destination: "/",
+        batchId: "folder",
+        folderUpload: {
+            id: "folder",
+            name: "Folder",
+            root_path: "/folder",
+            created_at: 1,
+        },
+        relativePath: "Folder/" + key + ".bin",
+        state: "uploading",
+        phase: "Queued for Telegram",
+        stage: "queued",
+        jobId: key,
+        ...overrides,
+    };
+}
+
+function observe(
+    tracker: BatchProgressTracker,
+    items: Transfer[],
+    now: number,
+) {
+    tracker.observe(summarizeBatches(items, now), now);
+    return summarizeBatches(items, now, tracker.snapshot())[0];
+}
+
+describe("batch throughput observations", () => {
+    it("estimates small files that finish between polls without individual speed samples", () => {
+        const tracker = new BatchProgressTracker();
+        const rows = [item("one"), item("two"), item("three")];
+        expect(observe(tracker, rows, 1000).displayEta).toBeUndefined();
+        rows[0] = { ...rows[0], state: "completed", current: 100 };
+        expect(observe(tracker, rows, 3000)).toMatchObject({
+            displayRate: 50,
+            displayEta: 4,
+        });
+        rows[1] = { ...rows[1], stage: "finalizing", current: 100 };
+        expect(observe(tracker, rows, 5000)).toMatchObject({
+            displayRate: 50,
+            displayEta: 2,
+        });
+        // A short gap between files keeps measured throughput; it does not create bytes.
+        expect(observe(tracker, rows, 6000).displayEta).toBe(2);
+        expect(observe(tracker, rows, 20000).displayEta).toBeUndefined();
+    });
+
+    it("retains device observations across handoffs and starts a new Telegram baseline", () => {
+        const tracker = new BatchProgressTracker();
+        const rows = [
+            item("one", {
+                state: "receiving",
+                stage: "preparing",
+                jobId: undefined,
+            }),
+            item("two", {
+                state: "queued",
+                stage: undefined,
+                jobId: undefined,
+            }),
+        ];
+        observe(tracker, rows, 1000);
+        rows[0] = item("one");
+        rows[1] = { ...rows[1], state: "receiving", current: 50 };
+        expect(observe(tracker, rows, 3000)).toMatchObject({
+            device: { current: 150, pending: true },
+            displayRate: 75,
+            displayEta: 50 / 75,
+        });
+        rows[1] = item("two");
+        expect(observe(tracker, rows, 4000).displayRate).toBeUndefined();
+        rows[0] = { ...rows[0], state: "completed", current: 100 };
+        expect(observe(tracker, rows, 6000)).toMatchObject({
+            device: { pending: false },
+            displayRate: 50,
+            displayEta: 2,
+        });
+    });
+
+    it("never derives a rate from the first restored snapshot or a wall clock tick", () => {
+        const tracker = new BatchProgressTracker();
+        const rows = [item("one", { current: 50, stage: "uploading" })];
+        observe(tracker, rows, 1000);
+        expect(observe(tracker, rows, 5000).displayRate).toBeUndefined();
+        expect(
+            currentRate(tracker.snapshot().get("folder"), 5000),
+        ).toBeUndefined();
+    });
+
+    it.each(["membership", "total", "regression", "cancellation"])(
+        "resets the baseline after %s changes",
+        (change) => {
+            const tracker = new BatchProgressTracker();
+            let rows = [item("one", { stage: "uploading" }), item("two")];
+            observe(tracker, rows, 1000);
+            rows[0] = { ...rows[0], current: 50 };
+            expect(observe(tracker, rows, 3000).displayRate).toBe(25);
+            if (change === "membership") rows.push(item("three"));
+            if (change === "total")
+                rows[0] = { ...rows[0], size: 200, total: 200 };
+            if (change === "regression") rows[0] = { ...rows[0], current: 0 };
+            if (change === "cancellation")
+                rows[1] = { ...rows[1], state: "cancelled" };
+            expect(observe(tracker, rows, 4000).displayRate).toBeUndefined();
+        },
+    );
+
+    it("drops observations for removed or finished batches", () => {
+        const tracker = new BatchProgressTracker();
+        observe(tracker, [item("one")], 1000);
+        expect(tracker.snapshot().size).toBe(1);
+        observe(tracker, [item("one", { state: "completed" })], 2000);
+        expect(tracker.snapshot().size).toBe(0);
+        tracker.observe([], 3000);
+        expect(tracker.snapshot().size).toBe(0);
+    });
+
+    it("starts new measurements after suspension without reviving the old rate", () => {
+        const tracker = new BatchProgressTracker();
+        const rows = [item("one", { stage: "uploading" })];
+        observe(tracker, rows, 1000);
+        rows[0].current = 50;
+        expect(observe(tracker, rows, 3000).displayRate).toBe(25);
+        tracker.clear();
+        expect(tracker.snapshot().size).toBe(0);
+        expect(observe(tracker, rows, 4000).displayRate).toBeUndefined();
+    });
+
+    it("does not turn a recent observation into speed during publishing or retry waits", () => {
+        const tracker = new BatchProgressTracker();
+        const rows = [item("one", { stage: "uploading" })];
+        observe(tracker, rows, 1000);
+        rows[0].current = 50;
+        expect(observe(tracker, rows, 3000).displayRate).toBe(25);
+        rows[0].stage = "retry_wait";
+        expect(observe(tracker, rows, 4000)).toMatchObject({
+            displayRate: undefined,
+            displayEta: undefined,
+        });
+        rows[0] = { ...rows[0], stage: "finalizing", current: 100 };
+        expect(observe(tracker, rows, 5000)).toMatchObject({
+            displayRate: undefined,
+            displayEta: undefined,
+        });
+    });
+});
diff --git a/website/src/features/transfers/batchProgress.ts b/website/src/features/transfers/batchProgress.ts
new file mode 100644
index 00000000..fbe39cff
--- /dev/null
+++ b/website/src/features/transfers/batchProgress.ts
@@ -0,0 +1,70 @@
+import { sampleProgress, type ProgressSample } from "./progress";
+import type { TransferBatch } from "./transferBatches";
+
+export type BatchProgressMeters = ReadonlyMap<string, ProgressSample>;
+
+interface BatchObservation {
+    stage: string;
+    total: number;
+    members: Map<string, string>;
+    sample: ProgressSample;
+}
+
+/** Browser observations survive file handoffs, but never become recovery data. */
+export class BatchProgressTracker {
+    private observations = new Map<string, BatchObservation>();
+    private meters = new Map<string, ProgressSample>();
+
+    observe(batches: TransferBatch[], now: number) {
+        const observations = new Map<string, BatchObservation>();
+        const meters = new Map<string, ProgressSample>();
+        for (const batch of batches) {
+            if (
+                !batch.pending ||
+                batch.items.some((item) =>
+                    ["remote", "delete"].includes(item.kind || ""),
+                )
+            )
+                continue;
+            const stage = batch.device.pending ? "device" : "telegram";
+            const total = batch.device.pending
+                ? batch.device.total
+                : batch.totalBytes;
+            if (total === undefined || !Number.isFinite(total) || total <= 0)
+                continue;
+            const bytes = batch.displayBytes;
+            if (!Number.isFinite(bytes) || bytes < 0) continue;
+            const members = new Map(
+                batch.items.map((item) => [
+                    item.key,
+                    item.size + ":" + (item.state === "cancelled"),
+                ]),
+            );
+            const previous = this.observations.get(batch.id);
+            const unchanged =
+                previous?.stage === stage &&
+                previous.total === total &&
+                previous.members.size === members.size &&
+                [...members].every(
+                    ([key, value]) => previous.members.get(key) === value,
+                );
+            const sample = sampleProgress(
+                unchanged ? previous.sample : undefined,
+                stage,
+                bytes,
+                now,
+            );
+            observations.set(batch.id, { stage, total, members, sample });
+            meters.set(batch.id, sample);
+        }
+        this.observations = observations;
+        this.meters = meters;
+    }
+
+    snapshot = (): BatchProgressMeters => this.meters;
+
+    clear() {
+        this.observations.clear();
+        this.meters = new Map();
+    }
+}
diff --git a/website/src/features/transfers/deviceUploadConcurrency.test.ts b/website/src/features/transfers/deviceUploadConcurrency.test.ts
new file mode 100644
index 00000000..653816c8
--- /dev/null
+++ b/website/src/features/transfers/deviceUploadConcurrency.test.ts
@@ -0,0 +1,329 @@
+import { describe, expect, it } from "vitest";
+import {
+    DeviceUploadConcurrency,
+    INITIAL_DEVICE_UPLOAD_CONCURRENCY,
+    MAX_DEVICE_UPLOAD_CONCURRENCY,
+} from "./deviceUploadConcurrency";
+
+/** Two long PATCH bodies make rate tests independent of file completion. */
+function connection() {
+    const controller = new DeviceUploadConcurrency();
+    let now = 0;
+    let sequence = 0;
+    const chunks = new Map<string, number>();
+    function active(count: number) {
+        while (chunks.size < count) {
+            const id = String(++sequence);
+            chunks.set(id, 0);
+            controller.chunkStarted(id, now, 1e9);
+        }
+        while (chunks.size > count) {
+            const id = [...chunks.keys()].at(-1)!;
+            controller.chunkFinished(id, now);
+            chunks.delete(id);
+        }
+    }
+    function tick(rate: number, backlog = true) {
+        now += 1000;
+        for (const [id, bytes] of chunks) {
+            const next = bytes + rate / chunks.size;
+            chunks.set(id, next);
+            controller.chunkProgress(id, next, now);
+        }
+        controller.sample(now, backlog);
+    }
+    function window(rate: number, backlog = true) {
+        for (let second = 0; second < 4; second++) tick(rate, backlog);
+        return controller.limit;
+    }
+    active(2);
+    return {
+        controller,
+        active,
+        tick,
+        window,
+        get now() {
+            return now;
+        },
+    };
+}
+
+describe("adaptive device upload concurrency", () => {
+    it("starts two requests immediately and waits for sustained measurement before probing", () => {
+        const link = connection();
+        expect(INITIAL_DEVICE_UPLOAD_CONCURRENCY).toBe(2);
+        expect(link.controller.limit).toBe(2);
+        expect(link.window(2000)).toBe(2);
+        expect(link.window(2000)).toBe(3);
+    });
+
+    it("keeps an extra sender only when aggregate throughput improves", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        expect(link.window(3000)).toBe(3);
+        expect(link.window(3000)).toBe(3);
+        // A successful probe still settles before another increase.
+        expect(link.window(3000)).toBe(3);
+        expect(link.window(3000)).toBe(3);
+        expect(link.window(3000)).toBe(4);
+        link.active(4);
+        link.window(4000);
+        link.window(4000);
+        for (let index = 0; index < 15; index++) link.window(4000);
+        expect(link.controller.limit).toBe(MAX_DEVICE_UPLOAD_CONCURRENCY);
+        expect(link.controller.limit).toBe(4);
+    });
+
+    it("rolls back a probe that only divides the same bandwidth among more files", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        link.window(2000);
+        expect(link.window(2000)).toBe(2);
+        link.active(2);
+        for (let index = 0; index < 7; index++)
+            expect(link.window(2000)).toBe(2);
+        expect(link.window(2000)).toBe(3);
+    });
+
+    it("rejects a marginal improvement below ten percent", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        link.window(2180);
+        expect(link.window(2180)).toBe(2);
+    });
+
+    it("compares both probe windows rather than retaining a short throughput spike", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        link.window(3500);
+        expect(link.window(500)).toBe(2);
+    });
+
+    it("requires a second degraded window before reducing admission", () => {
+        const link = connection();
+        link.window(2000);
+        // Do not offer a second stable window that would start an upward probe.
+        expect(link.window(1000)).toBe(2);
+        expect(link.window(1000)).toBe(1);
+        // Existing requests retain their progress and are not aborted/removed.
+        expect(link.window(1000)).toBe(1);
+    });
+
+    it("does not downshift for one isolated slow window", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(1000);
+        expect(link.window(2000)).toBe(3);
+    });
+
+    it("reduces immediately on transient pressure and recovers cautiously after cooldown", () => {
+        const link = connection();
+        link.controller.reportPressure(link.now);
+        expect(link.controller.limit).toBe(1);
+        link.active(1);
+        for (let index = 0; index < 7; index++)
+            expect(link.window(1000)).toBe(1);
+        expect(link.window(1000)).toBe(2);
+    });
+
+    it("reduces an in-progress three-sender probe by one, not two", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        expect(link.controller.limit).toBe(3);
+        link.controller.reportPressure(link.now);
+        expect(link.controller.limit).toBe(2);
+        for (let index = 0; index < 10; index++)
+            link.controller.reportPressure(link.now);
+        expect(link.controller.limit).toBe(1);
+    });
+
+    it("does not probe while the small batch is draining or preparation owns the slots", () => {
+        const draining = connection();
+        for (let index = 0; index < 10; index++)
+            expect(draining.window(2000, false)).toBe(2);
+        const preparing = connection();
+        preparing.active(1);
+        for (let index = 0; index < 10; index++)
+            expect(preparing.window(1000)).toBe(2);
+    });
+
+    it("discards a probe when there is insufficient remaining device work to compare", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        expect(link.window(3000, false)).toBe(2);
+    });
+
+    it("downshifts an observed stalled payload after fifteen seconds, without waiting for completion", () => {
+        const link = connection();
+        link.tick(2000);
+        for (let index = 0; index < 14; index++) link.tick(0);
+        expect(link.controller.limit).toBe(2);
+        link.tick(0);
+        expect(link.controller.limit).toBe(1);
+    });
+
+    it("does not classify a transport without browser progress as a stalled payload", () => {
+        const link = connection();
+        for (let index = 0; index < 24; index++) link.tick(0);
+        expect(link.controller.limit).toBe(2);
+    });
+
+    it("does not measure the server acknowledgement delay as device saturation or a stall", () => {
+        const controller = new DeviceUploadConcurrency();
+        controller.chunkStarted("a", 0, 1000);
+        controller.chunkStarted("b", 0, 1000);
+        controller.chunkProgress("a", 1000, 1000);
+        controller.chunkProgress("b", 1000, 1000);
+        for (let now = 2000; now <= 40000; now += 1000)
+            expect(controller.sample(now, true)).toBe(2);
+    });
+
+    it("uses confirmed bytes as a fallback without counting browser-observed bytes twice", () => {
+        const controller = new DeviceUploadConcurrency();
+        for (let index = 0; index < 2; index++) {
+            const at = index * 4000;
+            controller.chunkStarted(`a${index}`, at, 10000);
+            controller.chunkStarted(`b${index}`, at, 10000);
+            controller.chunkProgress(`a${index}`, 6000, at + 3000);
+            controller.chunkFinished(`a${index}`, at + 4000, 10000);
+            controller.chunkFinished(`b${index}`, at + 4000, 10000);
+            controller.sample(at + 4000, true);
+        }
+        expect(controller.limit).toBe(3);
+        // Baseline is 5000 bytes/s, so a real 6000 bytes/s is a useful increase.
+        for (let index = 0; index < 2; index++) {
+            const at = 8000 + index * 4000;
+            for (let part = 0; part < 3; part++)
+                controller.chunkStarted(`${index}-${part}`, at, 8000);
+            for (let part = 0; part < 3; part++)
+                controller.chunkFinished(`${index}-${part}`, at + 4000, 8000);
+            controller.sample(at + 4000, true);
+        }
+        expect(controller.limit).toBe(3);
+    });
+
+    it("ignores unknown, regressing and invalid chunk progress", () => {
+        const controller = new DeviceUploadConcurrency();
+        for (let index = 0; index < 2; index++) {
+            const at = index * 4000;
+            controller.chunkStarted(`a${index}`, at, 10000);
+            controller.chunkStarted(`b${index}`, at, 10000);
+            controller.chunkProgress(`a${index}`, 5000, at + 1000);
+            controller.chunkProgress(`a${index}`, 3000, at + 2000);
+            controller.chunkProgress(`a${index}`, Number.NaN, at + 2000);
+            controller.chunkProgress(`a${index}`, -100, at + 2000);
+            controller.chunkProgress("unknown", 1e12, at + 2000);
+            controller.chunkFinished(`a${index}`, at + 4000, 10000);
+            controller.chunkFinished(`b${index}`, at + 4000, 10000);
+            controller.sample(at + 4000, true);
+        }
+        expect(controller.limit).toBe(3);
+        // Invalid observations must not inflate the baseline used by the probe.
+        for (let index = 0; index < 2; index++) {
+            const at = 8000 + index * 4000;
+            for (let part = 0; part < 3; part++)
+                controller.chunkStarted(`probe-${index}-${part}`, at, 8000);
+            for (let part = 0; part < 3; part++)
+                controller.chunkFinished(
+                    `probe-${index}-${part}`,
+                    at + 4000,
+                    8000,
+                );
+            controller.sample(at + 4000, true);
+        }
+        expect(controller.limit).toBe(3);
+    });
+
+    it("drops long timer gaps instead of treating background-tab time as poor throughput", () => {
+        const link = connection();
+        link.window(2000);
+        expect(link.controller.sample(link.now + 60000, true)).toBe(2);
+        // Old progress/offsets cannot turn a resumed tab into an instantaneous probe.
+        link.controller.chunkProgress("1", 1e8, link.now + 60001);
+        expect(link.controller.sample(link.now + 61000, true)).toBe(2);
+    });
+
+    it("pauses hidden-tab measurements, retains a learned limit and resumes with a fresh window", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        link.window(3000);
+        link.window(3000);
+        expect(link.controller.limit).toBe(3);
+        link.controller.pauseMeasurements(link.now);
+        link.controller.chunkProgress("1", 1e8, link.now + 60000);
+        expect(link.controller.sample(link.now + 60000, true)).toBe(3);
+        for (let offset = 1000; offset <= 16000; offset += 1000)
+            expect(
+                link.controller.sample(link.now + 60000 + offset, true),
+            ).toBe(3);
+    });
+
+    it("resets at true idle so the next batch starts at two", () => {
+        const link = connection();
+        link.controller.reportPressure(link.now);
+        expect(link.controller.limit).toBe(1);
+        link.controller.reset(50000);
+        expect(link.controller.limit).toBe(2);
+        // Progress from a completed earlier batch is ignored after reset.
+        link.controller.chunkProgress("1", 1e9, 51000);
+        expect(link.controller.sample(54000, true)).toBe(2);
+    });
+
+    it("discards a tentative fourth sender across suspension but preserves a measured fourth sender", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        for (let index = 0; index < 5; index++) link.window(3000);
+        expect(link.controller.limit).toBe(4);
+        link.controller.pauseMeasurements(link.now);
+        expect(link.controller.limit).toBe(3);
+        link.controller.sample(link.now, true);
+        link.window(3000);
+        expect(link.window(3000)).toBe(4);
+        link.active(4);
+        link.window(4000);
+        link.window(4000);
+        link.controller.pauseMeasurements(link.now);
+        expect(link.controller.limit).toBe(4);
+        expect(link.controller.sample(link.now + 60000, true)).toBe(4);
+        expect(link.controller.sample(link.now + 120000, true)).toBe(4);
+    });
+
+    it("does not repeatedly penalize the same observed stall without new browser progress", () => {
+        const link = connection();
+        link.window(2000);
+        link.window(2000);
+        link.active(3);
+        for (let index = 0; index < 5; index++) link.window(3000);
+        link.active(4);
+        link.window(4000);
+        link.window(4000);
+        for (let index = 0; index < 15; index++) link.tick(0);
+        expect(link.controller.limit).toBe(3);
+        for (let index = 0; index < 60; index++) link.tick(0);
+        expect(link.controller.limit).toBe(3);
+    });
+
+    it("discards measurements after a backwards clock adjustment", () => {
+        const link = connection();
+        link.window(2000);
+        expect(link.controller.sample(-1000, true)).toBe(2);
+        // Returning to the prior clock cannot reuse its stable comparison window.
+        expect(link.controller.sample(link.now, true)).toBe(2);
+        expect(link.window(2000)).toBe(2);
+    });
+});
diff --git a/website/src/features/transfers/deviceUploadConcurrency.ts b/website/src/features/transfers/deviceUploadConcurrency.ts
new file mode 100644
index 00000000..6a6c4808
--- /dev/null
+++ b/website/src/features/transfers/deviceUploadConcurrency.ts
@@ -0,0 +1,221 @@
+export const INITIAL_DEVICE_UPLOAD_CONCURRENCY = 2;
+export const MAX_DEVICE_UPLOAD_CONCURRENCY = 4;
+
+const WINDOW_MS = 4000;
+const MAX_SAMPLE_GAP_MS = 12000;
+const STALL_MS = 15000;
+const COOLDOWN_MS = 30000;
+interface Chunk {
+    bytes: number;
+    total?: number;
+}
+interface Probe {
+    previousLimit: number;
+    baseline: number;
+    rates: number[];
+}
+
+/** Measures only device PATCH payloads. All times are supplied by the caller. */
+export class DeviceUploadConcurrency {
+    private concurrency = INITIAL_DEVICE_UPLOAD_CONCURRENCY;
+    private chunks = new Map<string, Chunk>();
+    private windowAt?: number;
+    private lastAt?: number;
+    private bytes = 0;
+    private busyTime = 0;
+    private baseline?: number;
+    private stableWindows = 0;
+    private degradedWindows = 0;
+    private cooldownUntil = 0;
+    private probe?: Probe;
+    private lastPayloadProgressAt?: number;
+    private paused = false;
+
+    get limit() {
+        return this.concurrency;
+    }
+
+    chunkStarted(id: string, now: number, totalBytes?: number) {
+        this.advance(now);
+        if (this.chunks.has(id)) return;
+        this.chunks.set(id, {
+            bytes: 0,
+            total:
+                totalBytes !== undefined && Number.isFinite(totalBytes)
+                    ? Math.max(0, totalBytes)
+                    : undefined,
+        });
+        // Give a newly started request a full stall interval to make progress.
+        if (this.lastPayloadProgressAt !== undefined)
+            this.lastPayloadProgressAt = now;
+    }
+
+    /** cumulativeBytes is relative to this PATCH body, never a file/resume offset. */
+    chunkProgress(id: string, cumulativeBytes: number, now: number) {
+        const chunk = this.chunks.get(id);
+        if (!chunk || !Number.isFinite(cumulativeBytes) || cumulativeBytes < 0)
+            return;
+        const measurable = this.advance(now);
+        const next = Math.max(
+            chunk.bytes,
+            Math.min(cumulativeBytes, chunk.total ?? cumulativeBytes),
+        );
+        if (measurable && next > chunk.bytes) {
+            this.bytes += next - chunk.bytes;
+            this.lastPayloadProgressAt = now;
+        }
+        chunk.bytes = next;
+    }
+
+    /** A successful receipt supplies a fallback for transports without progress. */
+    chunkFinished(id: string, now: number, confirmedBytes?: number) {
+        const chunk = this.chunks.get(id);
+        if (!chunk) return;
+        const measurable = this.advance(now);
+        if (confirmedBytes !== undefined && Number.isFinite(confirmedBytes)) {
+            const final = Math.min(
+                confirmedBytes,
+                chunk.total ?? confirmedBytes,
+            );
+            if (measurable) this.bytes += Math.max(0, final - chunk.bytes);
+        }
+        this.chunks.delete(id);
+        if (!this.sendingCount()) this.lastPayloadProgressAt = undefined;
+    }
+
+    /** Call regularly while visible, including during a single long file. */
+    sample(now: number, hasBacklog: boolean): number {
+        if (this.paused) {
+            this.paused = false;
+            this.restartWindow(now);
+            return this.limit;
+        }
+        if (!this.advance(now)) return this.limit;
+        if (
+            this.sendingCount() &&
+            this.lastPayloadProgressAt !== undefined &&
+            now - this.lastPayloadProgressAt >= STALL_MS
+        ) {
+            this.reportPressure(now);
+            return this.limit;
+        }
+        const elapsed = now - this.windowAt!;
+        if (elapsed < WINDOW_MS) return this.limit;
+        const rate = (this.bytes * 1000) / elapsed;
+        const saturated = this.busyTime >= elapsed * this.limit * 0.7;
+        this.windowAt = now;
+        this.bytes = this.busyTime = 0;
+
+        // Preparation, server acknowledgement and a draining queue are not evidence
+        // that the network would benefit from another simultaneous payload.
+        if (!hasBacklog || !saturated) {
+            this.clearTrend();
+            return this.limit;
+        }
+        if (this.probe) {
+            this.probe.rates.push(rate);
+            if (this.probe.rates.length < 2) return this.limit;
+            const average = (this.probe.rates[0] + this.probe.rates[1]) / 2;
+            const improved = average >= this.probe.baseline * 1.1;
+            this.baseline = improved ? average : this.probe.baseline;
+            if (!improved) this.concurrency = this.probe.previousLimit;
+            this.probe = undefined;
+            this.stableWindows = this.degradedWindows = 0;
+            this.cooldownUntil =
+                now + (improved ? MAX_SAMPLE_GAP_MS : COOLDOWN_MS);
+            return this.limit;
+        }
+        // A silent transport can be using the receipt fallback. Only actual prior
+        // browser progress enables the separate, longer stall timeout above.
+        if (!rate) return this.limit;
+        if (this.baseline && rate < this.baseline * 0.65) {
+            if (++this.degradedWindows >= 2) this.reportPressure(now);
+            return this.limit;
+        }
+        this.degradedWindows = 0;
+        const stable =
+            this.baseline !== undefined &&
+            Math.abs(rate - this.baseline) <= this.baseline * 0.25;
+        this.stableWindows = stable ? this.stableWindows + 1 : 1;
+        this.baseline = stable ? this.baseline! * 0.75 + rate * 0.25 : rate;
+        if (
+            rate > 0 &&
+            this.stableWindows >= 2 &&
+            now >= this.cooldownUntil &&
+            this.limit < MAX_DEVICE_UPLOAD_CONCURRENCY
+        ) {
+            this.probe = {
+                previousLimit: this.limit,
+                baseline: this.baseline,
+                rates: [],
+            };
+            this.concurrency++;
+            this.stableWindows = 0;
+        }
+        return this.limit;
+    }
+
+    /** Only transient device-transport/network/overload failures belong here. */
+    reportPressure(now: number) {
+        const reduced = Math.max(1, this.limit - 1);
+        this.clearTrend();
+        this.concurrency = reduced;
+        this.cooldownUntil = now + COOLDOWN_MS;
+        this.restartWindow(now);
+    }
+
+    /** Hidden tabs discard measurement windows while preserving request offsets. */
+    pauseMeasurements(now: number) {
+        this.clearTrend();
+        this.restartWindow(now);
+        this.paused = true;
+    }
+
+    /** Use only at true idle, after both device work and its queue have drained. */
+    reset(now: number) {
+        this.chunks.clear();
+        this.clearTrend();
+        this.concurrency = INITIAL_DEVICE_UPLOAD_CONCURRENCY;
+        this.cooldownUntil = 0;
+        this.paused = false;
+        this.restartWindow(now);
+    }
+
+    private sendingCount() {
+        let count = 0;
+        for (const chunk of this.chunks.values())
+            if (chunk.total === undefined || chunk.bytes < chunk.total) count++;
+        return count;
+    }
+
+    private clearTrend() {
+        if (this.probe) this.concurrency = this.probe.previousLimit;
+        this.probe = undefined;
+        this.baseline = undefined;
+        this.stableWindows = this.degradedWindows = 0;
+    }
+
+    private restartWindow(now: number) {
+        this.windowAt = this.lastAt = now;
+        this.bytes = this.busyTime = 0;
+        this.lastPayloadProgressAt = undefined;
+    }
+
+    private advance(now: number): boolean {
+        if (this.paused || !Number.isFinite(now)) return false;
+        if (
+            this.lastAt === undefined ||
+            now < this.lastAt ||
+            now - this.lastAt > MAX_SAMPLE_GAP_MS ||
+            now - this.windowAt! > MAX_SAMPLE_GAP_MS
+        ) {
+            this.clearTrend();
+            this.restartWindow(now);
+            return false;
+        }
+        this.busyTime +=
+            (now - this.lastAt) * Math.min(this.sendingCount(), this.limit);
+        this.lastAt = now;
+        return true;
+    }
+}
diff --git a/website/src/features/transfers/deviceUploadRetries.test.ts b/website/src/features/transfers/deviceUploadRetries.test.ts
new file mode 100644
index 00000000..9de87ded
--- /dev/null
+++ b/website/src/features/transfers/deviceUploadRetries.test.ts
@@ -0,0 +1,389 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TransferManager } from "./transfers";
+import type { Job } from "../../shared/types";
+import type { UploadChunkTransport } from "./uploadTransport";
+
+const managers: TransferManager[] = [];
+type PendingChunk = {
+    offset: number;
+    signal: AbortSignal;
+    resolve: (response: Response) => void;
+    reject: (error: unknown) => void;
+};
+
+async function deviceUpload() {
+    const pending: PendingChunk[] = [];
+    let offset = 0;
+    let jobs: Job[] = [];
+    let createStatus = 201;
+    let headFailure: unknown;
+    let inspectionOffset: number | undefined;
+    let completionFailure = false;
+    const requests: string[] = [];
+    const receipt = () => ({
+        id: "receipt",
+        offset,
+        total_size: 8,
+        chunk_size: 4,
+        checksums: Array.from({ length: offset / 4 }, (_, index) => ({
+            offset: index * 4,
+            size: 4,
+            sha256: "0102",
+        })),
+    });
+    vi.stubGlobal(
+        "fetch",
+        vi.fn(async (url: string, options: RequestInit = {}) => {
+            requests.push((options.method || "GET") + " " + url);
+            if (url === "/api/v1/jobs") return Response.json({ jobs });
+            if (url === "/api/v1/uploads")
+                return createStatus === 201
+                    ? Response.json(receipt(), { status: 201 })
+                    : Response.json(
+                          { detail: "Creation interrupted" },
+                          { status: createStatus },
+                      );
+            if (options.method === "HEAD") {
+                if (headFailure) throw headFailure;
+                expect(options.signal).toBeInstanceOf(AbortSignal);
+                return new Response(null, {
+                    headers: {
+                        "Upload-Offset": String(offset),
+                        "Upload-Length": "8",
+                    },
+                });
+            }
+            if (url.endsWith("/complete")) {
+                if (completionFailure)
+                    throw new TypeError("Completion response lost");
+                return Response.json({ id: "receipt" });
+            }
+            if (url.endsWith("/cancel"))
+                return Response.json({ state: "cancelled" });
+            if (url === "/api/v1/uploads/receipt") {
+                if (inspectionOffset !== undefined) offset = inspectionOffset;
+                return Response.json(receipt());
+            }
+            throw new Error("Unexpected request: " + url);
+        }),
+    );
+    const send: UploadChunkTransport = (_url, options) =>
+        new Promise<Response>((resolve, reject) => {
+            pending.push({
+                offset: Number(
+                    new Headers(options.headers).get("Upload-Offset"),
+                ),
+                signal: options.signal,
+                resolve,
+                reject,
+            });
+            options.signal.addEventListener(
+                "abort",
+                () => reject(new DOMException("Upload paused", "AbortError")),
+                { once: true },
+            );
+        });
+    const manager = new TransferManager(send);
+    managers.push(manager);
+    const flush = () => vi.advanceTimersByTimeAsync(0);
+    const start = async () => {
+        manager.add([new File(["abcdefgh"], "sample.bin")], "/", 10);
+        manager.setEnabled(true);
+        await flush();
+    };
+    const fail = async (status = 503, retryAfter = 0, code = "") => {
+        pending
+            .shift()!
+            .resolve(
+                Response.json(
+                    { detail: "Temporarily unavailable", code },
+                    { status, headers: { "Retry-After": String(retryAfter) } },
+                ),
+            );
+        await flush();
+    };
+    const acknowledge = async () => {
+        const chunk = pending.shift()!;
+        offset = chunk.offset + 4;
+        chunk.resolve(
+            new Response(null, {
+                status: 204,
+                headers: { "Upload-Offset": String(offset) },
+            }),
+        );
+        await flush();
+    };
+    return {
+        manager,
+        pending,
+        requests,
+        start,
+        flush,
+        fail,
+        acknowledge,
+        setOffset: (value: number) => {
+            offset = value;
+        },
+        setJobs: (value: Job[]) => {
+            jobs = value;
+        },
+        failCreation: (status: number) => {
+            createStatus = status;
+        },
+        failHead: (error: unknown) => {
+            headFailure = error;
+        },
+        commitBeforeInspection: (value: number) => {
+            inspectionOffset = value;
+        },
+        failCompletion: () => {
+            completionFailure = true;
+        },
+    };
+}
+
+beforeEach(() => {
+    vi.useFakeTimers();
+    const values = new Map<string, string>();
+    vi.stubGlobal("localStorage", {
+        get length() {
+            return values.size;
+        },
+        key: (index: number) => [...values.keys()][index] ?? null,
+        removeItem: (key: string) => values.delete(key),
+        getItem: (key: string) => values.get(key) || null,
+        setItem: (key: string, value: string) => values.set(key, value),
+    });
+    vi.stubGlobal("window", new EventTarget());
+    vi.spyOn(crypto.subtle, "digest").mockResolvedValue(
+        new Uint8Array([1, 2]).buffer,
+    );
+});
+
+afterEach(async () => {
+    for (const manager of managers.splice(0)) manager.setEnabled(false);
+    await vi.advanceTimersByTimeAsync(0);
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+});
+
+describe("device receipt retries", () => {
+    it.each([0, 408, 500, 502, 503, 504])(
+        "reconciles a known receipt after a transient %s failure without recreating it",
+        async (status) => {
+            const upload = await deviceUpload();
+            await upload.start();
+            if (status) await upload.fail(status);
+            else {
+                upload.pending
+                    .shift()!
+                    .reject(new TypeError("Connection interrupted"));
+                await upload.flush();
+            }
+            expect(upload.manager.snapshot()[0]).toMatchObject({
+                state: "queued",
+                stage: "retry_wait",
+                current: 0,
+            });
+            expect(upload.manager.snapshot()[0].error).toBeUndefined();
+            await vi.advanceTimersByTimeAsync(1999);
+            expect(upload.pending).toHaveLength(0);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(upload.pending[0].offset).toBe(0);
+            expect(
+                upload.requests.filter(
+                    (request) => request === "POST /api/v1/uploads",
+                ),
+            ).toHaveLength(1);
+            expect(upload.requests).toContain("HEAD /api/v1/uploads/receipt");
+            expect(upload.requests).toContain("GET /api/v1/uploads/receipt");
+        },
+    );
+
+    it("verifies a chunk accepted before its response was lost and resumes at the server offset", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        upload.setOffset(4);
+        upload.pending.shift()!.reject(new TypeError("Acknowledgement lost"));
+        await upload.flush();
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(crypto.subtle.digest).toHaveBeenCalledOnce();
+        expect(upload.pending[0].offset).toBe(4);
+        expect(upload.manager.snapshot()[0].current).toBe(4);
+        await upload.acknowledge();
+        expect(upload.manager.snapshot()[0].jobId).toBe("receipt");
+    });
+
+    it("uses the newer receipt snapshot when a prior chunk commits between HEAD and inspection", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        await upload.fail();
+        upload.commitBeforeInspection(4);
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(crypto.subtle.digest).toHaveBeenCalledOnce();
+        expect(upload.pending[0].offset).toBe(4);
+        expect(upload.manager.snapshot()[0].current).toBe(4);
+    });
+
+    it.each([-1, 12, 4.5])(
+        "rejects an invalid inspected offset of %s before checking or sending bytes",
+        async (offset) => {
+            const upload = await deviceUpload();
+            await upload.start();
+            await upload.fail();
+            upload.commitBeforeInspection(offset);
+            await vi.advanceTimersByTimeAsync(2000);
+            expect(upload.manager.snapshot()[0]).toMatchObject({
+                state: "error",
+                error: "The server returned an invalid upload position.",
+            });
+            expect(crypto.subtle.digest).not.toHaveBeenCalled();
+            expect(upload.pending).toHaveLength(0);
+        },
+    );
+
+    it("reconciles a precise offset conflict while leaving other conflicts for manual retry", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        await upload.fail(409, 0, "UPLOAD_OFFSET_CHANGED");
+        expect(upload.manager.snapshot()[0].state).toBe("queued");
+        upload.setOffset(4);
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(upload.pending[0].offset).toBe(4);
+        await upload.fail(409, 0, "DESTINATION_UNAVAILABLE");
+        expect(upload.manager.snapshot()[0].state).toBe("error");
+        await vi.advanceTimersByTimeAsync(30_000);
+        expect(upload.pending).toHaveLength(0);
+    });
+
+    it("retries a stalled PATCH timeout as a transient transport failure", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        upload.pending
+            .shift()!
+            .reject(new DOMException("No progress", "TimeoutError"));
+        await upload.flush();
+        expect(upload.manager.snapshot()[0]).toMatchObject({
+            state: "queued",
+            stage: "retry_wait",
+        });
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(upload.pending).toHaveLength(1);
+        expect(upload.pending[0].offset).toBe(0);
+    });
+
+    it("stops after three retries without acknowledged progress and resets on manual retry", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        for (const delay of [2000, 4000, 8000]) {
+            await upload.fail();
+            await vi.advanceTimersByTimeAsync(delay - 1);
+            expect(upload.pending).toHaveLength(0);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(upload.pending).toHaveLength(1);
+        }
+        await upload.fail();
+        expect(upload.manager.snapshot()[0].state).toBe("error");
+        await vi.advanceTimersByTimeAsync(30_000);
+        expect(upload.pending).toHaveLength(0);
+        await upload.manager.retry(upload.manager.snapshot()[0].key);
+        await upload.flush();
+        await upload.fail();
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(upload.pending).toHaveLength(1);
+    });
+
+    it("starts a fresh retry allowance after acknowledged payload progress", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        for (const delay of [2000, 4000, 8000]) {
+            await upload.fail();
+            await vi.advanceTimersByTimeAsync(delay);
+        }
+        await upload.acknowledge();
+        expect(upload.pending[0].offset).toBe(4);
+        await upload.fail();
+        expect(upload.manager.snapshot()[0].state).toBe("queued");
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(upload.pending[0].offset).toBe(4);
+    });
+
+    it("honors a longer Retry-After and cancellation removes scheduled retries", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        await upload.fail(503, 20);
+        await vi.advanceTimersByTimeAsync(19_999);
+        expect(upload.pending).toHaveLength(0);
+        await upload.manager.cancel(upload.manager.snapshot()[0].key);
+        await vi.advanceTimersByTimeAsync(20_000);
+        expect(upload.pending).toHaveLength(0);
+        expect(upload.manager.snapshot()[0].state).toBe("cancelled");
+        expect(
+            upload.requests.filter((request) => request.startsWith("HEAD ")),
+        ).toHaveLength(0);
+    });
+
+    it("does not replay receipt creation when its result is uncertain", async () => {
+        const upload = await deviceUpload();
+        upload.failCreation(503);
+        await upload.start();
+        await vi.advanceTimersByTimeAsync(30_000);
+        expect(upload.manager.snapshot()[0]).toMatchObject({ state: "error" });
+        expect(upload.manager.snapshot()[0].uploadId).toBeUndefined();
+        expect(
+            upload.requests.filter(
+                (request) => request === "POST /api/v1/uploads",
+            ),
+        ).toHaveLength(1);
+        expect(upload.pending).toHaveLength(0);
+    });
+
+    it("retries a timed-out offset request through the same bounded retry policy", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        await upload.fail();
+        upload.failHead(new DOMException("Timed out", "TimeoutError"));
+        await vi.advanceTimersByTimeAsync(2000);
+        expect(upload.manager.snapshot()[0]).toMatchObject({
+            state: "queued",
+            stage: "retry_wait",
+        });
+        upload.failHead(undefined);
+        await vi.advanceTimersByTimeAsync(3999);
+        expect(upload.pending).toHaveLength(0);
+        await vi.advanceTimersByTimeAsync(1);
+        expect(upload.pending).toHaveLength(1);
+    });
+
+    it("keeps a late server job authoritative after a completion response is lost", async () => {
+        const upload = await deviceUpload();
+        await upload.start();
+        upload.failCompletion();
+        await upload.acknowledge();
+        await upload.acknowledge();
+        expect(upload.manager.snapshot()[0].state).toBe("queued");
+        upload.setJobs([
+            {
+                id: "receipt",
+                status: "running",
+                phase: "uploading",
+                current: 0,
+                total: 8,
+                name: "sample.bin",
+                destination: "/",
+            },
+        ]);
+        upload.manager.refreshJobs();
+        await upload.flush();
+        await vi.advanceTimersByTimeAsync(10_000);
+        expect(upload.manager.snapshot()[0]).toMatchObject({
+            jobId: "receipt",
+            state: "uploading",
+        });
+        expect(upload.manager.snapshot()[0].file).toBeUndefined();
+        expect(
+            upload.requests.filter((request) => request.endsWith("/complete")),
+        ).toHaveLength(1);
+    });
+});
diff --git a/website/src/features/transfers/deviceUploadStatus.test.ts b/website/src/features/transfers/deviceUploadStatus.test.ts
new file mode 100644
index 00000000..b54d133c
--- /dev/null
+++ b/website/src/features/transfers/deviceUploadStatus.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import {
+    deviceUploadMessage,
+    deviceUploadProgress,
+    needsDeviceUpload,
+} from "./deviceUploadStatus";
+import type { Transfer } from "./transfers";
+
+const local = (change: Partial<Transfer> = {}): Transfer => ({
+    key: "device-file",
+    name: "Photo.jpg",
+    size: 100,
+    total: 100,
+    current: 0,
+    lastModified: 0,
+    destination: "/",
+    initiatedHere: true,
+    state: "queued",
+    phase: "Waiting to send from this device",
+    ...change,
+});
+
+describe("device upload readiness", () => {
+    it("requires server acceptance even when every byte has been sent", () => {
+        for (const state of [
+            "queued",
+            "verifying",
+            "receiving",
+            "uploading",
+        ] as const) {
+            const item = local({ state, current: 100, sentCurrent: 100 });
+            expect(needsDeviceUpload(item)).toBe(true);
+            expect(deviceUploadProgress([item])).toMatchObject({
+                received: 0,
+                count: 1,
+                pending: true,
+                current: 100,
+                fraction: 0.99,
+            });
+            expect(deviceUploadMessage([item])).toContain("Keep this tab open");
+            expect(deviceUploadMessage([item])).not.toContain("You can close");
+        }
+    });
+
+    it("releases device dependence only after a job exists or the transfer ended", () => {
+        expect(
+            needsDeviceUpload(local({ jobId: "accepted", state: "uploading" })),
+        ).toBe(false);
+        expect(needsDeviceUpload(local({ state: "completed" }))).toBe(false);
+        expect(needsDeviceUpload(local({ state: "cancelled" }))).toBe(false);
+        expect(needsDeviceUpload(local({ state: "cancelling" }))).toBe(true);
+        expect(
+            deviceUploadMessage([
+                local({ jobId: "accepted", state: "uploading" }),
+            ]),
+        ).toBe("You can close this tab");
+    });
+
+    it("retains device dependence for missing originals and local upload failures", () => {
+        for (const state of ["error", "awaiting_file"] as const) {
+            expect(needsDeviceUpload(local({ state }))).toBe(true);
+            expect(needsDeviceUpload(local({ state, jobId: "accepted" }))).toBe(
+                false,
+            );
+            expect(deviceUploadMessage([local({ state })])).toContain(
+                "Keep this tab open",
+            );
+        }
+        expect(
+            deviceUploadMessage([local({ state: "error", jobId: "accepted" })]),
+        ).toBe("You can close this tab");
+    });
+
+    it("counts only uncancelled device files and confirms a whole batch together", () => {
+        const received = local({ jobId: "accepted", state: "uploading" });
+        const queued = local({ key: "queued" });
+        const completed = local({ key: "finished", state: "completed" });
+        const cancelled = local({ key: "cancelled", state: "cancelled" });
+        expect(
+            deviceUploadProgress([received, queued, completed, cancelled]),
+        ).toMatchObject({ received: 2, count: 3, current: 200, total: 300 });
+        expect(deviceUploadMessage([received, completed, cancelled])).toContain(
+            "You can close this tab",
+        );
+        expect(deviceUploadMessage([completed, cancelled])).toBeNull();
+        expect(deviceUploadMessage([])).toBeNull();
+    });
+
+    it("does not treat URL uploads or server history as device transfers", () => {
+        for (const change of [
+            { kind: "remote" },
+            { kind: "delete" },
+            { historyOnly: true },
+            { initiatedHere: false },
+        ]) {
+            const item = local(change);
+            expect(needsDeviceUpload(item)).toBe(false);
+            expect(deviceUploadMessage([item])).toBeNull();
+        }
+    });
+
+    it("does not offer to close the tab while another batch still needs the device", () => {
+        const received = local({ jobId: "accepted", state: "uploading" });
+        expect(deviceUploadMessage([received], true)).toBe(
+            "Keep this tab open for other uploads",
+        );
+        expect(deviceUploadMessage([received], true)).not.toContain(
+            "You can close",
+        );
+    });
+
+    it("uses live browser bytes and retains received bytes while Telegram progresses", () => {
+        const sending = local({
+            state: "receiving",
+            current: 20,
+            sentCurrent: 40,
+        });
+        const accepted = local({
+            key: "accepted",
+            jobId: "job",
+            state: "uploading",
+            current: 1,
+        });
+        expect(deviceUploadProgress([sending, accepted])).toMatchObject({
+            pending: true,
+            received: 1,
+            current: 140,
+            total: 200,
+            fraction: 0.7,
+        });
+        expect(
+            deviceUploadProgress([
+                { ...sending, state: "verifying", sentCurrent: 90 },
+            ]),
+        ).toMatchObject({ current: 20 });
+    });
+});
diff --git a/website/src/features/transfers/deviceUploadStatus.ts b/website/src/features/transfers/deviceUploadStatus.ts
new file mode 100644
index 00000000..cfd3faac
--- /dev/null
+++ b/website/src/features/transfers/deviceUploadStatus.ts
@@ -0,0 +1,86 @@
+import type { Transfer } from "./transfers";
+
+function isDeviceTransfer(item: Transfer): boolean {
+    return (
+        item.kind !== "remote" &&
+        item.kind !== "delete" &&
+        !item.historyOnly &&
+        item.initiatedHere === true
+    );
+}
+
+/** Device progress includes handed-off files, independent of their Telegram stage. */
+export function deviceUploadProgress(items: Transfer[]) {
+    const files = items.filter(
+        (item) => isDeviceTransfer(item) && item.state !== "cancelled",
+    );
+    const pending = files.filter(needsDeviceUpload);
+    const sizes = files.map((item) => item.size);
+    const known = sizes.every((size) => Number.isFinite(size) && size >= 0);
+    const total = known
+        ? sizes.reduce((sum, size) => sum + size, 0)
+        : undefined;
+    const current = files.reduce((sum, item) => {
+        if (!Number.isFinite(item.size) || item.size < 0) return sum;
+        if (!needsDeviceUpload(item)) return sum + item.size;
+        const observed =
+            item.state === "receiving" && Number.isFinite(item.sentCurrent)
+                ? Math.max(item.current, item.sentCurrent!)
+                : item.current;
+        return (
+            sum +
+            (Number.isFinite(observed)
+                ? Math.max(0, Math.min(observed, item.size))
+                : 0)
+        );
+    }, 0);
+    return {
+        count: files.length,
+        received: files.length - pending.length,
+        pending: pending.length > 0,
+        current,
+        total,
+        fraction:
+            total && total > 0
+                ? Math.min(pending.length ? 0.99 : 1, current / total)
+                : undefined,
+    };
+}
+
+/** A job ID confirms that the server owns the file and its remaining work. */
+export function needsDeviceUpload(item: Transfer): boolean {
+    return (
+        isDeviceTransfer(item) &&
+        !item.jobId &&
+        item.state !== "completed" &&
+        item.state !== "cancelled"
+    );
+}
+
+export function deviceUploadMessage(
+    items: Transfer[],
+    otherDeviceUploadsPending = false,
+): string | null {
+    const deviceItems = items.filter(
+        (item) => isDeviceTransfer(item) && item.state !== "cancelled",
+    );
+    // Finished receipts and server-discovered transfers need no device reminder.
+    if (
+        !deviceItems.length ||
+        deviceItems.every((item) => item.state === "completed")
+    )
+        return null;
+
+    const pending = deviceItems.filter(needsDeviceUpload).length;
+    if (pending) {
+        return "Keep this tab open";
+    }
+
+    if (otherDeviceUploadsPending)
+        return "Keep this tab open for other uploads";
+
+    if (deviceItems.some((item) => item.state === "error"))
+        return "You can close this tab";
+
+    return "You can close this tab";
+}
diff --git a/website/src/features/transfers/progress.test.ts b/website/src/features/transfers/progress.test.ts
new file mode 100644
index 00000000..3ec6caa2
--- /dev/null
+++ b/website/src/features/transfers/progress.test.ts
@@ -0,0 +1,307 @@
+import { describe, expect, it } from "vitest";
+import {
+    sampleProgress,
+    currentRate,
+    formatDuration,
+    formatProgressPercent,
+    transferDetails,
+    transferProgress,
+} from "./progress";
+describe("truthful stage timing", () => {
+    it("shows measured progress below one percent without rounding it up", () => {
+        expect(formatProgressPercent(16 / (1.62 * 1024))).toBe("0.9%");
+        expect(formatProgressPercent(0.00001)).toBe("<0.1%");
+        expect(formatProgressPercent(0)).toBe("0%");
+        expect(formatProgressPercent(0.25)).toBe("25%");
+    });
+    it("smooths acknowledged byte samples and expires stalled speed", () => {
+        const first = sampleProgress(undefined, "receipt", 0, 1000);
+        const second = sampleProgress(first, "receipt", 1000, 2000);
+        expect(currentRate(second, 2500)).toBe(1000);
+        const third = sampleProgress(second, "receipt", 3000, 3000);
+        expect(currentRate(third, 3000)).toBeGreaterThan(1000);
+        expect(currentRate(third, 19000)).toBeUndefined();
+    });
+    it("never carries throughput across stages, counter resets or restart gaps", () => {
+        const sample = sampleProgress(
+            sampleProgress(undefined, "download", 0, 1000),
+            "download",
+            100,
+            2000,
+        );
+        expect(sampleProgress(sample, "upload", 0, 3000).rate).toBeUndefined();
+        expect(
+            sampleProgress(sample, "download", 0, 3000).rate,
+        ).toBeUndefined();
+        expect(
+            sampleProgress(sample, "download", 200, 200000).rate,
+        ).toBeUndefined();
+    });
+    it("shows no fabricated ETA for unknown totals or server waits", () => {
+        const item = {
+            state: "uploading",
+            phase: "Downloading from URL",
+            stage: "downloading",
+            current: 40,
+            total: 0,
+            speedBytesPerSecond: 20,
+            serverObservedAt: 1000,
+        };
+        expect(transferDetails(item, 2000)).toMatchObject({
+            rate: 20,
+            eta: undefined,
+        });
+        expect(
+            transferDetails(
+                { ...item, stage: "retry_wait", total: 100, etaSeconds: 3 },
+                2000,
+            ).rate,
+        ).toBeUndefined();
+        expect(
+            transferDetails(
+                {
+                    ...item,
+                    total: 100,
+                    etaSeconds: 3,
+                    error: "Connection lost",
+                },
+                2000,
+            ).eta,
+        ).toBeUndefined();
+        expect(
+            transferDetails({ ...item, total: 100, etaSeconds: 3 }, 17000).eta,
+        ).toBeUndefined();
+    });
+    it("calculates a stage estimate from fresh measured speed when the server omits ETA", () => {
+        const item = {
+            state: "uploading",
+            phase: "Sending to Telegram",
+            stage: "uploading",
+            current: 40,
+            total: 100,
+            speedBytesPerSecond: 20,
+            serverObservedAt: 2000,
+            progressUpdatedAt: 2,
+        };
+        expect(transferDetails(item, 2100)).toMatchObject({ rate: 20, eta: 3 });
+        expect(transferDetails({ ...item, etaSeconds: NaN }, 2100).eta).toBe(3);
+        expect(
+            transferDetails({ ...item, speedBytesPerSecond: -20 }, 2100),
+        ).toMatchObject({
+            rate: undefined,
+            eta: undefined,
+            timing: "calculating",
+        });
+    });
+    it("distinguishes initial measurements, stalls, provider waits and stage completion", () => {
+        const item = {
+            state: "uploading",
+            phase: "Downloading from URL",
+            stage: "downloading",
+            current: 20,
+            total: 100,
+            serverObservedAt: 2000,
+            progressUpdatedAt: 2,
+        };
+        expect(transferDetails(item, 2100).timing).toBe("calculating");
+        expect(transferDetails(item, 18000)).toMatchObject({
+            rate: undefined,
+            eta: undefined,
+            timing: "stalled",
+        });
+        expect(
+            transferDetails({ ...item, stage: "retry_wait" }, 2100).timing,
+        ).toBe("waiting");
+        expect(
+            transferDetails({ ...item, stage: "finalizing" }, 2100).timing,
+        ).toBe("finishing");
+        expect(transferDetails({ ...item, current: 100 }, 2100).timing).toBe(
+            "finishing",
+        );
+        expect(
+            transferDetails(
+                {
+                    ...item,
+                    state: "receiving",
+                    meter: {
+                        stage: "receiving",
+                        bytes: 20,
+                        at: 1000,
+                        advancedAt: 1000,
+                        rate: 20,
+                    },
+                },
+                18000,
+            ).timing,
+        ).toBe("stalled");
+    });
+    it("keeps elapsed time through reloads and freezes terminal durations", () => {
+        const item = {
+            state: "completed",
+            phase: "Available",
+            current: 100,
+            total: 100,
+            createdAt: 1000,
+            startedAt: 2000,
+            finishedAt: 5000,
+        };
+        expect(transferDetails(item, 99000).elapsed).toBe(3);
+        expect(
+            transferDetails(
+                {
+                    ...item,
+                    kind: "delete",
+                    state: "uploading",
+                    stage: "uploading",
+                    speedBytesPerSecond: 30,
+                    serverObservedAt: 99000,
+                },
+                99000,
+            ).rate,
+        ).toBeUndefined();
+        expect(formatDuration(3661)).toBe("1h 1m");
+    });
+});
+
+it("does not show queue age or stale server-queue speed as work", () => {
+    const queued = {
+        state: "queued",
+        phase: "Waiting",
+        current: 0,
+        total: 100,
+        createdAt: 1000,
+    };
+    expect(transferDetails(queued, 120000)).toMatchObject({
+        elapsed: undefined,
+        rate: undefined,
+        eta: undefined,
+        measuring: false,
+    });
+    expect(
+        transferDetails(
+            {
+                ...queued,
+                state: "uploading",
+                stage: "uploading",
+                serverStatus: "queued",
+                speedBytesPerSecond: 50,
+                etaSeconds: 2,
+                serverObservedAt: 120000,
+            },
+            120001,
+        ),
+    ).toMatchObject({ rate: undefined, eta: undefined, measuring: false });
+    expect(
+        transferDetails(
+            {
+                ...queued,
+                state: "receiving",
+                startedAt: 119000,
+            },
+            120000,
+        ).elapsed,
+    ).toBe(1);
+});
+
+describe("stage-local byte and percentage display", () => {
+    const item = {
+        state: "receiving",
+        phase: "Sending from your device",
+        current: 100,
+        total: 100,
+    };
+    it("starts Telegram at zero after finishing the device transfer", () => {
+        expect(transferProgress(item)).toMatchObject({
+            current: 100,
+            fraction: 0.99,
+        });
+        expect(
+            transferProgress({
+                ...item,
+                state: "uploading",
+                stage: "uploading",
+                current: 0,
+            }),
+        ).toMatchObject({ current: 0, fraction: 0 });
+        expect(
+            transferProgress({
+                ...item,
+                state: "uploading",
+                stage: "uploading",
+                current: 38,
+            }),
+        ).toMatchObject({ current: 38, fraction: 0.38 });
+        expect(transferProgress({ ...item, state: "completed" }).fraction).toBe(
+            1,
+        );
+    });
+    it("bounds invalid counts and never displays old progress for a queued job", () => {
+        expect(
+            transferProgress({
+                ...item,
+                state: "uploading",
+                stage: "uploading",
+                serverStatus: "queued",
+            }),
+        ).toMatchObject({ current: 0, fraction: 0 });
+        expect(transferProgress({ ...item, current: Infinity }).current).toBe(
+            0,
+        );
+        expect(transferProgress({ ...item, current: -1 }).current).toBe(0);
+        expect(
+            transferProgress({ ...item, total: 0 }).fraction,
+        ).toBeUndefined();
+        expect(
+            transferProgress({ ...item, total: Infinity }).fraction,
+        ).toBeUndefined();
+    });
+    it("shows measured in-flight bytes without treating them as a saved resume offset", () => {
+        const observed = { ...item, current: 20, sentCurrent: 45 };
+        expect(transferProgress(observed)).toMatchObject({
+            current: 45,
+            fraction: 0.45,
+        });
+        expect(transferProgress({ ...observed, state: "error" }).current).toBe(
+            20,
+        );
+        expect(
+            transferProgress({ ...observed, state: "uploading" }).current,
+        ).toBe(20);
+        expect(
+            transferDetails({ ...observed, stage: "confirming" }, 1000),
+        ).toMatchObject({ rate: undefined, eta: undefined });
+    });
+});
+
+it("keeps acknowledged upload progress during local verification without reporting hashing speed", () => {
+    const item = {
+        state: "verifying",
+        phase: "Checking the original file before resuming",
+        current: 87,
+        total: 100,
+        meter: {
+            stage: "old",
+            bytes: 87,
+            at: 1000,
+            advancedAt: 1000,
+            rate: 268000000,
+        },
+        speedBytesPerSecond: 268000000,
+        etaSeconds: 1,
+        serverObservedAt: 1000,
+    };
+    expect(transferProgress(item)).toMatchObject({
+        current: 87,
+        total: 100,
+        fraction: 0.87,
+    });
+    expect(transferDetails(item, 1100)).toMatchObject({
+        rate: undefined,
+        eta: undefined,
+        measuring: false,
+    });
+    const baseline = sampleProgress(undefined, "receiving", 87, 2000);
+    expect(baseline.rate).toBeUndefined();
+    const resumed = sampleProgress(baseline, "receiving", 97, 3000);
+    expect(resumed.rate).toBe(10); // Only new bytes count toward transfer speed.
+});
diff --git a/website/src/features/transfers/progress.ts b/website/src/features/transfers/progress.ts
new file mode 100644
index 00000000..a05ede1f
--- /dev/null
+++ b/website/src/features/transfers/progress.ts
@@ -0,0 +1,198 @@
+export interface ProgressSample {
+    stage: string;
+    bytes: number;
+    at: number;
+    advancedAt: number;
+    rate?: number;
+}
+/** Rate uses observed transport bytes; it never extrapolates stalled progress. */
+export function sampleProgress(
+    previous: ProgressSample | undefined,
+    stage: string,
+    bytes: number,
+    now: number,
+): ProgressSample {
+    if (
+        !previous ||
+        previous.stage !== stage ||
+        bytes < previous.bytes ||
+        now < previous.at ||
+        now - previous.at > 120000
+    )
+        return { stage, bytes, at: now, advancedAt: now };
+    if (bytes === previous.bytes) return previous;
+    const seconds = (now - previous.at) / 1000;
+    if (seconds < 0.1) return previous;
+    const instant = (bytes - previous.bytes) / seconds;
+    const weight = 1 - Math.exp(-seconds / 5);
+    return {
+        stage,
+        bytes,
+        at: now,
+        advancedAt: now,
+        rate:
+            previous.rate === undefined
+                ? instant
+                : previous.rate + weight * (instant - previous.rate),
+    };
+}
+export function currentRate(
+    sample: ProgressSample | undefined,
+    now: number,
+): number | undefined {
+    return sample?.rate &&
+        Number.isFinite(sample.rate) &&
+        now - sample.advancedAt < 15000
+        ? sample.rate
+        : undefined;
+}
+export function formatDuration(seconds: number): string {
+    if (!Number.isFinite(seconds) || seconds < 0) return "—";
+    const whole = Math.floor(seconds);
+    if (whole < 60) return whole + "s";
+    if (whole < 3600) return Math.floor(whole / 60) + "m " + (whole % 60) + "s";
+    if (whole < 86400)
+        return (
+            Math.floor(whole / 3600) +
+            "h " +
+            Math.floor((whole % 3600) / 60) +
+            "m"
+        );
+    return (
+        Math.floor(whole / 86400) +
+        "d " +
+        Math.floor((whole % 86400) / 3600) +
+        "h"
+    );
+}
+
+/** Keep small measured transfers visible instead of rounding received data to 0%. */
+export function formatProgressPercent(fraction: number): string {
+    if (!Number.isFinite(fraction) || fraction <= 0) return "0%";
+    const percent = Math.floor(Math.min(1, fraction) * 1000) / 10;
+    if (percent === 0) return "<0.1%";
+    return (percent < 10 ? percent.toFixed(1) : Math.floor(percent)) + "%";
+}
+
+export interface ProgressTransfer {
+    state: string;
+    kind?: string;
+    stage?: string;
+    phase: string;
+    current: number;
+    sentCurrent?: number;
+    total: number;
+    createdAt?: number;
+    startedAt?: number;
+    serverStatus?: string;
+    finishedAt?: number;
+    meter?: ProgressSample;
+    error?: string;
+    speedBytesPerSecond?: number | null;
+    etaSeconds?: number | null;
+    progressUpdatedAt?: number | null;
+    serverObservedAt?: number;
+}
+export function transferDetails(item: ProgressTransfer, now: number) {
+    const local =
+        item.state === "receiving" &&
+        !["preparing", "confirming"].includes(item.stage || "");
+    const server =
+        item.state === "uploading" &&
+        item.serverStatus !== "queued" &&
+        ["saving", "uploading", "downloading"].includes(item.stage || "") &&
+        item.kind !== "delete";
+    const freshServer =
+        now - (item.serverObservedAt || 0) < 15000 &&
+        (!item.progressUpdatedAt ||
+            now - item.progressUpdatedAt * 1000 < 15000);
+    const rate = local
+        ? currentRate(item.meter, now)
+        : server &&
+            freshServer &&
+            !item.error &&
+            item.speedBytesPerSecond &&
+            Number.isFinite(item.speedBytesPerSecond) &&
+            item.speedBytesPerSecond > 0
+          ? item.speedBytesPerSecond
+          : undefined;
+    const remaining =
+        item.total > 0
+            ? Math.max(0, item.total - transferProgress(item).current)
+            : undefined;
+    const serverEta = item.etaSeconds;
+    const eta =
+        rate && remaining
+            ? !local &&
+              typeof serverEta === "number" &&
+              Number.isFinite(serverEta) &&
+              serverEta > 0
+                ? serverEta
+                : remaining / rate
+            : undefined;
+    const lastAdvance = local
+        ? item.meter?.advancedAt
+        : item.progressUpdatedAt
+          ? item.progressUpdatedAt * 1000
+          : undefined;
+    const timing =
+        item.state === "uploading" &&
+        ["retry_wait", "source_retry_wait", "waiting_for_telegram"].includes(
+            item.stage || "",
+        )
+            ? "waiting"
+            : (item.state === "receiving" && item.stage === "confirming") ||
+                (item.state === "uploading" &&
+                    ["finalizing", "backup_pending"].includes(
+                        item.stage || "",
+                    )) ||
+                ((local || server) && remaining === 0)
+              ? "finishing"
+              : (local || server) && !rate
+                ? (lastAdvance !== undefined && now - lastAdvance >= 15000) ||
+                  (server && !freshServer)
+                    ? "stalled"
+                    : "calculating"
+                : undefined;
+    const end = item.finishedAt || now;
+    return {
+        elapsed:
+            item.startedAt && Number.isFinite(item.startedAt)
+                ? Math.max(0, (end - item.startedAt) / 1000)
+                : undefined,
+        rate,
+        eta: eta && Number.isFinite(eta) && eta > 0 ? eta : undefined,
+        measuring: (local || server) && !rate,
+        timing,
+    };
+}
+
+/** The visible bar and byte counter always describe the same transfer stage. */
+export function transferProgress(item: ProgressTransfer) {
+    const total =
+        Number.isFinite(item.total) && item.total > 0 ? item.total : 0;
+    const queued =
+        item.state === "queued" ||
+        (item.state === "uploading" &&
+            (item.stage === "queued" || item.serverStatus === "queued"));
+    const observed =
+        item.state === "receiving" && Number.isFinite(item.sentCurrent)
+            ? Math.max(item.current, item.sentCurrent!)
+            : item.current;
+    const current =
+        item.state === "completed"
+            ? total
+            : queued || !Number.isFinite(observed)
+              ? 0
+              : Math.max(0, Math.min(observed, total || observed));
+    return {
+        current,
+        total,
+        fraction:
+            item.state === "completed"
+                ? 1
+                : total
+                  ? Math.min(0.99, current / total)
+                  : undefined,
+    };
+}
diff --git a/website/src/features/transfers/transferBatches.test.ts b/website/src/features/transfers/transferBatches.test.ts
new file mode 100644
index 00000000..fa85f5d5
--- /dev/null
+++ b/website/src/features/transfers/transferBatches.test.ts
@@ -0,0 +1,802 @@
+import { describe, expect, it } from "vitest";
+import type { Transfer } from "./transfers";
+import { summarizeBatches, batchCategory } from "./transferBatches";
+
+function item(overrides: Partial<Transfer> = {}): Transfer {
+    const relativePath = Object.hasOwn(overrides, "relativePath")
+        ? overrides.relativePath
+        : "My folder/one.bin";
+    const batchId = Object.hasOwn(overrides, "batchId")
+        ? overrides.batchId
+        : "batch";
+    return {
+        key: "one",
+        initiatedHere: true,
+        name: "one.bin",
+        size: 100,
+        lastModified: 0,
+        destination: "/",
+        batchId: "batch",
+        batchName: "My folder",
+        relativePath: "My folder/one.bin",
+        folderUpload:
+            relativePath && batchId
+                ? {
+                      id: batchId,
+                      name: overrides.batchName || "My folder",
+                      root_path: "/folder",
+                      created_at: 1,
+                  }
+                : undefined,
+        batchCreatedAt: 1000,
+        state: "queued",
+        phase: "Waiting",
+        current: 0,
+        total: 100,
+        ...overrides,
+    };
+}
+function summary(items: Transfer[], now = 10000) {
+    return summarizeBatches(items, now)[0];
+}
+const rate = {
+    serverObservedAt: 9000,
+    progressUpdatedAt: 9,
+    speedBytesPerSecond: 10,
+};
+
+describe("truthful batch work", () => {
+    it("weights file bytes instead of averaging file percentages", () => {
+        const batch = summary([
+            item({
+                size: 900,
+                total: 900,
+                state: "completed",
+                finishedAt: 8000,
+            }),
+            item({ key: "small", size: 100, state: "queued" }),
+        ]);
+        expect(batch.totalBytes).toBe(1000);
+        expect(batch.completedBytes).toBe(900);
+        expect(batch.progress).toBe(0.9);
+        expect(batch).toMatchObject({
+            count: 2,
+            completed: 1,
+            queued: 1,
+            active: 0,
+            pending: true,
+        });
+    });
+    it("uses the actual stage counter and resets for the Telegram queue", () => {
+        expect(
+            summary([item({ state: "receiving", current: 100 })]).progress,
+        ).toBe(0.99);
+        expect(
+            summary([item({ state: "verifying", current: 50, total: 50 })])
+                .progress,
+        ).toBe(0.5);
+        expect(
+            summary([item({ state: "awaiting_file", current: 1000 })]).progress,
+        ).toBe(0.99);
+        expect(
+            summary([
+                item({
+                    state: "uploading",
+                    jobId: "job",
+                    stage: "queued",
+                    current: 100,
+                }),
+            ]).progress,
+        ).toBe(0);
+        expect(
+            summary([
+                item({
+                    state: "uploading",
+                    jobId: "job",
+                    stage: "uploading",
+                    current: 40,
+                }),
+            ]).progress,
+        ).toBe(0.4);
+    });
+    it("resets to the new stage counter and never treats finalization as complete", () => {
+        const receiving = item({ state: "receiving", current: 100 });
+        expect(summary([receiving]).progress).toBe(0.99);
+        const sending = {
+            ...receiving,
+            state: "uploading" as const,
+            jobId: "job",
+            stage: "uploading",
+            current: 0,
+        };
+        expect(summary([sending]).progress).toBe(0);
+        expect(
+            summary([{ ...sending, current: 100, stage: "finalizing" }])
+                .progress,
+        ).toBe(0.99);
+        expect(summary([{ ...sending, state: "completed" }]).progress).toBe(1);
+    });
+    it("bounds invalid counters and suppresses percentages for unknown sizes", () => {
+        expect(
+            summary([item({ state: "receiving", current: -20 })]).progress,
+        ).toBe(0);
+        expect(
+            summary([item({ state: "receiving", current: Infinity })]).progress,
+        ).toBe(0);
+        expect(summary([item({ size: 0, total: 0 })]).progress).toBeUndefined();
+        expect(
+            summary([item({ size: 0, total: 0 })]).totalBytes,
+        ).toBeUndefined();
+        expect(
+            summary([item({ size: 0, total: 0, state: "completed" })]).progress,
+        ).toBe(1);
+        expect(
+            summary([
+                item({
+                    size: 0,
+                    total: 20,
+                    jobId: "job",
+                    state: "uploading",
+                    current: 5,
+                }),
+            ]).progress,
+        ).toBe(0.25);
+    });
+    it("never counts cancelled or failed files as confirmed completion", () => {
+        const batch = summary([
+            item({ state: "completed", finishedAt: 7000 }),
+            item({
+                key: "cancelled",
+                state: "cancelled",
+                jobId: "job",
+                current: 100,
+                finishedAt: 8000,
+            }),
+        ]);
+        expect(batch).toMatchObject({
+            completed: 1,
+            cancelled: 1,
+            completedBytes: 100,
+            pending: false,
+            progress: 0.5,
+        });
+        expect(
+            summary([item({ state: "error", current: 100, jobId: "job" })]),
+        ).toMatchObject({
+            failed: 1,
+            pending: true,
+            progress: 0.99,
+            completedBytes: 0,
+        });
+    });
+    it("keeps URL imports and deletions on their own stage units", () => {
+        const remote = summary([
+            item({
+                kind: "remote",
+                state: "uploading",
+                stage: "downloading",
+                size: 0,
+                current: 25,
+                total: 100,
+                jobId: "job",
+            }),
+        ]);
+        expect(remote.progress).toBe(0.25);
+        expect(remote.totalBytes).toBe(100);
+        expect(
+            summary([item({ kind: "remote", total: 0, size: 0 })]).progress,
+        ).toBeUndefined();
+        const deletion = summary([
+            item({
+                kind: "delete",
+                jobId: "job",
+                state: "uploading",
+                current: 2,
+                total: 4,
+            }),
+        ]);
+        expect(deletion).toMatchObject({ progress: 0.5, completedBytes: 0 });
+        expect(deletion.totalBytes).toBeUndefined();
+        expect(
+            summary([item({ kind: "delete", state: "completed" })]).progress,
+        ).toBe(1);
+        const mixed = summary([
+            item({ state: "completed" }),
+            item({
+                key: "delete",
+                kind: "delete",
+                state: "uploading",
+                current: 3,
+                total: 5,
+            }),
+        ]);
+        expect(mixed.progress).toBeUndefined();
+        expect(mixed.totalBytes).toBeUndefined();
+    });
+});
+
+describe("stage rates and batch ETA", () => {
+    it("sums fresh device and Telegram rates independently", () => {
+        const batch = summary([
+            item({
+                state: "receiving",
+                meter: {
+                    stage: "receipt",
+                    bytes: 20,
+                    at: 9000,
+                    advancedAt: 9000,
+                    rate: 20,
+                },
+            }),
+            item({
+                key: "server",
+                state: "uploading",
+                jobId: "job",
+                stage: "uploading",
+                current: 40,
+                ...rate,
+            }),
+        ]);
+        expect(batch.deviceRate).toBe(20);
+        expect(batch.telegramRate).toBe(10);
+        expect(batch.eta).toBeUndefined();
+    });
+    it("omits stale, failed, finalizing and URL-download rates", () => {
+        expect(
+            summary(
+                [
+                    item({
+                        state: "receiving",
+                        meter: {
+                            stage: "receipt",
+                            bytes: 20,
+                            at: 1000,
+                            advancedAt: 1000,
+                            rate: 20,
+                        },
+                    }),
+                ],
+                17000,
+            ).deviceRate,
+        ).toBeUndefined();
+        for (const change of [
+            { serverObservedAt: 1000 },
+            { progressUpdatedAt: 1 },
+            { error: "Disconnected" },
+            { stage: "retry_wait" },
+            { stage: "finalizing" },
+            { kind: "remote", stage: "downloading" },
+        ]) {
+            const batch = summary(
+                [
+                    item({
+                        state: "uploading",
+                        jobId: "job",
+                        stage: "uploading",
+                        ...rate,
+                        ...change,
+                    }),
+                ],
+                17000,
+            );
+            expect(batch.telegramRate).toBeUndefined();
+            expect(batch.eta).toBeUndefined();
+        }
+    });
+    it("estimates only known remaining server-side Telegram work", () => {
+        const running = item({
+            state: "uploading",
+            jobId: "job",
+            stage: "uploading",
+            current: 40,
+            ...rate,
+        });
+        const queued = item({
+            key: "next",
+            state: "uploading",
+            jobId: "nextjob",
+            stage: "queued",
+            current: 80,
+        });
+        const batch = summary([running, queued]);
+        expect(batch.telegramRate).toBe(10);
+        expect(batch.eta).toBe(16);
+        for (const change of [
+            { state: "error" as const },
+            { state: "awaiting_file" as const },
+            { state: "cancelling" as const },
+            { stage: "retry_wait" },
+            { stage: "waiting_for_telegram" },
+            { stage: "finalizing" },
+            { size: 0, total: 0 },
+            { jobId: undefined },
+        ])
+            expect(
+                summary([running, { ...queued, ...change }]).eta,
+            ).toBeUndefined();
+        expect(summary([running, { ...queued, state: "cancelled" }]).eta).toBe(
+            6,
+        );
+        expect(
+            summary([
+                running,
+                { ...queued, state: "cancelled", size: 0, total: 0 },
+            ]).eta,
+        ).toBe(6);
+    });
+
+    it("allows byte-complete publishing siblings without estimating their publication wait", () => {
+        const running = item({
+            state: "uploading",
+            jobId: "job",
+            stage: "uploading",
+            current: 40,
+            ...rate,
+        });
+        for (const stage of ["finalizing", "backup_pending"]) {
+            const publishing = item({
+                key: "publishing",
+                jobId: "publishing",
+                state: "uploading",
+                stage,
+                current: 100,
+            });
+            expect(summary([running, publishing]).eta).toBe(6);
+            expect(summary([publishing]).eta).toBeUndefined();
+        }
+    });
+
+    it("uses fresh batch observations only as a fallback for the displayed stage", () => {
+        const running = item({
+            state: "uploading",
+            jobId: "job",
+            stage: "uploading",
+            current: 40,
+        });
+        const meter = new Map([
+            [
+                "batch",
+                {
+                    stage: "telegram",
+                    bytes: 40,
+                    at: 9000,
+                    advancedAt: 9000,
+                    rate: 20,
+                },
+            ],
+        ]);
+        expect(summarizeBatches([running], 10000, meter)[0]).toMatchObject({
+            telegramRate: 20,
+            displayEta: 3,
+        });
+        expect(
+            summarizeBatches([{ ...running, ...rate }], 10000, meter)[0],
+        ).toMatchObject({
+            telegramRate: 10,
+            displayEta: 6,
+        });
+        expect(
+            summarizeBatches([running], 24000, meter)[0].displayEta,
+        ).toBeUndefined();
+        meter.get("batch")!.stage = "device";
+        expect(
+            summarizeBatches([running], 10000, meter)[0].displayEta,
+        ).toBeUndefined();
+    });
+
+    it("does not let a Telegram failure hide healthy pending device ETA", () => {
+        const device = item({
+            state: "receiving",
+            current: 50,
+            meter: {
+                stage: "receiving",
+                bytes: 50,
+                at: 9000,
+                advancedAt: 9000,
+                rate: 10,
+            },
+        });
+        const failed = item({
+            key: "server-error",
+            jobId: "accepted",
+            state: "error",
+            error: "Telegram failed",
+        });
+        expect(summary([device, failed]).displayEta).toBe(5);
+        expect(
+            summary([
+                { ...device, state: "queued", stage: "retry_wait" },
+                failed,
+            ]).displayEta,
+        ).toBeUndefined();
+        expect(
+            summary([{ ...device, state: "awaiting_file" }, failed]).displayEta,
+        ).toBeUndefined();
+    });
+});
+
+describe("batch identity, attention and elapsed time", () => {
+    it("keeps each ordinary selection in its own file task", () => {
+        const tasks = summarizeBatches(
+            [
+                item({
+                    key: "first",
+                    name: "first.bin",
+                    relativePath: undefined,
+                }),
+                item({
+                    key: "second",
+                    name: "second.bin",
+                    relativePath: undefined,
+                }),
+            ],
+            10000,
+        );
+        expect(tasks).toHaveLength(2);
+        expect(tasks.map((task) => task.name).sort()).toEqual([
+            "first.bin",
+            "second.bin",
+        ]);
+        expect(tasks.every((task) => task.count === 1 && !task.folder)).toBe(
+            true,
+        );
+        expect(new Set(tasks.map((task) => task.id)).size).toBe(2);
+    });
+    it("uses persisted folder metadata across independently discovered server rows", () => {
+        const folderUpload = {
+            id: "folder-upload-identity",
+            name: "Project files",
+            root_path: "/project-root",
+            created_at: 1,
+        };
+        const tasks = summarizeBatches(
+            [
+                item({
+                    key: "server-one",
+                    batchId: "history:one",
+                    relativePath: undefined,
+                    folderUpload,
+                }),
+                item({
+                    key: "server-two",
+                    batchId: "server:two",
+                    relativePath: undefined,
+                    folderUpload,
+                }),
+            ],
+            10000,
+        );
+        expect(tasks).toHaveLength(1);
+        expect(tasks[0]).toMatchObject({
+            id: folderUpload.id,
+            name: folderUpload.name,
+            folder: true,
+            count: 2,
+        });
+        expect(summary([tasks[0].items[0]])).toMatchObject({
+            id: folderUpload.id,
+            folder: true,
+            count: 1,
+        });
+    });
+    it("sorts attention, active and finished batches by newest within class", () => {
+        const rows = [
+            item({
+                key: "done",
+                batchId: "done",
+                state: "completed",
+                batchCreatedAt: 9000,
+            }),
+            item({
+                key: "active-old",
+                batchId: "active-old",
+                batchCreatedAt: 2000,
+            }),
+            item({
+                key: "error",
+                batchId: "error",
+                state: "error",
+                batchCreatedAt: 3000,
+            }),
+            item({
+                key: "await",
+                batchId: "await",
+                state: "awaiting_file",
+                batchCreatedAt: 4000,
+            }),
+            item({
+                key: "active-new",
+                batchId: "active-new",
+                batchCreatedAt: 5000,
+            }),
+        ];
+        expect(summarizeBatches(rows, 10000).map((batch) => batch.id)).toEqual([
+            "await",
+            "error",
+            "active-new",
+            "active-old",
+            "done",
+        ]);
+        expect(rows.map((row) => row.key)).toEqual([
+            "done",
+            "active-old",
+            "error",
+            "await",
+            "active-new",
+        ]);
+    });
+    it("sorts member attention before running, queued and terminal files", () => {
+        const rows = [
+            item({ key: "cancel", state: "cancelled" }),
+            item({ key: "done", state: "completed" }),
+            item({ key: "queue", state: "queued" }),
+            item({ key: "active", state: "receiving" }),
+            item({ key: "await", state: "awaiting_file" }),
+            item({ key: "error", state: "error" }),
+        ];
+        const batch = summary(rows);
+        expect(batch.items.map((row) => row.key)).toEqual([
+            "error",
+            "await",
+            "active",
+            "queue",
+            "done",
+            "cancel",
+        ]);
+        expect(batch).toMatchObject({
+            count: 6,
+            completed: 1,
+            cancelled: 1,
+            failed: 1,
+            awaiting: 1,
+            active: 1,
+            queued: 1,
+        });
+    });
+    it("uses stable local identities for standalone files", () => {
+        expect(
+            summarizeBatches(
+                [
+                    item({
+                        batchId: undefined,
+                        relativePath: undefined,
+                        jobId: "server",
+                    }),
+                    item({
+                        key: "local",
+                        batchId: undefined,
+                        relativePath: undefined,
+                    }),
+                ],
+                10000,
+            )
+                .map((batch) => batch.id)
+                .sort(),
+        ).toEqual(["local", "one"]);
+        expect(
+            summary([
+                item({
+                    batchId: undefined,
+                    batchName: undefined,
+                    relativePath: undefined,
+                }),
+            ]).name,
+        ).toBe("one.bin");
+        expect(summarizeBatches([], 10000)).toEqual([]);
+    });
+    it("starts with actual work and freezes only fully settled batches", () => {
+        const rows = [
+            item({
+                createdAt: 3000,
+                startedAt: 4000,
+                batchCreatedAt: 1000,
+                state: "completed",
+                finishedAt: 5000,
+            }),
+            item({
+                key: "two",
+                createdAt: 4000,
+                startedAt: 5000,
+                batchCreatedAt: 2000,
+                state: "cancelled",
+                finishedAt: 7000,
+            }),
+        ];
+        expect(summary(rows, 90000).elapsed).toBe(3);
+        expect(summary([{ ...rows[0], state: "error" }], 90000).elapsed).toBe(
+            86,
+        );
+        expect(
+            summary([item({ createdAt: undefined, batchCreatedAt: undefined })])
+                .elapsed,
+        ).toBeUndefined();
+        expect(
+            summary([item({ state: "completed", finishedAt: undefined })])
+                .elapsed,
+        ).toBeUndefined();
+    });
+});
+
+it("recognizes server queued status without reusing the old counter or rate", () => {
+    const queued = item({
+        state: "uploading",
+        jobId: "job",
+        serverStatus: "queued",
+        stage: "uploading",
+        current: 100,
+        ...rate,
+    });
+    expect(summary([queued])).toMatchObject({
+        progress: 0,
+        queued: 1,
+        active: 0,
+    });
+    expect(summary([queued]).telegramRate).toBeUndefined();
+    expect(summary([{ ...queued, kind: "remote" }]).progress).toBe(0);
+});
+
+it("keeps missing dates behind newer batches and emits no nonfinite ETA", () => {
+    const missing = item({
+        key: "missing",
+        batchId: "missing",
+        batchCreatedAt: undefined,
+        createdAt: undefined,
+    });
+    const known = item({
+        key: "known",
+        batchId: "known",
+        batchCreatedAt: 1000,
+    });
+    expect(
+        summarizeBatches([missing, known], 10000).map((batch) => batch.id),
+    ).toEqual(["known", "missing"]);
+    expect(
+        summary([
+            item({
+                state: "uploading",
+                jobId: "job",
+                stage: "uploading",
+                ...rate,
+                speedBytesPerSecond: 1e-320,
+            }),
+        ]).eta,
+    ).toBeUndefined();
+});
+
+it("keeps queued-only batches free of elapsed time and ETA", () => {
+    const queued = item({ createdAt: 1000, batchCreatedAt: 1000 });
+    expect(summary([queued], 3600000)).toMatchObject({
+        queued: 1,
+        elapsed: undefined,
+        deviceRate: undefined,
+        telegramRate: undefined,
+        eta: undefined,
+    });
+    const working = item({
+        key: "started",
+        state: "receiving",
+        createdAt: 2000,
+        startedAt: 9000,
+    });
+    expect(summary([queued, working], 10000).elapsed).toBe(1);
+});
+
+it("keeps Telegram accounting separate while device progress owns the visible bar", () => {
+    const sending = item({
+        key: "sending",
+        state: "uploading",
+        jobId: "job",
+        stage: "uploading",
+        current: 40,
+    });
+    const receiving = item({ key: "device", state: "receiving", current: 100 });
+    const first = summary([sending, receiving]);
+    expect(first).toMatchObject({
+        uploadedBytes: 40,
+        completedBytes: 0,
+        totalBytes: 200,
+        displayBytes: 200,
+        progress: 0.99,
+        device: { pending: true, received: 1, count: 2 },
+    });
+    expect(summary([{ ...sending, current: 60 }, receiving])).toMatchObject({
+        uploadedBytes: 60,
+        progress: 0.99,
+    });
+    expect(
+        summary([{ ...sending, state: "completed" }, receiving]),
+    ).toMatchObject({
+        uploadedBytes: 100,
+        completedBytes: 100,
+        progress: 0.99,
+    });
+    expect(
+        summary([{ ...sending, current: 100, stage: "queued" }, receiving]),
+    ).toMatchObject({ uploadedBytes: 0, progress: 0.99 });
+    expect(
+        summary([
+            sending,
+            {
+                ...receiving,
+                jobId: "second",
+                state: "uploading",
+                stage: "queued",
+                current: 0,
+            },
+        ]),
+    ).toMatchObject({
+        device: { pending: false, received: 2 },
+        uploadedBytes: 40,
+        displayBytes: 40,
+        progress: 0.2,
+    });
+});
+
+it("puts pending device batches before Telegram work even when they are older", () => {
+    const device = item({ batchId: "device", batchCreatedAt: 1000 });
+    const telegram = item({
+        key: "telegram",
+        batchId: "telegram",
+        batchCreatedAt: 9000,
+        jobId: "job",
+        state: "uploading",
+        stage: "uploading",
+    });
+    expect(
+        summarizeBatches([telegram, device], 10000).map((batch) => batch.id),
+    ).toEqual(["device", "telegram"]);
+});
+
+it("does not count finalizing bytes twice or invent cancelled upload completion", () => {
+    const done = item({ state: "completed" });
+    const sending = item({
+        key: "sending",
+        state: "uploading",
+        jobId: "job",
+        stage: "finalizing",
+        current: 100,
+    });
+    expect(summary([done, sending])).toMatchObject({
+        uploadedBytes: 200,
+        totalBytes: 200,
+        progress: 0.99,
+    });
+    expect(summary([done, { ...sending, state: "error" }])).toMatchObject({
+        uploadedBytes: 100,
+        progress: 0.5,
+    });
+});
+
+it("keeps one folder category until every child completes", () => {
+    const running = item({
+        key: "running",
+        state: "uploading",
+        stage: "uploading",
+    });
+    const queued = item({ key: "queued", state: "queued" });
+    const completed = item({ key: "done", state: "completed" });
+    expect(batchCategory(summary([running, queued, completed]))).toBe(
+        "running",
+    );
+    expect(batchCategory(summary([queued, completed]))).toBe("queued");
+    expect(
+        batchCategory(
+            summary([queued, item({ key: "failed-sibling", state: "error" })]),
+        ),
+    ).toBe("queued");
+    expect(batchCategory(summary([queued]))).toBe("queued");
+    expect(batchCategory(summary([completed]))).toBe("completed");
+    expect(
+        batchCategory(
+            summary([completed, item({ key: "failed", state: "error" })]),
+        ),
+    ).toBe("error");
+    expect(
+        batchCategory(
+            summary([
+                completed,
+                item({ key: "cancelled", state: "cancelled" }),
+            ]),
+        ),
+    ).toBe("cancelled");
+});
diff --git a/website/src/features/transfers/transferBatches.ts b/website/src/features/transfers/transferBatches.ts
new file mode 100644
index 00000000..54f460c7
--- /dev/null
+++ b/website/src/features/transfers/transferBatches.ts
@@ -0,0 +1,311 @@
+import type { Transfer } from "./transfers";
+import { currentRate, transferDetails, transferProgress } from "./progress";
+import { deviceUploadProgress, needsDeviceUpload } from "./deviceUploadStatus";
+import type { BatchProgressMeters } from "./batchProgress";
+import { isFolderTransfer, transferTaskId } from "./transferTasks";
+
+export interface TransferBatch {
+    id: string;
+    name: string;
+    folder: boolean;
+    items: Transfer[];
+    count: number;
+    completed: number;
+    cancelled: number;
+    failed: number;
+    awaiting: number;
+    active: number;
+    queued: number;
+    pending: boolean;
+    unfinished: number;
+    device: ReturnType<typeof deviceUploadProgress>;
+    displayBytes: number;
+    displayRate?: number;
+    displayEta?: number;
+    totalBytes?: number;
+    completedBytes: number;
+    uploadedBytes: number;
+    progress?: number;
+    elapsed?: number;
+    deviceRate?: number;
+    telegramRate?: number;
+    eta?: number;
+}
+
+function positive(value: number | undefined | null): value is number {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function bounded(value: number, maximum: number): number {
+    return Number.isFinite(value) ? Math.max(0, Math.min(value, maximum)) : 0;
+}
+function isUrl(item: Transfer): boolean {
+    return item.kind === "remote";
+}
+function isQueued(item: Transfer): boolean {
+    return (
+        item.state === "queued" ||
+        (item.state === "uploading" &&
+            (item.stage === "queued" || item.serverStatus === "queued"))
+    );
+}
+function finished(item: Transfer): boolean {
+    return item.state === "completed" || item.state === "cancelled";
+}
+function sizeOf(item: Transfer): number | undefined {
+    if (item.kind === "delete") return;
+    if (positive(item.size)) return item.size;
+    if ((item.jobId || isUrl(item)) && positive(item.total)) return item.total;
+}
+function priority(item: Transfer): number {
+    if (item.state === "error") return 0;
+    if (item.state === "awaiting_file") return 1;
+    if (!finished(item)) return isQueued(item) ? 3 : 2;
+    return item.state === "completed" ? 4 : 5;
+}
+function timestamps(items: Transfer[]): number[] {
+    return items
+        .flatMap((item) => [item.batchCreatedAt, item.createdAt])
+        .filter(positive);
+}
+function elapsed(items: Transfer[], now: number): number | undefined {
+    const starts = items.map((item) => item.startedAt).filter(positive);
+    if (!starts.length) return;
+    let end = now;
+    if (items.every(finished)) {
+        const ends = items.map((item) => item.finishedAt).filter(positive);
+        if (ends.length !== items.length) return;
+        end = Math.max(...ends);
+    }
+    return Math.max(0, (end - Math.min(...starts)) / 1000);
+}
+/** Received device bytes are not Telegram upload bytes. */
+function telegramBytes(item: Transfer, size: number): number {
+    if (item.state === "completed") return size;
+    if (
+        !item.jobId ||
+        isQueued(item) ||
+        ["cancelled", "error", "awaiting_file"].includes(item.state) ||
+        ["saving", "verifying", "downloading"].includes(item.stage || "")
+    )
+        return 0;
+    return bounded(item.current, size);
+}
+function progress(
+    items: Transfer[],
+    total: number | undefined,
+    uploadedBytes: number,
+): number | undefined {
+    if (items.length === 1) return transferProgress(items[0]).fraction;
+    if (items.every((item) => item.state === "completed")) return 1;
+    if (
+        !positive(total) ||
+        items.some((item) => isUrl(item) || item.kind === "delete")
+    )
+        return;
+    return Math.min(0.99, uploadedBytes / total);
+}
+function summarize(
+    id: string,
+    source: Transfer[],
+    now: number,
+    meters?: BatchProgressMeters,
+): TransferBatch {
+    const items = [...source].sort((a, b) => priority(a) - priority(b));
+    const sizes = items.map(sizeOf);
+    const allSizes = sizes.every(positive);
+    const sum = sizes.reduce<number>((total, size) => total + (size ?? 0), 0);
+    const totalBytes = allSizes && positive(sum) ? sum : undefined;
+    let completedBytes = 0;
+    let uploadedBytes = 0;
+    let deviceRate = 0;
+    let telegramRate = 0;
+    for (let index = 0; index < items.length; index++) {
+        const item = items[index];
+        if (item.state === "completed") completedBytes += sizes[index] ?? 0;
+        const size = sizes[index];
+        if (positive(size)) uploadedBytes += telegramBytes(item, size);
+        const rate = transferDetails(item, now).rate;
+        if (!positive(rate) || item.error || isQueued(item)) continue;
+        if (item.state === "receiving" || item.state === "verifying")
+            deviceRate += rate;
+        else if (
+            item.state === "uploading" &&
+            item.stage === "uploading" &&
+            item.kind !== "delete"
+        )
+            telegramRate += rate;
+    }
+    const completed = items.filter((item) => item.state === "completed").length;
+    const cancelled = items.filter((item) => item.state === "cancelled").length;
+    const failed = items.filter((item) => item.state === "error").length;
+    const awaiting = items.filter(
+        (item) => item.state === "awaiting_file",
+    ).length;
+    const queued = items.filter(isQueued).length;
+    const active =
+        items.length - completed - cancelled - failed - awaiting - queued;
+    const remaining = items.filter((item) => !finished(item));
+    const device = deviceUploadProgress(items);
+    const deviceRemaining =
+        device.total !== undefined
+            ? Math.max(0, device.total - device.current)
+            : 0;
+    const deviceUnblocked = items
+        .filter(needsDeviceUpload)
+        .every(
+            (item) =>
+                !item.error &&
+                !["error", "awaiting_file", "cancelling"].includes(
+                    item.state,
+                ) &&
+                !["retry_wait", "waiting_for_telegram"].includes(
+                    item.stage || "",
+                ),
+        );
+    const pendingTelegramBytes = remaining.some(
+        (item) =>
+            item.jobId &&
+            item.state === "uploading" &&
+            !item.error &&
+            ["uploading", "queued"].includes(item.stage || "") &&
+            positive(sizeOf(item)) &&
+            (isQueued(item) || item.current < sizeOf(item)!),
+    );
+    const meter = meters?.get(id);
+    const observedRate = currentRate(meter, now);
+    if (
+        device.pending &&
+        deviceUnblocked &&
+        positive(deviceRemaining) &&
+        meter?.stage === "device" &&
+        !positive(deviceRate)
+    )
+        deviceRate = observedRate ?? 0;
+    else if (
+        !device.pending &&
+        pendingTelegramBytes &&
+        meter?.stage === "telegram" &&
+        !positive(telegramRate)
+    )
+        telegramRate = observedRate ?? 0;
+    let eta: number | undefined;
+    if (
+        remaining.every((item) => positive(sizeOf(item))) &&
+        positive(telegramRate) &&
+        remaining.length &&
+        remaining.every(
+            (item) =>
+                item.jobId &&
+                item.state === "uploading" &&
+                !item.error &&
+                !isUrl(item) &&
+                item.kind !== "delete" &&
+                (["uploading", "queued"].includes(item.stage || "") ||
+                    (["finalizing", "backup_pending"].includes(
+                        item.stage || "",
+                    ) &&
+                        bounded(item.current, sizeOf(item)!) >= sizeOf(item)!)),
+        )
+    ) {
+        const bytes = remaining.reduce((sum, item) => {
+            const size = sizeOf(item)!;
+            return (
+                sum + size - (isQueued(item) ? 0 : bounded(item.current, size))
+            );
+        }, 0);
+        const estimate = bytes / telegramRate;
+        if (positive(estimate)) eta = estimate;
+    }
+    const deviceEstimate =
+        positive(deviceRate) && positive(deviceRemaining) && deviceUnblocked
+            ? deviceRemaining / deviceRate
+            : undefined;
+    const deviceEta = positive(deviceEstimate) ? deviceEstimate : undefined;
+    return {
+        id,
+        name:
+            source.find((item) => item.folderUpload)?.folderUpload?.name ||
+            source[0].name ||
+            "Transfer",
+        folder: source.some(isFolderTransfer),
+        items,
+        count: items.length,
+        completed,
+        cancelled,
+        failed,
+        awaiting,
+        active,
+        queued,
+        pending: items.some((item) => !finished(item)),
+        unfinished: items.filter(
+            (item) => !finished(item) && item.state !== "error",
+        ).length,
+        device,
+        displayBytes: device.pending ? device.current : uploadedBytes,
+        displayRate: device.pending
+            ? positive(deviceRate)
+                ? deviceRate
+                : undefined
+            : positive(telegramRate)
+              ? telegramRate
+              : undefined,
+        displayEta: device.pending ? deviceEta : eta,
+        totalBytes,
+        completedBytes,
+        uploadedBytes,
+        progress: device.pending
+            ? device.fraction
+            : progress(items, totalBytes, uploadedBytes),
+        elapsed: elapsed(items, now),
+        deviceRate: positive(deviceRate) ? deviceRate : undefined,
+        telegramRate: positive(telegramRate) ? telegramRate : undefined,
+        eta,
+    };
+}
+
+/** Pure aggregation: no browser storage, timers, mutations, or provider requests. */
+export function summarizeBatches(
+    items: Transfer[],
+    now: number,
+    meters?: BatchProgressMeters,
+): TransferBatch[] {
+    const groups = new Map<string, Transfer[]>();
+    for (const item of items) {
+        const id = transferTaskId(item);
+        const group = groups.get(id) || [];
+        group.push(item);
+        groups.set(id, group);
+    }
+    const order = (batch: TransferBatch) =>
+        batch.device.pending
+            ? batch.failed || batch.awaiting
+                ? 0
+                : 1
+            : batch.failed || batch.awaiting
+              ? 2
+              : batch.pending
+                ? 3
+                : 4;
+    const created = (batch: TransferBatch) => {
+        const starts = timestamps(batch.items);
+        return starts.length ? Math.min(...starts) : 0;
+    };
+    return [...groups]
+        .map(([id, group]) => summarize(id, group, now, meters))
+        .sort(
+            (a, b) =>
+                order(a) - order(b) ||
+                created(b) - created(a) ||
+                a.id.localeCompare(b.id),
+        );
+}
+
+/** A batch belongs to one category; child file states never split its identity. */
+export function batchCategory(
+    batch: TransferBatch,
+): "running" | "queued" | "error" | "completed" | "cancelled" {
+    if (batch.active > 0) return "running";
+    if (batch.queued > 0) return "queued";
+    if (batch.failed + batch.awaiting > 0) return "error";
+    return batch.completed === batch.count ? "completed" : "cancelled";
+}
diff --git a/website/src/features/transfers/transferHistory.test.ts b/website/src/features/transfers/transferHistory.test.ts
new file mode 100644
index 00000000..e34d7af1
--- /dev/null
+++ b/website/src/features/transfers/transferHistory.test.ts
@@ -0,0 +1,214 @@
+import { describe, expect, it } from "vitest";
+import { historyStatus, mergeHistory, visibleHistory } from "./transferHistory";
+import { canCancelTransfer, type Transfer } from "./transfers";
+import type { Job } from "../../shared/types";
+
+function local(change: Partial<Transfer> = {}): Transfer {
+    return {
+        key: "local",
+        initiatedHere: true,
+        name: "file.bin",
+        size: 100,
+        total: 100,
+        current: 0,
+        lastModified: 0,
+        destination: "/",
+        state: "queued",
+        phase: "Waiting",
+        folderUpload: change.relativePath
+            ? {
+                  id: change.batchId || "folder",
+                  name: "Folder",
+                  root_path: "/folder",
+                  created_at: 1,
+              }
+            : undefined,
+        ...change,
+    };
+}
+function job(change: Partial<Job> = {}): Job {
+    return {
+        id: "server",
+        name: "old.bin",
+        kind: "upload",
+        status: "completed",
+        phase: "completed",
+        total: 100,
+        current: 100,
+        created_at: 1000,
+        finished_at: 1100,
+        ...change,
+    };
+}
+describe("history merged with live browser work", () => {
+    it("keeps live running and queued batches above every finished filter", () => {
+        const active = local({ key: "active", state: "receiving" });
+        const queued = local({ key: "queued", state: "queued" });
+        const rows = visibleHistory(
+            [job(), job({ id: "failure", status: "error" })],
+            [active, queued],
+            "error",
+            true,
+        );
+        expect(rows.map((row) => row.jobId || row.key).sort()).toEqual([
+            "active",
+            "failure",
+            "queued",
+        ]);
+    });
+    it("does not prepend unrelated recent completions to an older cursor page", () => {
+        const rows = visibleHistory(
+            [job({ id: "older" })],
+            [
+                local({ key: "recent", state: "completed" }),
+                local({ key: "live", state: "receiving" }),
+            ],
+            "all",
+            false,
+        );
+        expect(rows.map((row) => row.jobId || row.key).sort()).toEqual([
+            "live",
+            "older",
+        ]);
+    });
+    it("keeps the first server page bounded when older job-backed completions remain locally", () => {
+        const rows = visibleHistory(
+            [job({ id: "newest" })],
+            [
+                local({
+                    key: "old-local",
+                    jobId: "archived-older",
+                    state: "completed",
+                }),
+                local({ key: "receipt", state: "error" }),
+            ],
+            "all",
+            true,
+        );
+        expect(rows.map((row) => row.jobId || row.key).sort()).toEqual([
+            "newest",
+            "receipt",
+        ]);
+    });
+    it("preserves completed siblings inside a live folder on older pages", () => {
+        const rows = visibleHistory(
+            [job({ id: "older" })],
+            [
+                local({
+                    key: "live",
+                    batchId: "folder",
+                    relativePath: "Folder/live.bin",
+                    state: "receiving",
+                }),
+                local({
+                    key: "sibling",
+                    batchId: "folder",
+                    relativePath: "Folder/sibling.bin",
+                    state: "completed",
+                }),
+                local({ key: "unrelated", state: "completed" }),
+            ],
+            "all",
+            false,
+        );
+        expect(rows.map((row) => row.jobId || row.key).sort()).toEqual([
+            "live",
+            "older",
+            "sibling",
+        ]);
+    });
+    it("keeps cleared server records and unfinished browser-only transfers visible", () => {
+        const rows = mergeHistory([job()], [local()], "all");
+        expect(rows).toHaveLength(2);
+        const past = rows.find((item) => item.jobId === "server")!;
+        expect(past.state).toBe("completed");
+        expect(past.phase).toBe("Upload completed");
+        expect(past.historyOnly).toBe(true);
+        expect(canCancelTransfer(past)).toBe(false);
+        expect(mergeHistory([job()], [], "completed")).toHaveLength(1);
+    });
+    it("uses current retry/progress state without duplicating a history entry", () => {
+        const current = local({
+            jobId: "server",
+            state: "uploading",
+            stage: "uploading",
+            current: 40,
+        });
+        const rows = mergeHistory(
+            [job({ status: "error" })],
+            [current],
+            "running",
+        );
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toBe(current);
+        expect(
+            mergeHistory([job({ status: "error" })], [current], "error"),
+        ).toEqual([]);
+    });
+    it("distinguishes browser/server queue, active work, failures and cancellations", () => {
+        expect(historyStatus(local())).toBe("queued");
+        expect(historyStatus(local({ state: "receiving" }))).toBe("running");
+        expect(
+            historyStatus(
+                local({ state: "uploading", serverStatus: "queued" }),
+            ),
+        ).toBe("queued");
+        expect(historyStatus(local({ state: "cancelling" }))).toBe("running");
+        expect(historyStatus(local({ state: "awaiting_file" }))).toBe("error");
+        expect(historyStatus(local({ state: "cancelled" }))).toBe("cancelled");
+        expect(mergeHistory([job({ kind: "delete" })], [], "all")).toEqual([]);
+    });
+});
+
+it("retains the current catalog destination when live progress replaces history", () => {
+    const location = {
+        available: true,
+        folder_path: "/moved",
+        folder_label: "My Files / Saved",
+        item_id: "exact",
+    };
+    const rows = mergeHistory(
+        [job({ location })],
+        [local({ jobId: "server", state: "completed" })],
+        "all",
+    );
+    expect(rows).toHaveLength(1);
+    expect(rows[0].location).toEqual(location);
+});
+
+it("filters whole folders instead of extracting matching children into duplicate groups", () => {
+    const items = [
+        local({
+            key: "one",
+            batchId: "folder",
+            relativePath: "Folder/one.bin",
+            state: "uploading",
+            stage: "uploading",
+        }),
+        local({
+            key: "two",
+            batchId: "folder",
+            relativePath: "Folder/two.bin",
+            state: "queued",
+        }),
+        local({
+            key: "three",
+            batchId: "folder",
+            relativePath: "Folder/three.bin",
+            state: "completed",
+        }),
+    ];
+    expect(mergeHistory([], items, "running")).toHaveLength(3);
+    expect(mergeHistory([], items, "completed")).toEqual([]);
+    expect(mergeHistory([], items, "queued")).toEqual([]);
+    const waiting = items.map((item) =>
+        item.key === "one" ? { ...item, state: "queued" as const } : item,
+    );
+    expect(mergeHistory([], waiting, "queued")).toHaveLength(3);
+    expect(mergeHistory([], waiting, "completed")).toEqual([]);
+    const finished = items.map((item) => ({
+        ...item,
+        state: "completed" as const,
+    }));
+    expect(mergeHistory([], finished, "completed")).toHaveLength(3);
+});
diff --git a/website/src/features/transfers/transferHistory.ts b/website/src/features/transfers/transferHistory.ts
new file mode 100644
index 00000000..74c18a4c
--- /dev/null
+++ b/website/src/features/transfers/transferHistory.ts
@@ -0,0 +1,258 @@
+import { summarizeBatches, batchCategory } from "./transferBatches";
+import type { Job } from "../../shared/types";
+import { fromJob, type Transfer } from "./transfers";
+import { api, type TransferHistoryContext } from "../../shared/api";
+import type { TransferTaskHistoryPage } from "../../shared/types";
+
+export const TRANSFER_TASK_PAGE_SIZE = 20;
+
+export type HistoryFilter =
+    | "all"
+    | "queued"
+    | "running"
+    | "finished"
+    | "completed"
+    | "error"
+    | "cancelled";
+export function historyStatus(
+    item: Transfer,
+): Exclude<HistoryFilter, "all" | "finished"> {
+    if (item.state === "completed" || item.state === "cancelled")
+        return item.state;
+    if (item.state === "error" || item.state === "awaiting_file")
+        return "error";
+    if (
+        item.state === "queued" ||
+        (item.state === "uploading" &&
+            (item.serverStatus === "queued" || item.stage === "queued"))
+    )
+        return "queued";
+    return "running";
+}
+export function mergeHistory(
+    jobs: Job[],
+    local: Transfer[],
+    filter: HistoryFilter,
+    includeLocalFinished: boolean | "selected" = true,
+): Transfer[] {
+    const records = new Map<string, Transfer>();
+    for (const job of jobs) {
+        if (job.kind === "delete") continue;
+        records.set(job.id, {
+            key: "history:" + job.id,
+            name: job.name || "Transfer",
+            size: job.total || 0,
+            total: job.total || 0,
+            current: 0,
+            lastModified: 0,
+            destination: job.destination || "/",
+            batchId: "history:" + job.id,
+            batchName: job.name || "Transfer",
+            batchCreatedAt: job.created_at ? job.created_at * 1000 : undefined,
+            jobId: job.id,
+            state: "uploading",
+            phase: "Loading transfer",
+            ...fromJob(job),
+            historyOnly: true,
+        });
+    }
+    // Browser receipts have not reached the server job list yet; live records
+    // also replace stale history samples with current progress/retry state.
+    const liveKeys = new Set(
+        summarizeBatches(local, Date.now())
+            .filter((batch) =>
+                ["running", "queued"].includes(batchCategory(batch)),
+            )
+            .flatMap((batch) => batch.items.map((item) => item.key)),
+    );
+    for (const item of local) {
+        if (item.kind !== "delete") {
+            const key = item.jobId || item.uploadId || item.key;
+            const historical = records.get(key);
+            if (
+                includeLocalFinished !== "selected" &&
+                (!includeLocalFinished || item.jobId) &&
+                !historical &&
+                !liveKeys.has(item.key)
+            )
+                continue;
+            records.set(
+                key,
+                historical?.location || historical?.folderUpload
+                    ? {
+                          ...item,
+                          ...(historical.location
+                              ? { location: historical.location }
+                              : {}),
+                          ...(historical.folderUpload && !item.folderUpload
+                              ? { folderUpload: historical.folderUpload }
+                              : {}),
+                      }
+                    : item,
+            );
+        }
+    }
+    const all = [...records.values()];
+    const matching = new Set(
+        summarizeBatches(all, Date.now())
+            .filter(
+                (batch) =>
+                    filter === "all" ||
+                    (filter === "finished"
+                        ? !["running", "queued"].includes(batchCategory(batch))
+                        : batchCategory(batch) === filter),
+            )
+            .flatMap((batch) => batch.items.map((item) => item.key)),
+    );
+    return all
+        .filter((item) => matching.has(item.key))
+        .map((item) =>
+            item.state === "completed"
+                ? { ...item, phase: "Upload completed" }
+                : item,
+        );
+}
+
+/** Keep current batches above the selected terminal history page. */
+export function visibleHistory(
+    jobs: Job[],
+    local: Transfer[],
+    filter: HistoryFilter,
+    firstPage: boolean,
+    selectedLocalTasks = false,
+): Transfer[] {
+    const rows = mergeHistory(
+        jobs,
+        local,
+        "all",
+        selectedLocalTasks ? "selected" : firstPage,
+    );
+    const matching = new Set(
+        summarizeBatches(rows, Date.now())
+            .filter((batch) => {
+                const category = batchCategory(batch);
+                return (
+                    category === "running" ||
+                    category === "queued" ||
+                    filter === "all" ||
+                    category === filter
+                );
+            })
+            .flatMap((batch) => batch.items.map((item) => item.key)),
+    );
+    return rows.filter((item) => matching.has(item.key));
+}
+
+/** Search keeps every child of a matching folder together. */
+export function matchHistoryTasks(
+    items: Transfer[],
+    query: string,
+): Transfer[] {
+    const term = query.normalize("NFC").toLocaleLowerCase().trim();
+    if (!term) return items;
+    return summarizeBatches(items, Date.now())
+        .filter((task) =>
+            [task.name, ...task.items.map((item) => item.name)].some((name) =>
+                name.normalize("NFC").toLocaleLowerCase().includes(term),
+            ),
+        )
+        .flatMap((task) => task.items);
+}
+
+export function liveHistoryRows(items: Transfer[]): Transfer[] {
+    return summarizeBatches(items, Date.now())
+        .filter((task) => ["running", "queued"].includes(batchCategory(task)))
+        .flatMap((task) => task.items);
+}
+
+/** Merge browser-owned finished tasks into the same 20-task page budget. */
+export async function loadTaskHistoryPage(
+    local: Transfer[],
+    filter: HistoryFilter,
+    page: number,
+    signal: AbortSignal,
+    query = "",
+): Promise<TransferTaskHistoryPage & { localItems: Transfer[] }> {
+    const tasks = summarizeBatches(local, Date.now());
+    const context: TransferHistoryContext = { exclude_folders: [] };
+    for (const task of tasks) {
+        if (
+            task.folder &&
+            task.items.some((item) => item.jobId || item.uploadId) &&
+            task.items.some((item) => !item.jobId)
+        )
+            context.exclude_folders!.push(task.id);
+    }
+    const matchingKeys = new Set(
+        matchHistoryTasks(local, query).map((item) => item.key),
+    );
+    const localFinished = tasks
+        .filter((task) => {
+            const category = batchCategory(task);
+            return (
+                task.items.some((item) => !item.jobId && !item.historyOnly) &&
+                !["running", "queued"].includes(category) &&
+                (filter === "all" ||
+                    filter === "finished" ||
+                    filter === category) &&
+                task.items.some((item) => matchingKeys.has(item.key))
+            );
+        })
+        .sort((a, b) => {
+            const created = (task: typeof a) =>
+                Math.min(
+                    ...task.items.map(
+                        (item) => item.batchCreatedAt || item.createdAt || 0,
+                    ),
+                );
+            return created(b) - created(a) || a.id.localeCompare(b.id);
+        });
+    const start = (page - 1) * TRANSFER_TASK_PAGE_SIZE;
+    const localPage = localFinished.slice(
+        start,
+        start + TRANSFER_TASK_PAGE_SIZE,
+    );
+    context.offset = Math.max(0, start - localFinished.length);
+    const result = await api.transferTaskHistory(
+        filter === "all" ? "finished" : filter,
+        page,
+        signal,
+        query,
+        context,
+    );
+    const selectedIds = new Set<string>();
+    const capacity = TRANSFER_TASK_PAGE_SIZE - localPage.length;
+    for (const job of result.jobs) {
+        const id = job.folder_upload
+            ? "folder:" + job.folder_upload.id
+            : "job:" + job.id;
+        if (selectedIds.has(id) || selectedIds.size < capacity)
+            selectedIds.add(id);
+    }
+    const jobs = result.jobs.filter((job) =>
+        selectedIds.has(
+            job.folder_upload
+                ? "folder:" + job.folder_upload.id
+                : "job:" + job.id,
+        ),
+    );
+    const jobIds = new Set(jobs.map((job) => job.id));
+    const localItems = [
+        ...localPage.flatMap((task) => task.items),
+        ...local.filter((item) =>
+            jobIds.has(item.jobId || item.uploadId || ""),
+        ),
+    ];
+    const total = result.total_tasks + localFinished.length;
+    const totalPages = Math.max(1, Math.ceil(total / TRANSFER_TASK_PAGE_SIZE));
+    return {
+        ...result,
+        jobs,
+        localItems,
+        page: Math.min(page, totalPages),
+        page_size: TRANSFER_TASK_PAGE_SIZE,
+        total_tasks: total,
+        total_pages: totalPages,
+        has_more: start + TRANSFER_TASK_PAGE_SIZE < total,
+    };
+}
diff --git a/website/src/features/transfers/transferTaskHistory.test.ts b/website/src/features/transfers/transferTaskHistory.test.ts
new file mode 100644
index 00000000..3cb2b934
--- /dev/null
+++ b/website/src/features/transfers/transferTaskHistory.test.ts
@@ -0,0 +1,189 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { api } from "../../shared/api";
+import {
+    liveHistoryRows,
+    loadTaskHistoryPage,
+    matchHistoryTasks,
+    visibleHistory,
+} from "./transferHistory";
+import { summarizeBatches } from "./transferBatches";
+import type { Transfer } from "./transfers";
+import type { Job } from "../../shared/types";
+
+afterEach(() => vi.restoreAllMocks());
+
+const local = (change: Partial<Transfer> = {}): Transfer => ({
+    key: "local",
+    initiatedHere: true,
+    name: "file.bin",
+    size: 4,
+    lastModified: 0,
+    destination: "/root",
+    state: "error",
+    phase: "Upload interrupted",
+    current: 0,
+    total: 4,
+    createdAt: 1000,
+    ...change,
+});
+const job = (index: number): Job => ({
+    id: "job-" + index,
+    name: "file-" + index,
+    status: "completed",
+    phase: "completed",
+    current: 4,
+    total: 4,
+    created_at: 100 - index,
+});
+const folder = (count = 72) =>
+    Array.from({ length: count }, (_, index) =>
+        local({
+            key: "folder-" + index,
+            name: "file-" + index,
+            relativePath: "Folder/file-" + index,
+            batchId: "folder-selection-id",
+            batchName: "Folder",
+            folderUpload: {
+                id: "folder-selection-id",
+                name: "Folder",
+                root_path: "/root",
+                created_at: 1,
+            },
+            // One failed device file keeps this whole task browser-owned.
+            ...(index
+                ? { jobId: "member-" + index, state: "completed" as const }
+                : {}),
+        }),
+    );
+
+function serverHistory(count: number) {
+    return vi
+        .spyOn(api, "transferTaskHistory")
+        .mockImplementation(
+            async (_status, page, _signal, _query, context = {}) => {
+                const offset = context.offset || 0;
+                return {
+                    jobs: Array.from(
+                        { length: Math.min(20, Math.max(0, count - offset)) },
+                        (_, index) => job(offset + index),
+                    ),
+                    page,
+                    page_size: 20,
+                    total_tasks: count,
+                    total_pages: Math.max(1, Math.ceil(count / 20)),
+                    has_more: offset + 20 < count,
+                };
+            },
+        );
+}
+
+describe("finished transfer task pages", () => {
+    it("counts a remembered 72-file folder once and fills the other 19 task slots", async () => {
+        const backend = serverHistory(25);
+        const localFolder = folder();
+        const page = await loadTaskHistoryPage(
+            localFolder,
+            "all",
+            1,
+            new AbortController().signal,
+        );
+        expect(page.total_tasks).toBe(26);
+        expect(page.total_pages).toBe(2);
+        expect(page.localItems).toHaveLength(72);
+        expect(page.jobs).toHaveLength(19);
+        const rows = visibleHistory(
+            page.jobs,
+            page.localItems,
+            "all",
+            true,
+            true,
+        );
+        expect(summarizeBatches(rows, 0)).toHaveLength(20);
+        expect(
+            summarizeBatches(rows, 0).find((task) => task.folder)?.count,
+        ).toBe(72);
+        const context = backend.mock.calls[0][4]!;
+        expect(context.exclude_folders).toEqual(["folder-selection-id"]);
+    });
+
+    it("uses the server offset after browser-only tasks without skipping history", async () => {
+        const backend = serverHistory(25);
+        const page = await loadTaskHistoryPage(
+            folder(),
+            "all",
+            2,
+            new AbortController().signal,
+        );
+        expect(backend.mock.calls[0][4]?.offset).toBe(19);
+        expect(page.localItems).toEqual([]);
+        expect(page.jobs.map((row) => row.id)).toEqual(
+            Array.from({ length: 6 }, (_, index) => "job-" + (index + 19)),
+        );
+    });
+
+    it("keeps ordinary selections separate when browser-only work spans pages", async () => {
+        const backend = serverHistory(3);
+        const files = Array.from({ length: 25 }, (_, index) =>
+            local({
+                key: "file-" + index,
+                batchId: "file-" + index,
+                batchName: "25 files",
+            }),
+        );
+        const page = await loadTaskHistoryPage(
+            files,
+            "all",
+            2,
+            new AbortController().signal,
+        );
+        expect(page.total_tasks).toBe(28);
+        expect(page.localItems).toHaveLength(5);
+        expect(page.jobs).toHaveLength(3);
+        expect(backend.mock.calls[0][4]?.offset).toBe(0);
+        expect(summarizeBatches(page.localItems, 0)).toHaveLength(5);
+    });
+
+    it("returns a reachable page when history shrinks", async () => {
+        serverHistory(1);
+        const page = await loadTaskHistoryPage(
+            [],
+            "all",
+            5,
+            new AbortController().signal,
+        );
+        expect(page.page).toBe(1);
+        expect(page.total_pages).toBe(1);
+    });
+
+    it("keeps a locally pending folder out of finished server pages", async () => {
+        const backend = serverHistory(0);
+        const rows = folder(3);
+        rows[0].state = "receiving";
+        const page = await loadTaskHistoryPage(
+            rows,
+            "all",
+            1,
+            new AbortController().signal,
+        );
+        expect(page.total_tasks).toBe(0);
+        expect(page.localItems).toEqual([]);
+        expect(backend.mock.calls[0][4]?.exclude_folders).toEqual([
+            "folder-selection-id",
+        ]);
+        expect(liveHistoryRows(rows)).toHaveLength(3);
+    });
+
+    it("searches a whole folder while ordinary files match independently", () => {
+        const rows = folder(3);
+        expect(matchHistoryTasks(rows, "file-1")).toHaveLength(3);
+        expect(
+            matchHistoryTasks(
+                [
+                    local({ key: "one", name: "one.txt", batchId: "one" }),
+                    local({ key: "two", name: "two.txt", batchId: "two" }),
+                ],
+                "one.txt",
+            ).map((row) => row.key),
+        ).toEqual(["one"]);
+    });
+});
diff --git a/website/src/features/transfers/transferTasks.test.ts b/website/src/features/transfers/transferTasks.test.ts
new file mode 100644
index 00000000..d6a33b61
--- /dev/null
+++ b/website/src/features/transfers/transferTasks.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import type { Transfer } from "./transfers";
+import { transferFolderDestination, transferTaskId } from "./transferTasks";
+
+const item: Transfer = {
+    key: "one",
+    name: "one.bin",
+    destination: "/root/child",
+    size: 1,
+    total: 1,
+    current: 1,
+    lastModified: 0,
+    state: "completed",
+    phase: "Available in your drive",
+};
+
+describe("transfer folder identity", () => {
+    it("locates a server-discovered folder root without needing relative file paths", () => {
+        const folderUpload = {
+            id: "folder-upload-identity",
+            name: "Project files",
+            root_path: "/original-parent/root-id",
+            created_at: 1,
+        };
+        expect(transferTaskId({ ...item, folderUpload })).toBe(folderUpload.id);
+        expect(transferFolderDestination({ ...item, folderUpload })).toBe(
+            "/original-parent/root-id",
+        );
+    });
+    it("uses the file identity and destination for standalone uploads", () => {
+        expect(transferTaskId(item)).toBe(item.key);
+        expect(transferFolderDestination(item)).toBe("/root/child");
+    });
+});
diff --git a/website/src/features/transfers/transferTasks.ts b/website/src/features/transfers/transferTasks.ts
new file mode 100644
index 00000000..bc1a7c2a
--- /dev/null
+++ b/website/src/features/transfers/transferTasks.ts
@@ -0,0 +1,15 @@
+import type { Transfer } from "./transfers";
+
+/** Folder selections are one task; ordinary files each keep their own identity. */
+export function isFolderTransfer(item: Transfer): boolean {
+    return Boolean(item.folderUpload);
+}
+
+export function transferTaskId(item: Transfer): string {
+    return item.folderUpload?.id || item.key;
+}
+
+/** The final catalog id lets the server resolve a folder after it moves. */
+export function transferFolderDestination(item: Transfer): string {
+    return item.folderUpload?.root_path || item.destination;
+}
diff --git a/website/src/features/transfers/transfers.test.ts b/website/src/features/transfers/transfers.test.ts
new file mode 100644
index 00000000..94be639b
--- /dev/null
+++ b/website/src/features/transfers/transfers.test.ts
@@ -0,0 +1,2566 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+    fromJob,
+    safeTransferMetadata,
+    uploadBackupState,
+    verifyReceivedChunks,
+    TransferManager,
+    retainTransferBatches,
+    BROWSER_RECEIVE_INITIAL_CONCURRENCY,
+    type Transfer,
+} from "./transfers";
+import { transferTaskId } from "./transferTasks";
+import {
+    fileUrl,
+    itemPath,
+    formatBytes,
+    formatByteProgress,
+    remainingBytesHint,
+    type Job,
+} from "../../shared/types";
+const managerForTest = () =>
+    new TransferManager((url, options) => fetch(url, options));
+
+function folderBatch(name: string, rootPath = "/" + name) {
+    return {
+        name,
+        folderUpload: {
+            id: crypto.randomUUID(),
+            name,
+            root_path: rootPath,
+            created_at: Date.now() / 1000,
+        },
+    };
+}
+
+async function hash(data: string) {
+    return [
+        ...new Uint8Array(
+            await crypto.subtle.digest(
+                "SHA-256",
+                new TextEncoder().encode(data),
+            ),
+        ),
+    ]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+beforeEach(() => {
+    const data = new Map<string, string>();
+    vi.stubGlobal("localStorage", {
+        get length() {
+            return data.size;
+        },
+        key: (index: number) => [...data.keys()][index] ?? null,
+        removeItem: (key: string) => data.delete(key),
+        getItem: (key: string) => data.get(key) || null,
+        setItem: (key: string, value: string) => data.set(key, value),
+    });
+    vi.stubGlobal("window", new EventTarget());
+});
+afterEach(() => vi.unstubAllGlobals());
+describe("manual transfer history clearing", () => {
+    function seedHistory(manager: TransferManager) {
+        manager.addEntries(
+            ["completed", "cancelled", "error", "queued", "awaiting_file"].map(
+                (name) => ({ file: new File(["x"], name), destination: "/" }),
+            ),
+            10,
+            true,
+        );
+        const states = [
+            "completed",
+            "cancelled",
+            "error",
+            "queued",
+            "awaiting_file",
+        ] as const;
+        manager.snapshot().forEach((item, index) => {
+            item.state = states[index];
+            if (index < 3) item.jobId = "job-" + item.name;
+        });
+        const folderUpload = {
+            id: "unfinished-folder-0001",
+            name: "Folder",
+            root_path: "/folder",
+            created_at: 1000,
+        };
+        manager.addEntries(
+            ["first", "second"].map((name) => ({
+                file: new File(["x"], name),
+                destination: "/folder",
+                relativePath: "Folder/" + name,
+            })),
+            10,
+            true,
+            { name: "Folder", folderUpload },
+        );
+        manager.snapshot().find((item) => item.name === "first")!.state =
+            "completed";
+        return folderUpload;
+    }
+
+    it("clears saved history and local finished rows while keeping unfinished folders", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json({ cleared: 3 })),
+        );
+        const manager = managerForTest();
+        const folder = seedHistory(manager);
+        await manager.clearHistory();
+        expect(fetch).toHaveBeenCalledWith(
+            "/api/v1/transfers/history",
+            expect.objectContaining({
+                method: "DELETE",
+                body: JSON.stringify({ exclude_folders: [folder.id] }),
+            }),
+        );
+        expect(manager.snapshot().map((item) => item.name)).toEqual([
+            "queued",
+            "awaiting_file",
+            "first",
+            "second",
+        ]);
+        expect(
+            managerForTest()
+                .snapshot()
+                .map((item) => item.name),
+        ).toEqual(["queued", "awaiting_file", "first", "second"]);
+    });
+
+    it("keeps browser history when the server cannot confirm clearing", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    { detail: "History could not be saved" },
+                    { status: 503 },
+                ),
+            ),
+        );
+        const manager = managerForTest();
+        seedHistory(manager);
+        const keys = manager.snapshot().map((item) => item.key);
+        await expect(manager.clearHistory()).rejects.toThrow(
+            "History could not be saved",
+        );
+        expect(manager.snapshot().map((item) => item.key)).toEqual(keys);
+    });
+
+    it("ignores terminal rows from a job poll started before clearing", async () => {
+        let resolvePoll!: (response: Response) => void;
+        const pending = new Promise<Response>((resolve) => {
+            resolvePoll = resolve;
+        });
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (url: string) =>
+                url === "/api/v1/jobs"
+                    ? pending
+                    : Response.json({ cleared: 1 }),
+            ),
+        );
+        const manager = managerForTest();
+        const published = vi.fn();
+        manager.subscribe(published);
+        try {
+            manager.setEnabled(true);
+            await manager.clearHistory();
+            published.mockClear();
+            resolvePoll(
+                Response.json({
+                    jobs: [
+                        {
+                            id: "stale-finished",
+                            name: "Old file",
+                            kind: "upload",
+                            status: "completed",
+                            phase: "done",
+                            current: 1,
+                            total: 1,
+                        },
+                    ],
+                }),
+            );
+            await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
+            await vi.waitFor(() => expect(published).toHaveBeenCalled());
+            expect(manager.snapshot()).toEqual([]);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+
+    it("settles local progress when another browser clears the completed job", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    jobs: [
+                        {
+                            id: "cleared-elsewhere",
+                            name: "Uploading",
+                            kind: "upload",
+                            status: "completed",
+                            phase: "done",
+                            current: 1,
+                            total: 1,
+                            history_cleared: true,
+                        },
+                    ],
+                }),
+            ),
+        );
+        const manager = managerForTest();
+        manager.addEntries(
+            [{ file: new File(["x"], "Uploading"), destination: "/" }],
+            10,
+            true,
+        );
+        Object.assign(manager.snapshot()[0], {
+            jobId: "cleared-elsewhere",
+            state: "uploading",
+            file: undefined,
+        });
+        const changed = vi.fn();
+        window.addEventListener("tgdrive:files-changed", changed);
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(changed).toHaveBeenCalledOnce());
+            expect(manager.snapshot()).toEqual([]);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+describe("deletion progress", () => {
+    const deletion = (status: string, id = "deletion"): Job => ({
+        id,
+        kind: "delete",
+        name: "Old file",
+        status,
+        phase: status,
+        current: 0,
+        total: 1,
+    });
+
+    it("shows accepted work immediately and retains completion first seen after it finished", async () => {
+        const changes = vi.fn();
+        window.addEventListener("tgdrive:files-changed", changes);
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    jobs: [
+                        deletion("completed", "historic"),
+                        deletion("completed"),
+                    ],
+                }),
+            ),
+        );
+        const manager = managerForTest();
+        try {
+            manager.trackDeletions([{ id: "deletion", name: "Old file" }]);
+            expect(manager.deletionSnapshot().jobs[0].status).toBe("queued");
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().completed).toBe(1),
+            );
+            expect(changes).toHaveBeenCalledOnce();
+            manager.dismissDeletionResult();
+            expect(manager.deletionSnapshot().completed).toBe(0);
+            manager.refreshJobs();
+            await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
+            expect(manager.deletionSnapshot().completed).toBe(0);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+
+    it("does not show success for historical completed jobs after a reload", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json({ jobs: [deletion("completed")] })),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().jobs).toHaveLength(1),
+            );
+            expect(manager.deletionSnapshot().completed).toBe(0);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+
+    it("rechecks a retry after an older poll and ignores its stale failure", async () => {
+        let polls = 0;
+        let resolveOld!: (response: Response) => void;
+        const oldPoll = new Promise<Response>((resolve) => {
+            resolveOld = resolve;
+        });
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (url: string) => {
+                if (url.endsWith("/retry"))
+                    return Response.json(deletion("queued"));
+                polls++;
+                if (polls === 2) return oldPoll;
+                return Response.json({
+                    jobs: [deletion(polls === 1 ? "error" : "completed")],
+                });
+            }),
+        );
+        const manager = managerForTest();
+        const statuses: string[] = [];
+        manager.subscribe(() =>
+            statuses.push(manager.deletionSnapshot().jobs[0]?.status),
+        );
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().jobs[0]?.status).toBe(
+                    "error",
+                ),
+            );
+            manager.refreshJobs();
+            await vi.waitFor(() => expect(polls).toBe(2));
+            await manager.retryDeletion("deletion");
+            expect(manager.deletionSnapshot().jobs[0].status).toBe("queued");
+            statuses.length = 0;
+            resolveOld(Response.json({ jobs: [deletion("error")] }));
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().completed).toBe(1),
+            );
+            expect(polls).toBe(3);
+            expect(statuses).not.toContain("error");
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+
+    it("keeps active deletion visible with a connection warning until polling recovers", async () => {
+        const fetcher = vi
+            .fn()
+            .mockRejectedValueOnce(new Error("offline"))
+            .mockResolvedValueOnce(
+                Response.json({ jobs: [deletion("completed")] }),
+            );
+        vi.stubGlobal("fetch", fetcher);
+        const manager = managerForTest();
+        try {
+            manager.trackDeletions([{ id: "deletion" }]);
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().error).toContain(
+                    "Retrying automatically",
+                ),
+            );
+            expect(manager.deletionSnapshot().jobs[0].status).toBe("queued");
+            manager.refreshJobs();
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().completed).toBe(1),
+            );
+            expect(manager.deletionSnapshot().error).toBe("");
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+
+describe("safe resume and browser persistence", () => {
+    it("checks all uploaded chunks before allowing a same-sized reselected file", async () => {
+        const file = new File(["original"], "name.txt");
+        const chunks = [
+            { offset: 0, size: 4, sha256: await hash("orig") },
+            { offset: 4, size: 4, sha256: await hash("inal") },
+        ];
+        await expect(
+            verifyReceivedChunks(file, chunks, 8),
+        ).resolves.toBeUndefined();
+        await expect(
+            verifyReceivedChunks(new File(["changed!"], "name.txt"), chunks, 8),
+        ).rejects.toThrow("differs");
+    });
+    it("rejects missing and non-contiguous resume checksums", async () => {
+        const file = new File(["abcd"], "a");
+        await expect(verifyReceivedChunks(file, [], 4)).rejects.toThrow(
+            "incomplete",
+        );
+        await expect(
+            verifyReceivedChunks(
+                file,
+                [{ offset: 1, size: 3, sha256: await hash("bcd") }],
+                4,
+            ),
+        ).rejects.toThrow("incomplete");
+    });
+    it("persists tracking metadata without source files, abort controllers or arbitrary error strings", () => {
+        const transfer = {
+            key: "id",
+            name: "file.txt",
+            size: 4,
+            lastModified: 1,
+            destination: "/",
+            state: "error",
+            phase: "Paused",
+            current: 0,
+            total: 4,
+            file: new File(["test"], "file.txt"),
+            controller: new AbortController(),
+            error: "https://private.example/?credential=secret",
+            password: "secret",
+            auth: "token",
+            url: "https://secret/",
+        } as Transfer;
+        const saved = JSON.stringify(safeTransferMetadata([transfer]));
+        expect(saved).not.toContain("secret");
+        expect(saved).not.toContain("token");
+        expect(saved).not.toContain("controller");
+        expect(saved).not.toContain('file":');
+    });
+    it("recovers unfinished browser receipt as a source-reselection action", () => {
+        localStorage.setItem(
+            "tgdrive.uploads.v2",
+            JSON.stringify([
+                {
+                    key: "key",
+                    initiatedHere: true,
+                    name: "file",
+                    size: 4,
+                    lastModified: 1,
+                    destination: "/",
+                    state: "receiving",
+                    phase: "Receiving",
+                    current: 2,
+                    total: 4,
+                    uploadId: "upload",
+                },
+            ]),
+        );
+        const manager = managerForTest();
+        expect(manager.snapshot()[0].state).toBe("awaiting_file");
+        expect(manager.snapshot()[0].initiatedHere).toBe(true);
+    });
+    it("keeps URL jobs server-owned across a browser reload", async () => {
+        const manager = managerForTest();
+        manager.addJob("url-server-job", "URL file", "/", "remote");
+        const restored = managerForTest();
+        expect(restored.snapshot()[0]).toMatchObject({
+            jobId: "url-server-job",
+            kind: "remote",
+            state: "uploading",
+            initiatedHere: true,
+        });
+        await expect(
+            restored.resume(
+                restored.snapshot()[0].key,
+                new File(["data"], "URL file"),
+            ),
+        ).rejects.toThrow("resume on the server");
+    });
+    it("never requests a local original for a URL receipt missing its server job", async () => {
+        localStorage.setItem(
+            "tgdrive.uploads.v2",
+            JSON.stringify([
+                {
+                    key: "missing",
+                    initiatedHere: true,
+                    name: "URL file",
+                    size: 4,
+                    lastModified: 0,
+                    destination: "/",
+                    kind: "remote",
+                    state: "uploading",
+                    phase: "Sending",
+                    current: 1,
+                    total: 4,
+                },
+            ]),
+        );
+        const restored = managerForTest();
+        expect(restored.snapshot()[0].state).toBe("error");
+        expect(restored.snapshot()[0].phase).not.toContain("original");
+        await expect(restored.retry("missing")).rejects.toThrow(
+            "no server job",
+        );
+    });
+    it("does not turn globally discovered transfers into local popup receipts", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    jobs: [
+                        {
+                            id: "another-device",
+                            kind: "upload",
+                            status: "running",
+                            phase: "uploading",
+                            current: 1,
+                            total: 4,
+                        },
+                    ],
+                }),
+            ),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(manager.snapshot()).toHaveLength(1));
+            expect(manager.snapshot()[0].initiatedHere).not.toBe(true);
+            const restored = managerForTest();
+            // The server is authoritative for discovered rows; stale browser copies
+            // must not resurrect a job removed by a fixture/drive reset.
+            expect(restored.snapshot()).toEqual([]);
+            try {
+                restored.setEnabled(true);
+                await vi.waitFor(() =>
+                    expect(restored.snapshot()).toHaveLength(1),
+                );
+                expect(restored.snapshot()[0].initiatedHere).not.toBe(true);
+                expect(restored.snapshot()[0].jobId).toBe("another-device");
+            } finally {
+                restored.setEnabled(false);
+            }
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+describe("resumable HTTP upload protocol", () => {
+    it("publishes in-flight device bytes without persisting or resuming unconfirmed bytes", async () => {
+        let report: ((bytes: number) => void) | undefined;
+        let receipt: ((response: Response) => void) | undefined;
+        const offsets: string[] = [];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input.endsWith("/complete"))
+                    return Response.json({ id: "job" });
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "8" },
+                    });
+                return Response.json({
+                    id: "u",
+                    offset: 0,
+                    total_size: 8,
+                    chunk_size: 8,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = new TransferManager(async (_url, options, progress) => {
+            offsets.push(new Headers(options.headers).get("Upload-Offset")!);
+            report = progress;
+            return new Promise<Response>((resolve) => {
+                receipt = resolve;
+            });
+        });
+        try {
+            manager.setEnabled(true);
+            manager.add([new File(["abcdefgh"], "source.txt")], "/", 10);
+            await vi.waitFor(() => expect(report).toBeDefined());
+            const writes = vi.spyOn(localStorage, "setItem");
+            const scans = vi.spyOn(localStorage, "key");
+            report!(3);
+            expect(manager.snapshot()[0]).toMatchObject({
+                current: 0,
+                sentCurrent: 3,
+                state: "receiving",
+            });
+            report!(6);
+            expect(manager.snapshot()[0].sentCurrent).toBe(6);
+            expect(writes).not.toHaveBeenCalled();
+            expect(scans).not.toHaveBeenCalled();
+            writes.mockRestore();
+            scans.mockRestore();
+            const saved = JSON.parse(
+                localStorage.getItem(
+                    "tgdrive.uploads.v2:" + manager.snapshot()[0].key,
+                )!,
+            );
+            expect(saved.current).toBe(0);
+            expect(saved.sentCurrent).toBeUndefined();
+            receipt!(new Response(null, { status: 409 }));
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].state).toBe("error"),
+            );
+            expect(manager.snapshot()[0].sentCurrent).toBeUndefined();
+            const key = manager.snapshot()[0].key;
+            report = undefined;
+            await manager.retry(key);
+            await vi.waitFor(() => expect(report).toBeDefined());
+            expect(offsets).toEqual(["0", "0"]);
+            expect(manager.snapshot()[0]).toMatchObject({
+                current: 0,
+                sentCurrent: 0,
+            });
+            report!(8);
+            expect(manager.snapshot()[0].phase).toContain(
+                "Waiting for server confirmation",
+            );
+            receipt!(
+                new Response(null, {
+                    status: 204,
+                    headers: { "Upload-Offset": "8" },
+                }),
+            );
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].jobId).toBe("job"),
+            );
+            expect(manager.snapshot()[0].sentCurrent).toBeUndefined();
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("sends each chunk at its acknowledged offset, then tracks the independent Telegram job", async () => {
+        const calls: {
+            url: string;
+            method: string;
+            offset: string | null;
+            size: number;
+        }[] = [];
+        let offset = 0;
+        let complete = false;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                const method = options.method || "GET";
+                const headers = new Headers(options.headers);
+                calls.push({
+                    url: input,
+                    method,
+                    offset: headers.get("Upload-Offset"),
+                    size: options.body instanceof Blob ? options.body.size : 0,
+                });
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (method === "POST" && input === "/api/v1/uploads")
+                    return Response.json({
+                        id: "upload",
+                        offset: 0,
+                        total_size: 8,
+                        chunk_size: 4,
+                    });
+                if (method === "HEAD")
+                    return new Response(null, {
+                        headers: {
+                            "Upload-Offset": String(offset),
+                            "Upload-Length": "8",
+                        },
+                    });
+                if (method === "PATCH") {
+                    expect(Number(headers.get("Upload-Offset"))).toBe(offset);
+                    offset += (options.body as Blob).size;
+                    return new Response(null, {
+                        status: 204,
+                        headers: { "Upload-Offset": String(offset) },
+                    });
+                }
+                if (input.endsWith("/complete")) {
+                    complete = true;
+                    return Response.json({ id: "job" });
+                }
+                return Response.json({
+                    id: "upload",
+                    offset,
+                    total_size: 8,
+                    chunk_size: 4,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            manager.add([new File(["abcdefgh"], "source.txt")], "/", 1024);
+            await vi.waitFor(() => expect(complete).toBe(true));
+            expect(
+                calls
+                    .filter((call) => call.method === "PATCH")
+                    .map((call) => [call.offset, call.size]),
+            ).toEqual([
+                ["0", 4],
+                ["4", 4],
+            ]);
+            expect(manager.snapshot()[0].jobId).toBe("job");
+            expect(manager.snapshot()[0].phase).toBe("Queued for Telegram");
+            expect(calls.some((call) => call.method === "HEAD")).toBe(false);
+            expect(
+                calls.some(
+                    (call) =>
+                        call.method === "GET" &&
+                        call.url === "/api/v1/uploads/upload",
+                ),
+            ).toBe(false);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("does not complete a file when the server fails to acknowledge the chunk", async () => {
+        let completed = false;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (options.method === "POST" && input === "/api/v1/uploads")
+                    return Response.json({
+                        id: "u",
+                        offset: 0,
+                        total_size: 4,
+                        chunk_size: 4,
+                    });
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                    });
+                if (options.method === "PATCH")
+                    return new Response(null, { status: 204 });
+                if (input.endsWith("/complete")) completed = true;
+                return Response.json({
+                    id: "u",
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            manager.add([new File(["abcd"], "a")], "/", 10);
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].state).toBe("error"),
+            );
+            expect(completed).toBe(false);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+describe("opaque paths and Unicode filenames", () => {
+    it("joins nested IDs without exposing filenames as paths", () =>
+        expect(
+            itemPath({
+                id: "file",
+                path: "/folder/",
+                name: "資料 #1.txt",
+                type: "file",
+            }),
+        ).toBe("/folder/file"));
+    it("encodes share credentials and paths as query data", () => {
+        const url = new URL(
+            fileUrl("/folder/id", "signed+/token"),
+            "http://test",
+        );
+        expect(url.searchParams.get("auth")).toBe("signed+/token");
+        expect(url.searchParams.get("path")).toBe("/folder/id");
+    });
+    it("formats zero bytes honestly", () => expect(formatBytes(0)).toBe("0 B"));
+});
+
+describe("ambiguous completion and verification cancellation", () => {
+    it("reattaches a server-accepted upload after its complete response is lost", async () => {
+        let accepted = false;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({
+                        jobs: accepted
+                            ? [
+                                  {
+                                      id: "same-id",
+                                      status: "running",
+                                      phase: "uploading",
+                                      current: 0,
+                                      total: 4,
+                                      name: "original.bin",
+                                      destination: "/",
+                                  },
+                              ]
+                            : [],
+                    });
+                if (options.method === "POST" && input === "/api/v1/uploads")
+                    return Response.json({
+                        id: "same-id",
+                        offset: 0,
+                        total_size: 4,
+                        chunk_size: 4,
+                    });
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                    });
+                if (options.method === "PATCH")
+                    return new Response(null, {
+                        status: 204,
+                        headers: { "Upload-Offset": "4" },
+                    });
+                if (input.endsWith("/complete")) {
+                    accepted = true;
+                    throw new TypeError("network interrupted after acceptance");
+                }
+                return Response.json({
+                    id: "same-id",
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            manager.add([new File(["abcd"], "original.bin")], "/", 10);
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0]).toMatchObject({
+                    state: "queued",
+                    stage: "retry_wait",
+                }),
+            );
+            manager.setEnabled(false);
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].jobId).toBe("same-id"),
+            );
+            expect(manager.snapshot()).toHaveLength(1);
+            expect(manager.snapshot()[0].state).toBe("uploading");
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("stops original-file verification when cancellation is requested", async () => {
+        const controller = new AbortController();
+        controller.abort();
+        await expect(
+            verifyReceivedChunks(
+                new File(["abcd"], "source"),
+                [{ offset: 0, size: 4, sha256: await hash("abcd") }],
+                4,
+                () => {},
+                controller.signal,
+            ),
+        ).rejects.toMatchObject({ name: "AbortError" });
+    });
+});
+
+it("shows the server's actionable chunk error without persisting its details", async () => {
+    vi.stubGlobal(
+        "fetch",
+        vi.fn(async (input: string, options: RequestInit = {}) => {
+            if (input === "/api/v1/jobs") return Response.json({ jobs: [] });
+            if (options.method === "POST" && input === "/api/v1/uploads")
+                return Response.json({
+                    id: "quota",
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                });
+            if (options.method === "HEAD")
+                return new Response(null, {
+                    headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                });
+            if (options.method === "PATCH")
+                return Response.json(
+                    {
+                        detail: "Temporary Storage is full. Free disk space before retrying.",
+                    },
+                    { status: 507 },
+                );
+            return Response.json({
+                id: "quota",
+                offset: 0,
+                total_size: 4,
+                chunk_size: 4,
+                checksums: [],
+            });
+        }),
+    );
+    const manager = managerForTest();
+    try {
+        manager.setEnabled(true);
+        manager.add([new File(["abcd"], "quota.bin")], "/", 10);
+        await vi.waitFor(() =>
+            expect(manager.snapshot()[0].phase).toBe(
+                "Waiting for server space",
+            ),
+        );
+        expect(manager.snapshot()[0].state).toBe("queued");
+        expect(JSON.stringify(managerForTest().snapshot())).not.toContain(
+            "Free disk space",
+        );
+    } finally {
+        manager.setEnabled(false);
+    }
+});
+
+it("opens the demo protection notice when a resumed upload chunk becomes read-only", async () => {
+    const refused = vi.fn();
+    window.addEventListener("tgdrive:demo-files-read-only", refused);
+    vi.stubGlobal(
+        "fetch",
+        vi.fn(async (input: string, options: RequestInit = {}) => {
+            if (input === "/api/v1/jobs") return Response.json({ jobs: [] });
+            if (options.method === "HEAD")
+                return new Response(null, {
+                    headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                });
+            if (options.method === "PATCH")
+                return Response.json(
+                    {
+                        code: "DEMO_FILES_READ_ONLY",
+                        detail: "Demo Files is read-only.",
+                    },
+                    { status: 403 },
+                );
+            return Response.json({
+                id: "protected-upload",
+                offset: 0,
+                total_size: 4,
+                chunk_size: 4,
+                checksums: [],
+            });
+        }),
+    );
+    const manager = managerForTest();
+    try {
+        manager.setEnabled(true);
+        manager.add(
+            [new File(["abcd"], "demo.bin")],
+            "/tgdrive-demo-files",
+            10,
+        );
+        await vi.waitFor(() =>
+            expect(manager.snapshot()[0].state).toBe("error"),
+        );
+        expect(refused).toHaveBeenCalledOnce();
+        expect(manager.snapshot()[0].error).toBe("Demo Files is read-only.");
+    } finally {
+        manager.setEnabled(false);
+    }
+});
+
+describe("whole-batch recovery and bounded admission", () => {
+    it("gives every ordinary file a stable task identity before and after reload", () => {
+        const manager = managerForTest();
+        manager.add(
+            [new File(["one"], "first.bin"), new File(["two"], "second.bin")],
+            "/",
+            10,
+        );
+        const original = manager.snapshot();
+        expect(original.map((item) => item.batchName)).toEqual([
+            "first.bin",
+            "second.bin",
+        ]);
+        expect(new Set(original.map(transferTaskId)).size).toBe(2);
+        const restored = managerForTest().snapshot();
+        expect(restored.map(transferTaskId)).toEqual(
+            original.map(transferTaskId),
+        );
+        expect(restored.every((item) => !item.folderUpload)).toBe(true);
+    });
+    it("persists explicit folder task metadata and reads the same identity from server jobs", () => {
+        const folderUpload = {
+            id: "folder-upload-identity",
+            name: "Folder",
+            root_path: "/root",
+            created_at: 1000,
+        };
+        const manager = managerForTest();
+        manager.addEntries(
+            [
+                { file: new File(["one"], "first.bin"), destination: "/root" },
+                { file: new File(["two"], "second.bin"), destination: "/root" },
+            ],
+            10,
+            true,
+            { name: "Folder", folderUpload },
+        );
+        const restored = managerForTest().snapshot();
+        expect(
+            restored.every((item) => item.folderUpload?.id === folderUpload.id),
+        ).toBe(true);
+        expect(new Set(restored.map(transferTaskId))).toEqual(
+            new Set([folderUpload.id]),
+        );
+        const job = fromJob({
+            id: "server-member",
+            status: "queued",
+            phase: "queued",
+            current: 0,
+            total: 3,
+            folder_upload: folderUpload,
+        });
+        expect(job).toMatchObject({
+            folderUpload,
+            batchId: folderUpload.id,
+            batchName: folderUpload.name,
+            batchCreatedAt: 1_000_000,
+        });
+        expect(
+            fromJob({
+                id: "standalone-member",
+                status: "queued",
+                phase: "queued",
+                current: 0,
+                total: 3,
+            }),
+        ).not.toHaveProperty("folderUpload");
+    });
+    it("retains completed siblings in an unfinished batch beyond the old hundred-row limit", () => {
+        const manager = managerForTest();
+        manager.addEntries(
+            Array.from({ length: 150 }, (_, i) => ({
+                file: new File(["x"], "file-" + i),
+                relativePath: "Folder/file-" + i,
+                destination: "/",
+            })),
+            10,
+            true,
+            folderBatch("Folder"),
+        );
+        const original = manager.snapshot();
+        for (const item of original.slice(0, -1)) {
+            item.state = "completed";
+            item.finishedAt = Date.now();
+        }
+        manager.clearFinished();
+        expect(manager.snapshot()).toHaveLength(150);
+        const reloaded = managerForTest().snapshot();
+        expect(reloaded).toHaveLength(150);
+        expect(
+            reloaded.filter((item) => item.state === "completed"),
+        ).toHaveLength(149);
+        expect(reloaded[149].state).toBe("awaiting_file");
+        expect(new Set(reloaded.map((item) => item.batchId)).size).toBe(1);
+    });
+    it("keeps history as whole batches and retains errors", () => {
+        const rows = Array.from({ length: 31 }, (_, batch) =>
+            Array.from(
+                { length: 2 },
+                (_, index) =>
+                    ({
+                        key: batch + "-" + index,
+                        batchId: "batch-" + batch,
+                        folderUpload: {
+                            id: "batch-" + batch,
+                            name: "Folder",
+                            root_path: "/folder",
+                            created_at: 1,
+                        },
+                        relativePath: "Folder/file-" + index,
+                        name: "file",
+                        destination: "/",
+                        size: 1,
+                        lastModified: 1,
+                        state: "completed",
+                        phase: "Done",
+                        current: 1,
+                        total: 1,
+                        finishedAt: batch + 1,
+                    }) as Transfer,
+            ),
+        ).flat();
+        const failed = {
+            ...rows[0],
+            key: "failed",
+            batchId: "failed",
+            folderUpload: undefined,
+            state: "error" as const,
+        };
+        const kept = retainTransferBatches([...rows, failed]);
+        expect(kept).toHaveLength(61);
+        expect(kept.some((item) => item.batchId === "batch-0")).toBe(false);
+        expect(kept.some((item) => item.key === "failed")).toBe(true);
+        for (let batch = 1; batch < 31; batch++)
+            expect(
+                kept.filter((item) => item.batchId === "batch-" + batch),
+            ).toHaveLength(2);
+    });
+    it("caps unfinished-batch rows at 2000 including retained completed siblings", () => {
+        const manager = managerForTest();
+        manager.addEntries(
+            Array.from({ length: 2000 }, (_, i) => ({
+                file: new File(["x"], "" + i),
+                relativePath: "Folder/" + i,
+                destination: "/",
+            })),
+            10,
+            true,
+            folderBatch("Folder"),
+        );
+        manager.snapshot()[0].state = "completed";
+        expect(manager.canQueue(1)).toBe(false);
+        expect(manager.add([new File(["x"], "extra")], "/", 10)[0]).toContain(
+            "2,000",
+        );
+        expect(manager.snapshot()).toHaveLength(2000);
+    });
+    it("matches folder resume by exact rooted path without flattening duplicate basenames", async () => {
+        const file = (path: string, data = "same") => {
+            const file = new File([data], path.split("/").at(-1)!);
+            Object.defineProperty(file, "webkitRelativePath", { value: path });
+            return file;
+        };
+        const manager = managerForTest();
+        manager.addEntries(
+            [
+                {
+                    file: file("Root/a/notes.txt"),
+                    relativePath: "Root/a/notes.txt",
+                    destination: "/r/a",
+                },
+                {
+                    file: file("Root/b/notes.txt"),
+                    relativePath: "Root/b/notes.txt",
+                    destination: "/r/b",
+                },
+            ],
+            10,
+            true,
+            folderBatch("Root", "/r"),
+        );
+        const reloaded = managerForTest();
+        const id = reloaded.snapshot()[0].batchId!;
+        const result = await reloaded.resumeBatchFiles(id, [
+            file("Root/b/notes.txt"),
+        ]);
+        expect(result).toMatchObject({ matched: 1, remaining: 1 });
+        expect(reloaded.snapshot()[0].state).toBe("awaiting_file");
+        expect(reloaded.snapshot()[1].state).toBe("queued");
+        expect(reloaded.snapshot()[1].destination).toBe("/r/b");
+        expect(
+            new Set(reloaded.snapshot().map((item) => item.batchId)).size,
+        ).toBe(1);
+    });
+    it("resumes only the selected ordinary task when file signatures are identical", async () => {
+        const manager = managerForTest();
+        const source = new File(["same"], "same.txt", { lastModified: 42 });
+        manager.add([source, source], "/", 10);
+        const reloaded = managerForTest();
+        const result = await reloaded.resumeBatchFiles(
+            reloaded.snapshot()[0].batchId!,
+            [source],
+        );
+        expect(result.matched).toBe(1);
+        expect(result.remaining).toBe(0);
+        expect(result.errors).toEqual([]);
+        expect(reloaded.snapshot()[0].state).toBe("queued");
+        expect(reloaded.snapshot()[1].state).toBe("awaiting_file");
+    });
+});
+
+describe("independent browser receiving and Telegram backlog", () => {
+    it("drains receipt handoffs after failures without stranding later files", async () => {
+        const handoffs: string[] = [];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input === "/api/v1/uploads") {
+                    const body = JSON.parse(String(options.body));
+                    return Response.json({
+                        id: body.name,
+                        offset: 0,
+                        total_size: 4,
+                        chunk_size: 4,
+                    });
+                }
+                if (input.endsWith("/complete")) {
+                    const id = input.split("/")[4];
+                    handoffs.push(id);
+                    return id === "file-0" || id === "file-1"
+                        ? Response.json(
+                              { detail: "Receipt verification unavailable" },
+                              { status: 503 },
+                          )
+                        : Response.json({ id });
+                }
+                throw new Error("Unexpected request: " + input);
+            }),
+        );
+        const manager = new TransferManager(
+            async () =>
+                new Response(null, {
+                    status: 204,
+                    headers: { "Upload-Offset": "4" },
+                }),
+        );
+        try {
+            manager.add(
+                Array.from(
+                    { length: 6 },
+                    (_, i) => new File(["data"], "file-" + i),
+                ),
+                "/",
+                10,
+            );
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(handoffs).toHaveLength(6));
+            expect(
+                manager
+                    .snapshot()
+                    .filter(
+                        (item) =>
+                            item.state === "queued" &&
+                            item.stage === "retry_wait",
+                    ),
+            ).toHaveLength(2);
+            expect(
+                manager
+                    .snapshot()
+                    .slice(2)
+                    .every((item) => item.jobId && !item.controller),
+            ).toBe(true);
+            expect(
+                manager
+                    .snapshot()
+                    .slice(0, 2)
+                    .every(
+                        (item) => item.file && !item.jobId && !item.controller,
+                    ),
+            ).toBe(true);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("pauses a late-created receipt on logout and safely resumes it after login", async () => {
+        let created!: (response: Response) => void;
+        let creations = 0;
+        let cancellations = 0;
+        let checks = 0;
+        const snapshot = {
+            id: "receipt",
+            offset: 0,
+            total_size: 4,
+            chunk_size: 4,
+        };
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input === "/api/v1/uploads") {
+                    creations += 1;
+                    return new Promise<Response>((resolve) => {
+                        created = resolve;
+                    });
+                }
+                if (input.endsWith("/cancel")) {
+                    cancellations += 1;
+                    return Response.json({});
+                }
+                if (input.endsWith("/complete"))
+                    return Response.json({ id: "receipt" });
+                if (options.method === "HEAD") {
+                    checks += 1;
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                    });
+                }
+                return Response.json(snapshot);
+            }),
+        );
+        const send = vi.fn(
+            async () =>
+                new Response(null, {
+                    status: 204,
+                    headers: { "Upload-Offset": "4" },
+                }),
+        );
+        const manager = new TransferManager(send);
+        const file = new File(["data"], "file");
+        try {
+            manager.setEnabled(true);
+            manager.add([file], "/", 10);
+            await vi.waitFor(() => expect(created).toBeDefined());
+            manager.setEnabled(false);
+            created(Response.json(snapshot));
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].state).toBe("awaiting_file"),
+            );
+            expect(cancellations).toBe(0);
+            expect(send).not.toHaveBeenCalled();
+            manager.setEnabled(true);
+            await manager.resume(manager.snapshot()[0].key, file);
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].jobId).toBe("receipt"),
+            );
+            expect(creations).toBe(1);
+            expect(checks).toBe(1);
+            expect(send).toHaveBeenCalledOnce();
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("cancels a late-created receipt even when its row was cleared before creation returned", async () => {
+        let created!: (response: Response) => void;
+        let cancellations = 0;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input === "/api/v1/uploads")
+                    return new Promise<Response>((resolve) => {
+                        created = resolve;
+                    });
+                if (input.endsWith("/cancel")) {
+                    cancellations += 1;
+                    return Response.json({});
+                }
+                throw new Error("Unexpected request: " + input);
+            }),
+        );
+        const send = vi.fn();
+        const manager = new TransferManager(send);
+        try {
+            manager.setEnabled(true);
+            manager.add([new File(["data"], "file")], "/", 10);
+            await vi.waitFor(() => expect(created).toBeDefined());
+            await manager.cancel(manager.snapshot()[0].key);
+            manager.clearFinished();
+            expect(manager.snapshot()).toHaveLength(0);
+            created(
+                Response.json({
+                    id: "late",
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                }),
+            );
+            await vi.waitFor(() => expect(cancellations).toBe(1));
+            expect(send).not.toHaveBeenCalled();
+            expect(manager.snapshot()).toHaveLength(0);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("applies Retry-After to queued receipt handoffs without stopping active payloads", async () => {
+        vi.useFakeTimers();
+        const handoffs: string[] = [];
+        const patched: string[] = [];
+        const finishers: ((response: Response) => void)[] = [];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input === "/api/v1/uploads") {
+                    const body = JSON.parse(String(options.body));
+                    return Response.json({
+                        id: body.name,
+                        offset: 0,
+                        total_size: 4,
+                        chunk_size: 4,
+                    });
+                }
+                const id = input.split("/")[4];
+                if (input.endsWith("/complete")) {
+                    handoffs.push(id);
+                    if (handoffs.length === 1)
+                        return Response.json(
+                            { detail: "Admission busy" },
+                            { status: 429, headers: { "Retry-After": "10" } },
+                        );
+                    return new Promise<Response>((resolve) =>
+                        finishers.push(resolve),
+                    );
+                }
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                    });
+                return Response.json({
+                    id,
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                });
+            }),
+        );
+        const manager = new TransferManager(async (url) => {
+            patched.push(url.split("/")[4]);
+            return new Response(null, {
+                status: 204,
+                headers: { "Upload-Offset": "4" },
+            });
+        });
+        try {
+            manager.add(
+                Array.from(
+                    { length: 5 },
+                    (_, i) => new File(["data"], "file-" + i),
+                ),
+                "/",
+                10,
+            );
+            manager.setEnabled(true);
+            await vi.advanceTimersByTimeAsync(0);
+            expect(handoffs).toHaveLength(2);
+            expect(patched.length).toBeGreaterThan(handoffs.length);
+            await vi.advanceTimersByTimeAsync(9999);
+            expect(handoffs).toHaveLength(2);
+            await vi.advanceTimersByTimeAsync(1);
+            expect(handoffs).toHaveLength(3);
+        } finally {
+            manager.setEnabled(false);
+            for (const finish of finishers)
+                finish(Response.json({ id: "accepted" }));
+            await vi.advanceTimersByTimeAsync(0);
+            vi.useRealTimers();
+        }
+    });
+    it("keeps device bytes flowing through a bounded, slow receipt handoff", async () => {
+        const patched: string[] = [];
+        const finishers = new Map<string, (response: Response) => void>();
+        let completing = 0;
+        let maximumCompleting = 0;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input === "/api/v1/uploads") {
+                    const body = JSON.parse(String(options.body));
+                    return Response.json({
+                        id: body.name,
+                        offset: 0,
+                        total_size: body.total_size,
+                        chunk_size: 4,
+                        checksums: [],
+                    });
+                }
+                const id = input.split("/")[4];
+                if (input.endsWith("/cancel")) return Response.json({});
+                if (input.endsWith("/complete")) {
+                    completing += 1;
+                    maximumCompleting = Math.max(maximumCompleting, completing);
+                    return new Promise<Response>((resolve) => {
+                        finishers.set(id, (response) => {
+                            completing -= 1;
+                            resolve(response);
+                        });
+                    });
+                }
+                throw new Error("Unexpected receipt check: " + input);
+            }),
+        );
+        const manager = new TransferManager(async (url) => {
+            patched.push(url.split("/")[4]);
+            return new Response(null, {
+                status: 204,
+                headers: { "Upload-Offset": "4" },
+            });
+        });
+        try {
+            manager.add(
+                Array.from(
+                    { length: 7 },
+                    (_, i) => new File(["data"], "file-" + i),
+                ),
+                "/",
+                10,
+            );
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(patched).toHaveLength(7));
+            expect(finishers.size).toBe(2);
+            expect(maximumCompleting).toBe(2);
+            expect(manager.snapshot().every((item) => item.current === 4)).toBe(
+                true,
+            );
+            // Received bytes alone cannot declare the tab safe to close.
+            expect(
+                manager.snapshot().every((item) => !item.jobId && item.file),
+            ).toBe(true);
+            const cancelled = manager.snapshot()[4];
+            await manager.cancel(cancelled.key);
+            expect(cancelled.state).toBe("cancelled");
+            // Release each admitted handoff; queued cancellations must never enter it.
+            for (const id of [
+                "file-0",
+                "file-1",
+                "file-2",
+                "file-3",
+                "file-5",
+                "file-6",
+            ]) {
+                await vi.waitFor(() => expect(finishers.has(id)).toBe(true));
+                finishers.get(id)!(Response.json({ id }));
+            }
+            await vi.waitFor(() =>
+                expect(
+                    manager.snapshot().filter((item) => item.jobId),
+                ).toHaveLength(6),
+            );
+            expect(finishers.has("file-4")).toBe(false);
+            expect(maximumCompleting).toBe(2);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("gives a newly added folder the next device slot before an older folder's backlog", async () => {
+        const admitted: string[] = [];
+        const patches = new Map<string, (response: Response) => void>();
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input === "/api/v1/uploads") {
+                    const body = JSON.parse(String(options.body));
+                    admitted.push(body.name);
+                    return Response.json({
+                        id: body.name,
+                        offset: 0,
+                        total_size: body.total_size,
+                        chunk_size: 4,
+                    });
+                }
+                if (input.endsWith("/complete"))
+                    return Response.json({ id: input.split("/")[4] });
+                throw new Error("Unexpected receipt check: " + input);
+            }),
+        );
+        const manager = new TransferManager(
+            (url, options) =>
+                new Promise<Response>((resolve, reject) => {
+                    patches.set(url.split("/")[4], resolve);
+                    options.signal.addEventListener("abort", () =>
+                        reject(new DOMException("Upload paused", "AbortError")),
+                    );
+                }),
+        );
+        const entries = (prefix: string, count: number) =>
+            Array.from({ length: count }, (_, i) => ({
+                file: new File(["data"], prefix + i),
+                destination: "/" + prefix,
+                relativePath: prefix + "/" + i,
+            }));
+        const acknowledge = (id: string) =>
+            patches.get(id)!(
+                new Response(null, {
+                    status: 204,
+                    headers: { "Upload-Offset": "4" },
+                }),
+            );
+        try {
+            manager.addEntries(
+                entries("old", 5),
+                10,
+                true,
+                folderBatch("Old", "/old"),
+            );
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(patches.size).toBe(2));
+            manager.addEntries(
+                entries("new", 2),
+                10,
+                true,
+                folderBatch("New", "/new"),
+            );
+            acknowledge("old0");
+            await vi.waitFor(() => expect(admitted).toHaveLength(3));
+            expect(admitted).toEqual(["old0", "old1", "new0"]);
+            await vi.waitFor(() => expect(patches.has("new0")).toBe(true));
+            acknowledge("new0");
+            await vi.waitFor(() => expect(admitted).toHaveLength(4));
+            expect(admitted[3]).toBe("old2");
+            acknowledge("old1");
+            await vi.waitFor(() => expect(admitted).toHaveLength(5));
+            expect(admitted[4]).toBe("new1");
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("notifies the listing once per poll when files become available before backup finishes", async () => {
+        const changed = vi.fn();
+        window.addEventListener("tgdrive:files-changed", changed);
+        const jobs = Array.from({ length: 3 }, (_, index) => ({
+            id: "visible-" + index,
+            kind: "upload",
+            status: "running",
+            phase: "backup_pending",
+            current: 4,
+            total: 4,
+        }));
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json({ jobs })),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(manager.snapshot()).toHaveLength(3));
+            expect(changed).toHaveBeenCalledTimes(1);
+            for (const job of jobs) job.status = "completed";
+            manager.refreshJobs();
+            await vi.waitFor(() =>
+                expect(
+                    manager
+                        .snapshot()
+                        .every((item) => item.state === "completed"),
+                ).toBe(true),
+            );
+            expect(changed).toHaveBeenCalledTimes(1);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("admits smaller files while larger files wait for staging space", async () => {
+        const complete: string[] = [];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json({ jobs: [] });
+                if (input === "/api/v1/uploads") {
+                    const body = JSON.parse(String(options.body));
+                    if (body.name.startsWith("large"))
+                        return Response.json(
+                            { detail: "Not enough space" },
+                            { status: 507 },
+                        );
+                    return Response.json({
+                        id: body.name,
+                        offset: 0,
+                        total_size: body.total_size,
+                        chunk_size: 4,
+                        checksums: [],
+                    });
+                }
+                const id = input.split("/")[4];
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                    });
+                if (options.method === "PATCH")
+                    return new Response(null, {
+                        status: 204,
+                        headers: { "Upload-Offset": "4" },
+                    });
+                if (input.endsWith("/complete")) {
+                    complete.push(id);
+                    return Response.json({ id });
+                }
+                return Response.json({
+                    id,
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = managerForTest();
+        try {
+            manager.add(
+                [
+                    ...Array.from(
+                        { length: 4 },
+                        (_, i) => new File(["large-data"], "large-" + i),
+                    ),
+                    new File(["data"], "small"),
+                ],
+                "/",
+                100,
+            );
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(complete).toEqual(["small"]));
+            expect(
+                manager
+                    .snapshot()
+                    .slice(0, 4)
+                    .every((item) => item.state === "queued"),
+            ).toBe(true);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("keeps sending around a slow file even when progress polling is unavailable", async () => {
+        let receipts = 0;
+        const completed: string[] = [];
+        let release!: () => void;
+        const slow = new Promise<void>((resolve) => {
+            release = resolve;
+        });
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs")
+                    return Response.json(
+                        { detail: "Progress unavailable" },
+                        { status: 503 },
+                    );
+                if (input === "/api/v1/uploads")
+                    return Response.json({
+                        id: "receipt-" + ++receipts,
+                        offset: 0,
+                        total_size: 4,
+                        chunk_size: 4,
+                        checksums: [],
+                    });
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                    });
+                const id = input.split("/")[4];
+                if (input.endsWith("/complete")) {
+                    completed.push(id);
+                    return Response.json({ id });
+                }
+                return Response.json({
+                    id,
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = new TransferManager(async (url) => {
+            if (url.endsWith("receipt-1")) await slow;
+            return new Response(null, {
+                status: 204,
+                headers: { "Upload-Offset": "4" },
+            });
+        });
+        try {
+            manager.add(
+                Array.from(
+                    { length: 7 },
+                    (_, i) => new File(["data"], "file-" + i),
+                ),
+                "/",
+                10,
+            );
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(completed).toHaveLength(6));
+            expect(receipts).toBe(7);
+            expect(manager.snapshot()[0].state).toBe("receiving");
+            expect(
+                manager
+                    .snapshot()
+                    .slice(1)
+                    .every((item) => item.jobId),
+            ).toBe(true);
+            release();
+            await vi.waitFor(() => expect(completed).toHaveLength(7));
+        } finally {
+            release();
+            manager.setEnabled(false);
+        }
+    });
+    it("receives all five files while earlier Telegram uploads remain busy", async () => {
+        let receipts = 0;
+        let complete = 0;
+        let patching = 0;
+        let maxPatching = 0;
+        const jobs: {
+            id: string;
+            status: string;
+            phase: string;
+            current: number;
+            total: number;
+            kind: string;
+        }[] = [];
+        const offsets = new Map<string, number>();
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs") return Response.json({ jobs });
+                if (input === "/api/v1/uploads" && options.method === "POST") {
+                    const id = "upload-" + ++receipts;
+                    offsets.set(id, 0);
+                    return Response.json({
+                        id,
+                        offset: 0,
+                        total_size: 4,
+                        chunk_size: 4,
+                    });
+                }
+                const id = input.split("/")[4];
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: {
+                            "Upload-Offset": String(offsets.get(id)),
+                            "Upload-Length": "4",
+                        },
+                    });
+                if (options.method === "PATCH") {
+                    patching += 1;
+                    maxPatching = Math.max(maxPatching, patching);
+                    await Promise.resolve();
+                    offsets.set(id, 4);
+                    patching -= 1;
+                    return new Response(null, {
+                        status: 204,
+                        headers: { "Upload-Offset": "4" },
+                    });
+                }
+                if (input.endsWith("/complete")) {
+                    jobs.push({
+                        id,
+                        status: "running",
+                        phase: "uploading",
+                        current: 0,
+                        total: 4,
+                        kind: "upload",
+                    });
+                    complete += 1;
+                    return Response.json({ id });
+                }
+                return Response.json({
+                    id,
+                    offset: offsets.get(id),
+                    total_size: 4,
+                    chunk_size: 4,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = managerForTest();
+        try {
+            manager.add(
+                Array.from({ length: 5 }, (_, i) => new File(["data"], "" + i)),
+                "/",
+                10,
+            );
+            manager.setEnabled(true);
+            await vi.waitFor(() => expect(complete).toBe(5));
+            expect(receipts).toBe(5);
+            expect(jobs.every((job) => job.status === "running")).toBe(true);
+            expect(maxPatching).toBe(BROWSER_RECEIVE_INITIAL_CONCURRENCY);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("preserves known URL origin when the server changes its job kind to upload", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    jobs: [
+                        {
+                            id: "remote",
+                            status: "running",
+                            phase: "uploading",
+                            current: 1,
+                            total: 4,
+                            kind: "upload",
+                        },
+                    ],
+                }),
+            ),
+        );
+        const manager = managerForTest();
+        manager.addJob("remote", "URL file", "/", "remote");
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].serverStatus).toBe("running"),
+            );
+            expect(manager.snapshot()[0].kind).toBe("remote");
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+
+it("warns when browser storage cannot retain recovery metadata while allowing uploads", () => {
+    vi.stubGlobal("localStorage", {
+        length: 0,
+        getItem: () => null,
+        setItem: () => {
+            throw new DOMException("full", "QuotaExceededError");
+        },
+    });
+    const manager = managerForTest();
+    expect(manager.add([new File(["data"], "file")], "/", 10)).toEqual([]);
+    expect(manager.snapshot()).toHaveLength(1);
+    expect(manager.recoveryWarning).toContain("could not save");
+});
+
+it("continues device receipts while four recovered Telegram jobs are busy", async () => {
+    let receipts = 0;
+    const jobs = Array.from({ length: 4 }, (_, i) => ({
+        id: "recovered-" + i,
+        name: "server",
+        destination: "/",
+        status: "running",
+        phase: "uploading",
+        current: 0,
+        total: 4,
+        kind: "remote",
+    }));
+    vi.stubGlobal(
+        "fetch",
+        vi.fn(async (input: string) => {
+            if (input === "/api/v1/jobs") return Response.json({ jobs });
+            if (input === "/api/v1/uploads") receipts += 1;
+            throw new Error("synthetic stopped receipt");
+        }),
+    );
+    const manager = managerForTest();
+    try {
+        manager.add([new File(["data"], "new")], "/", 10);
+        manager.setEnabled(true);
+        await vi.waitFor(() => expect(manager.snapshot()).toHaveLength(5));
+        await vi.waitFor(() => expect(receipts).toBe(1));
+    } finally {
+        manager.setEnabled(false);
+    }
+});
+
+describe("Telegram backup protection", () => {
+    it("keeps checkpoint-pending files unfinished and refuses cancellation locally", async () => {
+        const fetchMock = vi.fn(async () =>
+            Response.json({
+                jobs: [
+                    {
+                        id: "protected-job",
+                        status: "running",
+                        phase: "backup_pending",
+                        name: "safe.txt",
+                        current: 4,
+                        total: 4,
+                        kind: "upload",
+                    },
+                ],
+            }),
+        );
+        vi.stubGlobal("fetch", fetchMock);
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0]?.stage).toBe("backup_pending"),
+            );
+            manager.setEnabled(false);
+            fetchMock.mockClear();
+            expect(manager.snapshot()[0].state).toBe("uploading");
+            expect(manager.snapshot()[0].phase).toContain(
+                "Securing your drive backup",
+            );
+            await manager.cancelAll();
+            await manager.cancel(manager.snapshot()[0].key);
+            expect(fetchMock).not.toHaveBeenCalled();
+            expect(manager.snapshot()[0].state).toBe("uploading");
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("reconciles a committed upload if cancellation races the checkpoint phase", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    { detail: "Already catalogued", code: "BACKUP_PENDING" },
+                    { status: 409 },
+                ),
+            ),
+        );
+        const manager = managerForTest();
+        manager.addJob("raced-job", "safe.txt", "/");
+        await manager.cancel(manager.snapshot()[0].key);
+        expect(manager.snapshot()[0].stage).toBe("backup_pending");
+        expect(manager.snapshot()[0].state).toBe("uploading");
+        expect(manager.snapshot()[0].error).toBeUndefined();
+    });
+    it("labels a failed checkpoint as a backup retry, not an upload retry", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    jobs: [
+                        {
+                            id: "retry-job",
+                            status: "error",
+                            phase: "backup_pending",
+                            name: "safe.txt",
+                            current: 4,
+                            total: 4,
+                        },
+                    ],
+                }),
+            ),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0]?.state).toBe("error"),
+            );
+            expect(manager.snapshot()[0].phase).toContain(
+                "Backup Needs Attention",
+            );
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+
+describe("overall backup readiness", () => {
+    const row = (state: Transfer["state"], kind = "upload"): Transfer => ({
+        key: state,
+        name: "file",
+        size: 4,
+        lastModified: 1,
+        destination: "/",
+        phase: state,
+        state,
+        current: 0,
+        total: 4,
+        kind,
+    });
+    it("does not claim full protection while selected files are still queued or receiving", () => {
+        expect(uploadBackupState([row("completed"), row("queued")])).toBe(
+            "pending",
+        );
+        expect(uploadBackupState([row("receiving")])).toBe("pending");
+        expect(uploadBackupState([row("uploading")])).toBe("pending");
+    });
+    it("requires failed uploads and missing originals to be resolved", () => {
+        expect(uploadBackupState([row("error")])).toBe("attention");
+        expect(uploadBackupState([row("awaiting_file")])).toBe("attention");
+    });
+    it("allows protection after completion or intentional cancellation", () => {
+        expect(
+            uploadBackupState([row("completed"), row("cancelled")]),
+        ).toBeNull();
+    });
+    it("does not confuse pending deletion with an unsent upload", () => {
+        expect(uploadBackupState([row("error", "delete")])).toBeNull();
+    });
+});
+
+describe("deletion operation tracking", () => {
+    it("keeps active and failed deletions out of upload history, including restored browser history", async () => {
+        localStorage.setItem(
+            "tgdrive.uploads.v2",
+            JSON.stringify([
+                {
+                    key: "old-delete",
+                    initiatedHere: true,
+                    name: "Old",
+                    destination: "/",
+                    size: 0,
+                    kind: "delete",
+                    jobId: "delete-old",
+                    state: "uploading",
+                },
+            ]),
+        );
+        const jobs = [
+            {
+                id: "delete-1",
+                kind: "delete",
+                status: "running",
+                phase: "deleting",
+                current: 0,
+                total: 10,
+                name: "First",
+            },
+            {
+                id: "delete-2",
+                kind: "delete",
+                status: "error",
+                phase: "deleting",
+                current: 0,
+                total: 10,
+                name: "Second",
+                error: "Try Again",
+            },
+            {
+                id: "upload-1",
+                kind: "upload",
+                status: "running",
+                phase: "uploading",
+                current: 3,
+                total: 10,
+                name: "Upload",
+            },
+        ];
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json({ jobs })),
+        );
+        const manager = managerForTest();
+        expect(manager.snapshot()).toEqual([]);
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().jobs).toHaveLength(2),
+            );
+            expect(manager.snapshot().map((item) => item.jobId)).toEqual([
+                "upload-1",
+            ]);
+            expect(JSON.stringify(managerForTest().snapshot())).not.toContain(
+                "delete-",
+            );
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+    it("refreshes files when a tracked deletion actually completes", async () => {
+        let completed = false;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    jobs: [
+                        {
+                            id: "delete-1",
+                            kind: "delete",
+                            status: completed ? "completed" : "running",
+                            phase: "deleting",
+                            current: 0,
+                            total: 10,
+                            name: "First",
+                        },
+                    ],
+                }),
+            ),
+        );
+        const changed = vi.fn();
+        window.addEventListener("tgdrive:files-changed", changed);
+        const manager = managerForTest();
+        try {
+            manager.setEnabled(true);
+            await vi.waitFor(() =>
+                expect(manager.deletionSnapshot().jobs).toHaveLength(1),
+            );
+            expect(changed).not.toHaveBeenCalled();
+            completed = true;
+            manager.refreshJobs();
+            await vi.waitFor(() => expect(changed).toHaveBeenCalledOnce());
+            expect(manager.snapshot()).toEqual([]);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+
+describe("connection restart admission", () => {
+    it("keeps job polling and cancellation available while pausing new browser receipts", async () => {
+        let polls = 0;
+        let receipts = 0;
+        let complete = false;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: string, options: RequestInit = {}) => {
+                if (input === "/api/v1/jobs") {
+                    polls++;
+                    return Response.json({ jobs: [] });
+                }
+                if (input === "/api/v1/uploads" && options.method === "POST") {
+                    receipts++;
+                    return Response.json({
+                        id: "receipt",
+                        offset: 0,
+                        total_size: 4,
+                        chunk_size: 4,
+                    });
+                }
+                if (options.method === "HEAD")
+                    return new Response(null, {
+                        headers: { "Upload-Offset": "0", "Upload-Length": "4" },
+                    });
+                if (options.method === "PATCH")
+                    return new Response(null, {
+                        status: 204,
+                        headers: { "Upload-Offset": "4" },
+                    });
+                if (input.endsWith("/complete")) {
+                    complete = true;
+                    return Response.json({ id: "job" });
+                }
+                return Response.json({
+                    id: "receipt",
+                    offset: 0,
+                    total_size: 4,
+                    chunk_size: 4,
+                    checksums: [],
+                });
+            }),
+        );
+        const manager = managerForTest();
+        try {
+            manager.setAdmissionPaused(true);
+            manager.setEnabled(true);
+            manager.add([new File(["test"], "waiting.txt")], "/", 10);
+            await vi.waitFor(() => expect(polls).toBeGreaterThan(0));
+            expect(receipts).toBe(0);
+            manager.refreshJobs();
+            await vi.waitFor(() => expect(polls).toBeGreaterThan(1));
+            await manager.cancel(manager.snapshot()[0].key);
+            expect(manager.snapshot()[0].state).toBe("cancelled");
+            manager.add([new File(["test"], "next.txt")], "/", 10);
+            expect(receipts).toBe(0);
+            manager.setAdmissionPaused(false);
+            await vi.waitFor(() => expect(complete).toBe(true));
+            expect(receipts).toBe(1);
+        } finally {
+            manager.setEnabled(false);
+        }
+    });
+});
+
+it("cancels only uploads included in the confirmed selection", async () => {
+    const manager = managerForTest();
+    manager.add(
+        [new File(["a"], "first.txt"), new File(["b"], "second.txt")],
+        "/",
+        100,
+    );
+    const confirmedKeys = manager.snapshot().map((item) => item.key);
+    manager.add([new File(["new"], "added-later.txt")], "/", 100);
+    // A file can finish while the confirmation is open; it must be kept.
+    manager.snapshot()[0].state = "completed";
+    await manager.cancelAll(confirmedKeys);
+    expect(
+        manager.snapshot().find((item) => item.name === "first.txt")?.state,
+    ).toBe("completed");
+    expect(
+        manager.snapshot().find((item) => item.name === "second.txt")?.state,
+    ).toBe("cancelled");
+    expect(
+        manager.snapshot().find((item) => item.name === "added-later.txt")
+            ?.state,
+    ).toBe("queued");
+});
+
+it("queues device files for automatic retry when staging is full", async () => {
+    let receipts = 0;
+    vi.stubGlobal(
+        "fetch",
+        vi.fn(async (input: string) => {
+            if (input === "/api/v1/jobs") return Response.json({ jobs: [] });
+            receipts++;
+            return Response.json(
+                { detail: "Temporary Storage budget is full" },
+                { status: 507 },
+            );
+        }),
+    );
+    const manager = managerForTest();
+    try {
+        manager.add(
+            [new File(["data"], "one"), new File(["more"], "two")],
+            "/",
+            10,
+        );
+        manager.setEnabled(true);
+        await vi.waitFor(() => expect(receipts).toBe(2));
+        await vi.waitFor(() =>
+            expect(manager.snapshot()[0].state).toBe("queued"),
+        );
+        expect(manager.snapshot()[0].phase).toBe("Waiting for server space");
+        expect(manager.snapshot()[0].file).toBeDefined();
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        expect(receipts).toBe(2);
+    } finally {
+        manager.setEnabled(false);
+    }
+});
+
+it("distinguishes bytes sent from multipart messages stored in the channel", () => {
+    const job = {
+        id: "parts",
+        status: "running",
+        phase: "uploading",
+        current: 3200,
+        total: 4500,
+        telegram_parts: { stored: 0, total: 3 },
+    };
+    expect(fromJob(job).phase).toBe(
+        "Uploading to Telegram · 0/3 Parts in Channel",
+    );
+    expect(
+        fromJob({ ...job, telegram_parts: { stored: 1, total: 3 } }).phase,
+    ).toContain("1/3");
+    expect(fromJob({ ...job, status: "completed" }).phase).toBe(
+        "Available in your drive",
+    );
+    expect(fromJob({ ...job, telegram_parts: undefined }).phase).toBe(
+        "Uploading to Telegram",
+    );
+});
+
+it("keeps near-complete byte counters precise without implying completion", () => {
+    const gb = 1024 ** 3;
+    expect(formatByteProgress(4.2 * gb, 4.25 * gb)).toBe("4.2 / 4.25 GB");
+    expect(formatByteProgress(4.2499 * gb, 4.25 * gb)).toBe("4.25 / 4.25 GB");
+    expect(remainingBytesHint(4.25 * gb - 1024, 4.25 * gb)).toBe(
+        "1 KB remaining",
+    );
+    expect(remainingBytesHint(4.25 * gb, 4.25 * gb)).toBe("");
+    expect(remainingBytesHint(gb, 4.25 * gb)).toBe("");
+});
+
+describe("recovery records across reloads and open tabs", () => {
+    it("restores valid receipts beside a malformed record and keeps a recovery warning", () => {
+        const first = managerForTest();
+        first.add([new File(["x"], "valid.txt")], "/", 10);
+        localStorage.setItem("tgdrive.uploads.v2:broken", "{invalid");
+        const restored = managerForTest();
+        expect(restored.snapshot().map((row) => row.name)).toEqual([
+            "valid.txt",
+        ]);
+        expect(restored.recoveryWarning).toContain(
+            "Some transfer recovery information",
+        );
+        restored.add([new File(["x"], "new.txt")], "/", 10);
+        expect(restored.recoveryWarning).toContain("Valid saved transfers");
+        expect(
+            managerForTest()
+                .snapshot()
+                .map((row) => row.name),
+        ).toEqual(["valid.txt", "new.txt"]);
+    });
+
+    it("retains distinct dismissals even when two tabs write at the same time", async () => {
+        const first = managerForTest();
+        const second = managerForTest();
+        first.addJob("first-finished", "first.txt", "/");
+        second.addJob("second-finished", "second.txt", "/");
+        first.snapshot()[0].state = "completed";
+        second.snapshot()[0].state = "completed";
+        const write = localStorage.setItem;
+        let interleaved = false;
+        const spy = vi
+            .spyOn(localStorage, "setItem")
+            .mockImplementation((key, value) => {
+                if (
+                    !interleaved &&
+                    key === "tgdrive.dismissed-jobs.v1:first-finished"
+                ) {
+                    interleaved = true;
+                    second.clearFinished();
+                }
+                write(key, value);
+            });
+        first.clearFinished();
+        spy.mockRestore();
+        expect(interleaved).toBe(true);
+        expect(
+            localStorage.getItem("tgdrive.dismissed-jobs.v1:first-finished"),
+        ).not.toBeNull();
+        expect(
+            localStorage.getItem("tgdrive.dismissed-jobs.v1:second-finished"),
+        ).not.toBeNull();
+        localStorage.setItem("tgdrive.dismissed-jobs.v1", "{invalid");
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({
+                    jobs: [
+                        {
+                            id: "first-finished",
+                            status: "completed",
+                            phase: "Complete",
+                            current: 1,
+                            total: 1,
+                        },
+                        {
+                            id: "second-finished",
+                            status: "completed",
+                            phase: "Complete",
+                            current: 1,
+                            total: 1,
+                        },
+                    ],
+                }),
+            ),
+        );
+        const restored = managerForTest();
+        try {
+            restored.setEnabled(true);
+            await vi.waitFor(() => expect(fetch).toHaveBeenCalledOnce());
+            expect(restored.snapshot()).toEqual([]);
+        } finally {
+            restored.setEnabled(false);
+        }
+    });
+
+    it("keeps another tab's acknowledged receipt through idle and stale snapshot writes", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => Response.json({ jobs: [] })),
+        );
+        const first = managerForTest();
+        const emptyTab = managerForTest();
+        first.add([new File(["abcdefgh"], "source.txt")], "/", 10);
+        const item = first.snapshot()[0];
+        Object.assign(item, {
+            uploadId: "receipt-id",
+            current: 4,
+            state: "receiving",
+        });
+        first.addJob("publish-first", "server-first", "/");
+        const staleTab = managerForTest();
+        Object.assign(item, { current: 6 });
+        first.addJob("publish-second", "server-second", "/");
+        try {
+            emptyTab.setEnabled(true);
+            staleTab.setEnabled(true);
+            await vi.waitFor(() => expect(fetch).toHaveBeenCalledTimes(2));
+            emptyTab.setEnabled(false);
+            staleTab.setEnabled(false);
+            // Other rows can be added without replacing the acknowledged receipt.
+            emptyTab.add([new File(["x"], "second.txt")], "/", 10);
+            staleTab.addJob("stale-publish", "server-third", "/");
+            const restored = managerForTest().snapshot();
+            expect(restored.find((row) => row.key === item.key)).toMatchObject({
+                uploadId: "receipt-id",
+                current: 6,
+                state: "awaiting_file",
+            });
+            expect(restored.some((row) => row.name === "second.txt")).toBe(
+                true,
+            );
+        } finally {
+            emptyTab.setEnabled(false);
+            staleTab.setEnabled(false);
+        }
+    });
+
+    it("does not resurrect a cleared local receipt from a stale tab", () => {
+        const first = managerForTest();
+        first.add([new File(["x"], "cancelled.txt")], "/", 10);
+        first.snapshot()[0].state = "cancelled";
+        first.setAdmissionPaused(true);
+        const stale = managerForTest();
+        first.clearFinished();
+        stale.snapshot()[0].phase = "Late cancelled response";
+        stale.add([new File(["x"], "next.txt")], "/", 10);
+        expect(
+            managerForTest()
+                .snapshot()
+                .map((row) => row.name),
+        ).toEqual(["next.txt"]);
+    });
+
+    it("keeps current v2 array receipts recoverable while new records are stored separately", () => {
+        const row = {
+            key: "current-v2",
+            initiatedHere: true,
+            name: "source.txt",
+            size: 8,
+            lastModified: 1,
+            destination: "/",
+            state: "receiving",
+            phase: "Receiving",
+            current: 4,
+            total: 8,
+            uploadId: "current-receipt",
+        };
+        localStorage.setItem("tgdrive.uploads.v2", JSON.stringify([row]));
+        const restored = managerForTest();
+        restored.add([new File(["x"], "new.txt")], "/", 10);
+        const stale = managerForTest();
+        expect(
+            managerForTest()
+                .snapshot()
+                .find((item) => item.key === row.key),
+        ).toMatchObject({
+            uploadId: row.uploadId,
+            current: 4,
+            state: "awaiting_file",
+        });
+        restored.snapshot().find((item) => item.key === row.key)!.state =
+            "cancelled";
+        restored.clearFinished();
+        expect(
+            managerForTest()
+                .snapshot()
+                .map((item) => item.name),
+        ).toEqual(["new.txt"]);
+        expect(localStorage.getItem("tgdrive.uploads.v2")).toBeNull();
+        stale.snapshot().find((item) => item.key === row.key)!.phase =
+            "Late response";
+        stale.addJob("unrelated", "another.txt", "/");
+        expect(
+            managerForTest()
+                .snapshot()
+                .some((item) => item.key === row.key),
+        ).toBe(false);
+    });
+
+    it("bounds persisted dismissal records without rewriting older IDs", () => {
+        for (let index = 0; index <= 1000; index++)
+            localStorage.setItem(
+                "tgdrive.dismissed-jobs.v1:" + index,
+                String(index + 1),
+            );
+        managerForTest().add([new File(["x"], "new.txt")], "/", 10);
+        const keys = Array.from({ length: localStorage.length }, (_, index) =>
+            localStorage.key(index)!,
+        );
+        expect(
+            keys.filter((key) => key.startsWith("tgdrive.dismissed-jobs.v1:")),
+        ).toHaveLength(1000);
+        expect(localStorage.getItem("tgdrive.dismissed-jobs.v1:0")).toBeNull();
+    });
+
+    it("does not let a stale controller overwrite another tab's dismissals", () => {
+        const first = managerForTest();
+        first.addJob("completed-job", "finished.jpg", "/");
+        first.snapshot()[0].state = "completed";
+        first.addJob("active-job", "active.mov", "/");
+        const second = managerForTest();
+        expect(
+            second.snapshot().some((item) => item.jobId === "completed-job"),
+        ).toBe(true);
+        first.clearFinished();
+        expect(first.snapshot().map((item) => item.jobId)).toEqual([
+            "active-job",
+        ]);
+        // The stale tab writes after the clear, as a normal progress poll would.
+        second.addJob("another-job", "another.mov", "/");
+        expect(
+            second.snapshot().some((item) => item.jobId === "completed-job"),
+        ).toBe(false);
+        expect(
+            localStorage.getItem("tgdrive.dismissed-jobs.v1:completed-job"),
+        ).not.toBeNull();
+        expect(
+            managerForTest()
+                .snapshot()
+                .some((item) => item.jobId === "completed-job"),
+        ).toBe(false);
+    });
+    it("suppresses stale saved completed rows during construction", () => {
+        localStorage.setItem(
+            "tgdrive.dismissed-jobs.v1",
+            JSON.stringify(["finished-job"]),
+        );
+        localStorage.setItem(
+            "tgdrive.uploads.v2",
+            JSON.stringify([
+                {
+                    key: "saved",
+                    name: "finished.jpg",
+                    destination: "/",
+                    size: 1,
+                    state: "completed",
+                    current: 1,
+                    total: 1,
+                    lastModified: 0,
+                    jobId: "finished-job",
+                    initiatedHere: true,
+                },
+            ]),
+        );
+        expect(managerForTest().snapshot()).toEqual([]);
+    });
+});
diff --git a/website/src/features/transfers/transfers.ts b/website/src/features/transfers/transfers.ts
new file mode 100644
index 00000000..99ef9d9b
--- /dev/null
+++ b/website/src/features/transfers/transfers.ts
@@ -0,0 +1,2031 @@
+import {
+    api,
+    ApiError,
+    errorMessage,
+    notifyDemoFilesReadOnly,
+    request,
+    sessionExpiryHandler,
+} from "../../shared/api";
+import type {
+    Job,
+    UploadSnapshot,
+    TransferLocation,
+    FolderUploadMetadata,
+} from "../../shared/types";
+import { transferTaskId } from "./transferTasks";
+import { sampleProgress, type ProgressSample } from "./progress";
+import { BatchProgressTracker } from "./batchProgress";
+import { summarizeBatches } from "./transferBatches";
+import { sendUploadChunk, type UploadChunkTransport } from "./uploadTransport";
+import {
+    DeviceUploadConcurrency,
+    INITIAL_DEVICE_UPLOAD_CONCURRENCY,
+    MAX_DEVICE_UPLOAD_CONCURRENCY,
+} from "./deviceUploadConcurrency";
+export type TransferState =
+    | "queued"
+    | "verifying"
+    | "receiving"
+    | "awaiting_file"
+    | "uploading"
+    | "cancelling"
+    | "completed"
+    | "error"
+    | "cancelled";
+export interface Transfer {
+    key: string;
+    name: string;
+    size: number;
+    lastModified: number;
+    destination: string;
+    relativePath?: string;
+    folderUpload?: FolderUploadMetadata;
+    batchId?: string;
+    batchName?: string;
+    batchCreatedAt?: number;
+    state: TransferState;
+    phase: string;
+    current: number;
+    /** Transient browser-observed bytes; current remains the confirmed resume offset. */
+    sentCurrent?: number;
+    total: number;
+    uploadId?: string;
+    jobId?: string;
+    remoteRequestId?: string;
+    kind?: string;
+    error?: string;
+    file?: File;
+    controller?: AbortController;
+    createdAt?: number;
+    startedAt?: number;
+    finishedAt?: number;
+    meter?: ProgressSample;
+    stage?: string;
+    serverStatus?: string;
+    speedBytesPerSecond?: number | null;
+    etaSeconds?: number | null;
+    progressUpdatedAt?: number | null;
+    serverObservedAt?: number;
+    historyOnly?: boolean;
+    /** Browser-only receipt: server-discovered jobs never open this device's popup. */
+    initiatedHere?: boolean;
+    location?: TransferLocation;
+}
+const STORAGE_KEY = "tgdrive.uploads.v2";
+const STORAGE_PREFIX = STORAGE_KEY + ":";
+const DISMISSED_KEY = "tgdrive.dismissed-jobs.v1";
+const DISMISSED_PREFIX = DISMISSED_KEY + ":";
+function readRecoveryRecords() {
+    // The current v2 array is a read-only seed until its rows are updated or cleared.
+    let seed: Transfer[] = [];
+    let invalid = false;
+    try {
+        const value: unknown = JSON.parse(
+            localStorage.getItem(STORAGE_KEY) || "[]",
+        );
+        if (!Array.isArray(value)) throw new Error("Invalid recovery array");
+        seed = value.filter((row) => row && typeof row.key === "string");
+        invalid = seed.length !== value.length;
+    } catch {
+        invalid = true;
+    }
+    const rows = new Map<string, Transfer>();
+    const add = (key: string, value: Transfer | null) => {
+        if (value === null) rows.delete(key);
+        else if (!value || typeof value !== "object") invalid = true;
+        else if (value.kind !== "delete" && value.initiatedHere === true) {
+            if (
+                value.key === key &&
+                typeof value.name === "string" &&
+                typeof value.destination === "string" &&
+                Number.isFinite(value.size)
+            )
+                rows.set(key, value);
+            else invalid = true;
+        }
+    };
+    for (const row of seed) add(row.key, row);
+    for (let index = 0; index < localStorage.length; index++) {
+        const key = localStorage.key(index);
+        if (!key?.startsWith(STORAGE_PREFIX)) continue;
+        try {
+            add(
+                key.slice(STORAGE_PREFIX.length),
+                JSON.parse(localStorage.getItem(key)!),
+            );
+        } catch {
+            invalid = true;
+        }
+    }
+    return { rows: [...rows.values()], seed, invalid };
+}
+export const MAX_BROWSER_QUEUE = 2000;
+// Device receipts have their own slots; Telegram work never holds one.
+export const BROWSER_RECEIVE_CONCURRENCY = MAX_DEVICE_UPLOAD_CONCURRENCY;
+export const BROWSER_RECEIVE_INITIAL_CONCURRENCY =
+    INITIAL_DEVICE_UPLOAD_CONCURRENCY;
+const MAX_HISTORY_BATCHES = 30;
+const MAX_HISTORY_ROWS = 2000;
+// Receipt verification/handoff is control work, independent of payload slots.
+const RECEIPT_COMPLETION_CONCURRENCY = 2;
+const DEVICE_RETRY_DELAYS_MS = [2000, 4000, 8000];
+const TRANSIENT_DEVICE_STATUSES = new Set([0, 408, 500, 502, 503, 504]);
+export interface UploadEntry {
+    file: File;
+    destination: string;
+    relativePath?: string;
+}
+const terminal = new Set<TransferState>(["completed", "cancelled", "error"]);
+export function safeTransferMetadata(transfers: Transfer[]) {
+    return transfers.map(
+        ({
+            key,
+            name,
+            size,
+            lastModified,
+            destination,
+            relativePath,
+            folderUpload,
+            batchId,
+            batchName,
+            batchCreatedAt,
+            state,
+            phase,
+            current,
+            total,
+            uploadId,
+            jobId,
+            remoteRequestId,
+            kind,
+            initiatedHere,
+            createdAt,
+            startedAt,
+            finishedAt,
+        }) => ({
+            key,
+            name,
+            size,
+            lastModified,
+            destination,
+            relativePath,
+            folderUpload,
+            batchId,
+            batchName,
+            batchCreatedAt,
+            state,
+            phase,
+            current,
+            total,
+            uploadId,
+            jobId,
+            remoteRequestId,
+            kind,
+            initiatedHere,
+            createdAt,
+            startedAt,
+            finishedAt,
+        }),
+    );
+}
+export function retainTransferBatches(items: Transfer[]): Transfer[] {
+    const groups = new Map<string, Transfer[]>();
+    for (const item of items) {
+        const id = transferTaskId(item);
+        const batch = groups.get(id) || [];
+        batch.push(item);
+        groups.set(id, batch);
+    }
+    const keep = new Set<string>();
+    const finished: { id: string; rows: Transfer[]; time: number }[] = [];
+    for (const [id, rows] of groups) {
+        if (
+            rows.some(
+                (item) => !["completed", "cancelled"].includes(item.state),
+            )
+        )
+            keep.add(id);
+        else
+            finished.push({
+                id,
+                rows,
+                time: Math.max(
+                    ...rows.map(
+                        (item) =>
+                            item.finishedAt ||
+                            item.batchCreatedAt ||
+                            item.createdAt ||
+                            0,
+                    ),
+                ),
+            });
+    }
+    finished.sort((a, b) => b.time - a.time);
+    let historyRows = 0;
+    for (const batch of finished.slice(0, MAX_HISTORY_BATCHES)) {
+        if (historyRows + batch.rows.length > MAX_HISTORY_ROWS) continue;
+        keep.add(batch.id);
+        historyRows += batch.rows.length;
+    }
+    return items.filter((item) => keep.has(transferTaskId(item)));
+}
+export async function verifyReceivedChunks(
+    file: File,
+    chunks: NonNullable<UploadSnapshot["checksums"]>,
+    offset: number,
+    progress: (bytes: number) => void = () => {},
+    signal?: AbortSignal,
+): Promise<void> {
+    let checked = 0;
+    for (const chunk of [...chunks].sort((a, b) => a.offset - b.offset)) {
+        if (signal?.aborted)
+            throw new DOMException("Upload paused", "AbortError");
+        if (chunk.offset >= offset) break;
+        if (
+            chunk.offset !== checked ||
+            chunk.size <= 0 ||
+            chunk.offset + chunk.size > offset
+        )
+            throw new Error(
+                "The server has incomplete resume information. Start a new upload.",
+            );
+        const digest = await crypto.subtle.digest(
+            "SHA-256",
+            await file
+                .slice(chunk.offset, chunk.offset + chunk.size)
+                .arrayBuffer(),
+        );
+        const hash = [...new Uint8Array(digest)]
+            .map((byte) => byte.toString(16).padStart(2, "0"))
+            .join("");
+        if (hash !== chunk.sha256)
+            throw new Error(
+                "This file differs from the original upload. Choose the original file or cancel and start again.",
+            );
+        if (signal?.aborted)
+            throw new DOMException("Upload paused", "AbortError");
+        checked += chunk.size;
+        progress(checked);
+    }
+    if (checked !== offset)
+        throw new Error(
+            "The server has incomplete resume information. Start a new upload.",
+        );
+}
+export function uploadBackupState(
+    items: Transfer[],
+): "pending" | "attention" | null {
+    const unfinished = items.filter(
+        (item) =>
+            item.kind !== "delete" &&
+            !["completed", "cancelled"].includes(item.state),
+    );
+    if (
+        unfinished.some((item) =>
+            ["error", "awaiting_file"].includes(item.state),
+        )
+    )
+        return "attention";
+    return unfinished.length ? "pending" : null;
+}
+export function canCancelTransfer(item: Transfer): boolean {
+    return (
+        !item.historyOnly &&
+        item.kind !== "delete" &&
+        item.stage !== "backup_pending" &&
+        !["completed", "cancelled"].includes(item.state)
+    );
+}
+export function fromJob(job: Job, previousKind?: string): Partial<Transfer> {
+    const state: TransferState =
+        job.status === "completed"
+            ? "completed"
+            : job.status === "cancelled"
+              ? "cancelled"
+              : job.status === "error" ||
+                  job.status === "failed" ||
+                  job.status === "interrupted"
+                ? "error"
+                : job.status === "cancelling" ||
+                    job.status === "cancel_requested"
+                  ? "cancelling"
+                  : "uploading";
+    let phase =
+        state === "error"
+            ? job.kind === "delete"
+                ? "Deletion failed. Retry to finish cleanup"
+                : job.phase === "backup_pending"
+                  ? "Backup Needs Attention. Retry to secure this file"
+                  : "Upload failed"
+            : state === "cancelled"
+              ? "Cancelled"
+              : state === "completed"
+                ? job.kind === "delete"
+                    ? "Permanently deleted"
+                    : "Available in your drive"
+                : state === "cancelling"
+                  ? "Cancelling and cleaning up"
+                  : job.kind === "delete"
+                    ? "Deleting from Telegram"
+                    : job.phase === "backup_pending"
+                      ? "Securing your drive backup in Telegram"
+                      : job.phase === "source_retry_wait"
+                        ? "Source interrupted · retrying automatically in " +
+                          Math.max(
+                              0,
+                              Math.ceil(
+                                  (job.retry_at || Date.now() / 1000) -
+                                      Date.now() / 1000,
+                              ),
+                          ) +
+                          "s · attempt " +
+                          (job.source_attempt || 2) +
+                          " of " +
+                          (job.source_max_attempts || 4)
+                        : job.phase === "retry_wait"
+                          ? "Waiting for Telegram; retry scheduled"
+                          : ["checking_source", "downloading"].includes(
+                                  job.phase,
+                              ) && job.download_mode === "waiting_storage"
+                            ? "Waiting for temporary storage"
+                            : job.phase === "checking_source" &&
+                                job.download_mode === "queued"
+                              ? "Waiting for a source connection"
+                              : job.phase === "checking_source"
+                                ? job.status === "queued"
+                                    ? "Waiting to check source"
+                                    : "Checking source…"
+                                : job.phase === "downloading"
+                                  ? job.download_mode === "warm"
+                                      ? "Queued · receiving slowly"
+                                      : "Downloading from URL"
+                                  : job.phase === "finalizing"
+                                    ? "Publishing to the channel"
+                                    : job.status === "queued"
+                                      ? "Queued for Telegram"
+                                      : "Uploading to Telegram";
+    if (
+        state === "uploading" &&
+        job.status === "running" &&
+        ["uploading", "finalizing"].includes(job.phase) &&
+        job.telegram_parts &&
+        job.telegram_parts.total > 1
+    ) {
+        const { stored, total } = job.telegram_parts;
+        phase += " · " + stored + "/" + total + " Parts in Channel";
+    }
+    if (job.queue && job.queue.position > 0) {
+        phase += " · Queue position " + job.queue.position;
+        if (job.queue.estimated_wait_seconds != null)
+            phase +=
+                " · about " +
+                Math.ceil(job.queue.estimated_wait_seconds) +
+                "s wait";
+    }
+    return {
+        state,
+        phase,
+        ...(job.folder_upload
+            ? {
+                  folderUpload: job.folder_upload,
+                  batchId: job.folder_upload.id,
+                  batchName: job.folder_upload.name,
+                  batchCreatedAt: job.folder_upload.created_at * 1000,
+              }
+            : {}),
+        ...(job.location ? { location: job.location } : {}),
+        ...(previousKind === "remote"
+            ? { kind: "remote" }
+            : job.kind
+              ? { kind: job.kind }
+              : {}),
+        current: job.current ?? 0,
+        total: job.total ?? 0,
+        error: job.error || undefined,
+        stage: job.phase,
+        serverStatus: job.status,
+        speedBytesPerSecond: job.speed_bytes_per_second,
+        etaSeconds: job.eta_seconds,
+        progressUpdatedAt: job.progress_updated_at,
+        serverObservedAt: Date.now(),
+        ...(job.created_at ? { createdAt: job.created_at * 1000 } : {}),
+        ...(job.started_at ? { startedAt: job.started_at * 1000 } : {}),
+        ...(job.finished_at ? { finishedAt: job.finished_at * 1000 } : {}),
+    };
+}
+export interface DeletionProgress {
+    jobs: Job[];
+    completed: number;
+    error: string;
+}
+
+const deletionTerminal = new Set([
+    "completed",
+    "cancelled",
+    "error",
+    "failed",
+    "interrupted",
+]);
+
+export class TransferManager {
+    recoveryWarning = "";
+    private items: Transfer[] = [];
+    private deletionJobs: Job[] = [];
+    private noticedDeletions = new Set<string>();
+    private deletionVersion = 0;
+    private deletionUpdates = new Map<string, number>();
+    private deletionProgress: DeletionProgress = {
+        jobs: [],
+        completed: 0,
+        error: "",
+    };
+    private listeners = new Set<() => void>();
+    private batchProgress = new BatchProgressTracker();
+    private enabled = false;
+    private admissionPaused = false;
+    private receiving = new Set<string>();
+    private processing = new Set<string>();
+    private lastReceivingBatch: string | undefined;
+    private completing = 0;
+    private completionQueue: (() => void)[] = [];
+    private deviceConcurrency = new DeviceUploadConcurrency();
+    private concurrencyTimer: ReturnType<typeof setInterval> | undefined;
+    private timer: ReturnType<typeof setTimeout> | undefined;
+    private stagingTimer: ReturnType<typeof setTimeout> | undefined;
+    private polling = false;
+    private refreshRequested = false;
+    private stagingRetries = new Map<string, number>();
+    private deviceRetryAttempts = new Map<string, number>();
+    private admissionRetryAt = 0;
+    private dismissed = new Set<string>();
+    private persistedDismissed = new Set<string>();
+    private historyRevision = 0;
+    private remoteStarts = new Map<
+        string,
+        {
+            url: string;
+            destination: string;
+            singleThreaded: boolean;
+            requestId: string;
+        }
+    >();
+    private remoteSubmitting = new Set<string>();
+    private persisted = new Map<string, string>();
+    constructor(
+        private readonly sendChunk: UploadChunkTransport = sendUploadChunk,
+    ) {
+        try {
+            const saved = readRecoveryRecords();
+            if (saved.invalid)
+                this.recoveryWarning =
+                    "Some transfer recovery information could not be loaded. Valid saved transfers are still available.";
+            this.items = saved.rows.map((item) => ({
+                ...safeTransferMetadata([item])[0],
+                initiatedHere: true,
+                batchId: transferTaskId(item),
+                batchName:
+                    item.folderUpload?.name || item.batchName || item.name,
+                batchCreatedAt:
+                    (item.folderUpload
+                        ? item.folderUpload.created_at * 1000
+                        : 0) ||
+                    item.batchCreatedAt ||
+                    item.createdAt ||
+                    Date.now(),
+                state:
+                    item.jobId ||
+                    (item.kind === "remote" && item.remoteRequestId)
+                        ? item.state
+                        : terminal.has(item.state)
+                          ? item.state
+                          : item.kind === "remote"
+                            ? "error"
+                            : "awaiting_file",
+                phase:
+                    item.kind === "remote" &&
+                    item.remoteRequestId &&
+                    !item.jobId &&
+                    !terminal.has(item.state)
+                        ? "Checking import status…"
+                        : item.jobId
+                          ? item.phase
+                          : terminal.has(item.state)
+                            ? item.phase
+                            : item.kind === "remote"
+                              ? "URL transfer is missing its server job. Start a new URL upload."
+                              : "Choose the original file to resume",
+            }));
+        } catch {
+            this.recoveryWarning =
+                "Your browser could not load transfer recovery information. Keep this tab open until device transfers finish.";
+        }
+        this.mergeDismissed();
+        this.persistedDismissed = new Set(this.dismissed);
+        this.persisted = new Map(
+            safeTransferMetadata(this.items).map((row) => [
+                row.key,
+                JSON.stringify(row),
+            ]),
+        );
+    }
+    subscribe = (listener: () => void) => {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    };
+    snapshot = () => this.items;
+    batchProgressSnapshot = () => this.batchProgress.snapshot();
+    deletionSnapshot = () => this.deletionProgress;
+    private updateDeletionProgress(error = "") {
+        this.deletionProgress = {
+            jobs: this.deletionJobs,
+            completed: this.deletionJobs.filter(
+                (job) =>
+                    job.status === "completed" &&
+                    this.noticedDeletions.has(job.id),
+            ).length,
+            error,
+        };
+    }
+    trackDeletions(jobs: Pick<Job, "id" | "name">[]) {
+        if (!jobs.length) return;
+        if (!this.deletionJobs.some((job) => !deletionTerminal.has(job.status)))
+            this.noticedDeletions.clear();
+        for (const job of jobs) {
+            const queued: Job = {
+                ...job,
+                kind: "delete",
+                status: "queued",
+                phase: "queued",
+                current: 0,
+                total: 0,
+            };
+            this.deletionJobs = [
+                ...this.deletionJobs.filter((old) => old.id !== job.id),
+                queued,
+            ];
+            this.noticedDeletions.add(job.id);
+            this.deletionUpdates.set(job.id, ++this.deletionVersion);
+        }
+        this.updateDeletionProgress();
+        this.publish(false);
+        this.refreshJobs();
+    }
+    dismissDeletionResult = () => {
+        for (const job of this.deletionJobs)
+            if (job.status === "completed")
+                this.noticedDeletions.delete(job.id);
+        this.updateDeletionProgress(this.deletionProgress.error);
+        this.publish(false);
+    };
+    refreshJobs = () => {
+        if (this.polling) this.refreshRequested = true;
+        else void this.poll();
+    };
+    async retryDeletion(id: string) {
+        if (
+            !this.deletionJobs.some(
+                (job) => job.id === id && job.kind === "delete",
+            )
+        )
+            return;
+        const job = await request<Job>(
+            "/api/v1/jobs/" + encodeURIComponent(id) + "/retry",
+            {},
+        );
+        this.deletionJobs = [
+            ...this.deletionJobs.filter((old) => old.id !== id),
+            job,
+        ];
+        this.noticedDeletions.add(id);
+        this.deletionUpdates.set(id, ++this.deletionVersion);
+        this.updateDeletionProgress();
+        this.publish(false);
+        // A poll started before this retry must be followed by a fresh request.
+        this.refreshJobs();
+    }
+    private mergeDismissed() {
+        try {
+            let saved: unknown;
+            try {
+                saved = JSON.parse(localStorage.getItem(DISMISSED_KEY) || "[]");
+            } catch {
+                /* Independent dismissal records remain readable. */
+            }
+            if (Array.isArray(saved))
+                for (const id of saved)
+                    if (typeof id === "string") this.dismissed.add(id);
+            const records: [string, number][] = [];
+            for (let index = 0; index < localStorage.length; index++) {
+                const key = localStorage.key(index);
+                if (key?.startsWith(DISMISSED_PREFIX))
+                    records.push([key, Number(localStorage.getItem(key)) || 0]);
+            }
+            records.sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]));
+            for (const [key] of records)
+                this.dismissed.add(key.slice(DISMISSED_PREFIX.length));
+            this.dismissed = new Set([...this.dismissed].slice(-1000));
+        } catch {
+            /* Keep in-memory dismissals when browser storage is unavailable. */
+        }
+        const unfinished = new Set(
+            this.items
+                .filter(
+                    (item) => !["completed", "cancelled"].includes(item.state),
+                )
+                .map(transferTaskId),
+        );
+        this.items = this.items.filter(
+            (item) =>
+                !item.jobId ||
+                !this.dismissed.has(item.jobId) ||
+                !["completed", "cancelled"].includes(item.state) ||
+                unfinished.has(transferTaskId(item)),
+        );
+    }
+    private publish(persist = true) {
+        const now = Date.now();
+        if (this.enabled && !this.admissionPaused)
+            this.batchProgress.observe(summarizeBatches(this.items, now), now);
+        else this.batchProgress.clear();
+        if (!persist) {
+            this.items = [...this.items];
+            for (const listener of this.listeners) listener();
+            return;
+        }
+        // Another tab may have cleared finished rows since the previous poll.
+        this.mergeDismissed();
+        const retained = retainTransferBatches(this.items);
+        const retainedKeys = new Set(retained.map((item) => item.key));
+        for (const item of this.items)
+            if (item.jobId && !retainedKeys.has(item.key))
+                this.dismissed.add(item.jobId);
+        this.items = [...retained];
+        try {
+            const invalid = this.persistRecovery();
+            this.persistDismissed();
+            this.recoveryWarning = invalid
+                ? "Some transfer recovery information could not be loaded. Valid saved transfers are still available."
+                : "";
+        } catch {
+            this.recoveryWarning =
+                "Your browser could not save transfer recovery information. Keep this tab open until device transfers finish.";
+        }
+        for (const listener of this.listeners) listener();
+    }
+    private persistRecovery() {
+        const { seed, invalid } = readRecoveryRecords();
+        const seedKeys = new Set(seed.map((row) => row.key));
+        const remove = (key: string) => {
+            // A seed tombstone prevents a still-open tab restoring a cleared row.
+            if (seedKeys.has(key))
+                localStorage.setItem(STORAGE_PREFIX + key, "null");
+            else localStorage.removeItem(STORAGE_PREFIX + key);
+        };
+        for (const row of seed)
+            if (!row.initiatedHere || row.kind === "delete") remove(row.key);
+        const current = new Map<string, string>();
+        const removed = new Set<string>();
+        for (const row of safeTransferMetadata(this.items)) {
+            if (!row.initiatedHere || row.kind === "delete") continue;
+            const stored = localStorage.getItem(STORAGE_PREFIX + row.key);
+            if (
+                stored === "null" ||
+                (this.persisted.has(row.key) &&
+                    stored === null &&
+                    !seedKeys.has(row.key))
+            ) {
+                removed.add(row.key);
+                continue;
+            }
+            const serialized = JSON.stringify(row);
+            if (serialized !== this.persisted.get(row.key))
+                localStorage.setItem(STORAGE_PREFIX + row.key, serialized);
+            current.set(row.key, serialized);
+        }
+        for (const key of this.persisted.keys())
+            if (!current.has(key) && !removed.has(key)) remove(key);
+        this.items = this.items.filter((row) => !removed.has(row.key));
+        this.persisted = current;
+        const saved = readRecoveryRecords().rows;
+        const retained = new Set(
+            retainTransferBatches(saved).map((row) => row.key),
+        );
+        for (const row of saved) if (!retained.has(row.key)) remove(row.key);
+        if (
+            seed.length &&
+            seed.every(
+                (row) =>
+                    localStorage.getItem(STORAGE_PREFIX + row.key) !== null,
+            )
+        ) {
+            localStorage.removeItem(STORAGE_KEY);
+            for (const row of seed)
+                if (localStorage.getItem(STORAGE_PREFIX + row.key) === "null")
+                    localStorage.removeItem(STORAGE_PREFIX + row.key);
+        }
+        return invalid;
+    }
+    private persistDismissed() {
+        for (const id of this.dismissed)
+            if (
+                !this.persistedDismissed.has(id) &&
+                localStorage.getItem(DISMISSED_PREFIX + id) === null
+            )
+                localStorage.setItem(DISMISSED_PREFIX + id, String(Date.now()));
+        const records: [string, number][] = [];
+        for (let index = 0; index < localStorage.length; index++) {
+            const key = localStorage.key(index);
+            if (key?.startsWith(DISMISSED_PREFIX))
+                records.push([key, Number(localStorage.getItem(key)) || 0]);
+        }
+        records.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+        for (const [key] of records.slice(1000)) localStorage.removeItem(key);
+        if (records.length >= 1000) localStorage.removeItem(DISMISSED_KEY);
+        this.persistedDismissed = new Set(this.dismissed);
+    }
+    private update(key: string, values: Partial<Transfer>) {
+        const item = this.items.find((item) => item.key === key);
+        if (item) {
+            Object.assign(item, values);
+            if (item.state !== "receiving") item.sentCurrent = undefined;
+            if (["receiving", "verifying"].includes(item.state))
+                item.startedAt ??= Date.now();
+            if (values.state && !terminal.has(values.state))
+                item.finishedAt = undefined;
+            if (terminal.has(item.state)) item.finishedAt ??= Date.now();
+            if (item.state === "receiving")
+                item.meter = sampleProgress(
+                    item.meter,
+                    item.state,
+                    item.sentCurrent ?? item.current,
+                    Date.now(),
+                );
+            else item.meter = undefined;
+            this.publish(
+                Object.keys(values).some((key) => key !== "sentCurrent"),
+            );
+        }
+    }
+    setEnabled(enabled: boolean) {
+        if (this.enabled === enabled) return;
+        this.enabled = enabled;
+        if (!enabled) {
+            this.batchProgress.clear();
+            clearTimeout(this.timer);
+            clearTimeout(this.stagingTimer);
+            clearInterval(this.concurrencyTimer);
+            this.concurrencyTimer = undefined;
+            this.deviceConcurrency.pauseMeasurements(Date.now());
+            for (const item of this.items) item.controller?.abort();
+            return;
+        }
+        void this.poll();
+        void this.startNext();
+    }
+    setAdmissionPaused(paused: boolean) {
+        if (this.admissionPaused === paused) return;
+        this.admissionPaused = paused;
+        if (paused) this.batchProgress.clear();
+        this.deviceConcurrency.pauseMeasurements(Date.now());
+        this.updateConcurrencyTimer();
+        if (!paused) void this.startNext();
+    }
+    canQueue(count: number): boolean {
+        const unfinished = new Set(
+            this.items
+                .filter(
+                    (item) => !["completed", "cancelled"].includes(item.state),
+                )
+                .map(transferTaskId),
+        );
+        const retainedRows = this.items.filter((item) =>
+            unfinished.has(transferTaskId(item)),
+        ).length;
+        return (
+            Number.isSafeInteger(count) &&
+            count >= 0 &&
+            retainedRows + count <= MAX_BROWSER_QUEUE
+        );
+    }
+    add(files: File[], destination: string, maxSize: number): string[] {
+        return this.addEntries(
+            files.map((file) => ({ file, destination })),
+            maxSize,
+        );
+    }
+    addEntries(
+        entries: UploadEntry[],
+        maxSize: number,
+        requireAll = false,
+        batch?: {
+            name: string;
+            folderUpload: FolderUploadMetadata;
+        },
+    ): string[] {
+        const rejected: string[] = [];
+        const accepted = entries.filter(({ file }) => {
+            if (
+                !Number.isSafeInteger(file.size) ||
+                !file.size ||
+                file.size > maxSize
+            ) {
+                rejected.push(
+                    file.name +
+                        (file.size
+                            ? ": exceeds the upload limit"
+                            : ": empty files are not supported"),
+                );
+                return false;
+            }
+            return true;
+        });
+        if (requireAll && rejected.length) return rejected;
+        if (!this.canQueue(accepted.length))
+            return [
+                "The upload queue can track up to 2,000 files in unfinished batches. Finish or cancel an existing batch, then try again.",
+            ];
+        if (!accepted.length) return rejected;
+        const folder = batch?.folderUpload;
+        const createdAt = folder ? folder.created_at * 1000 : Date.now();
+        for (const { file, destination, relativePath } of accepted) {
+            const key = crypto.randomUUID();
+            this.items.push({
+                key,
+                initiatedHere: true,
+                createdAt: Date.now(),
+                batchId: folder?.id || key,
+                batchName: folder?.name || file.name,
+                batchCreatedAt: createdAt,
+                relativePath,
+                ...(folder ? { folderUpload: folder } : {}),
+                name: file.name,
+                size: file.size,
+                lastModified: file.lastModified,
+                destination,
+                state: "queued",
+                phase: "Waiting to send from this device",
+                current: 0,
+                total: file.size,
+                file,
+            });
+        }
+        this.publish();
+        void this.startNext();
+        return rejected;
+    }
+    addJob(jobId: string, name: string, destination: string, kind = "upload") {
+        if (kind === "delete") {
+            this.refreshJobs();
+            return;
+        }
+        this.items.push({
+            key: crypto.randomUUID(),
+            initiatedHere: true,
+            createdAt: Date.now(),
+            name,
+            batchId: crypto.randomUUID(),
+            batchName: name,
+            batchCreatedAt: Date.now(),
+            size: 0,
+            lastModified: 0,
+            destination,
+            jobId,
+            kind,
+            state: "uploading",
+            phase: "Queued on server",
+            current: 0,
+            total: 0,
+        });
+        this.publish();
+        void this.poll();
+    }
+    startRemote(
+        url: string,
+        destination: string,
+        singleThreaded: boolean,
+        requestId: string,
+    ): string {
+        const parsed = new URL(url);
+        if (!["http:", "https:"].includes(parsed.protocol))
+            throw new Error("Enter a direct HTTP or HTTPS file link.");
+        if (!this.canQueue(1))
+            throw new Error(
+                "Finish or cancel an existing transfer before adding more.",
+            );
+        const key = crypto.randomUUID();
+        let name = parsed.pathname.split("/").at(-1) || "URL import";
+        try {
+            name = decodeURIComponent(name);
+        } catch {
+            /* Keep the URL basename. */
+        }
+        const now = Date.now();
+        this.items.push({
+            key,
+            name,
+            destination,
+            batchId: key,
+            batchName: name,
+            batchCreatedAt: now,
+            createdAt: now,
+            initiatedHere: true,
+            size: 0,
+            lastModified: 0,
+            current: 0,
+            total: 0,
+            kind: "remote",
+            remoteRequestId: requestId,
+            state: "uploading",
+            stage: "checking_source",
+            phase: "Starting URL import…",
+        });
+        this.remoteStarts.set(key, {
+            url,
+            destination,
+            singleThreaded,
+            requestId,
+        });
+        this.publish();
+        void this.submitRemote(key);
+        return key;
+    }
+    private acceptRemote(key: string, result: { id: string; data?: Job }) {
+        const item = this.items.find((row) => row.key === key);
+        if (!item) return;
+        if (result.id) {
+            item.jobId = result.id;
+            // Polling may discover this server job before its start response arrives.
+            this.items = this.items.filter(
+                (row) => row.key === key || row.jobId !== result.id,
+            );
+            this.remoteStarts.delete(key);
+        }
+        if (result.data && item.state !== "cancelled")
+            Object.assign(item, fromJob(result.data, "remote"));
+        else if (!["cancelled", "cancelling"].includes(item.state)) {
+            item.state = "uploading";
+            item.phase = "Checking source…";
+            item.stage = "checking_source";
+            item.error = undefined;
+        }
+        this.publish();
+    }
+    private async recoverRemote(key: string, originalError?: unknown) {
+        const item = this.items.find((row) => row.key === key);
+        if (!item?.remoteRequestId) return;
+        try {
+            const result = await api.remoteRequest(item.remoteRequestId);
+            if (!result.id && result.data.status === "queued")
+                throw new Error(
+                    "The server is still accepting this import. Retry to check it.",
+                );
+            this.acceptRemote(key, result);
+        } catch (error) {
+            if (["cancelled", "cancelling"].includes(item.state)) return;
+            this.update(key, {
+                state: "error",
+                stage: "checking_source",
+                phase: "Import needs attention",
+                error: errorMessage(originalError || error),
+            });
+        }
+    }
+    private async submitRemote(key: string) {
+        const pending = this.remoteStarts.get(key);
+        if (!pending || this.remoteSubmitting.has(key)) return;
+        this.remoteSubmitting.add(key);
+        try {
+            this.acceptRemote(
+                key,
+                await api.remote(
+                    pending.url,
+                    pending.destination,
+                    pending.singleThreaded,
+                    pending.requestId,
+                ),
+            );
+        } catch (error) {
+            // A lost response must not silently create a second import on retry.
+            await this.recoverRemote(key, error);
+        } finally {
+            this.remoteSubmitting.delete(key);
+            void this.poll();
+        }
+    }
+    async resume(key: string, file: File) {
+        const item = this.items.find((item) => item.key === key);
+        if (!item) return;
+        if (item.kind === "remote")
+            throw new Error(
+                "URL uploads resume on the server. Retry the transfer instead.",
+            );
+        if (
+            file.name.normalize("NFC") !== item.name.normalize("NFC") ||
+            file.size !== item.size
+        )
+            throw new Error(
+                "Choose the same file name and size as the original upload.",
+            );
+        this.deviceRetryAttempts.delete(key);
+        this.stagingRetries.delete(key);
+        this.update(key, {
+            file,
+            state: "queued",
+            error: undefined,
+            phase: "Waiting to check the original file",
+        });
+        void this.startNext();
+    }
+    async resumeBatchFiles(batchId: string, files: File[]) {
+        const pending = this.items.filter(
+            (item) =>
+                transferTaskId(item) === batchId &&
+                !item.jobId &&
+                (item.state === "awaiting_file" || item.state === "error"),
+        );
+        const folderBatch = pending.some((item) => Boolean(item.folderUpload));
+        const fileKey = (file: File) =>
+            folderBatch
+                ? "path:" + (file.webkitRelativePath || "").normalize("NFC")
+                : JSON.stringify([
+                      file.name.normalize("NFC"),
+                      file.size,
+                      file.lastModified,
+                  ]);
+        const itemKey = (item: Transfer) =>
+            folderBatch
+                ? "path:" + (item.relativePath || "").normalize("NFC")
+                : JSON.stringify([
+                      item.name.normalize("NFC"),
+                      item.size,
+                      item.lastModified,
+                  ]);
+        const selected = new Map<string, File[]>();
+        for (const file of files) {
+            const key = fileKey(file);
+            selected.set(key, [...(selected.get(key) || []), file]);
+        }
+        const expected = new Map<string, number>();
+        for (const item of pending) {
+            const key = itemKey(item);
+            expected.set(key, (expected.get(key) || 0) + 1);
+        }
+        let matched = 0;
+        const errors: string[] = [];
+        for (const item of pending) {
+            const key = itemKey(item);
+            const candidates = selected.get(key);
+            if (!candidates?.length) continue;
+            if (candidates.length !== 1 || expected.get(key) !== 1) {
+                errors.push(
+                    "More than one file matches " +
+                        (item.relativePath || item.name) +
+                        ". Choose that file individually.",
+                );
+                continue;
+            }
+            const file = candidates[0];
+            if (
+                file.name.normalize("NFC") !== item.name.normalize("NFC") ||
+                file.size !== item.size
+            ) {
+                errors.push(
+                    (item.relativePath || item.name) +
+                        ": the name or size differs from the original upload.",
+                );
+                continue;
+            }
+            Object.assign(item, {
+                file,
+                state: "queued",
+                error: undefined,
+                finishedAt: undefined,
+                phase: "Waiting to check the original file",
+            });
+            this.deviceRetryAttempts.delete(item.key);
+            this.stagingRetries.delete(item.key);
+            matched += 1;
+        }
+        if (matched) {
+            this.publish();
+            void this.startNext();
+        }
+        return {
+            matched,
+            remaining: pending.length - matched,
+            unmatched: files.length - matched,
+            errors,
+        };
+    }
+    async retry(key: string) {
+        const item = this.items.find((item) => item.key === key);
+        if (!item) return;
+        if (item.jobId) {
+            const payload = await request<{ id: string }>(
+                "/api/v1/jobs/" + encodeURIComponent(item.jobId) + "/retry",
+                {},
+            );
+            this.update(key, {
+                jobId: payload.id,
+                state: "uploading",
+                error: undefined,
+                phase: "Queued for retry",
+            });
+            void this.poll();
+        } else if (item.file) {
+            this.deviceRetryAttempts.delete(key);
+            this.stagingRetries.delete(key);
+            this.update(key, {
+                state: "queued",
+                error: undefined,
+                phase: "Waiting to resume",
+            });
+            void this.startNext();
+        } else if (item.kind === "remote") {
+            this.update(key, {
+                state: "uploading",
+                error: undefined,
+                phase: "Checking import status…",
+            });
+            if (this.remoteStarts.has(key)) await this.submitRemote(key);
+            else if (item.remoteRequestId) await this.recoverRemote(key);
+            else
+                throw new Error(
+                    "This URL transfer has no server job. Start a new URL upload.",
+                );
+        } else
+            this.update(key, {
+                state: "awaiting_file",
+                error: undefined,
+                phase: "Choose the original file to resume",
+            });
+    }
+    async cancel(key: string) {
+        const item = this.items.find((item) => item.key === key);
+        if (!item || !canCancelTransfer(item)) return;
+        this.stagingRetries.delete(item.key);
+        this.deviceRetryAttempts.delete(item.key);
+        this.update(key, {
+            state: "cancelling",
+            phase: "Cancelling and cleaning up",
+            error: undefined,
+        });
+        item.controller?.abort();
+        try {
+            if (item.jobId) {
+                const result = await api.cancelJob(item.jobId);
+                if (result.data)
+                    this.update(key, fromJob(result.data, item.kind));
+            } else if (item.kind === "remote" && item.remoteRequestId) {
+                this.acceptRemote(
+                    key,
+                    await api.cancelRemoteRequest(item.remoteRequestId),
+                );
+                this.remoteStarts.delete(key);
+            } else {
+                if (item.uploadId) await api.cancelUpload(item.uploadId);
+                this.update(key, {
+                    state: "cancelled",
+                    phase: "Cancelled",
+                    file: undefined,
+                });
+            }
+        } catch (error) {
+            if (error instanceof ApiError && error.code === "BACKUP_PENDING") {
+                this.update(key, {
+                    state: "uploading",
+                    stage: "backup_pending",
+                    error: undefined,
+                    phase: "Securing your drive backup in Telegram",
+                });
+                void this.poll();
+                return;
+            }
+            this.update(key, {
+                state: "cancelling",
+                error: errorMessage(error),
+                phase: "Cancellation not yet confirmed. Try Again.",
+            });
+            throw error;
+        } finally {
+            void this.startNext();
+        }
+    }
+    clearFinished() {
+        for (const item of this.items)
+            if (item.jobId && ["completed", "cancelled"].includes(item.state))
+                this.dismissed.add(item.jobId);
+        const unfinished = new Set(
+            this.items
+                .filter(
+                    (item) => !["completed", "cancelled"].includes(item.state),
+                )
+                .map(transferTaskId),
+        );
+        this.items = this.items.filter((item) =>
+            unfinished.has(transferTaskId(item)),
+        );
+        this.publish();
+    }
+    async clearHistory() {
+        const unfinished = new Set(
+            this.items
+                .filter(
+                    (item) =>
+                        !["completed", "cancelled", "error"].includes(
+                            item.state,
+                        ),
+                )
+                .map(transferTaskId),
+        );
+        const removed = this.items.filter(
+            (item) =>
+                item.kind !== "delete" && !unfinished.has(transferTaskId(item)),
+        );
+        const keys = new Set(removed.map((item) => item.key));
+        const excludeFolders = [
+            ...new Set(
+                this.items
+                    .filter((item) => unfinished.has(transferTaskId(item)))
+                    .flatMap((item) =>
+                        item.folderUpload ? [item.folderUpload.id] : [],
+                    ),
+            ),
+        ];
+        await api.clearTransferHistory(excludeFolders);
+        this.historyRevision++;
+        this.items = this.items.filter((item) => !keys.has(item.key));
+        this.publish();
+    }
+    private async cancelItems(items: Transfer[]) {
+        for (const item of items) {
+            item.state = "cancelling";
+            item.phase = "Cancelling and cleaning up";
+            item.controller?.abort();
+        }
+        this.publish();
+        const errors: unknown[] = [];
+        for (const item of items) {
+            try {
+                await this.cancel(item.key);
+            } catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length)
+            throw new Error(
+                "Some cancellations are not confirmed. Check the affected files and try again.",
+            );
+    }
+    async cancelBatch(batchId: string) {
+        await this.cancelItems(
+            this.items.filter(
+                (item) =>
+                    transferTaskId(item) === batchId && canCancelTransfer(item),
+            ),
+        );
+    }
+    async retryBatch(batchId: string) {
+        for (const item of this.items.filter(
+            (item) =>
+                transferTaskId(item) === batchId && item.state === "error",
+        ))
+            await this.retry(item.key);
+    }
+    async cancelAll(keys?: string[]) {
+        const selected = keys ? new Set(keys) : null;
+        await this.cancelItems(
+            this.items.filter(
+                (item) =>
+                    canCancelTransfer(item) &&
+                    (!selected || selected.has(item.key)),
+            ),
+        );
+    }
+    private startNext() {
+        try {
+            if (!this.enabled || this.admissionPaused) return;
+            clearTimeout(this.stagingTimer);
+            if (Date.now() < this.admissionRetryAt) {
+                this.stagingTimer = setTimeout(
+                    () => this.startNext(),
+                    this.admissionRetryAt - Date.now(),
+                );
+                return;
+            }
+            this.startCompletions();
+            while (this.receiving.size < this.deviceConcurrency.limit) {
+                const eligible = this.items.filter(
+                    (item) =>
+                        item.state === "queued" &&
+                        item.file &&
+                        !this.processing.has(item.key) &&
+                        Date.now() >= (this.stagingRetries.get(item.key) || 0),
+                );
+                if (!eligible.length) break;
+                // Give each selection/folder a turn. A newly added folder can use the
+                // next free device slot without waiting behind an older folder's tail.
+                const batches = [...new Set(eligible.map(transferTaskId))];
+                const previous = batches.indexOf(this.lastReceivingBatch || "");
+                const nextBatch = batches[(previous + 1) % batches.length];
+                const item = eligible.find(
+                    (candidate) => transferTaskId(candidate) === nextBatch,
+                );
+                if (!item) break;
+                this.lastReceivingBatch = transferTaskId(item);
+                this.stagingRetries.delete(item.key);
+                this.receiving.add(item.key);
+                this.processing.add(item.key);
+                void this.receiveNext(item);
+            }
+            const retryTimes = this.items
+                .filter((item) => item.state === "queued" && item.file)
+                .map((item) => this.stagingRetries.get(item.key) || 0)
+                .filter((at) => at > Date.now());
+            if (retryTimes.length)
+                this.stagingTimer = setTimeout(
+                    () => this.startNext(),
+                    Math.max(0, Math.min(...retryTimes) - Date.now()),
+                );
+        } finally {
+            this.updateConcurrencyTimer();
+        }
+    }
+    private canMeasureDeviceUpload() {
+        return (
+            this.enabled &&
+            !this.admissionPaused &&
+            (typeof document === "undefined" ||
+                document.visibilityState !== "hidden")
+        );
+    }
+    private sampleDeviceConcurrency() {
+        const now = Date.now();
+        if (!this.canMeasureDeviceUpload()) {
+            this.deviceConcurrency.pauseMeasurements(now);
+            return;
+        }
+        const previous = this.deviceConcurrency.limit;
+        const hasBacklog =
+            now >= this.admissionRetryAt &&
+            this.items.some(
+                (item) =>
+                    item.state === "queued" &&
+                    item.file &&
+                    !this.processing.has(item.key) &&
+                    now >= (this.stagingRetries.get(item.key) || 0),
+            );
+        this.deviceConcurrency.sample(now, hasBacklog);
+        if (previous !== this.deviceConcurrency.limit) this.startNext();
+    }
+    private updateConcurrencyTimer() {
+        if (this.enabled && !this.admissionPaused && this.receiving.size) {
+            this.concurrencyTimer ??= setInterval(
+                () => this.sampleDeviceConcurrency(),
+                1000,
+            );
+            return;
+        }
+        clearInterval(this.concurrencyTimer);
+        this.concurrencyTimer = undefined;
+        this.deviceConcurrency.pauseMeasurements(Date.now());
+        if (
+            !this.receiving.size &&
+            !this.items.some(
+                (item) =>
+                    !item.jobId &&
+                    item.file &&
+                    !["completed", "cancelled"].includes(item.state),
+            )
+        )
+            this.deviceConcurrency.reset(Date.now());
+    }
+    private async sendDeviceChunk(
+        chunkId: string,
+        expectedOffset: number,
+        url: string,
+        options: Parameters<UploadChunkTransport>[1],
+        progress: Parameters<UploadChunkTransport>[2],
+    ) {
+        if (!this.canMeasureDeviceUpload())
+            this.deviceConcurrency.pauseMeasurements(Date.now());
+        this.deviceConcurrency.chunkStarted(
+            chunkId,
+            Date.now(),
+            options.body.size,
+        );
+        let confirmedBytes: number | undefined;
+        try {
+            const response = await this.sendChunk(url, options, (sent) => {
+                if (options.signal.aborted) return;
+                if (!this.canMeasureDeviceUpload())
+                    this.deviceConcurrency.pauseMeasurements(Date.now());
+                this.deviceConcurrency.chunkProgress(chunkId, sent, Date.now());
+                progress(sent);
+            });
+            if (
+                response.ok &&
+                Number(response.headers.get("Upload-Offset")) === expectedOffset
+            )
+                confirmedBytes = options.body.size;
+            return response;
+        } catch (error) {
+            if (error instanceof DOMException && error.name === "TimeoutError")
+                throw new ApiError(
+                    "TGDrive stopped confirming this upload. Try Again.",
+                    408,
+                    "REQUEST_TIMEOUT",
+                );
+            if (error instanceof TypeError)
+                throw new ApiError(errorMessage(error));
+            throw error;
+        } finally {
+            this.deviceConcurrency.chunkFinished(
+                chunkId,
+                Date.now(),
+                confirmedBytes,
+            );
+            this.sampleDeviceConcurrency();
+        }
+    }
+    private async receiveNext(item: Transfer) {
+        try {
+            await this.receive(item);
+        } catch (error) {
+            if (
+                this.enabled &&
+                !this.admissionPaused &&
+                !item.controller?.signal.aborted &&
+                !item.jobId &&
+                !["cancelling", "cancelled"].includes(item.state) &&
+                error instanceof ApiError &&
+                [0, 408, 429, 500, 502, 503, 504].includes(error.status)
+            )
+                this.deviceConcurrency.reportPressure(Date.now());
+            if (item.jobId) {
+                // The server can accept a receipt before its HTTP response is lost.
+                // Its polled job remains authoritative over late device-request errors.
+                this.refreshJobs();
+            } else if (
+                this.enabled &&
+                !this.admissionPaused &&
+                !item.controller?.signal.aborted &&
+                !["cancelling", "cancelled"].includes(item.state) &&
+                item.uploadId &&
+                item.file &&
+                error instanceof ApiError &&
+                (TRANSIENT_DEVICE_STATUSES.has(error.status) ||
+                    (error.status === 409 &&
+                        error.code === "UPLOAD_OFFSET_CHANGED")) &&
+                (this.deviceRetryAttempts.get(item.key) || 0) <
+                    DEVICE_RETRY_DELAYS_MS.length
+            ) {
+                // Retry only a known receipt: an unacknowledged creation may have
+                // succeeded, so automatically repeating its POST could create a second
+                // receipt. HEAD/checksums reconcile ambiguous PATCH/completion results.
+                const attempt = this.deviceRetryAttempts.get(item.key) || 0;
+                this.deviceRetryAttempts.set(item.key, attempt + 1);
+                this.stagingRetries.set(
+                    item.key,
+                    Date.now() +
+                        Math.max(
+                            DEVICE_RETRY_DELAYS_MS[attempt],
+                            error.retryAfter * 1000,
+                        ),
+                );
+                this.update(item.key, {
+                    state: "queued",
+                    stage: "retry_wait",
+                    phase: "Connection interrupted. Retrying automatically…",
+                    error: undefined,
+                });
+            } else if (
+                item.state !== "cancelling" &&
+                item.state !== "cancelled" &&
+                error instanceof ApiError &&
+                [429, 507].includes(error.status)
+            ) {
+                const retryAt =
+                    Date.now() + Math.max(5000, error.retryAfter * 1000);
+                if (error.status === 429)
+                    this.admissionRetryAt = Math.max(
+                        this.admissionRetryAt,
+                        retryAt,
+                    );
+                else this.stagingRetries.set(item.key, retryAt);
+                this.update(item.key, {
+                    state: "queued",
+                    phase: "Waiting for server space",
+                    stage: "retry_wait",
+                    error: undefined,
+                    ...(item.uploadId ? {} : { startedAt: undefined }),
+                });
+            } else if (
+                item.state !== "cancelling" &&
+                item.state !== "cancelled"
+            )
+                this.update(item.key, {
+                    state:
+                        error instanceof DOMException &&
+                        error.name === "AbortError"
+                            ? "awaiting_file"
+                            : "error",
+                    phase: "Upload paused",
+                    error: errorMessage(error),
+                });
+        } finally {
+            item.controller = undefined;
+            this.receiving.delete(item.key);
+            this.processing.delete(item.key);
+            this.startNext();
+        }
+    }
+    private async receive(item: Transfer) {
+        const file = item.file!;
+        const previouslyAcknowledged = item.current;
+        const controller = new AbortController();
+        item.controller = controller;
+        this.update(item.key, {
+            state: "receiving",
+            stage: "preparing",
+            phase: "Preparing device upload",
+            sentCurrent: undefined,
+        });
+        let snapshot: UploadSnapshot | undefined;
+        if (!item.uploadId) {
+            snapshot = await api.createUpload(
+                item.name,
+                item.destination,
+                item.size,
+                item.folderUpload,
+            );
+            // Cancellation can remove the row before creation returns. Retain the id
+            // on this operation as well so its late receipt can still be cleaned up.
+            item.uploadId = snapshot.id;
+            this.update(item.key, { uploadId: snapshot.id });
+        }
+        if (["cancelling", "cancelled"].includes(item.state)) {
+            if (item.uploadId) await api.cancelUpload(item.uploadId);
+            return;
+        }
+        if (controller.signal.aborted)
+            throw new DOMException("Upload paused", "AbortError");
+        const id = item.uploadId!;
+        // Creation already returns the authoritative, empty receipt. Rechecking it
+        // with HEAD and GET adds two round trips to every small file unnecessarily.
+        let offset = snapshot ? snapshot.offset : 0;
+        let length = snapshot ? snapshot.total_size : 0;
+        if (!snapshot) {
+            const expireSession = sessionExpiryHandler();
+            const head = await fetch(
+                "/api/v1/uploads/" + encodeURIComponent(id),
+                {
+                    method: "HEAD",
+                    credentials: "same-origin",
+                    signal: AbortSignal.any([
+                        controller.signal,
+                        AbortSignal.timeout(60000),
+                    ]),
+                },
+            ).catch((error) => {
+                if (
+                    error instanceof DOMException &&
+                    error.name === "TimeoutError"
+                )
+                    throw new ApiError(
+                        "TGDrive did not confirm the upload position in time. Try Again.",
+                        408,
+                        "REQUEST_TIMEOUT",
+                    );
+                if (error instanceof TypeError)
+                    throw new ApiError(errorMessage(error));
+                throw error;
+            });
+            if (!head.ok) {
+                expireSession(head.status);
+                throw new ApiError(
+                    head.status === 404 || head.status === 410
+                        ? "This upload has expired. Cancel it and start a new upload."
+                        : "Could not check the upload position. Try Again.",
+                    head.status,
+                    "",
+                    Math.max(0, Number(head.headers.get("Retry-After")) || 0),
+                );
+            }
+            const offsetHeader = head.headers.get("Upload-Offset");
+            const lengthHeader = head.headers.get("Upload-Length");
+            offset =
+                offsetHeader === null || offsetHeader === ""
+                    ? NaN
+                    : Number(offsetHeader);
+            length =
+                lengthHeader === null || lengthHeader === ""
+                    ? NaN
+                    : Number(lengthHeader);
+        }
+        if (
+            !Number.isSafeInteger(offset) ||
+            offset < 0 ||
+            offset > file.size ||
+            !Number.isSafeInteger(length) ||
+            length !== file.size
+        )
+            throw new Error("The server returned an invalid upload position.");
+        snapshot ??= await api.upload(id);
+        if (item.jobId) return;
+        // A prior PATCH can commit between HEAD and this inspection. Its newer
+        // offset and checksum journal belong to one snapshot; never replay the old
+        // offset or combine it with a newer journal. A receipt cannot move backward.
+        if (
+            !Number.isSafeInteger(snapshot.offset) ||
+            snapshot.offset < offset ||
+            snapshot.offset > file.size ||
+            snapshot.total_size !== file.size
+        )
+            throw new Error("The server returned an invalid upload position.");
+        offset = snapshot.offset;
+        if (controller.signal.aborted)
+            throw new DOMException("Upload paused", "AbortError");
+        if (offset) {
+            this.update(item.key, {
+                state: "verifying",
+                phase: "Checking the original file before resuming",
+                current: offset,
+                total: file.size,
+            });
+            await verifyReceivedChunks(
+                file,
+                snapshot.checksums || [],
+                offset,
+                undefined, // Hashing must not replace acknowledged upload progress.
+                controller.signal,
+            );
+        }
+        if (offset > previouslyAcknowledged)
+            this.deviceRetryAttempts.delete(item.key);
+        const chunkSize = snapshot.chunk_size;
+        if (
+            !Number.isSafeInteger(chunkSize) ||
+            chunkSize <= 0 ||
+            chunkSize > 32 * 1024 * 1024
+        )
+            throw new Error("The server returned an invalid chunk size.");
+        this.update(item.key, {
+            state: "receiving",
+            phase: "Uploading from your device",
+            stage: "sending",
+            current: offset,
+            sentCurrent: offset,
+            total: file.size,
+            error: undefined,
+        });
+        while (offset < file.size) {
+            if (controller.signal.aborted)
+                throw new DOMException("Upload paused", "AbortError");
+            const end = Math.min(offset + chunkSize, file.size);
+            const expireSession = sessionExpiryHandler();
+            const response = await this.sendDeviceChunk(
+                item.key + ":" + offset,
+                end,
+                "/api/v1/uploads/" + encodeURIComponent(id),
+                {
+                    method: "PATCH",
+                    credentials: "same-origin",
+                    headers: {
+                        "Content-Type": "application/octet-stream",
+                        "Upload-Offset": String(offset),
+                    },
+                    body: file.slice(offset, end),
+                    signal: controller.signal,
+                },
+                (sent) => {
+                    if (controller.signal.aborted || item.state !== "receiving")
+                        return;
+                    this.update(item.key, {
+                        sentCurrent: Math.max(
+                            item.sentCurrent ?? offset,
+                            offset + sent,
+                        ),
+                        ...(offset + sent >= file.size
+                            ? {
+                                  stage: "confirming",
+                                  phase: "Sent from device. Waiting for server confirmation",
+                              }
+                            : {}),
+                    });
+                },
+            );
+            if (!response.ok) {
+                expireSession(response.status);
+                let detail = "";
+                let code = "";
+                try {
+                    const failure = await response.json();
+                    if (typeof failure.detail === "string")
+                        detail = failure.detail.slice(0, 500);
+                    if (typeof failure.code === "string") code = failure.code;
+                } catch {
+                    /* A proxy may return a non-JSON error page. */
+                }
+                notifyDemoFilesReadOnly(code);
+                throw new ApiError(
+                    detail ||
+                        (response.status === 409
+                            ? "The upload position changed. Retry to safely resume."
+                            : response.status === 507
+                              ? "Temporary Storage is full. Free space or cancel a transfer, then retry."
+                              : "Sending this file was interrupted. Retry to resume."),
+                    response.status,
+                    code,
+                    Math.max(
+                        0,
+                        Number(response.headers.get("Retry-After")) || 0,
+                    ),
+                );
+            }
+            const nextOffset = Number(response.headers.get("Upload-Offset"));
+            if (nextOffset !== end)
+                throw new Error(
+                    "The server did not confirm this file chunk. Retry to check the upload position.",
+                );
+            offset = nextOffset;
+            this.deviceRetryAttempts.delete(item.key);
+            this.update(item.key, { current: offset, sentCurrent: offset });
+        }
+        if (controller.signal.aborted)
+            throw new DOMException("Upload paused", "AbortError");
+        this.update(item.key, {
+            phase: "Receipt complete. Preparing Telegram upload",
+            stage: "confirming",
+        });
+        // All payload bytes are acknowledged. Let another file send while receipt
+        // verification and durable Telegram admission finish in their bounded lane.
+        this.receiving.delete(item.key);
+        this.startNext();
+        await this.completeReceipt(item, controller);
+    }
+    private startCompletions() {
+        if (Date.now() < this.admissionRetryAt) return;
+        while (
+            this.completing < RECEIPT_COMPLETION_CONCURRENCY &&
+            this.completionQueue.length
+        )
+            this.completionQueue.shift()!();
+    }
+    private completeReceipt(item: Transfer, controller: AbortController) {
+        return new Promise<void>((resolve, reject) => {
+            let waiting = true;
+            const abort = () => {
+                if (!waiting) return;
+                waiting = false;
+                this.completionQueue = this.completionQueue.filter(
+                    (entry) => entry !== start,
+                );
+                reject(new DOMException("Upload paused", "AbortError"));
+            };
+            const start = () => {
+                if (!waiting) return;
+                waiting = false;
+                controller.signal.removeEventListener("abort", abort);
+                this.completing += 1;
+                // Do not abandon an admitted completion request on browser cancellation:
+                // the server may already own the job, so reconcile its response instead.
+                void this.finishReceipt(item)
+                    .then(resolve, reject)
+                    .finally(() => {
+                        this.completing -= 1;
+                        this.startCompletions();
+                    });
+            };
+            if (controller.signal.aborted) {
+                abort();
+                return;
+            }
+            controller.signal.addEventListener("abort", abort, { once: true });
+            this.completionQueue.push(start);
+            this.startCompletions();
+        });
+    }
+    private async finishReceipt(item: Transfer) {
+        const result = await api
+            .completeUpload(item.uploadId!)
+            .catch((error) => {
+                // Publish pressure before the completion lane can admit its next request.
+                if (error instanceof ApiError && error.status === 429)
+                    this.admissionRetryAt = Math.max(
+                        this.admissionRetryAt,
+                        Date.now() + Math.max(5000, error.retryAfter * 1000),
+                    );
+                throw error;
+            });
+        this.deviceRetryAttempts.delete(item.key);
+        this.stagingRetries.delete(item.key);
+        // Polling or cancellation can finish while the receipt response is in flight.
+        // Attach ownership without replacing that newer server/cancellation state.
+        if (
+            item.jobId ||
+            ["cancelling", "cancelled", "completed"].includes(item.state)
+        )
+            this.update(item.key, { jobId: result.id, file: undefined });
+        else
+            this.update(item.key, {
+                jobId: result.id,
+                state: "uploading",
+                phase: "Queued for Telegram",
+                current: 0,
+                total: item.size,
+                file: undefined,
+            });
+        this.refreshJobs();
+    }
+    private async poll() {
+        if (!this.enabled || this.polling) return;
+        clearTimeout(this.timer);
+        this.polling = true;
+        for (const item of this.items
+            .filter(
+                (row) =>
+                    row.kind === "remote" &&
+                    row.remoteRequestId &&
+                    !row.jobId &&
+                    !terminal.has(row.state) &&
+                    !this.remoteSubmitting.has(row.key),
+            )
+            .slice(0, 8)) {
+            this.remoteSubmitting.add(item.key);
+            void this.recoverRemote(item.key).finally(() =>
+                this.remoteSubmitting.delete(item.key),
+            );
+        }
+        const deletionVersion = this.deletionVersion;
+        const historyRevision = this.historyRevision;
+        try {
+            const payload = await api.jobs();
+            let filesChanged = false;
+            const previousDeletions = new Map(
+                this.deletionJobs.map((job) => [job.id, job.status]),
+            );
+            const latestDeletions = new Map(
+                this.deletionJobs.map((job) => [job.id, job]),
+            );
+            this.deletionJobs = payload.jobs
+                .filter((job) => job.kind === "delete")
+                .map((job) => {
+                    // Do not replace accepted work with a response captured before it started.
+                    if (
+                        (this.deletionUpdates.get(job.id) || 0) >
+                        deletionVersion
+                    )
+                        return latestDeletions.get(job.id) || job;
+                    this.deletionUpdates.delete(job.id);
+                    return job;
+                });
+            for (const [id, version] of this.deletionUpdates)
+                if (
+                    version > deletionVersion &&
+                    !this.deletionJobs.some((job) => job.id === id)
+                )
+                    this.deletionJobs.push(latestDeletions.get(id)!);
+            for (const job of this.deletionJobs)
+                if (!deletionTerminal.has(job.status))
+                    this.noticedDeletions.add(job.id);
+            this.updateDeletionProgress();
+            if (
+                this.deletionJobs.some(
+                    (job) =>
+                        job.status === "completed" &&
+                        previousDeletions.get(job.id) !== "completed",
+                )
+            )
+                filesChanged = true;
+            this.mergeDismissed();
+            const clearedKeys = new Set<string>();
+            for (const job of payload.jobs) {
+                // Deletions are a single file-operation notice, never upload transfers.
+                if (job.kind === "delete" || this.dismissed.has(job.id))
+                    continue;
+                if (
+                    historyRevision !== this.historyRevision &&
+                    ["completed", "cancelled", "error"].includes(job.status)
+                )
+                    continue;
+                let item = this.items.find(
+                    (item) => item.jobId === job.id || item.uploadId === job.id,
+                );
+                if (job.history_cleared && !item) continue;
+                if (!item) {
+                    item = {
+                        key: crypto.randomUUID(),
+                        name: job.name || "Server transfer",
+                        batchId: "server:" + job.id,
+                        batchName: job.name || "Server transfer",
+                        batchCreatedAt: job.created_at
+                            ? job.created_at * 1000
+                            : Date.now(),
+                        size: job.total || 0,
+                        lastModified: 0,
+                        destination: job.destination || "/",
+                        jobId: job.id,
+                        state: "uploading",
+                        phase: "Queued",
+                        current: 0,
+                        total: job.total,
+                    };
+                    this.items.push(item);
+                }
+                if (!item.jobId) {
+                    item.jobId = job.id;
+                    item.file = undefined;
+                }
+                this.deviceRetryAttempts.delete(item.key);
+                this.stagingRetries.delete(item.key);
+                const wasVisible =
+                    item.state === "completed" ||
+                    item.stage === "backup_pending";
+                const createdAt = item.createdAt;
+                const startedAt = item.startedAt;
+                Object.assign(item, fromJob(job, item.kind));
+                if (job.history_cleared) clearedKeys.add(item.key);
+                if (startedAt)
+                    item.startedAt = Math.min(
+                        startedAt,
+                        item.startedAt || startedAt,
+                    );
+                if (createdAt)
+                    item.createdAt = Math.min(
+                        createdAt,
+                        item.createdAt || createdAt,
+                    );
+                if (terminal.has(item.state)) item.finishedAt ??= Date.now();
+                else item.finishedAt = undefined;
+                item.meter = undefined;
+                if (
+                    !wasVisible &&
+                    (item.state === "completed" ||
+                        item.stage === "backup_pending")
+                )
+                    filesChanged = true;
+            }
+            const unfinished = new Set(
+                this.items
+                    .filter((item) => !terminal.has(item.state))
+                    .map(transferTaskId),
+            );
+            this.items = this.items.filter(
+                (item) =>
+                    !clearedKeys.has(item.key) ||
+                    unfinished.has(transferTaskId(item)),
+            );
+            this.publish();
+            if (filesChanged)
+                window.dispatchEvent(new Event("tgdrive:files-changed"));
+        } catch {
+            this.updateDeletionProgress(
+                this.deletionJobs.some(
+                    (job) => !deletionTerminal.has(job.status),
+                )
+                    ? "Could not check deletion progress. Retrying automatically…"
+                    : "",
+            );
+            for (const item of this.items)
+                if (item.jobId && !terminal.has(item.state))
+                    item.error = "Progress connection lost. Trying again…";
+            this.publish();
+        } finally {
+            this.polling = false;
+            if (this.refreshRequested && this.enabled) {
+                this.refreshRequested = false;
+                void this.poll();
+                return;
+            }
+            this.refreshRequested = false;
+            if (this.enabled) void this.startNext();
+            if (this.enabled)
+                this.timer = setTimeout(
+                    () => {
+                        void this.poll();
+                    },
+                    this.items.some(
+                        (item) => item.jobId && !terminal.has(item.state),
+                    ) ||
+                        this.deletionJobs.some(
+                            (job) =>
+                                ![
+                                    "completed",
+                                    "cancelled",
+                                    "error",
+                                    "failed",
+                                    "interrupted",
+                                ].includes(job.status),
+                        )
+                        ? 1500
+                        : 10000,
+                );
+        }
+    }
+}
+export const transfers = new TransferManager();
+export function isTransferActive(item: Transfer) {
+    return !terminal.has(item.state);
+}
diff --git a/website/src/features/transfers/uploadScheduler.test.ts b/website/src/features/transfers/uploadScheduler.test.ts
new file mode 100644
index 00000000..19e8724f
--- /dev/null
+++ b/website/src/features/transfers/uploadScheduler.test.ts
@@ -0,0 +1,419 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+    BROWSER_RECEIVE_CONCURRENCY,
+    BROWSER_RECEIVE_INITIAL_CONCURRENCY,
+    TransferManager,
+} from "./transfers";
+import type { UploadChunkTransport } from "./uploadTransport";
+
+function deferred<T>() {
+    let resolve!: (value: T) => void;
+    const promise = new Promise<T>((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+
+const receipt = (id: string, size = 4) =>
+    Response.json({
+        id,
+        offset: 0,
+        total_size: size,
+        chunk_size: 4,
+        checksums: [],
+    });
+const position = (size = 4) =>
+    new Response(null, {
+        headers: { "Upload-Offset": "0", "Upload-Length": String(size) },
+    });
+const received = (offset = 4) =>
+    new Response(null, {
+        status: 204,
+        headers: { "Upload-Offset": String(offset) },
+    });
+const managers: TransferManager[] = [];
+const managerForTest = (sendChunk?: UploadChunkTransport) => {
+    const manager = new TransferManager(
+        sendChunk || ((url, options) => fetch(url, options)),
+    );
+    managers.push(manager);
+    return manager;
+};
+
+beforeEach(() => {
+    const values = new Map<string, string>();
+    vi.stubGlobal("localStorage", {
+        get length() {
+            return values.size;
+        },
+        key: (index: number) => [...values.keys()][index] ?? null,
+        removeItem: (key: string) => values.delete(key),
+        getItem: (key: string) => values.get(key) || null,
+        setItem: (key: string, value: string) => values.set(key, value),
+    });
+    vi.stubGlobal("window", new EventTarget());
+});
+
+afterEach(() => {
+    for (const manager of managers.splice(0)) manager.setEnabled(false);
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+});
+
+describe("device upload scheduling", () => {
+    it.each(["create", "head", "chunk"])(
+        "honors a server-wide Retry-After from %s without admitting more files early",
+        async (stage) => {
+            vi.useFakeTimers();
+            const progress = deferred<Response>();
+            let rejected = 0;
+            let created = 0;
+            vi.stubGlobal(
+                "fetch",
+                vi.fn(async (url: string, options: RequestInit = {}) => {
+                    if (url === "/api/v1/jobs") return progress.promise;
+                    const isCreate = url === "/api/v1/uploads";
+                    if (isCreate) created++;
+                    const shouldReject =
+                        stage === "create"
+                            ? isCreate
+                            : stage === "head"
+                              ? options.method === "HEAD"
+                              : options.method === "PATCH";
+                    if (
+                        shouldReject &&
+                        rejected < BROWSER_RECEIVE_INITIAL_CONCURRENCY
+                    ) {
+                        rejected++;
+                        return Response.json(
+                            { detail: "Slow down" },
+                            {
+                                status: 429,
+                                headers: { "Retry-After": "30" },
+                            },
+                        );
+                    }
+                    if (isCreate) return receipt("rate-" + created);
+                    if (options.method === "HEAD") return position();
+                    if (options.method === "PATCH") return received();
+                    const id = url.split("/")[4];
+                    if (url.endsWith("/complete")) return Response.json({ id });
+                    return receipt(id);
+                }),
+            );
+            const manager = managerForTest();
+            manager.add(
+                Array.from(
+                    { length: 5 },
+                    (_, i) => new File(["data"], "file-" + i),
+                ),
+                "/",
+                10,
+            );
+            if (stage === "head")
+                for (const [index, item] of manager
+                    .snapshot()
+                    .slice(0, BROWSER_RECEIVE_INITIAL_CONCURRENCY)
+                    .entries())
+                    item.uploadId = "resumed-" + index;
+            const initialCreations =
+                stage === "head" ? 0 : BROWSER_RECEIVE_INITIAL_CONCURRENCY;
+            try {
+                manager.setEnabled(true);
+                await vi.advanceTimersByTimeAsync(0);
+                expect(rejected).toBe(BROWSER_RECEIVE_INITIAL_CONCURRENCY);
+                expect(created).toBe(initialCreations);
+                await vi.advanceTimersByTimeAsync(29999);
+                expect(created).toBe(initialCreations);
+                await vi.advanceTimersByTimeAsync(1);
+                expect(
+                    manager.snapshot().every((item) => Boolean(item.jobId)),
+                ).toBe(true);
+            } finally {
+                manager.setEnabled(false);
+                progress.resolve(Response.json({ jobs: [] }));
+                await vi.advanceTimersByTimeAsync(0);
+            }
+        },
+    );
+    it("keeps a cancellation final when an earlier receipt snapshot arrives late", async () => {
+        const snapshot = deferred<Response>();
+        const snapshotStarted = deferred<void>();
+        let chunks = 0;
+        let completions = 0;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (url: string, options: RequestInit = {}) => {
+                if (url === "/api/v1/jobs") return Response.json({ jobs: [] });
+                if (url === "/api/v1/uploads")
+                    return receipt("cancelled-receipt");
+                if (url.endsWith("/cancel"))
+                    return Response.json({ state: "cancelled" });
+                if (options.method === "HEAD") return position();
+                if (options.method === "PATCH") {
+                    chunks++;
+                    return received();
+                }
+                if (url.endsWith("/complete")) {
+                    completions++;
+                    return Response.json({ id: "cancelled-receipt" });
+                }
+                snapshotStarted.resolve();
+                return snapshot.promise;
+            }),
+        );
+        const manager = managerForTest();
+        manager.add([new File(["data"], "cancel.bin")], "/", 10);
+        manager.snapshot()[0].uploadId = "cancelled-receipt";
+        manager.setEnabled(true);
+        await snapshotStarted.promise;
+        const key = manager.snapshot()[0].key;
+        await manager.cancel(key);
+        expect(manager.snapshot()[0].state).toBe("cancelled");
+
+        snapshot.resolve(receipt("cancelled-receipt"));
+        await vi.waitFor(() =>
+            expect(manager.snapshot()[0].controller).toBeUndefined(),
+        );
+        expect(manager.snapshot()[0].state).toBe("cancelled");
+        expect(manager.snapshot()[0].file).toBeUndefined();
+        expect(chunks).toBe(0);
+        expect(completions).toBe(0);
+    });
+
+    it.each(["success", "failure"])(
+        "preserves a polled completion when its delayed receipt response is a %s",
+        async (response) => {
+            const completion = deferred<Response>();
+            const completionStarted = deferred<void>();
+            const changes = vi.fn();
+            window.addEventListener("tgdrive:files-changed", changes);
+            let accepted = false;
+            vi.stubGlobal(
+                "fetch",
+                vi.fn(async (url: string, options: RequestInit = {}) => {
+                    if (url === "/api/v1/jobs")
+                        return Response.json({
+                            jobs: accepted
+                                ? [
+                                      {
+                                          id: "already-completed",
+                                          kind: "upload",
+                                          status: "completed",
+                                          phase: "completed",
+                                          current: 4,
+                                          total: 4,
+                                      },
+                                  ]
+                                : [],
+                        });
+                    if (url === "/api/v1/uploads")
+                        return receipt("already-completed");
+                    if (options.method === "HEAD") return position();
+                    if (options.method === "PATCH") return received();
+                    if (url.endsWith("/complete")) {
+                        accepted = true;
+                        completionStarted.resolve();
+                        return completion.promise;
+                    }
+                    return receipt("already-completed");
+                }),
+            );
+            const manager = managerForTest();
+            manager.add([new File(["data"], "complete.bin")], "/", 10);
+            manager.setEnabled(true);
+            await completionStarted.promise;
+            manager.refreshJobs();
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].state).toBe("completed"),
+            );
+            expect(manager.snapshot()[0].current).toBe(4);
+
+            const laterStates: string[] = [];
+            manager.subscribe(() =>
+                laterStates.push(manager.snapshot()[0].state),
+            );
+            completion.resolve(
+                response === "success"
+                    ? Response.json({ id: "already-completed" })
+                    : Response.json(
+                          { detail: "Receipt response lost at the proxy" },
+                          { status: 503 },
+                      ),
+            );
+            await vi.waitFor(() =>
+                expect(manager.snapshot()[0].controller).toBeUndefined(),
+            );
+            expect(manager.snapshot()[0]).toMatchObject({
+                jobId: "already-completed",
+                state: "completed",
+                phase: "Available in your drive",
+                current: 4,
+                total: 4,
+                file: undefined,
+            });
+            expect(laterStates.every((state) => state === "completed")).toBe(
+                true,
+            );
+            expect(changes).toHaveBeenCalledOnce();
+        },
+    );
+
+    it("tries smaller queued files and retries staging on its own timer while polling is unavailable", async () => {
+        vi.useFakeTimers();
+        const progress = deferred<Response>();
+        const attempts = new Map<string, number>();
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (url: string, options: RequestInit = {}) => {
+                if (url === "/api/v1/jobs") return progress.promise;
+                if (url === "/api/v1/uploads") {
+                    const { name } = JSON.parse(String(options.body)) as {
+                        name: string;
+                    };
+                    const attempt = (attempts.get(name) || 0) + 1;
+                    attempts.set(name, attempt);
+                    if (name !== "small.bin" && attempt === 1)
+                        return Response.json(
+                            { detail: "Staging is full" },
+                            { status: 507 },
+                        );
+                    return receipt(name, name === "small.bin" ? 4 : 8);
+                }
+                const id = url.split("/")[4];
+                const size = id === "small.bin" ? 4 : 8;
+                if (options.method === "HEAD") return position(size);
+                if (options.method === "PATCH")
+                    return received(
+                        Number(
+                            new Headers(options.headers).get("Upload-Offset"),
+                        ) + (options.body as Blob).size,
+                    );
+                if (url.endsWith("/complete")) return Response.json({ id });
+                return receipt(id, size);
+            }),
+        );
+        const manager = managerForTest();
+        manager.add(
+            [
+                ...Array.from(
+                    { length: BROWSER_RECEIVE_CONCURRENCY },
+                    (_, index) =>
+                        new File(["big data"], "full-" + index + ".bin"),
+                ),
+                new File(["data"], "small.bin"),
+            ],
+            "/",
+            10,
+        );
+        try {
+            manager.setEnabled(true);
+            await vi.advanceTimersByTimeAsync(0);
+            expect(attempts.size).toBe(BROWSER_RECEIVE_CONCURRENCY + 1);
+            expect(
+                manager.snapshot().find((item) => item.name === "small.bin")
+                    ?.jobId,
+            ).toBe("small.bin");
+            expect(
+                manager.snapshot().filter((item) => item.state === "queued"),
+            ).toHaveLength(BROWSER_RECEIVE_CONCURRENCY);
+
+            await vi.advanceTimersByTimeAsync(4999);
+            expect(
+                [...attempts.values()].filter((count) => count > 1),
+            ).toHaveLength(0);
+            await vi.advanceTimersByTimeAsync(1);
+            expect([...attempts.values()]).toEqual([
+                ...Array(BROWSER_RECEIVE_CONCURRENCY).fill(2),
+                1,
+            ]);
+            expect(
+                manager.snapshot().every((item) => Boolean(item.jobId)),
+            ).toBe(true);
+        } finally {
+            manager.setEnabled(false);
+            progress.resolve(Response.json({ jobs: [] }));
+            await vi.advanceTimersByTimeAsync(0);
+        }
+    });
+
+    it("starts with two device slots and fills a cancelled slot immediately", async () => {
+        let active = 0;
+        let maximum = 0;
+        const pending = new Map<string, () => void>();
+        const started: string[] = [];
+        const sendChunk: UploadChunkTransport = (url, options) =>
+            new Promise<Response>((resolve, reject) => {
+                const id = url.split("/")[4];
+                let settled = false;
+                const finish = (aborted = false) => {
+                    if (settled) return;
+                    settled = true;
+                    options.signal.removeEventListener("abort", abort);
+                    pending.delete(id);
+                    active--;
+                    if (aborted)
+                        reject(new DOMException("Upload paused", "AbortError"));
+                    else resolve(received());
+                };
+                const abort = () => finish(true);
+                active++;
+                maximum = Math.max(maximum, active);
+                started.push(id);
+                pending.set(id, finish);
+                options.signal.addEventListener("abort", abort, { once: true });
+                if (options.signal.aborted) abort();
+            });
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (url: string, options: RequestInit = {}) => {
+                if (url === "/api/v1/jobs") return Response.json({ jobs: [] });
+                if (url === "/api/v1/uploads") {
+                    const { name } = JSON.parse(String(options.body)) as {
+                        name: string;
+                    };
+                    return receipt(name);
+                }
+                if (url.endsWith("/cancel"))
+                    return Response.json({ state: "cancelled" });
+                if (options.method === "HEAD") return position();
+                const id = url.split("/")[4];
+                if (url.endsWith("/complete")) return Response.json({ id });
+                return receipt(id);
+            }),
+        );
+        const manager = managerForTest(sendChunk);
+        manager.add(
+            Array.from(
+                { length: BROWSER_RECEIVE_INITIAL_CONCURRENCY + 1 },
+                (_, index) => new File(["data"], "file-" + index + ".bin"),
+            ),
+            "/",
+            10,
+        );
+        manager.setEnabled(true);
+        await vi.waitFor(() =>
+            expect(active).toBe(BROWSER_RECEIVE_INITIAL_CONCURRENCY),
+        );
+        expect(started).toHaveLength(BROWSER_RECEIVE_INITIAL_CONCURRENCY);
+        await manager.cancel(manager.snapshot()[0].key);
+        await vi.waitFor(() =>
+            expect(started).toHaveLength(
+                BROWSER_RECEIVE_INITIAL_CONCURRENCY + 1,
+            ),
+        );
+        expect(active).toBe(BROWSER_RECEIVE_INITIAL_CONCURRENCY);
+        expect(maximum).toBe(BROWSER_RECEIVE_INITIAL_CONCURRENCY);
+        expect(manager.snapshot()[0].state).toBe("cancelled");
+        for (const finish of [...pending.values()]) finish();
+        await vi.waitFor(() =>
+            expect(
+                manager.snapshot().filter((item) => Boolean(item.jobId)),
+            ).toHaveLength(BROWSER_RECEIVE_INITIAL_CONCURRENCY),
+        );
+        expect(new Set(started).size).toBe(
+            BROWSER_RECEIVE_INITIAL_CONCURRENCY + 1,
+        );
+        expect(maximum).toBe(BROWSER_RECEIVE_INITIAL_CONCURRENCY);
+    });
+});
diff --git a/website/src/features/transfers/uploadTransport.test.ts b/website/src/features/transfers/uploadTransport.test.ts
new file mode 100644
index 00000000..d13659d8
--- /dev/null
+++ b/website/src/features/transfers/uploadTransport.test.ts
@@ -0,0 +1,247 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { sendUploadChunk } from "./uploadTransport";
+
+class MockXHR {
+    static latest: MockXHR;
+    upload = {
+        onprogress: null as ((event: { loaded: number }) => void) | null,
+    };
+    onload: (() => void) | null = null;
+    onerror: (() => void) | null = null;
+    onabort: (() => void) | null = null;
+    status = 204;
+    statusText = "No Content";
+    responseText = "";
+    withCredentials = false;
+    open = vi.fn();
+    setRequestHeader = vi.fn();
+    send = vi.fn();
+    abort = vi.fn(() => this.onabort?.());
+    getAllResponseHeaders = () => "Upload-Offset: 8\r\nX-Test: receipt\r\n";
+    constructor() {
+        MockXHR.latest = this;
+    }
+}
+beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal("XMLHttpRequest", MockXHR);
+});
+afterEach(() => {
+    vi.clearAllTimers();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+});
+
+describe("observed browser upload transport", () => {
+    const options = (signal: AbortSignal) => ({
+        method: "PATCH",
+        headers: {
+            "Content-Type": "application/octet-stream",
+            "Upload-Offset": "0",
+        },
+        body: new Blob(["12345678"]),
+        signal,
+    });
+    it("reports within-chunk bytes before the server receipt and keeps resume headers", async () => {
+        const progress = vi.fn();
+        const result = sendUploadChunk(
+            "/api/v1/uploads/id",
+            options(new AbortController().signal),
+            progress,
+        );
+        const xhr = MockXHR.latest;
+        expect(xhr.open).toHaveBeenCalledWith("PATCH", "/api/v1/uploads/id");
+        expect(xhr.withCredentials).toBe(true);
+        expect(xhr.setRequestHeader).toHaveBeenCalledWith("upload-offset", "0");
+        xhr.upload.onprogress?.({ loaded: 2 });
+        xhr.upload.onprogress?.({ loaded: 5 });
+        xhr.upload.onprogress?.({ loaded: 99 });
+        expect(progress.mock.calls.map(([bytes]) => bytes)).toEqual([2, 5, 8]);
+        xhr.onload?.();
+        const response = await result;
+        expect(response.status).toBe(204);
+        expect(response.headers.get("Upload-Offset")).toBe("8");
+        expect(await response.text()).toBe("");
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("cancels the request, rejects with AbortError and ignores late progress", async () => {
+        const controller = new AbortController();
+        const progress = vi.fn();
+        const result = sendUploadChunk(
+            "/upload",
+            options(controller.signal),
+            progress,
+        );
+        const rejection = expect(result).rejects.toMatchObject({
+            name: "AbortError",
+        });
+        controller.abort();
+        MockXHR.latest.upload.onprogress?.({ loaded: 8 });
+        await rejection;
+        expect(MockXHR.latest.abort).toHaveBeenCalledOnce();
+        expect(progress).not.toHaveBeenCalled();
+        expect(MockXHR.latest.send).toHaveBeenCalledOnce();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("does not send an already cancelled chunk", async () => {
+        const controller = new AbortController();
+        controller.abort();
+        await expect(
+            sendUploadChunk("/upload", options(controller.signal), vi.fn()),
+        ).rejects.toMatchObject({ name: "AbortError" });
+        expect(MockXHR.latest.send).not.toHaveBeenCalled();
+    });
+    it("returns HTTP failures for the existing safe-resume path and propagates network failure", async () => {
+        const controller = new AbortController();
+        const result = sendUploadChunk(
+            "/upload",
+            options(controller.signal),
+            vi.fn(),
+        );
+        MockXHR.latest.status = 409;
+        MockXHR.latest.statusText = "Conflict";
+        MockXHR.latest.responseText = JSON.stringify({
+            detail: "Offset changed",
+        });
+        MockXHR.latest.onload?.();
+        const response = await result;
+        expect(response.ok).toBe(false);
+        expect(await response.json()).toEqual({ detail: "Offset changed" });
+        const failure = sendUploadChunk(
+            "/upload",
+            options(controller.signal),
+            vi.fn(),
+        );
+        const rejection = expect(failure).rejects.toThrow("interrupted");
+        MockXHR.latest.onerror?.();
+        await rejection;
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("times out an idle request and ignores late events after aborting it", async () => {
+        const controller = new AbortController();
+        const progress = vi.fn();
+        const result = sendUploadChunk(
+            "/upload",
+            options(controller.signal),
+            progress,
+        );
+        const rejection = expect(result).rejects.toMatchObject({
+            name: "TimeoutError",
+        });
+        const xhr = MockXHR.latest;
+        const lateProgress = xhr.upload.onprogress;
+        const lateLoad = xhr.onload;
+        await vi.advanceTimersByTimeAsync(59999);
+        expect(xhr.abort).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(1);
+        await rejection;
+        expect(xhr.abort).toHaveBeenCalledOnce();
+        lateProgress?.({ loaded: 8 });
+        lateLoad?.();
+        controller.abort();
+        expect(xhr.abort).toHaveBeenCalledOnce();
+        expect(progress).not.toHaveBeenCalled();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("resets inactivity only when the number of sent payload bytes increases", async () => {
+        const result = sendUploadChunk(
+            "/upload",
+            options(new AbortController().signal),
+            vi.fn(),
+        );
+        const rejection = expect(result).rejects.toMatchObject({
+            name: "TimeoutError",
+        });
+        const xhr = MockXHR.latest;
+        await vi.advanceTimersByTimeAsync(50000);
+        xhr.upload.onprogress?.({ loaded: 2 });
+        await vi.advanceTimersByTimeAsync(50000);
+        expect(xhr.abort).not.toHaveBeenCalled();
+        xhr.upload.onprogress?.({ loaded: 2 });
+        xhr.upload.onprogress?.({ loaded: 1 });
+        xhr.upload.onprogress?.({ loaded: NaN });
+        await vi.advanceTimersByTimeAsync(9999);
+        expect(xhr.abort).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(1);
+        await rejection;
+        expect(xhr.abort).toHaveBeenCalledOnce();
+    });
+    it("bounds the wait for a server receipt after all payload bytes are sent", async () => {
+        const result = sendUploadChunk(
+            "/upload",
+            options(new AbortController().signal),
+            vi.fn(),
+        );
+        const rejection = expect(result).rejects.toMatchObject({
+            name: "TimeoutError",
+        });
+        const xhr = MockXHR.latest;
+        await vi.advanceTimersByTimeAsync(30000);
+        xhr.upload.onprogress?.({ loaded: 8 });
+        await vi.advanceTimersByTimeAsync(59000);
+        // Repeated full-payload notifications are not new progress.
+        xhr.upload.onprogress?.({ loaded: 99 });
+        expect(xhr.abort).not.toHaveBeenCalled();
+        await vi.advanceTimersByTimeAsync(1000);
+        await rejection;
+        expect(xhr.abort).toHaveBeenCalledOnce();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("allows a slow chunk to keep progressing for longer than a minute", async () => {
+        const progress = vi.fn();
+        const result = sendUploadChunk(
+            "/upload",
+            options(new AbortController().signal),
+            progress,
+        );
+        const xhr = MockXHR.latest;
+        for (const loaded of [2, 4, 6, 8]) {
+            await vi.advanceTimersByTimeAsync(40000);
+            xhr.upload.onprogress?.({ loaded });
+        }
+        expect(xhr.abort).not.toHaveBeenCalled();
+        xhr.onload?.();
+        expect((await result).status).toBe(204);
+        expect(progress.mock.calls.map(([bytes]) => bytes)).toEqual([
+            2, 4, 6, 8,
+        ]);
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("keeps explicit cancellation distinct from an inactivity timeout", async () => {
+        const controller = new AbortController();
+        const result = sendUploadChunk(
+            "/upload",
+            options(controller.signal),
+            vi.fn(),
+        );
+        const rejection = expect(result).rejects.toMatchObject({
+            name: "AbortError",
+        });
+        const xhr = MockXHR.latest;
+        await vi.advanceTimersByTimeAsync(59000);
+        controller.abort();
+        await rejection;
+        await vi.advanceTimersByTimeAsync(120000);
+        expect(xhr.abort).toHaveBeenCalledOnce();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+    it("cleans up the timer and ignores late progress after a successful response", async () => {
+        const controller = new AbortController();
+        const progress = vi.fn();
+        const result = sendUploadChunk(
+            "/upload",
+            options(controller.signal),
+            progress,
+        );
+        const xhr = MockXHR.latest;
+        const lateProgress = xhr.upload.onprogress;
+        xhr.onload?.();
+        await result;
+        lateProgress?.({ loaded: 8 });
+        controller.abort();
+        await vi.advanceTimersByTimeAsync(120000);
+        expect(progress).not.toHaveBeenCalled();
+        expect(xhr.abort).not.toHaveBeenCalled();
+        expect(vi.getTimerCount()).toBe(0);
+    });
+});
diff --git a/website/src/features/transfers/uploadTransport.ts b/website/src/features/transfers/uploadTransport.ts
new file mode 100644
index 00000000..09665b39
--- /dev/null
+++ b/website/src/features/transfers/uploadTransport.ts
@@ -0,0 +1,115 @@
+export type UploadChunkTransport = (
+    url: string,
+    options: RequestInit & { body: Blob; signal: AbortSignal },
+    progress: (bytes: number) => void,
+) => Promise<Response>;
+
+const UPLOAD_INACTIVITY_TIMEOUT_MS = 60000;
+
+/** Upload events measure bytes sent by this browser, not durable server receipts. */
+export const sendUploadChunk: UploadChunkTransport = (url, options, progress) =>
+    new Promise((resolve, reject) => {
+        const xhr = new XMLHttpRequest();
+        const signal = options.signal;
+        let settled = false;
+        let sentBytes = 0;
+        let inactivityTimer: ReturnType<typeof setTimeout> | undefined;
+        const cleanup = () => {
+            clearTimeout(inactivityTimer);
+            signal.removeEventListener("abort", abort);
+            xhr.upload.onprogress = null;
+            xhr.onload = null;
+            xhr.onerror = null;
+            xhr.onabort = null;
+        };
+        const fail = (error: unknown, cancelRequest = false) => {
+            if (settled) return;
+            settled = true;
+            cleanup();
+            if (cancelRequest) xhr.abort();
+            reject(error);
+        };
+        const abort = () => {
+            fail(new DOMException("Upload paused", "AbortError"), true);
+        };
+        const resetInactivityTimer = () => {
+            clearTimeout(inactivityTimer);
+            inactivityTimer = setTimeout(() => {
+                fail(
+                    new DOMException(
+                        "TGDrive stopped acknowledging this upload. Checking its position before retrying.",
+                        "TimeoutError",
+                    ),
+                    true,
+                );
+            }, UPLOAD_INACTIVITY_TIMEOUT_MS);
+        };
+        if (signal.aborted) {
+            abort();
+            return;
+        }
+        xhr.open("PATCH", url);
+        xhr.withCredentials = true;
+        new Headers(options.headers).forEach((value, name) =>
+            xhr.setRequestHeader(name, value),
+        );
+        xhr.upload.onprogress = (event) => {
+            if (settled || signal.aborted || !Number.isFinite(event.loaded))
+                return;
+            const sent = Math.max(0, Math.min(event.loaded, options.body.size));
+            if (sent > sentBytes) {
+                sentBytes = sent;
+                resetInactivityTimer();
+            }
+            progress(sent);
+        };
+        xhr.onload = () => {
+            if (settled) return;
+            try {
+                const headers = new Headers();
+                for (const line of xhr
+                    .getAllResponseHeaders()
+                    .trim()
+                    .split(/[\r\n]+/)) {
+                    const colon = line.indexOf(":");
+                    if (colon > 0)
+                        headers.append(
+                            line.slice(0, colon),
+                            line.slice(colon + 1).trim(),
+                        );
+                }
+                const response = new Response(
+                    xhr.status === 204 ? null : xhr.responseText,
+                    {
+                        status: xhr.status,
+                        statusText: xhr.statusText,
+                        headers,
+                    },
+                );
+                settled = true;
+                cleanup();
+                resolve(response);
+            } catch (error) {
+                fail(error);
+            }
+        };
+        xhr.onerror = () => {
+            fail(
+                new TypeError(
+                    "Sending this file was interrupted. Retry to resume.",
+                ),
+            );
+        };
+        xhr.onabort = () => {
+            fail(new DOMException("Upload paused", "AbortError"));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        try {
+            // A slow chunk can keep sending for minutes. Only a lack of new payload
+            // bytes (including the wait for the final server receipt) times out.
+            resetInactivityTimer();
+            xhr.send(options.body);
+        } catch (error) {
+            fail(error);
+        }
+    });
diff --git a/website/src/features/transfers/urlImports.test.ts b/website/src/features/transfers/urlImports.test.ts
new file mode 100644
index 00000000..cbd28102
--- /dev/null
+++ b/website/src/features/transfers/urlImports.test.ts
@@ -0,0 +1,153 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { api } from "../../shared/api";
+import { fromJob, TransferManager } from "./transfers";
+import type { Job } from "../../shared/types";
+
+const job: Job = {
+    id: "remote-job",
+    kind: "remote",
+    name: "movie.mov",
+    status: "running",
+    phase: "checking_source",
+    current: 0,
+    total: 0,
+};
+const requestId = "url-import-request-0001";
+function deferred<T>() {
+    let resolve!: (value: T) => void;
+    const promise = new Promise<T>((done) => {
+        resolve = done;
+    });
+    return { promise, resolve };
+}
+beforeEach(() => {
+    const data = new Map<string, string>();
+    vi.stubGlobal("localStorage", {
+        get length() {
+            return data.size;
+        },
+        key: (index: number) => [...data.keys()][index] ?? null,
+        removeItem: (key: string) => data.delete(key),
+        getItem: (key: string) => data.get(key) || null,
+        setItem: (key: string, value: string) => data.set(key, value),
+    });
+    vi.stubGlobal("window", new EventTarget());
+});
+afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+});
+
+it("publishes an immediate source-check row while the start request is pending", async () => {
+    const response = deferred<{ status: string; id: string }>();
+    vi.spyOn(api, "remote").mockReturnValue(response.promise);
+    const manager = new TransferManager();
+    manager.startRemote(
+        "https://files.example/movie.mov?token=private",
+        "/",
+        false,
+        requestId,
+    );
+    expect(manager.snapshot()).toEqual([
+        expect.objectContaining({
+            phase: "Starting URL import…",
+            stage: "checking_source",
+            remoteRequestId: requestId,
+        }),
+    ]);
+    expect(
+        localStorage.getItem("tgdrive.uploads.v2:" + manager.snapshot()[0].key),
+    ).not.toContain("token=private");
+    response.resolve({ status: "ok", id: job.id });
+    await vi.waitFor(() => expect(manager.snapshot()[0].jobId).toBe(job.id));
+});
+
+it("cancels by request identity before the job ID arrives and ignores a late start", async () => {
+    const response = deferred<{ status: string; id: string }>();
+    vi.spyOn(api, "remote").mockReturnValue(response.promise);
+    const cancel = vi.spyOn(api, "cancelRemoteRequest").mockResolvedValue({
+        id: job.id,
+        data: { ...job, status: "cancelled" },
+    });
+    const manager = new TransferManager();
+    const key = manager.startRemote(
+        "https://files.example/movie.mov",
+        "/",
+        false,
+        requestId,
+    );
+    await manager.cancel(key);
+    expect(cancel).toHaveBeenCalledWith(requestId);
+    response.resolve({ status: "ok", id: job.id });
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(manager.snapshot()[0].state).toBe("cancelled");
+});
+
+it("recovers a lost start response without posting a second import", async () => {
+    const post = vi
+        .spyOn(api, "remote")
+        .mockRejectedValue(new Error("response lost"));
+    vi.spyOn(api, "remoteRequest").mockResolvedValue({ id: job.id, data: job });
+    const manager = new TransferManager();
+    manager.startRemote(
+        "https://files.example/movie.mov",
+        "/",
+        false,
+        requestId,
+    );
+    await vi.waitFor(() => expect(manager.snapshot()[0].jobId).toBe(job.id));
+    expect(post).toHaveBeenCalledTimes(1);
+    expect(manager.snapshot()[0].state).toBe("uploading");
+});
+
+it("merges a job found by polling before the start response", async () => {
+    const response = deferred<{ status: string; id: string }>();
+    vi.spyOn(api, "remote").mockReturnValue(response.promise);
+    const manager = new TransferManager();
+    manager.startRemote(
+        "https://files.example/movie.mov",
+        "/",
+        false,
+        requestId,
+    );
+    manager.addJob(job.id, "movie.mov", "/", "remote");
+    response.resolve({ status: "ok", id: job.id });
+    await vi.waitFor(() => expect(manager.snapshot()).toHaveLength(1));
+    expect(manager.snapshot()[0].remoteRequestId).toBe(requestId);
+});
+
+it("names queue and storage states without a made-up preflight percentage", () => {
+    expect(fromJob(job, "remote").phase).toBe("Checking source…");
+    expect(fromJob({ ...job, download_mode: "queued" }, "remote").phase).toBe(
+        "Waiting for a source connection",
+    );
+    expect(
+        fromJob(
+            { ...job, phase: "downloading", download_mode: "warm" },
+            "remote",
+        ).phase,
+    ).toBe("Queued · receiving slowly");
+    expect(
+        fromJob({ ...job, download_mode: "waiting_storage" }, "remote").phase,
+    ).toBe("Waiting for temporary storage");
+});
+
+it("shows a source retry countdown and its bounded attempt count", () => {
+    vi.spyOn(Date, "now").mockReturnValue(100_000);
+    const state = fromJob(
+        {
+            ...job,
+            phase: "source_retry_wait",
+            retry_at: 104,
+            source_attempt: 2,
+            source_max_attempts: 4,
+        },
+        "remote",
+    );
+    expect(state.state).toBe("uploading");
+    expect(state.phase).toBe(
+        "Source interrupted · retrying automatically in 4s · attempt 2 of 4",
+    );
+    expect(state.phase).not.toContain("Telegram");
+});
diff --git a/website/src/main.tsx b/website/src/main.tsx
new file mode 100644
index 00000000..ce5cae41
--- /dev/null
+++ b/website/src/main.tsx
@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./app/App";
+import "@mantine/core/styles.css";
+import "./app/style.css";
+import "./shared/design-system.css";
+import DesignSystem from "./shared/DesignSystem";
+import { initializeTheme } from "./shared/theme";
+initializeTheme();
+createRoot(document.getElementById("root")!).render(
+    <StrictMode>
+        <DesignSystem>
+            <App />
+        </DesignSystem>
+    </StrictMode>,
+);
diff --git a/website/src/shared/BrandLogo.tsx b/website/src/shared/BrandLogo.tsx
new file mode 100644
index 00000000..6ffdd36d
--- /dev/null
+++ b/website/src/shared/BrandLogo.tsx
@@ -0,0 +1,41 @@
+/** One accessible name and a wordmark that follows the chosen app appearance. */
+export default function BrandLogo({
+    size = "default",
+}: {
+    size?: "compact" | "default" | "large";
+}) {
+    return (
+        <span
+            className={`brand-logo brand-logo-${size}`}
+            role="img"
+            aria-label="TGDrive"
+        >
+            <img
+                className="brand-logo-light"
+                src="/static/brand/tgdrive-logo.svg"
+                width="2010"
+                height="401"
+                alt=""
+                aria-hidden="true"
+            />
+            <img
+                className="brand-logo-dark"
+                src="/static/brand/tgdrive-logo-dark.svg"
+                width="2010"
+                height="401"
+                alt=""
+                aria-hidden="true"
+            />
+            {size === "compact" && (
+                <img
+                    className="brand-logo-icon"
+                    src="/static/brand/tgdrive-icon.svg"
+                    width="512"
+                    height="512"
+                    alt=""
+                    aria-hidden="true"
+                />
+            )}
+        </span>
+    );
+}
diff --git a/website/src/shared/DemoModeNotice.tsx b/website/src/shared/DemoModeNotice.tsx
new file mode 100644
index 00000000..eb2bc7b9
--- /dev/null
+++ b/website/src/shared/DemoModeNotice.tsx
@@ -0,0 +1,10 @@
+export default function DemoModeNotice() {
+    return (
+        <p className="settings-help demo-mode-notice" role="note">
+            Public demo: configuration and management are read-only. You can
+            inspect settings and try the drive’s file features. Settings
+            changes, connection changes, backup actions and recovery-key
+            downloads are disabled.
+        </p>
+    );
+}
diff --git a/website/src/shared/DesignSystem.tsx b/website/src/shared/DesignSystem.tsx
new file mode 100644
index 00000000..2e4d8699
--- /dev/null
+++ b/website/src/shared/DesignSystem.tsx
@@ -0,0 +1,65 @@
+import { useAppearance } from "./ThemeControl";
+import { type ReactNode } from "react";
+import {
+    MantineProvider,
+    createTheme,
+    Button,
+    Fieldset,
+    NumberInput,
+    TextInput,
+    NativeSelect,
+    Switch,
+    Paper,
+} from "@mantine/core";
+
+export const driveTheme = createTheme({
+    scale: 16 / 14,
+    primaryColor: "blue",
+    primaryShade: { light: 6, dark: 3 },
+    fontFamily: "InterVariable, Inter, ui-sans-serif, system-ui, sans-serif",
+    fontFamilyMonospace: "ui-monospace, monospace",
+    defaultRadius: "md",
+    fontSizes: { xs: "12px", sm: "13px", md: "14px", lg: "16px", xl: "20px" },
+    headings: {
+        fontFamily: "InterVariable, Inter, sans-serif",
+        fontWeight: "600",
+    },
+    respectReducedMotion: true,
+    cursorType: "pointer",
+    components: {
+        Button: Button.extend({
+            defaultProps: { size: "sm", radius: "md" },
+            styles: { label: { gap: 8 } },
+        }),
+        Fieldset: Fieldset.extend({
+            defaultProps: { radius: "lg", variant: "filled" },
+        }),
+        NumberInput: NumberInput.extend({
+            defaultProps: { size: "md", radius: "md", clampBehavior: "none" },
+        }),
+        TextInput: TextInput.extend({
+            defaultProps: { size: "md", radius: "md" },
+        }),
+        NativeSelect: NativeSelect.extend({
+            defaultProps: { size: "sm", radius: "md" },
+        }),
+        Switch: Switch.extend({ defaultProps: { size: "md", color: "teal" } }),
+        Paper: Paper.extend({
+            defaultProps: { radius: "lg", withBorder: true, shadow: undefined },
+        }),
+    },
+});
+
+export default function DesignSystem({ children }: { children: ReactNode }) {
+    const { theme } = useAppearance();
+    return (
+        <MantineProvider
+            theme={driveTheme}
+            forceColorScheme={theme}
+            withCssVariables={false}
+            withGlobalClasses={false}
+        >
+            {children}
+        </MantineProvider>
+    );
+}
diff --git a/website/src/shared/GitHubMark.tsx b/website/src/shared/GitHubMark.tsx
new file mode 100644
index 00000000..fc478202
--- /dev/null
+++ b/website/src/shared/GitHubMark.tsx
@@ -0,0 +1,14 @@
+/** Primer Octicons mark-github-16; MIT notice in public/third-party/octicons-MIT.txt. */
+export default function GitHubMark() {
+    return (
+        <svg
+            width="18"
+            height="18"
+            viewBox="0 0 16 16"
+            fill="currentColor"
+            aria-hidden="true"
+        >
+            <path d="M6.766 11.328c-2.063-.25-3.516-1.734-3.516-3.656 0-.781.281-1.625.75-2.188-.203-.515-.172-1.609.063-2.062.625-.078 1.468.25 1.968.703.594-.187 1.219-.281 1.985-.281.765 0 1.39.094 1.953.265.484-.437 1.344-.765 1.969-.687.218.422.25 1.515.046 2.047.5.593.766 1.39.766 2.203 0 1.922-1.453 3.375-3.547 3.64.531.344.89 1.094.89 1.954v1.625c0 .468.391.734.86.547C13.781 14.359 16 11.53 16 8.03 16 3.61 12.406 0 7.984 0 3.563 0 0 3.61 0 8.031a7.88 7.88 0 0 0 5.172 7.422c.422.156.828-.125.828-.547v-1.25c-.219.094-.5.156-.75.156-1.031 0-1.64-.562-2.078-1.609-.172-.422-.36-.672-.719-.719-.187-.015-.25-.093-.25-.187 0-.188.313-.328.625-.328.453 0 .844.281 1.25.86.313.452.64.655 1.031.655s.641-.14 1-.5c.266-.265.47-.5.657-.656" />
+        </svg>
+    );
+}
diff --git a/website/src/shared/ThemeControl.tsx b/website/src/shared/ThemeControl.tsx
new file mode 100644
index 00000000..949d0442
--- /dev/null
+++ b/website/src/shared/ThemeControl.tsx
@@ -0,0 +1,165 @@
+import { useEffect, useId, useRef, useState, type KeyboardEvent } from "react";
+import { Check, Moon, Sun, SunMoon } from "lucide-react";
+import {
+    applyThemePreference,
+    readThemePreference,
+    saveThemePreference,
+    THEME_STORAGE_KEY,
+    THEME_CHANGE_EVENT,
+    type ThemePreference,
+    resolveTheme,
+} from "./theme";
+
+const choices = [
+    { value: "light" as const, label: "Light", icon: Sun },
+    { value: "dark" as const, label: "Dark", icon: Moon },
+    { value: "system" as const, label: "System", icon: SunMoon },
+];
+export function useAppearance() {
+    const [preference, setPreference] =
+        useState<ThemePreference>(readThemePreference);
+    const [theme, setTheme] = useState<"light" | "dark">(() =>
+        resolveTheme(
+            readThemePreference(),
+            window.matchMedia("(prefers-color-scheme: dark)").matches,
+        ),
+    );
+    useEffect(() => {
+        const media = window.matchMedia("(prefers-color-scheme: dark)");
+        const update = () => {
+            applyThemePreference(preference);
+            setTheme(resolveTheme(preference, media.matches));
+        };
+        const changed = (event: StorageEvent) => {
+            if (event.key === THEME_STORAGE_KEY || event.key === null)
+                setPreference(readThemePreference());
+        };
+        const local = (event: Event) => {
+            const value = (event as CustomEvent<ThemePreference>).detail;
+            if (value === "light" || value === "dark" || value === "system")
+                setPreference(value);
+        };
+        update();
+        media.addEventListener("change", update);
+        window.addEventListener("storage", changed);
+        window.addEventListener(THEME_CHANGE_EVENT, local);
+        return () => {
+            media.removeEventListener("change", update);
+            window.removeEventListener("storage", changed);
+            window.removeEventListener(THEME_CHANGE_EVENT, local);
+        };
+    }, [preference]);
+    const choose = (value: ThemePreference) => {
+        saveThemePreference(value);
+        setPreference(value);
+    };
+    return { preference, choose, theme };
+}
+export default function ThemeControl() {
+    const { preference, choose } = useAppearance();
+    const [open, setOpen] = useState(false);
+    const root = useRef<HTMLDivElement>(null);
+    const trigger = useRef<HTMLButtonElement>(null);
+    const menuId = useId();
+    const choice = choices.find((item) => item.value === preference)!;
+    useEffect(() => {
+        if (!open) return;
+        root.current
+            ?.querySelector<HTMLButtonElement>(
+                '[role="menuitemradio"][aria-checked="true"]',
+            )
+            ?.focus();
+        const outside = (event: PointerEvent) => {
+            if (!root.current?.contains(event.target as Node)) setOpen(false);
+        };
+        document.addEventListener("pointerdown", outside);
+        return () => document.removeEventListener("pointerdown", outside);
+    }, [open]);
+    const select = (value: ThemePreference) => {
+        choose(value);
+        setOpen(false);
+        trigger.current?.focus();
+    };
+    const menuKey = (event: KeyboardEvent<HTMLDivElement>) => {
+        if (event.key === "Escape") {
+            event.preventDefault();
+            event.stopPropagation();
+            setOpen(false);
+            trigger.current?.focus();
+        } else if (event.key === "Tab") {
+            setOpen(false);
+            trigger.current?.focus();
+        } else if (
+            ["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)
+        ) {
+            event.preventDefault();
+            const items = [
+                ...(root.current?.querySelectorAll<HTMLButtonElement>(
+                    '[role="menuitemradio"]',
+                ) || []),
+            ];
+            const current = items.indexOf(
+                document.activeElement as HTMLButtonElement,
+            );
+            const next =
+                event.key === "Home"
+                    ? 0
+                    : event.key === "End"
+                      ? items.length - 1
+                      : (current +
+                            (event.key === "ArrowDown" ? 1 : -1) +
+                            items.length) %
+                        items.length;
+            items[next]?.focus();
+        }
+    };
+    return (
+        <div className="theme-control" ref={root}>
+            <button
+                className="icon-button theme-trigger"
+                type="button"
+                ref={trigger}
+                aria-label="Change Appearance"
+                title={"Appearance: " + choice.label}
+                aria-haspopup="menu"
+                aria-expanded={open}
+                aria-controls={open ? menuId : undefined}
+                onClick={() => setOpen(!open)}
+                onKeyDown={(event) => {
+                    if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                        event.preventDefault();
+                        setOpen(true);
+                    }
+                }}
+            >
+                <SunMoon size={20} aria-hidden="true" />
+            </button>
+            {open && (
+                <div
+                    id={menuId}
+                    className="theme-menu"
+                    role="menu"
+                    aria-label="Appearance"
+                    onKeyDown={menuKey}
+                >
+                    {choices.map((item) => (
+                        <button
+                            key={item.value}
+                            type="button"
+                            role="menuitemradio"
+                            aria-checked={preference === item.value}
+                            tabIndex={preference === item.value ? 0 : -1}
+                            onClick={() => select(item.value)}
+                        >
+                            <item.icon size={18} aria-hidden="true" />
+                            <span>{item.label}</span>
+                            {preference === item.value && (
+                                <Check size={16} aria-hidden="true" />
+                            )}
+                        </button>
+                    ))}
+                </div>
+            )}
+        </div>
+    );
+}
diff --git a/website/src/shared/api.login.test.ts b/website/src/shared/api.login.test.ts
new file mode 100644
index 00000000..44843ffa
--- /dev/null
+++ b/website/src/shared/api.login.test.ts
@@ -0,0 +1,208 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { api, ApiError, sessionExpiryHandler } from "./api";
+
+function busy(retryAfter = "1") {
+    return Response.json(
+        { detail: "Login busy; retry shortly", code: "LOGIN_BUSY" },
+        { status: 429, headers: { "Retry-After": retryAfter } },
+    );
+}
+
+describe("owner login retries", () => {
+    beforeEach(() => vi.useFakeTimers());
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.unstubAllGlobals();
+    });
+
+    it("waits for a busy password worker, then keeps the original login request", async () => {
+        const fetcher = vi
+            .fn()
+            .mockResolvedValueOnce(busy())
+            .mockResolvedValueOnce(Response.json({ status: "ok" }));
+        vi.stubGlobal("fetch", fetcher);
+
+        const login = api.login("  shared owner password  ");
+        await vi.advanceTimersByTimeAsync(999);
+        expect(fetcher).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(1);
+        await expect(login).resolves.toEqual({ status: "ok" });
+        expect(fetcher).toHaveBeenCalledTimes(2);
+        for (const [url, options] of fetcher.mock.calls) {
+            expect(url).toBe("/api/checkPassword");
+            expect(options.credentials).toBe("same-origin");
+            expect(JSON.parse(options.body)).toEqual({
+                pass: "  shared owner password  ",
+            });
+        }
+    });
+
+    it("stops after three total attempts when the worker stays busy", async () => {
+        const fetcher = vi.fn().mockImplementation(async () => busy());
+        vi.stubGlobal("fetch", fetcher);
+        const result = api
+            .login("shared owner password")
+            .catch((error) => error);
+
+        await vi.advanceTimersByTimeAsync(2000);
+
+        expect(await result).toMatchObject({ status: 429, code: "LOGIN_BUSY" });
+        expect(fetcher).toHaveBeenCalledTimes(3);
+        await vi.advanceTimersByTimeAsync(10000);
+        expect(fetcher).toHaveBeenCalledTimes(3);
+    });
+
+    it.each([
+        ["2", 2000],
+        ["300", 2000],
+        ["0", 1000],
+        ["invalid", 1000],
+    ])("bounds Retry-After %s to a short wait", async (retryAfter, delay) => {
+        const fetcher = vi
+            .fn()
+            .mockResolvedValueOnce(busy(String(retryAfter)))
+            .mockResolvedValueOnce(Response.json({ status: "ok" }));
+        vi.stubGlobal("fetch", fetcher);
+        const login = api.login("shared owner password");
+
+        await vi.advanceTimersByTimeAsync(Number(delay) - 1);
+        expect(fetcher).toHaveBeenCalledTimes(1);
+        await vi.advanceTimersByTimeAsync(1);
+        await expect(login).resolves.toEqual({ status: "ok" });
+        expect(fetcher).toHaveBeenCalledTimes(2);
+    });
+
+    it.each([
+        [401, "INVALID_PASSWORD"],
+        [429, "LOGIN_RATE_LIMITED"],
+        [429, undefined],
+        [500, "LOGIN_BUSY"],
+    ])("does not retry status %s with code %s", async (status, code) => {
+        const fetcher = vi
+            .fn()
+            .mockResolvedValue(
+                Response.json({ detail: "Login denied", code }, { status }),
+            );
+        vi.stubGlobal("fetch", fetcher);
+
+        await expect(api.login("shared owner password")).rejects.toBeInstanceOf(
+            ApiError,
+        );
+        await vi.advanceTimersByTimeAsync(10000);
+        expect(fetcher).toHaveBeenCalledTimes(1);
+    });
+
+    it("stops retrying when a busy response is followed by an incorrect password", async () => {
+        const fetcher = vi
+            .fn()
+            .mockResolvedValueOnce(busy())
+            .mockResolvedValueOnce(
+                Response.json({ detail: "Invalid password" }, { status: 401 }),
+            );
+        vi.stubGlobal("fetch", fetcher);
+        const result = api
+            .login("incorrect owner password")
+            .catch((error) => error);
+
+        await vi.advanceTimersByTimeAsync(1000);
+
+        expect(await result).toMatchObject({
+            status: 401,
+            message: "Invalid password",
+        });
+        await vi.advanceTimersByTimeAsync(10000);
+        expect(fetcher).toHaveBeenCalledTimes(2);
+    });
+
+    it("does not resubmit credentials after a network failure", async () => {
+        const fetcher = vi
+            .fn()
+            .mockRejectedValue(new TypeError("network unavailable"));
+        vi.stubGlobal("fetch", fetcher);
+
+        await expect(api.login("shared owner password")).rejects.toMatchObject({
+            status: 0,
+        });
+        await vi.advanceTimersByTimeAsync(10000);
+        expect(fetcher).toHaveBeenCalledTimes(1);
+    });
+});
+
+describe("session expiry response ordering", () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    it("ignores an old request's 401 after logout and a successful new login, but expires current requests", async () => {
+        const expired = vi.fn();
+        const events = new EventTarget();
+        events.addEventListener("tgdrive:auth-required", expired);
+        vi.stubGlobal("window", events);
+        let finish!: (response: Response) => void;
+        vi.stubGlobal(
+            "fetch",
+            vi.fn((url: string) =>
+                url === "/api/v1/jobs"
+                    ? new Promise<Response>((resolve) => {
+                          finish = resolve;
+                      })
+                    : Promise.resolve(Response.json({ status: "ok" })),
+            ),
+        );
+        const pending = api.jobs().catch((error) => error);
+        const oldPreview = sessionExpiryHandler();
+        await api.logout();
+        await api.login("owner");
+        finish(
+            Response.json({ detail: "Old session expired" }, { status: 401 }),
+        );
+        expect(await pending).toMatchObject({ status: 401 });
+        oldPreview(401);
+        expect(expired).not.toHaveBeenCalled();
+
+        const duplicate = sessionExpiryHandler();
+        const current = api.jobs().catch((error) => error);
+        finish(
+            Response.json(
+                { detail: "Current session expired" },
+                { status: 401 },
+            ),
+        );
+        expect(await current).toMatchObject({ status: 401 });
+        duplicate(401);
+        expect(expired).toHaveBeenCalledOnce();
+        sessionExpiryHandler()(401);
+        expect(expired).toHaveBeenCalledTimes(2);
+    });
+
+    it("keeps current expiry guards valid when a login is rejected", async () => {
+        const events = new EventTarget();
+        const expired = vi.fn();
+        events.addEventListener("tgdrive:auth-required", expired);
+        vi.stubGlobal("window", events);
+        const current = sessionExpiryHandler();
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json({ detail: "Invalid password" }, { status: 401 }),
+            ),
+        );
+        await expect(api.login("incorrect")).rejects.toMatchObject({
+            status: 401,
+        });
+        expect(expired).not.toHaveBeenCalled();
+        current(401);
+        expect(expired).toHaveBeenCalledOnce();
+    });
+
+    it("expires a current session even if its 401 response body is unreadable", async () => {
+        const events = new EventTarget();
+        const expired = vi.fn();
+        events.addEventListener("tgdrive:auth-required", expired);
+        vi.stubGlobal("window", events);
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => new Response("Unauthorized", { status: 401 })),
+        );
+        await expect(api.jobs()).rejects.toMatchObject({ status: 401 });
+        expect(expired).toHaveBeenCalledOnce();
+    });
+});
diff --git a/website/src/shared/api.test.ts b/website/src/shared/api.test.ts
new file mode 100644
index 00000000..60a84b0f
--- /dev/null
+++ b/website/src/shared/api.test.ts
@@ -0,0 +1,238 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { api, ApiError, request } from "./api";
+
+afterEach(() => {
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+});
+
+describe("request transport failures", () => {
+    it.each(["headers", "body"])(
+        "still times out stalled %s when a caller supplies a lifecycle signal",
+        async (stage) => {
+            const nativeTimeout = AbortSignal.timeout.bind(AbortSignal);
+            const deadline = vi
+                .spyOn(AbortSignal, "timeout")
+                .mockImplementation((milliseconds) => {
+                    expect(milliseconds).toBe(60000);
+                    return nativeTimeout(10);
+                });
+            const controller = new AbortController();
+            const fetcher = vi.fn((_url: string, options: RequestInit) => {
+                const signal = options.signal!;
+                const stalled = new Promise<never>((_resolve, reject) => {
+                    signal.addEventListener(
+                        "abort",
+                        () => reject(signal.reason),
+                        { once: true },
+                    );
+                });
+                if (stage === "headers") return stalled;
+                const response = new Response();
+                vi.spyOn(response, "text").mockReturnValue(stalled);
+                return Promise.resolve(response);
+            });
+            vi.stubGlobal("fetch", fetcher);
+
+            await expect(
+                api.directory("/", "", controller.signal),
+            ).rejects.toMatchObject({ status: 408, code: "REQUEST_TIMEOUT" });
+            expect(deadline).toHaveBeenCalledOnce();
+            expect(controller.signal.aborted).toBe(false);
+            expect(fetcher).toHaveBeenCalledOnce();
+        },
+    );
+
+    it("keeps explicit caller cancellation distinct from the request deadline", async () => {
+        const controller = new AbortController();
+        const cancelled = new DOMException("Leaving this page", "AbortError");
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(
+                (_url: string, options: RequestInit) =>
+                    new Promise<Response>((_resolve, reject) => {
+                        options.signal!.addEventListener(
+                            "abort",
+                            () => reject(options.signal!.reason),
+                            { once: true },
+                        );
+                    }),
+            ),
+        );
+        const pending = request("/api/v1/settings", undefined, {
+            signal: controller.signal,
+        });
+        controller.abort(cancelled);
+        await expect(pending).rejects.toBe(cancelled);
+    });
+
+    it("preserves the longer deadline for connection saves and Premium verification", async () => {
+        const nativeTimeout = AbortSignal.timeout.bind(AbortSignal);
+        const deadline = vi.spyOn(AbortSignal, "timeout").mockImplementation(
+            // Scale time without replacing the native abort signal or cancellation.
+            (milliseconds) => nativeTimeout(milliseconds === 120000 ? 1000 : 5),
+        );
+        const fetcher = vi.fn(
+            (_url: string, options: RequestInit) =>
+                new Promise<Response>((resolve, reject) => {
+                    expect(options).not.toHaveProperty("timeoutMs");
+                    const signal = options.signal!;
+                    const aborted = () => {
+                        clearTimeout(timer);
+                        reject(signal.reason);
+                    };
+                    const timer = setTimeout(() => {
+                        signal.removeEventListener("abort", aborted);
+                        resolve(Response.json({ status: "ok" }));
+                    }, 25);
+                    signal.addEventListener("abort", aborted, { once: true });
+                }),
+        );
+        vi.stubGlobal("fetch", fetcher);
+        await expect(
+            Promise.all([
+                api.saveSettings({ expected_revision: 1 }),
+                api.verifyPremiumLogin("challenge", { code: "12345" }),
+            ]),
+        ).resolves.toEqual([{ status: "ok" }, { status: "ok" }]);
+        expect(
+            deadline.mock.calls.map(([milliseconds]) => milliseconds),
+        ).toEqual([120000, 120000]);
+    });
+
+    it.each(["headers", "body"])(
+        "reports a timeout while reading %s as a retryable request failure",
+        async (stage) => {
+            const timeout = new DOMException("Timed out", "TimeoutError");
+            const fetcher = vi.fn(async () => {
+                if (stage === "headers") throw timeout;
+                return {
+                    text: async () => {
+                        throw timeout;
+                    },
+                };
+            });
+            vi.stubGlobal("fetch", fetcher);
+
+            await expect(
+                request("/api/v1/uploads/known-receipt"),
+            ).rejects.toMatchObject({
+                name: "ApiError",
+                status: 408,
+                code: "REQUEST_TIMEOUT",
+            });
+            expect(fetcher).toHaveBeenCalledOnce();
+        },
+    );
+
+    it("normalizes a connection lost after response headers", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => ({
+                text: async () => {
+                    throw new TypeError("Connection lost");
+                },
+            })),
+        );
+
+        await expect(
+            request("/api/v1/uploads/known-receipt"),
+        ).rejects.toMatchObject({
+            name: "ApiError",
+            status: 0,
+        });
+    });
+
+    it.each(["headers", "body"])(
+        "preserves explicit cancellation while reading %s",
+        async (stage) => {
+            const cancelled = new DOMException("Cancelled", "AbortError");
+            vi.stubGlobal(
+                "fetch",
+                vi.fn(async () => {
+                    if (stage === "headers") throw cancelled;
+                    return {
+                        text: async () => {
+                            throw cancelled;
+                        },
+                    };
+                }),
+            );
+
+            await expect(request("/api/v1/uploads/known-receipt")).rejects.toBe(
+                cancelled,
+            );
+        },
+    );
+
+    it("keeps an HTTP failure status when a proxy sends unreadable JSON", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () => new Response("Bad gateway", { status: 502 })),
+        );
+
+        await expect(
+            request("/api/v1/uploads/known-receipt"),
+        ).rejects.toMatchObject({
+            name: "ApiError",
+            status: 502,
+        });
+    });
+
+    it("does not replay receipt creation when its response is lost", async () => {
+        const fetcher = vi.fn(async () => {
+            throw new TypeError("Connection lost");
+        });
+        vi.stubGlobal("fetch", fetcher);
+
+        await expect(
+            api.createUpload("file.txt", "/", 4),
+        ).rejects.toBeInstanceOf(ApiError);
+        expect(fetcher).toHaveBeenCalledOnce();
+    });
+});
+
+describe("transfer task API", () => {
+    it("sends a bounded task page and unfinished folder exclusions", async () => {
+        const fetcher = vi.fn(async () => Response.json({ jobs: [] }));
+        vi.stubGlobal("fetch", fetcher);
+        await api.transferTaskHistory("finished", 3, undefined, "photos", {
+            exclude_folders: ["folder-selection-id"],
+            offset: 39,
+        });
+        const [url, options] = fetcher.mock.calls[0] as unknown as [
+            string,
+            RequestInit,
+        ];
+        expect(url).toBe("/api/v1/transfers/history/tasks");
+        expect(options.method).toBe("POST");
+        expect(JSON.parse(options.body as string)).toEqual({
+            status: "finished",
+            page: 3,
+            limit: 20,
+            q: "photos",
+            exclude_folders: ["folder-selection-id"],
+            offset: 39,
+        });
+    });
+
+    it("marks only explicit folder receipts with durable group metadata", async () => {
+        const fetcher = vi.fn(async () => Response.json({ id: "receipt" }));
+        vi.stubGlobal("fetch", fetcher);
+        const folder = {
+            id: "folder-selection-id",
+            name: "Folder",
+            root_path: "/root",
+            created_at: 1,
+        };
+        await api.createUpload("one.bin", "/root", 4, folder);
+        await api.createUpload("two.bin", "/root", 4);
+        const calls = fetcher.mock.calls as unknown as [string, RequestInit][];
+        expect(JSON.parse(calls[0][1].body as string).folder_upload).toEqual(
+            folder,
+        );
+        expect(JSON.parse(calls[1][1].body as string)).not.toHaveProperty(
+            "folder_upload",
+        );
+    });
+});
diff --git a/website/src/shared/api.ts b/website/src/shared/api.ts
new file mode 100644
index 00000000..a7d6bf65
--- /dev/null
+++ b/website/src/shared/api.ts
@@ -0,0 +1,427 @@
+import type {
+    Directory,
+    FolderTreeRequest,
+    FolderTreeResponse,
+    Job,
+    ManagementSettings,
+    ManagementUpdate,
+    PublicConfig,
+    PremiumChallenge,
+    PremiumVerification,
+    ServerStatus,
+    SearchResults,
+    Share,
+    UploadSnapshot,
+    TransferTaskHistoryPage,
+    FolderUploadMetadata,
+    TransferLocation,
+} from "./types";
+export class ApiError extends Error {
+    constructor(
+        message: string,
+        public status = 0,
+        public code = "",
+        public retryAfter = 0,
+    ) {
+        super(message);
+        this.name = "ApiError";
+    }
+}
+export function notifyDemoFilesReadOnly(code: unknown) {
+    if (code === "DEMO_FILES_READ_ONLY")
+        window.dispatchEvent(new Event("tgdrive:demo-files-read-only"));
+}
+let sessionGeneration = 0;
+/** Capture before sending: an old response must not expire a newer login. */
+export function sessionExpiryHandler() {
+    const generation = sessionGeneration;
+    return (status: number) => {
+        if (status !== 401 || generation !== sessionGeneration) return;
+        sessionGeneration++;
+        window.dispatchEvent(new Event("tgdrive:auth-required"));
+    };
+}
+export async function request<T>(
+    url: string,
+    body?: unknown,
+    options: RequestInit & { timeoutMs?: number } = {},
+): Promise<T> {
+    const expireSession = sessionExpiryHandler();
+    const { timeoutMs = 60000, ...fetchOptions } = options;
+    const headers = new Headers(fetchOptions.headers);
+    headers.set("Accept", "application/json");
+    if (body !== undefined) headers.set("Content-Type", "application/json");
+    let response: Response;
+    let text: string;
+    try {
+        response = await fetch(url, {
+            credentials: "same-origin",
+            ...fetchOptions,
+            headers,
+            method:
+                fetchOptions.method ?? (body === undefined ? "GET" : "POST"),
+            body: body === undefined ? fetchOptions.body : JSON.stringify(body),
+            signal: fetchOptions.signal
+                ? AbortSignal.any([
+                      fetchOptions.signal,
+                      AbortSignal.timeout(timeoutMs),
+                  ])
+                : AbortSignal.timeout(timeoutMs),
+        });
+        if (url !== "/api/checkPassword") expireSession(response.status);
+        text = await response.text();
+    } catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError")
+            throw error;
+        if (error instanceof DOMException && error.name === "TimeoutError")
+            throw new ApiError(
+                "TGDrive took too long to respond. Try again.",
+                408,
+                "REQUEST_TIMEOUT",
+            );
+        throw new ApiError(
+            "Could not reach TGDrive. Check your connection and try again.",
+        );
+    }
+    let data: Record<string, unknown> = {};
+    try {
+        if (text) data = JSON.parse(text);
+    } catch {
+        throw new ApiError(
+            "The server returned an unreadable response. Try Again.",
+            response.status,
+        );
+    }
+    if (
+        !response.ok ||
+        (typeof data.status === "string" &&
+            data.status !== "ok" &&
+            data.status !== "cancelled" &&
+            !("phase" in data))
+    ) {
+        const detail =
+            typeof data.detail === "string"
+                ? data.detail
+                : typeof data.error === "string"
+                  ? data.error
+                  : typeof data.status === "string"
+                    ? data.status
+                    : "The request could not be completed.";
+        if (data.code === "SETTINGS_RESTART_REQUIRED")
+            window.dispatchEvent(new Event("tgdrive:restart-required"));
+        notifyDemoFilesReadOnly(data.code);
+        throw new ApiError(
+            detail,
+            response.status,
+            typeof data.code === "string" ? data.code : detail,
+            Math.max(0, Number(response.headers.get("Retry-After")) || 0),
+        );
+    }
+    return data as T;
+}
+export interface UploadPreferences {
+    uploads_per_bot: number;
+    connected_bots: number;
+    bot_upload_slots: number;
+}
+export interface BotUploadSettings {
+    folder_path: string | null;
+    resolved_path: string | null;
+    folder_label: string;
+    available: boolean;
+    enabled: boolean;
+    settings_url: string | null;
+}
+export interface TransferHistoryContext {
+    exclude_folders?: string[];
+    offset?: number;
+}
+export const api = {
+    botUploadSettings: (signal?: AbortSignal) =>
+        request<BotUploadSettings>("/api/v1/settings/bot-mode", undefined, {
+            signal,
+        }),
+    saveBotUploadSettings: (folder_path: string | null) =>
+        request<BotUploadSettings>(
+            "/api/v1/settings/bot-mode",
+            { folder_path, site_url: window.location.origin },
+            { method: "PATCH" },
+        ),
+    starred: (q = "", signal?: AbortSignal) =>
+        request<{ data: Directory; auth_home_path?: string }>(
+            "/api/v1/starred?" + new URLSearchParams({ q }),
+            undefined,
+            { signal },
+        ),
+    star: (path: string, starred: boolean) =>
+        request("/api/v1/starred", { path, starred }, { method: "PATCH" }),
+
+    transferLocation: (
+        transfer_id: string | undefined,
+        destination: string,
+        completed: boolean,
+    ) =>
+        request<TransferLocation>("/api/v1/transfers/location", {
+            transfer_id,
+            destination,
+            completed,
+        }),
+    uploadPreferences: (signal?: AbortSignal) =>
+        request<UploadPreferences>("/api/v1/settings/uploads", undefined, {
+            signal,
+        }),
+    saveUploadPreferences: (uploads_per_bot: number) =>
+        request<UploadPreferences>(
+            "/api/v1/settings/uploads",
+            { uploads_per_bot },
+            { method: "PATCH" },
+        ),
+    config: () =>
+        request<PublicConfig>("/api/config", undefined, { cache: "no-store" }),
+    session: () =>
+        request<{
+            authenticated: boolean;
+            demo_read_only?: boolean;
+            demo_admin?: boolean;
+        }>("/api/v1/session", undefined, { cache: "no-store" }),
+    login: async (password: string) => {
+        for (let attempt = 1; ; attempt++) {
+            try {
+                const result = await request("/api/checkPassword", {
+                    pass: password,
+                });
+                sessionGeneration++;
+                return result;
+            } catch (error) {
+                if (
+                    !(error instanceof ApiError) ||
+                    error.status !== 429 ||
+                    error.code !== "LOGIN_BUSY" ||
+                    attempt >= 3
+                )
+                    throw error;
+                const delay = Math.min(2, Math.max(1, error.retryAfter));
+                await new Promise<void>((resolve) =>
+                    setTimeout(resolve, delay * 1000),
+                );
+            }
+        }
+    },
+    logout: async () => {
+        const result = await request("/api/logout", {});
+        sessionGeneration++;
+        return result;
+    },
+    directory: (path: string, auth = "", signal?: AbortSignal) =>
+        request<{ data: Directory; auth_home_path?: string }>(
+            "/api/getDirectory",
+            { path, auth: auth || null },
+            { signal },
+        ),
+    trash: (query = "", signal?: AbortSignal) =>
+        request<{ data: Directory; auth_home_path?: string }>(
+            "/api/v1/trash?" + new URLSearchParams({ q: query }),
+            undefined,
+            { signal },
+        ),
+    search: (
+        query: string,
+        offset = 0,
+        sort: "name" | "date" | "size" = "name",
+        signal?: AbortSignal,
+        order?: "asc" | "desc",
+    ) => {
+        const params = new URLSearchParams({
+            q: query,
+            offset: String(offset),
+            limit: "100",
+            sort,
+            ...(order ? { order } : {}),
+        });
+        return request<SearchResults>("/api/v1/search?" + params, undefined, {
+            signal,
+        });
+    },
+    folder: (path: string, name: string) =>
+        request("/api/createNewFolder", { path, name }),
+    prepareFolderTree: (payload: FolderTreeRequest, signal?: AbortSignal) =>
+        request<FolderTreeResponse>("/api/v1/folders/tree", payload, {
+            signal,
+        }),
+    rename: (path: string, name: string) =>
+        request("/api/renameFileFolder", { path, name }),
+    bulk: (
+        paths: string[],
+        action: "trash" | "restore" | "delete",
+        allow_public_exposure = false,
+    ) =>
+        request<{
+            results?: {
+                path: string;
+                id?: string;
+                error?: string;
+                status?: string;
+            }[];
+        }>("/api/v1/nodes/bulk", { paths, action, allow_public_exposure }),
+    move: (
+        paths: string[],
+        destination: string,
+        conflict: string,
+        allow_public_exposure = false,
+    ) =>
+        request<{
+            results?: {
+                path: string;
+                id?: string;
+                error?: string;
+                status?: string;
+            }[];
+        }>("/api/v1/nodes/move", {
+            paths,
+            destination,
+            conflict,
+            allow_public_exposure,
+        }),
+    shares: () => request<{ shares: Share[] }>("/api/v1/shares"),
+    shareLink: (path: string, share_id?: string) =>
+        request<{
+            auth: string;
+            path: string;
+            type: "file" | "folder";
+            node_id: string;
+        }>("/api/v1/shares/link", { path, share_id }),
+    share: (
+        path: string,
+        expires_in_days: number | null,
+        label = "",
+        expires_at?: string,
+    ) =>
+        request<{ auth: string; path: string; expires_at: string | null }>(
+            "/api/v1/shares",
+            { path, expires_in_days, label, expires_at },
+        ),
+    revoke: (path: string, share_id?: string) =>
+        request("/api/v1/shares", { path, share_id }, { method: "DELETE" }),
+    status: (signal?: AbortSignal) =>
+        request<ServerStatus>("/api/v1/status", undefined, {
+            signal,
+        }),
+    backup: () => request("/api/v1/backup", {}),
+    refreshConnections: (signal?: AbortSignal) =>
+        request<ManagementSettings>("/api/v1/settings/refresh", {}, { signal }),
+    settings: (signal?: AbortSignal) =>
+        request<ManagementSettings>("/api/v1/settings", undefined, {
+            signal,
+        }),
+    saveSettings: (value: ManagementUpdate) =>
+        request<ManagementSettings>("/api/v1/settings", value, {
+            method: "PATCH",
+            timeoutMs: 120000,
+        }),
+    startPremiumLogin: (
+        expected_revision: number,
+        phone: string,
+        label: string,
+    ) =>
+        request<PremiumChallenge>("/api/v1/settings/premium-login/start", {
+            expected_revision,
+            phone,
+            label,
+        }),
+    verifyPremiumLogin: (
+        challenge_id: string,
+        value: { code?: string; password?: string },
+    ) =>
+        request<PremiumVerification>(
+            "/api/v1/settings/premium-login/verify",
+            {
+                challenge_id,
+                ...value,
+            },
+            { timeoutMs: 120000 },
+        ),
+    cancelPremiumLogin: (challenge_id: string) =>
+        request(
+            "/api/v1/settings/premium-login/" +
+                encodeURIComponent(challenge_id),
+            undefined,
+            { method: "DELETE" },
+        ),
+    jobs: () =>
+        request<{ jobs: Job[] }>("/api/v1/jobs", undefined, {
+            cache: "no-store",
+        }),
+    clearTransferHistory: (excludeFolders: string[] = []) =>
+        request<{ cleared: number }>(
+            "/api/v1/transfers/history",
+            { exclude_folders: excludeFolders },
+            { method: "DELETE" },
+        ),
+    transferTaskHistory: (
+        status: string,
+        page: number,
+        signal?: AbortSignal,
+        search = "",
+        context: TransferHistoryContext = {},
+    ) => {
+        return request<TransferTaskHistoryPage>(
+            "/api/v1/transfers/history/tasks",
+            { status, page, limit: 20, q: search, ...context },
+            {
+                signal,
+            },
+        );
+    },
+    cancelJob: async (id: string) => ({
+        data: await request<Job>(
+            "/api/v1/jobs/" + encodeURIComponent(id) + "/cancel",
+            {},
+        ),
+    }),
+    createUpload: (
+        name: string,
+        parent_id: string,
+        total_size: number,
+        folderUpload?: FolderUploadMetadata,
+    ) =>
+        request<UploadSnapshot>("/api/v1/uploads", {
+            name,
+            parent_id,
+            total_size,
+            ...(folderUpload ? { folder_upload: folderUpload } : {}),
+        }),
+    upload: (id: string) =>
+        request<UploadSnapshot>("/api/v1/uploads/" + encodeURIComponent(id)),
+    cancelUpload: (id: string) =>
+        request("/api/v1/uploads/" + encodeURIComponent(id) + "/cancel", {}),
+    completeUpload: (id: string) =>
+        request<{ id: string }>(
+            "/api/v1/uploads/" + encodeURIComponent(id) + "/complete",
+            {},
+        ),
+    remote: (
+        url: string,
+        path: string,
+        singleThreaded: boolean,
+        client_request_id: string,
+    ) =>
+        request<{ id: string }>("/api/startFileDownloadFromUrl", {
+            url,
+            path,
+            singleThreaded,
+            client_request_id,
+        }),
+    remoteRequest: (client_request_id: string) =>
+        request<{ id: string; data: Job }>("/api/getTransferByRequest", {
+            client_request_id,
+        }),
+    cancelRemoteRequest: (client_request_id: string) =>
+        request<{ id: string; data: Job }>("/api/cancelUpload", {
+            client_request_id,
+        }),
+};
+export function errorMessage(error: unknown): string {
+    return error instanceof Error
+        ? error.message
+        : "Something went wrong. Please try again.";
+}
diff --git a/website/src/shared/components.tsx b/website/src/shared/components.tsx
new file mode 100644
index 00000000..f241333f
--- /dev/null
+++ b/website/src/shared/components.tsx
@@ -0,0 +1,278 @@
+import { Alert } from "@mantine/core";
+import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import {
+    X,
+    LoaderCircle,
+    Folder,
+    File,
+    FileText,
+    Film,
+    Image,
+    Music,
+    FileArchive,
+    FileSpreadsheet,
+    Presentation,
+    BookOpen,
+    AlertCircle,
+} from "lucide-react";
+export function Spinner() {
+    return <LoaderCircle className="spinner" aria-hidden="true" size={18} />;
+}
+
+const FILE_ICON_GROUPS = [
+    { icon: Film, extensions: ["mp4", "mkv", "webm", "mov", "avi"] },
+    {
+        icon: Image,
+        extensions: [
+            "png",
+            "jpg",
+            "jpeg",
+            "gif",
+            "webp",
+            "avif",
+            "heic",
+            "svg",
+        ],
+    },
+    { icon: Music, extensions: ["mp3", "wav", "ogg", "flac", "m4a"] },
+    { icon: FileArchive, extensions: ["zip", "gz", "7z", "rar", "tar"] },
+    { icon: FileSpreadsheet, extensions: ["csv", "xlsx", "xls", "ods"] },
+    { icon: Presentation, extensions: ["ppt", "pptx", "odp"] },
+    { icon: BookOpen, extensions: ["epub", "cbz", "cbr"] },
+    { icon: FileText, extensions: ["txt", "md", "pdf", "doc", "docx"] },
+];
+
+function iconForExtension(extension: string) {
+    for (const group of FILE_ICON_GROUPS) {
+        if (group.extensions.includes(extension)) return group.icon;
+    }
+    return File;
+}
+
+export function FileIcon({
+    name,
+    folder = false,
+}: {
+    name: string;
+    folder?: boolean;
+}) {
+    const extension = name.split(".").at(-1)?.toLowerCase() || "";
+    const Icon = folder ? Folder : iconForExtension(extension);
+    return (
+        <span
+            className={"file-icon " + (folder ? "folder-icon" : "")}
+            data-extension={extension}
+        >
+            <Icon size={22} aria-hidden="true" />
+        </span>
+    );
+}
+export function Modal({
+    title,
+    children,
+    onClose,
+    wide = false,
+    initialFocus,
+}: {
+    title: string;
+    children: ReactNode;
+    onClose: () => void;
+    wide?: boolean;
+    initialFocus?: string;
+}) {
+    const dialog = useRef<HTMLDialogElement>(null);
+    const titleId = useId();
+    useEffect(() => {
+        const node = dialog.current!;
+        const trigger = document.activeElement as HTMLElement | null;
+        node.showModal();
+        const cycleFocus = (event: KeyboardEvent) => {
+            if (event.key !== "Tab") return;
+            const controls = Array.from(
+                node.querySelectorAll<HTMLElement>(
+                    "a[href], button, input, select, textarea, summary, [tabindex]",
+                ),
+            ).filter(
+                (node) =>
+                    node.tabIndex >= 0 &&
+                    !node.matches(":disabled") &&
+                    !node.closest("[inert]") &&
+                    node.getClientRects().length > 0 &&
+                    getComputedStyle(node).visibility !== "hidden",
+            );
+            const first = controls[0];
+            const last = controls.at(-1);
+            if (!first || !last) {
+                event.preventDefault();
+                return;
+            }
+            if (event.shiftKey && document.activeElement === first) {
+                event.preventDefault();
+                last.focus();
+            } else if (!event.shiftKey && document.activeElement === last) {
+                event.preventDefault();
+                first.focus();
+            }
+        };
+        // Use a DOM listener so notifications portaled into this dialog participate.
+        node.addEventListener("keydown", cycleFocus);
+        node.querySelector<HTMLElement>(
+            initialFocus || "input:not([type=checkbox]), select, textarea",
+        )?.focus();
+        return () => {
+            node.removeEventListener("keydown", cycleFocus);
+            node.close();
+            if (trigger?.isConnected && trigger !== document.body)
+                trigger.focus();
+            else document.getElementById("main-content")?.focus();
+        };
+    }, [initialFocus]);
+    return (
+        <dialog
+            ref={dialog}
+            className={"modal " + (wide ? "modal-wide" : "")}
+            onCancel={(event) => {
+                event.preventDefault();
+                onClose();
+            }}
+            onClick={(event) => {
+                if (event.target === event.currentTarget) {
+                    const rect = event.currentTarget.getBoundingClientRect();
+                    if (
+                        event.clientX < rect.left ||
+                        event.clientX > rect.right ||
+                        event.clientY < rect.top ||
+                        event.clientY > rect.bottom
+                    )
+                        onClose();
+                }
+            }}
+            aria-labelledby={titleId}
+        >
+            <header className="modal-header">
+                <h2 id={titleId}>{title}</h2>
+                <button
+                    className="icon-button"
+                    type="button"
+                    aria-label="Close Dialog"
+                    onClick={onClose}
+                >
+                    <X size={20} />
+                </button>
+            </header>
+            {children}
+        </dialog>
+    );
+}
+export function ErrorNotice({ message }: { message: string }) {
+    return message ? (
+        <Alert
+            className="error-notice"
+            color="red"
+            variant="light"
+            icon={<AlertCircle size={18} aria-hidden="true" />}
+            role="alert"
+        >
+            {message}
+        </Alert>
+    ) : null;
+}
+
+/** Native modal dialogs live above CSS z-index. Keep notices in their focus tree
+ * and raise a manual popover without moving the user's keyboard focus. */
+export function ToastNotice({
+    toast,
+    close,
+}: {
+    toast: { message: string; error: boolean };
+    close: () => void;
+}) {
+    const [container, setContainer] = useState<HTMLElement>(document.body);
+    const notice = useRef<HTMLDivElement>(null);
+    const returnFocus = useRef<HTMLElement | null>(null);
+    useEffect(() => {
+        if (!notice.current?.contains(document.activeElement))
+            returnFocus.current = document.activeElement as HTMLElement | null;
+    }, [toast]);
+    const closeNotice = useRef(close);
+    closeNotice.current = close;
+    const [hovered, setHovered] = useState(false);
+    const [focused, setFocused] = useState(false);
+    useEffect(() => {
+        if (toast.error || hovered || focused) return;
+        const timer = window.setTimeout(() => closeNotice.current(), 6000);
+        return () => window.clearTimeout(timer);
+    }, [toast, hovered, focused]);
+    useEffect(() => {
+        const modal = () => {
+            const dialogs =
+                document.querySelectorAll<HTMLDialogElement>("dialog[open]");
+            return dialogs[dialogs.length - 1] || document.body;
+        };
+        const anchor = modal();
+        setContainer(anchor);
+        const observer = new MutationObserver(() => {
+            // A notice belongs to the action that created it. Do not reannounce old
+            // feedback inside a different task's newly opened modal.
+            if (modal() !== anchor || !anchor.isConnected)
+                closeNotice.current();
+        });
+        observer.observe(document.body, {
+            subtree: true,
+            childList: true,
+            attributes: true,
+            attributeFilter: ["open"],
+        });
+        return () => observer.disconnect();
+    }, [toast.message, toast.error]);
+    useEffect(() => {
+        const node = notice.current;
+        // Portals move into the current modal before entering the top layer.
+        if (!node?.isConnected || typeof node.showPopover !== "function")
+            return;
+        node.showPopover();
+        return () => {
+            if (node.isConnected && node.matches(":popover-open"))
+                node.hidePopover();
+        };
+    }, [container, toast.message, toast.error]);
+    return createPortal(
+        <div
+            ref={notice}
+            popover="manual"
+            className={"toast " + (toast.error ? "toast-error" : "")}
+            role={toast.error ? "alert" : "status"}
+            aria-live={toast.error ? "assertive" : "polite"}
+            onMouseEnter={() => setHovered(true)}
+            onMouseLeave={() => setHovered(false)}
+            onFocusCapture={() => setFocused(true)}
+            onBlurCapture={(event) => {
+                if (!event.currentTarget.contains(event.relatedTarget))
+                    setFocused(false);
+            }}
+        >
+            <span tabIndex={toast.error ? 0 : undefined}>{toast.message}</span>
+            <button
+                className="icon-button"
+                type="button"
+                aria-label="Dismiss Notification"
+                onClick={() => {
+                    const restore = notice.current?.contains(
+                        document.activeElement,
+                    );
+                    close();
+                    if (restore) {
+                        const target = returnFocus.current;
+                        if (target?.isConnected && target !== document.body)
+                            target.focus();
+                        else document.getElementById("main-content")?.focus();
+                    }
+                }}
+            >
+                <X size={17} />
+            </button>
+        </div>,
+        container,
+    );
+}
diff --git a/website/src/shared/demoMode.test.ts b/website/src/shared/demoMode.test.ts
new file mode 100644
index 00000000..833c23d9
--- /dev/null
+++ b/website/src/shared/demoMode.test.ts
@@ -0,0 +1,78 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { api } from "./api";
+
+beforeEach(() => vi.stubGlobal("window", new EventTarget()));
+afterEach(() => vi.unstubAllGlobals());
+
+describe("public demo permissions and protected content", () => {
+    it("requests fresh session-specific configuration after a login change", async () => {
+        const fetcher = vi.fn(async () =>
+            Response.json({
+                demo_mode: true,
+                demo_read_only: false,
+                demo_admin: true,
+            }),
+        );
+        vi.stubGlobal("fetch", fetcher);
+        await expect(api.config()).resolves.toMatchObject({
+            demo_read_only: false,
+            demo_admin: true,
+        });
+        expect(fetcher).toHaveBeenCalledWith(
+            "/api/config",
+            expect.objectContaining({
+                cache: "no-store",
+                credentials: "same-origin",
+            }),
+        );
+    });
+
+    it("announces a protected mutation for the root popup while retaining the API error", async () => {
+        const denied = vi.fn();
+        window.addEventListener("tgdrive:demo-files-read-only", denied);
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    {
+                        code: "DEMO_FILES_READ_ONLY",
+                        detail: "Demo Files is read-only.",
+                    },
+                    { status: 403 },
+                ),
+            ),
+        );
+        await expect(
+            api.folder("/tgdrive-demo-files", "New folder"),
+        ).rejects.toMatchObject({
+            status: 403,
+            code: "DEMO_FILES_READ_ONLY",
+        });
+        expect(denied).toHaveBeenCalledOnce();
+    });
+
+    it("keeps normal file operations and unrelated failures out of the protection popup", async () => {
+        const denied = vi.fn();
+        window.addEventListener("tgdrive:demo-files-read-only", denied);
+        vi.stubGlobal(
+            "fetch",
+            vi
+                .fn()
+                .mockResolvedValueOnce(Response.json({ status: "ok" }))
+                .mockResolvedValueOnce(
+                    Response.json(
+                        {
+                            code: "NAME_CONFLICT",
+                            detail: "Choose another name.",
+                        },
+                        { status: 409 },
+                    ),
+                ),
+        );
+        await api.folder("/", "New folder");
+        await expect(api.folder("/", "New folder")).rejects.toMatchObject({
+            code: "NAME_CONFLICT",
+        });
+        expect(denied).not.toHaveBeenCalled();
+    });
+});
diff --git a/website/src/shared/design-system.css b/website/src/shared/design-system.css
new file mode 100644
index 00000000..8298e301
--- /dev/null
+++ b/website/src/shared/design-system.css
@@ -0,0 +1,606 @@
+/* TGDrive: one colorful, calm workspace. Native file/player controls share these tokens. */
+:root {
+    --mantine-color-body: var(--canvas);
+    --mantine-color-text: var(--ink);
+    --mantine-color-dimmed: var(--muted);
+    --mantine-color-default: var(--surface-raised);
+    --mantine-color-default-hover: var(--hover);
+    --mantine-color-default-color: var(--ink);
+    --mantine-color-default-border: var(--line);
+    --mantine-color-placeholder: var(--muted);
+}
+.main-content,
+.public-shell .main-content {
+    padding: 0;
+}
+.workspace {
+    border: 0;
+    border-inline-start: 1px solid var(--line-subtle);
+    border-radius: 0;
+}
+.sidebar {
+    background: var(--canvas);
+}
+.nav-section-label {
+    color: var(--muted);
+    letter-spacing: 0;
+}
+.drive-nav a {
+    transition:
+        background-color 140ms ease-out,
+        color 140ms ease-out;
+}
+.new-button {
+    background: var(--action);
+    color: var(--on-action);
+}
+.new-button:hover {
+    background: var(--action-hover);
+}
+.settings-help {
+    color: var(--muted);
+    font-size: 13px;
+    line-height: 1.55;
+}
+.page-heading h1 {
+    font-size: 24px;
+    letter-spacing: -0.025em;
+}
+.performance-settings > .performance-section-heading {
+    align-items: center;
+    gap: 16px;
+}
+.performance-settings > .performance-section-heading p {
+    margin: 0;
+    font-size: 13px;
+    max-width: 62ch;
+}
+.performance-settings .performance-setting-group {
+    padding: 12px 16px 4px;
+    margin: 24px 0 0;
+    background: var(--surface-subtle);
+    border: 1px solid var(--line);
+}
+.performance-settings .performance-setting-group legend {
+    padding-inline: 10px;
+    margin-left: -8px;
+    color: var(--ink);
+    font-size: 16px;
+}
+.configuration-group-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 9px;
+}
+.configuration-group-title svg {
+    color: var(--action);
+}
+.performance-setting-group:has(.configuration-auto-preload)
+    .configuration-group-title
+    svg {
+    color: var(--success);
+}
+.performance-field {
+    padding-block: 16px;
+    gap: 20px;
+}
+.performance-field p {
+    font-size: 12px;
+    max-width: 58ch;
+}
+.performance-field label {
+    font-size: 14px;
+}
+.configuration-value {
+    min-width: 0;
+    display: grid;
+    gap: 8px;
+    justify-items: end;
+}
+.configuration-value > .mantine-NumberInput-root {
+    width: 100%;
+}
+.configuration-value input.mantine-NumberInput-input,
+.performance-field input.mantine-TextInput-input {
+    min-height: 42px;
+    margin: 0;
+    padding: 8px 34px 8px 12px;
+    background: var(--canvas);
+    border-color: var(--input-line);
+    font-size: 14px;
+    color: var(--ink);
+}
+.configuration-value .mantine-NumberInput-control {
+    color: var(--muted);
+    border-color: var(--line);
+}
+@media (max-width: 720px), (pointer: coarse) {
+    .configuration-value input.mantine-NumberInput-input,
+    .performance-field input.mantine-TextInput-input {
+        min-height: 44px;
+        font-size: 16px;
+    }
+    .mantine-Tabs-tab {
+        min-height: 44px;
+    }
+}
+.configuration-auto-preload {
+    border-top: 1px solid var(--line);
+    padding-top: 18px;
+    margin-block: 10px 16px;
+}
+.configuration-auto-preload .mantine-Switch-label {
+    color: var(--ink);
+    font-size: 14px;
+}
+.configuration-auto-preload .mantine-Switch-description {
+    max-width: 55ch;
+    color: var(--muted);
+    line-height: 1.55;
+}
+.performance-settings .performance-advanced {
+    background: var(--surface-subtle);
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    padding: 8px 20px;
+}
+.performance-advanced > summary {
+    color: var(--warning);
+    font-size: 14px;
+}
+.performance-advanced > p {
+    font-size: 12px;
+}
+.preference-section.mantine-Paper-root {
+    margin-block: 24px;
+    padding: 20px;
+    background: var(--surface-subtle);
+    border-color: var(--line);
+}
+.configuration-section-heading {
+    display: flex;
+    align-items: baseline;
+    flex-wrap: wrap;
+    gap: 10px;
+    margin-bottom: 8px;
+}
+.preference-section .preference-description p {
+    font-size: 13px;
+    margin-bottom: 20px;
+}
+.preference-section .upload-limit-setting {
+    padding: 12px 0;
+    border-top: 0;
+}
+.preference-section .upload-limit-stepper {
+    background: var(--canvas);
+}
+.performance-actions,
+.upload-settings-actions {
+    gap: 10px;
+}
+.performance-actions {
+    background: var(--surface-subtle);
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    padding: 14px 16px;
+}
+.performance-save-state {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 12px;
+}
+.mantine-Button-root {
+    min-height: 38px;
+    font-size: 13px;
+}
+.mantine-Button-root.primary-button {
+    background: var(--action);
+    color: var(--on-action);
+}
+.mantine-Button-root.primary-button:disabled {
+    background: var(--line);
+    color: var(--muted);
+    opacity: 0.7;
+}
+.mantine-Button-root.secondary-button {
+    background: var(--surface-raised);
+    border: 1px solid var(--line);
+    color: var(--ink);
+}
+.mantine-Button-root.text-button {
+    background: transparent;
+    color: var(--action);
+    padding-inline: 10px;
+}
+.mantine-Button-root.icon-button {
+    background: transparent;
+    padding: 0;
+    min-width: 32px;
+    width: 32px;
+    height: 38px;
+}
+.error-notice.mantine-Alert-root {
+    background: var(--danger-soft);
+    border: 1px solid var(--danger);
+    color: var(--danger-soft-ink);
+    padding: 12px 14px;
+    border-radius: 10px;
+}
+.error-notice .mantine-Alert-message {
+    color: var(--danger-soft-ink);
+}
+.performance-notice,
+.management-notice {
+    background: var(--success-soft);
+    border: 1px solid var(--line);
+    padding: 12px 14px;
+    border-radius: 10px;
+    color: var(--success);
+    font-size: 13px;
+}
+.performance-toolbar {
+    padding-bottom: 18px;
+}
+.performance-view-tabs.mantine-Tabs-list {
+    gap: 4px;
+}
+.performance-view-tabs.mantine-Tabs-list::before {
+    display: none;
+}
+.performance-view-tabs .mantine-Tabs-tab {
+    min-height: 40px;
+    padding: 10px 14px;
+    border: 0;
+    border-radius: 0;
+    border-bottom: 2px solid transparent;
+    color: var(--muted);
+}
+.performance-view-tabs .mantine-Tabs-tab[data-active] {
+    color: var(--action);
+    background: transparent;
+    border-bottom-color: var(--action);
+}
+.performance-view-tabs .mantine-Tabs-tab:hover {
+    background: var(--hover);
+}
+.performance-metric-chart.mantine-Paper-root {
+    padding: 18px;
+    background: var(--surface-subtle);
+    border-color: var(--line);
+}
+.performance-resource-charts {
+    gap: 20px;
+}
+.performance-chart-heading {
+    padding-bottom: 12px;
+    border-bottom: 1px solid var(--line-subtle);
+    margin-bottom: 14px;
+}
+.performance-metric-chart[data-metric="cpu_percent"] {
+    --action: var(--violet);
+}
+.performance-metric-chart[data-metric="memory_bytes"] {
+    --action: var(--success);
+}
+.performance-section-title {
+    padding-bottom: 10px;
+    border-bottom: 1px solid var(--line-subtle);
+    margin-bottom: 12px;
+}
+.performance-section-title h3 {
+    margin-bottom: 0;
+}
+.performance-live-traffic {
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    background: var(--surface-subtle);
+    padding: 18px;
+}
+.performance-all-time {
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    background: var(--surface-subtle);
+    padding: 18px;
+    margin-top: 0;
+}
+.performance-totals-table th {
+    color: var(--muted);
+}
+.performance-totals-table tbody th {
+    color: var(--ink);
+}
+.performance-overview-status {
+    background: var(--success-soft);
+    border: 1px solid var(--line);
+    border-radius: 10px;
+    padding: 14px 16px;
+    color: var(--success);
+    margin-top: 16px;
+}
+.performance-table-wrap {
+    background: var(--surface-subtle);
+    border-color: var(--line);
+    border-radius: 10px;
+}
+.performance-table thead {
+    background: var(--surface-raised);
+}
+.preloads-page .cache-budget-summary {
+    background: var(--surface-subtle);
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    padding: 16px;
+}
+.preloads-page .cache-budget-summary progress {
+    accent-color: var(--success);
+}
+.cache-ready-state[data-complete="true"] {
+    background: var(--success-soft);
+    border-radius: 6px;
+    padding: 2px 6px;
+}
+.preloads-page .preload-recent {
+    background: var(--surface-subtle);
+    padding: 16px;
+    border: 1px solid var(--line);
+    border-radius: 12px;
+}
+.storage-page > .settings-section,
+.connection-management > .settings-section {
+    background: var(--surface-subtle);
+    padding: 20px;
+    border: 1px solid var(--line);
+    border-radius: 12px;
+    margin-bottom: 20px;
+}
+.storage-protection:has(.connection-ready) {
+    background: var(--success-soft);
+    border-color: var(--line);
+}
+.storage-protection:has(.error-notice) {
+    background: var(--surface-subtle) !important;
+    border-color: var(--line) !important;
+}
+.managed-client-list > li {
+    border-color: var(--line);
+    background: var(--canvas);
+    border-radius: 10px;
+}
+.share-column-heading,
+.activity-section-heading {
+    color: var(--muted);
+}
+.performance-chart-now {
+    color: var(--success);
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .main-content {
+        padding-top: 0;
+    }
+    .workspace {
+        border-inline-start: 0;
+        border-radius: 0;
+    }
+    .performance-settings > .performance-section-heading {
+        align-items: flex-start;
+        flex-wrap: wrap;
+    }
+    .performance-settings > .performance-section-heading > a {
+        font-size: 12px;
+    }
+    .performance-settings .performance-setting-group {
+        padding: 12px 14px 4px;
+        margin-top: 20px;
+    }
+    .performance-field {
+        grid-template-columns: 1fr;
+        gap: 10px;
+        padding-block: 14px;
+    }
+    .configuration-value {
+        grid-template-columns: minmax(0, 1fr) auto;
+        align-items: center;
+        justify-items: stretch;
+    }
+    .configuration-value input.mantine-NumberInput-input {
+        min-height: 44px;
+    }
+    .configuration-auto-preload {
+        margin-bottom: 14px;
+    }
+    .performance-actions {
+        gap: 10px;
+        padding: 12px;
+    }
+    .performance-actions .performance-save-state {
+        flex-basis: 100%;
+    }
+    .performance-actions .mantine-Button-root {
+        flex: 1;
+        min-height: 44px;
+        padding-inline: 10px;
+    }
+    .performance-actions .mantine-Button-root.text-button {
+        flex-basis: 100%;
+    }
+    .preference-section.mantine-Paper-root {
+        padding: 16px;
+    }
+    .upload-settings-actions {
+        flex-wrap: wrap;
+    }
+    .upload-settings-actions .mantine-Button-root {
+        min-height: 44px;
+    }
+    .performance-toolbar .performance-view-tabs .mantine-Tabs-tab {
+        padding-inline: 10px;
+    }
+    .performance-metric-chart.mantine-Paper-root {
+        padding: 14px;
+        margin-block: 8px;
+    }
+    .performance-live-traffic,
+    .performance-all-time {
+        padding: 14px;
+        margin-block: 8px;
+    }
+    .storage-page > .settings-section,
+    .connection-management > .settings-section {
+        padding: 16px;
+    }
+}
+@media (prefers-reduced-motion: no-preference) {
+    .mantine-Button-root {
+        transition:
+            background-color 140ms ease-out,
+            border-color 140ms ease-out;
+    }
+    .configuration-value input {
+        transition: border-color 140ms ease-out;
+    }
+}
+
+/* Static theme variables work under the application's strict stylesheet CSP. */
+:root[data-mantine-color-scheme] {
+    --mantine-scale: 1.1428571428571428;
+    --mantine-font-family:
+        InterVariable, Inter, ui-sans-serif, system-ui, sans-serif;
+    --mantine-font-family-headings: var(--mantine-font-family);
+    --mantine-font-size-xs: 12px;
+    --mantine-font-size-sm: 13px;
+    --mantine-font-size-md: 14px;
+    --mantine-font-size-lg: 16px;
+    --mantine-font-size-xl: 20px;
+    --mantine-color-body: var(--canvas);
+    --mantine-color-text: var(--ink);
+    --mantine-color-dimmed: var(--muted);
+    --mantine-color-placeholder: var(--muted);
+    --mantine-color-default: var(--surface-raised);
+    --mantine-color-default-color: var(--ink);
+    --mantine-color-default-hover: var(--hover);
+    --mantine-color-default-border: var(--line);
+    --mantine-primary-color-filled: var(--action);
+    --mantine-primary-color-filled-hover: var(--action-hover);
+    --mantine-primary-color-light: var(--action-soft);
+    --mantine-primary-color-light-color: var(--on-action-soft);
+    --mantine-primary-color-light-hover: var(--action-soft-hover);
+    --mantine-radius-default: var(--mantine-radius-md);
+}
+body,
+button,
+input,
+select,
+textarea {
+    font-family: InterVariable, Inter, ui-sans-serif, system-ui, sans-serif;
+}
+.drive-nav a:hover:not([aria-current]) {
+    background: var(--hover);
+    color: var(--ink);
+}
+.performance-metric-chart h3,
+.performance-chart-heading > strong {
+    color: var(--ink);
+}
+.performance-chart-heading > strong {
+    font-weight: 600;
+}
+.performance-overview-grid:not([hidden]) {
+    gap: 20px;
+}
+.performance-settings .performance-setting-group {
+    margin-top: 16px;
+    padding-top: 8px;
+}
+.performance-settings .performance-setting-group legend {
+    margin-bottom: 0;
+}
+.preference-section .configuration-section-heading h2 {
+    margin: 0;
+}
+.performance-settings .performance-field {
+    padding-block: 12px;
+}
+.performance-settings .performance-save-scope {
+    margin-top: 14px;
+    font-size: 12px;
+}
+.preference-section.mantine-Paper-root {
+    margin-block: 10px 18px;
+    padding: 16px 18px;
+}
+.preference-section .upload-limit-setting {
+    margin-block: 10px 4px;
+    padding-block: 10px;
+    gap: 12px;
+}
+.preference-section .settings-help {
+    margin-block: 6px 0;
+}
+.preference-section .upload-settings-actions {
+    margin-top: 8px;
+}
+@media (max-width: 720px),
+    (max-width: 1000px) and (max-height: 600px) and (pointer: coarse) {
+    .preference-section.mantine-Paper-root {
+        padding: 14px;
+        margin-top: 8px;
+    }
+    .preference-section .upload-limit-setting {
+        gap: 6px;
+    }
+    .preference-section .upload-limit-setting p {
+        margin-bottom: 0;
+    }
+    .preference-section .upload-limit-stepper {
+        margin-block: 0;
+    }
+    .preference-section .upload-settings-actions {
+        gap: 6px;
+    }
+    .preference-section .upload-settings-actions .mantine-Button-root {
+        min-height: 44px;
+    }
+    .performance-resource-charts:not([hidden]) {
+        gap: 12px;
+    }
+}
+
+.preference-section .upload-limit-setting {
+    margin-top: 0;
+    padding-top: 0;
+    border-top: 0;
+}
+.performance-actions {
+    background: transparent;
+    border: 0;
+    border-top: 1px solid var(--line);
+    border-radius: 0;
+    padding: 14px 0;
+}
+.performance-settings .performance-section-heading {
+    margin-bottom: 4px;
+}
+.performance-settings .performance-section-heading p {
+    max-width: 62ch;
+}
+.performance-chart-tooltip {
+    font-size: 12px;
+    box-shadow: none;
+}
+@media (prefers-reduced-motion: no-preference) {
+    .theme-menu,
+    .context-menu {
+        animation: drive-menu-open 120ms ease-out;
+    }
+    @keyframes drive-menu-open {
+        from {
+            opacity: 0;
+        }
+        to {
+            opacity: 1;
+        }
+    }
+}
diff --git a/website/src/shared/responsive.ts b/website/src/shared/responsive.ts
new file mode 100644
index 00000000..6d86d44a
--- /dev/null
+++ b/website/src/shared/responsive.ts
@@ -0,0 +1,4 @@
+// Keep in sync with the compact layout media queries in the stylesheets.
+// A rotated phone still needs touch navigation instead of the desktop sidebar.
+export const COMPACT_LAYOUT_QUERY =
+    "(max-width: 720px), (max-width: 1000px) and (max-height: 600px) and (pointer: coarse)";
diff --git a/website/src/shared/settingsApi.test.ts b/website/src/shared/settingsApi.test.ts
new file mode 100644
index 00000000..179ec8b3
--- /dev/null
+++ b/website/src/shared/settingsApi.test.ts
@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { api, ApiError } from "./api";
+
+beforeEach(() => vi.stubGlobal("window", new EventTarget()));
+afterEach(() => vi.unstubAllGlobals());
+
+describe("owner management HTTP boundary", () => {
+    it("refreshes connections without sending credentials or changing configuration", async () => {
+        const fetcher = vi.fn(async () => Response.json({ clients: [] }));
+        vi.stubGlobal("fetch", fetcher);
+        const controller = new AbortController();
+        await api.refreshConnections(controller.signal);
+        const [url, options] = fetcher.mock.calls[0] as unknown as [
+            string,
+            RequestInit,
+        ];
+        expect(url).toBe("/api/v1/settings/refresh");
+        expect(options.method).toBe("POST");
+        expect(options.credentials).toBe("same-origin");
+        expect(options.body).toBe("{}");
+        controller.abort();
+        expect(options.signal?.aborted).toBe(true);
+    });
+
+    it("sends secret replacements only in the mutation body, with a revision guard", async () => {
+        const fetcher = vi.fn(async () =>
+            Response.json({
+                revision: 4,
+                restart_required: true,
+                admission_paused: true,
+            }),
+        );
+        vi.stubGlobal("fetch", fetcher);
+        await api.saveSettings({
+            expected_revision: 3,
+            api_hash: "a".repeat(32),
+            clients: [
+                {
+                    label: "Storage",
+                    kind: "bot",
+                    enabled: true,
+                    credential: "private-token",
+                },
+            ],
+        });
+        const [url, options] = fetcher.mock.calls[0] as unknown as [
+            string,
+            RequestInit,
+        ];
+        expect(url).toBe("/api/v1/settings");
+        expect(url).not.toContain("private-token");
+        expect(options.method).toBe("PATCH");
+        expect(options.credentials).toBe("same-origin");
+        expect(JSON.parse(options.body as string).expected_revision).toBe(3);
+    });
+    it("uses owner-only phone/code/password bodies and an encoded challenge cancellation path", async () => {
+        const fetcher = vi.fn(async () =>
+            Response.json({
+                stage: "code",
+                challenge_id: "challenge",
+                expires_in_seconds: 300,
+            }),
+        );
+        vi.stubGlobal("fetch", fetcher);
+        await api.startPremiumLogin(4, "+441234567890", "My account");
+        await api.verifyPremiumLogin("challenge", { code: "12345" });
+        await api.verifyPremiumLogin("challenge", { password: "private-2fa" });
+        fetcher.mockImplementationOnce(
+            async () => Response.json({ status: "cancelled" }) as never,
+        );
+        await expect(api.cancelPremiumLogin("opaque/id")).resolves.toEqual({
+            status: "cancelled",
+        });
+        const calls = fetcher.mock.calls as unknown as [string, RequestInit][];
+        expect(calls.map(([url]) => url)).toEqual([
+            "/api/v1/settings/premium-login/start",
+            "/api/v1/settings/premium-login/verify",
+            "/api/v1/settings/premium-login/verify",
+            "/api/v1/settings/premium-login/opaque%2Fid",
+        ]);
+        expect(JSON.parse(calls[0][1].body as string)).toEqual({
+            expected_revision: 4,
+            phone: "+441234567890",
+            label: "My account",
+        });
+        expect(JSON.parse(calls[1][1].body as string)).toEqual({
+            challenge_id: "challenge",
+            code: "12345",
+        });
+        expect(JSON.parse(calls[2][1].body as string)).toEqual({
+            challenge_id: "challenge",
+            password: "private-2fa",
+        });
+        expect(calls[3][1].method).toBe("DELETE");
+    });
+    it("retains a server Retry-After so guided login respects an actual provider wait", async () => {
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    {
+                        detail: "Wait before requesting another code.",
+                        code: "PREMIUM_LOGIN_WAIT",
+                    },
+                    { status: 429, headers: { "Retry-After": "17" } },
+                ),
+            ),
+        );
+        try {
+            await api.startPremiumLogin(1, "+441234567890", "Account");
+        } catch (error) {
+            expect(error).toBeInstanceOf(ApiError);
+            expect((error as ApiError).retryAfter).toBe(17);
+            expect((error as ApiError).status).toBe(429);
+            return;
+        }
+        throw new Error("Expected the rate-limited response to reject");
+    });
+    it("reconciles the global paused state after any authoritative restart-required refusal", async () => {
+        const changed = vi.fn();
+        window.addEventListener("tgdrive:restart-required", changed);
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async () =>
+                Response.json(
+                    {
+                        detail: "Restart TGDrive to apply your connection changes.",
+                        code: "SETTINGS_RESTART_REQUIRED",
+                    },
+                    { status: 409 },
+                ),
+            ),
+        );
+        await expect(api.folder("/", "new")).rejects.toMatchObject({
+            code: "SETTINGS_RESTART_REQUIRED",
+        });
+        expect(changed).toHaveBeenCalledOnce();
+    });
+});
diff --git a/website/src/shared/theme.test.ts b/website/src/shared/theme.test.ts
new file mode 100644
index 00000000..d97925be
--- /dev/null
+++ b/website/src/shared/theme.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { readThemePreference, resolveTheme, THEME_STORAGE_KEY } from "./theme";
+describe("appearance preferences", () => {
+    it("respects explicit choices and follows the device only in system mode", () => {
+        expect(resolveTheme("light", true)).toBe("light");
+        expect(resolveTheme("dark", false)).toBe("dark");
+        expect(resolveTheme("system", true)).toBe("dark");
+        expect(resolveTheme("system", false)).toBe("light");
+    });
+    it("accepts only known saved choices and tolerates blocked storage", () => {
+        expect(
+            readThemePreference({
+                getItem: (key) => (key === THEME_STORAGE_KEY ? "dark" : null),
+            }),
+        ).toBe("dark");
+        expect(readThemePreference({ getItem: () => "light" })).toBe("light");
+        expect(readThemePreference({ getItem: () => "unexpected" })).toBe(
+            "system",
+        );
+        expect(
+            readThemePreference({
+                getItem: () => {
+                    throw new Error("blocked");
+                },
+            }),
+        ).toBe("system");
+    });
+});
diff --git a/website/src/shared/theme.ts b/website/src/shared/theme.ts
new file mode 100644
index 00000000..44653b64
--- /dev/null
+++ b/website/src/shared/theme.ts
@@ -0,0 +1,48 @@
+export type ThemePreference = "light" | "dark" | "system";
+export const THEME_STORAGE_KEY = "tgdrive.appearance";
+export const THEME_CHANGE_EVENT = "tgdrive:appearance-changed";
+
+export function resolveTheme(preference: ThemePreference, darkDevice: boolean) {
+    return preference === "system"
+        ? darkDevice
+            ? "dark"
+            : "light"
+        : preference;
+}
+export function readThemePreference(
+    storage?: Pick<Storage, "getItem">,
+): ThemePreference {
+    try {
+        const value = (storage || window.localStorage).getItem(
+            THEME_STORAGE_KEY,
+        );
+        return value === "light" || value === "dark" ? value : "system";
+    } catch {
+        return "system";
+    }
+}
+export function saveThemePreference(preference: ThemePreference) {
+    try {
+        window.localStorage.setItem(THEME_STORAGE_KEY, preference);
+    } catch {
+        /* The current tab still applies the choice when browser storage is blocked. */
+    }
+    window.dispatchEvent(
+        new CustomEvent(THEME_CHANGE_EVENT, { detail: preference }),
+    );
+}
+export function applyThemePreference(preference: ThemePreference) {
+    const theme = resolveTheme(
+        preference,
+        window.matchMedia("(prefers-color-scheme: dark)").matches,
+    );
+    document.documentElement.dataset.theme = theme;
+    document.documentElement.dataset.themePreference = preference;
+    document.documentElement.style.colorScheme = theme;
+    document
+        .querySelector('meta[name="theme-color"]')
+        ?.setAttribute("content", theme === "dark" ? "#1c1d1f" : "#f5f7f9");
+}
+export function initializeTheme() {
+    applyThemePreference(readThemePreference());
+}
diff --git a/website/src/shared/types.ts b/website/src/shared/types.ts
new file mode 100644
index 00000000..32fb249b
--- /dev/null
+++ b/website/src/shared/types.ts
@@ -0,0 +1,330 @@
+export interface DriveItem {
+    id: string;
+    name: string;
+    path: string;
+    type: "file" | "folder";
+    size?: number;
+    upload_date?: string;
+    parent_names?: string[];
+    starred?: boolean;
+    read_only?: boolean;
+    demo_files?: boolean;
+}
+export interface Directory {
+    name?: string;
+    read_only?: boolean;
+    contents: Record<string, DriveItem>;
+}
+export interface TransferLocation {
+    available: boolean;
+    folder_path?: string;
+    folder_label?: string;
+    item_id?: string | null;
+    item_name?: string | null;
+    display_path?: string;
+    reason?: string;
+}
+export interface FolderUploadMetadata {
+    id: string;
+    name: string;
+    root_path: string;
+    created_at: number;
+}
+export interface Job {
+    history_cleared?: boolean;
+    folder_upload?: FolderUploadMetadata;
+    queue?: { position: number; estimated_wait_seconds: number | null } | null;
+    telegram_parts?: { total: number; stored: number };
+    location?: TransferLocation;
+    id: string;
+    status: string;
+    phase: string;
+    current: number;
+    total: number;
+    percentage?: number;
+    error?: string | null;
+    name?: string;
+    destination?: string;
+    kind?: string;
+    retry_at?: number | null;
+    source_attempt?: number;
+    source_max_attempts?: number;
+    created_at?: number;
+    started_at?: number | null;
+    updated_at?: number;
+    finished_at?: number | null;
+    elapsed_seconds?: number;
+    speed_bytes_per_second?: number | null;
+    eta_seconds?: number | null;
+    progress_updated_at?: number | null;
+    download_mode?: "full" | "warm" | "queued" | "waiting_storage";
+}
+export interface TransferTaskHistoryPage {
+    jobs: Job[];
+    page: number;
+    page_size: number;
+    total_tasks: number;
+    total_pages: number;
+    has_more: boolean;
+}
+export interface UploadSnapshot {
+    folder_upload?: FolderUploadMetadata;
+    id: string;
+    offset: number;
+    total_size: number;
+    chunk_size: number;
+    expires_at?: string;
+    checksums?: { offset: number; size: number; sha256: string }[];
+}
+export interface Share {
+    label?: string;
+    id?: string;
+    node_id?: string;
+    path: string;
+    name?: string;
+    created_at: string;
+    expires_at: string | number | null;
+    type?: "file" | "folder";
+    size?: number;
+    folder_path?: string;
+    folder_label?: string;
+    copyable?: boolean;
+}
+export interface PublicConfig {
+    demo_data?: boolean;
+    demo_mode?: boolean;
+    demo_read_only?: boolean;
+    demo_admin?: boolean;
+    max_file_size: number;
+    timezone?: string;
+}
+export interface DriveProtection {
+    backend?: "mongodb";
+    backup_error?: string | null;
+    backup_key_configured?: boolean;
+    recovery_required?: boolean;
+    code?: string;
+    state: "protected" | "pending" | "error";
+    metadata_revision: number;
+    protected_revision: number;
+    checkpoint_message_id?: number | null;
+    last_success_at?: string | null;
+    error?: string | null;
+}
+export interface ServerStatus {
+    recovery?: DriveProtection | null;
+    telegram_ready?: boolean;
+    telegram_issues?: { code: string; detail: string }[];
+    admission_paused?: boolean;
+    restart_required?: boolean;
+    backup?: unknown;
+    [key: string]: unknown;
+}
+export type View =
+    | "starred"
+    | "files"
+    | "trash"
+    | "shares"
+    | "activity"
+    | "connections"
+    | "storage"
+    | "settings"
+    | "preloads"
+    | "performance";
+export function itemPath(item: DriveItem): string {
+    const parent = item.path.endsWith("/") ? item.path.slice(0, -1) : item.path;
+    return parent + "/" + item.id;
+}
+export function formatBytes(value: number | undefined): string {
+    if (value === undefined || !Number.isFinite(value) || value < 0) return "—";
+    if (value < 1024)
+        return (
+            new Intl.NumberFormat(undefined, {
+                maximumFractionDigits: 2,
+            }).format(value) + " B"
+        );
+    const exponent = Math.min(Math.floor(Math.log(value) / Math.log(1024)), 4);
+    return (
+        new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }).format(
+            value / 1024 ** exponent,
+        ) +
+        " " +
+        ["B", "KB", "MB", "GB", "TB"][exponent]
+    );
+}
+let instanceTimezone = "Asia/Kolkata";
+export function getTimezone(): string {
+    return instanceTimezone;
+}
+export function setTimezone(value: string) {
+    try {
+        new Intl.DateTimeFormat(undefined, { timeZone: value });
+        instanceTimezone = value;
+    } catch {
+        instanceTimezone = "Asia/Kolkata";
+    }
+}
+export function formatTimestamp(
+    value: string | number | null | undefined,
+): string {
+    if (!value) return "—";
+    const date = new Date(typeof value === "number" ? value * 1000 : value);
+    return Number.isNaN(date.getTime())
+        ? "—"
+        : new Intl.DateTimeFormat(undefined, {
+              dateStyle: "medium",
+              timeStyle: "long",
+              timeZone: instanceTimezone,
+          }).format(date);
+}
+export function formatDate(value: string | number | null | undefined): string {
+    if (!value) return "—";
+    const date = new Date(typeof value === "number" ? value * 1000 : value);
+    return Number.isNaN(date.getTime())
+        ? "—"
+        : new Intl.DateTimeFormat(undefined, {
+              dateStyle: "medium",
+              timeZone: instanceTimezone,
+          }).format(date);
+}
+const mediaRequests = new Map<string, string>();
+export function mediaRequestId(path: string, auth = ""): string {
+    const key = path + "\0" + auth;
+    let id = mediaRequests.get(key);
+    if (!id) {
+        id = crypto.randomUUID().replaceAll("-", "_");
+        mediaRequests.set(key, id);
+        if (mediaRequests.size > 256)
+            mediaRequests.delete(mediaRequests.keys().next().value!);
+    }
+    return id;
+}
+export function fileUrl(path: string, auth = "", download = false): string {
+    const search = new URLSearchParams({ path });
+    search.set("request_id", mediaRequestId(path, auth));
+    if (auth) search.set("auth", auth);
+    if (download) search.set("download", "1");
+    return "/file?" + search.toString();
+}
+
+export interface PreviewDescriptor {
+    kind: "text" | "pdf" | "video" | "book" | "unsupported";
+    size: number;
+    text?: string;
+    language?: string;
+    truncated?: boolean;
+    reason?: string;
+    url?: string;
+}
+
+export interface FolderTreeRequest {
+    destination: string;
+    root_name: string;
+    folders: string[][];
+    client_request_id: string;
+}
+export interface FolderTreeResponse {
+    root: DriveItem;
+    folders: Record<string, string>;
+}
+
+export interface ManagedClient {
+    id: string;
+    label: string;
+    display_name?: string | null;
+    username?: string | null;
+    connection_check?: "queued" | "checking" | "waiting" | "passed" | "failed";
+    connection_check_error?: string | null;
+    connection_checked_at?: number | null;
+    connection_retry_at?: number | null;
+    identity_refreshing?: boolean;
+    identity_retry_at?: number | null;
+    kind: "bot" | "user";
+    enabled: boolean;
+    configured: boolean;
+    connected: boolean | null;
+    healthy: boolean;
+    premium: boolean | null;
+    active_leases: number;
+    error: string | null;
+}
+export interface ManagementStats {
+    files: number;
+    folders: number;
+    total_bytes: number;
+    trashed_files: number;
+    trashed_bytes: number;
+    active_jobs: number;
+    queued_jobs: number;
+    failed_jobs: number;
+    staging_budget_bytes: number;
+    staging_reserved_bytes: number;
+    free_disk_bytes: number | null;
+}
+export interface ManagementSettings {
+    revision: number;
+    applied_revision: number;
+    restart_required: boolean;
+    application_mode: "restart";
+    admission_paused: boolean;
+    api_id: number;
+    api_hash_configured: boolean;
+    storage_channel: number;
+    storage_channel_error?: string | null;
+    clients: ManagedClient[];
+    active_clients: Omit<ManagedClient, "enabled" | "configured">[];
+    stats: ManagementStats;
+    recovery?: DriveProtection | null;
+}
+export interface ManagedClientUpdate {
+    id?: string;
+    label: string;
+    kind: "bot" | "user";
+    enabled: boolean;
+    credential?: string;
+}
+export interface ManagementUpdate {
+    expected_revision: number;
+    api_id?: number;
+    api_hash?: string;
+    clients?: ManagedClientUpdate[];
+}
+
+export interface PremiumChallenge {
+    challenge_id: string;
+    stage: "code" | "password";
+    expires_in_seconds: number;
+}
+export type PremiumVerification =
+    | PremiumChallenge
+    | {
+          stage: "complete";
+          settings: ManagementSettings;
+      };
+
+export interface SearchResults {
+    items: DriveItem[];
+    query: string;
+    has_more: boolean;
+    next_offset: number | null;
+}
+
+/** A shared unit keeps precise progress counters compact in narrow columns. */
+export function formatByteProgress(current: number, total: number): string {
+    const sent = formatBytes(current);
+    if (!Number.isFinite(total) || total <= 0) return sent;
+    const full = formatBytes(total);
+    const unit = sent.slice(sent.lastIndexOf(" ") + 1);
+    return full.endsWith(" " + unit)
+        ? sent.slice(0, sent.lastIndexOf(" ")) + " / " + full
+        : sent + " / " + full;
+}
+export function remainingBytesHint(current: number, total: number): string {
+    return Number.isFinite(current) &&
+        Number.isFinite(total) &&
+        total > 0 &&
+        current >= total * 0.95 &&
+        current < total
+        ? formatBytes(total - current) + " remaining"
+        : "";
+}
diff --git a/website/src/shared/useManualRefresh.ts b/website/src/shared/useManualRefresh.ts
new file mode 100644
index 00000000..1abe3176
--- /dev/null
+++ b/website/src/shared/useManualRefresh.ts
@@ -0,0 +1,50 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { errorMessage } from "./api";
+
+export type RefreshNotice = (message: string, error?: boolean) => void;
+
+/** Explicit refresh feedback; automatic polling stays with the page's loader. */
+export function useManualRefresh(onNotice?: RefreshNotice) {
+    const [refreshing, setRefreshing] = useState(false);
+    const mounted = useRef(true);
+    const active = useRef<AbortController | null>(null);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            active.current?.abort();
+            active.current = null;
+        };
+    }, []);
+    const run = useCallback(
+        async (
+            task: (signal: AbortSignal) => Promise<void | boolean>,
+            successMessage: string,
+        ) => {
+            // A ref closes the gap before React commits the disabled button state.
+            if (!mounted.current || active.current) return;
+            const controller = new AbortController();
+            active.current = controller;
+            setRefreshing(true);
+            try {
+                const result = await task(controller.signal);
+                if (
+                    mounted.current &&
+                    !controller.signal.aborted &&
+                    result !== false
+                )
+                    onNotice?.(successMessage);
+            } catch (cause) {
+                if (mounted.current && !controller.signal.aborted)
+                    onNotice?.(errorMessage(cause), true);
+            } finally {
+                if (active.current === controller) {
+                    active.current = null;
+                    if (mounted.current) setRefreshing(false);
+                }
+            }
+        },
+        [onNotice],
+    );
+    return { refreshing, run };
+}
diff --git a/website/static/assets/file-icon.svg b/website/static/assets/file-icon.svg
deleted file mode 100644
index 36aebc22..00000000
--- a/website/static/assets/file-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#4285F4" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M3 3a2 2 0 0 1 2-2h9.982a2 2 0 0 1 1.414.586l4.018 4.018A2 2 0 0 1 21 7.018V21a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2Zm2-.5a.5.5 0 0 0-.5.5v18a.5.5 0 0 0 .5.5h14a.5.5 0 0 0 .5-.5V8.5h-4a2 2 0 0 1-2-2v-4Zm10 0v4a.5.5 0 0 0 .5.5h4a.5.5 0 0 0-.146-.336l-4.018-4.018A.5.5 0 0 0 15 2.5Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/folder-icon.svg b/website/static/assets/folder-icon.svg
deleted file mode 100644
index a7a28e3f..00000000
--- a/website/static/assets/folder-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M2 4.75C2 3.784 2.784 3 3.75 3h4.971c.58 0 1.12.286 1.447.765l1.404 2.063c.046.069.124.11.207.11h8.471c.966 0 1.75.783 1.75 1.75V19.25A1.75 1.75 0 0 1 20.25 21H3.75A1.75 1.75 0 0 1 2 19.25Zm1.75-.25a.25.25 0 0 0-.25.25v14.5c0 .138.112.25.25.25h16.5a.25.25 0 0 0 .25-.25V7.687a.25.25 0 0 0-.25-.25h-8.471a1.75 1.75 0 0 1-1.447-.765L8.928 4.61a.252.252 0 0 0-.208-.11Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/folder-solid-icon.svg b/website/static/assets/folder-solid-icon.svg
deleted file mode 100644
index 35c8a2ea..00000000
--- a/website/static/assets/folder-solid-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg fill="#FBBC04" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M2 4.75C2 3.784 2.784 3 3.75 3h4.971c.58 0 1.12.286 1.447.765l1.404 2.063c.046.069.124.11.207.11h8.471c.966 0 1.75.783 1.75 1.75V19.25A1.75 1.75 0 0 1 20.25 21H3.75A1.75 1.75 0 0 1 2 19.25Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/home-icon.svg b/website/static/assets/home-icon.svg
deleted file mode 100644
index 293a6409..00000000
--- a/website/static/assets/home-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M11.03 2.59a1.501 1.501 0 0 1 1.94 0l7.5 6.363a1.5 1.5 0 0 1 .53 1.144V19.5a1.5 1.5 0 0 1-1.5 1.5h-5.75a.75.75 0 0 1-.75-.75V14h-2v6.25a.75.75 0 0 1-.75.75H4.5A1.5 1.5 0 0 1 3 19.5v-9.403c0-.44.194-.859.53-1.144ZM12 3.734l-7.5 6.363V19.5h5v-6.25a.75.75 0 0 1 .75-.75h3.5a.75.75 0 0 1 .75.75v6.25h5v-9.403Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/info-icon-small.svg b/website/static/assets/info-icon-small.svg
deleted file mode 100644
index ba409a68..00000000
--- a/website/static/assets/info-icon-small.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/link-icon.svg b/website/static/assets/link-icon.svg
deleted file mode 100644
index 6f3f087d..00000000
--- a/website/static/assets/link-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M14.78 3.653a3.936 3.936 0 1 1 5.567 5.567l-3.627 3.627a3.936 3.936 0 0 1-5.88-.353.75.75 0 0 0-1.18.928 5.436 5.436 0 0 0 8.12.486l3.628-3.628a5.436 5.436 0 1 0-7.688-7.688l-3 3a.75.75 0 0 0 1.06 1.061l3-3Z"></path><path d="M7.28 11.153a3.936 3.936 0 0 1 5.88.353.75.75 0 0 0 1.18-.928 5.436 5.436 0 0 0-8.12-.486L2.592 13.72a5.436 5.436 0 1 0 7.688 7.688l3-3a.75.75 0 1 0-1.06-1.06l-3 3a3.936 3.936 0 0 1-5.567-5.568l3.627-3.627Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/load-icon.svg b/website/static/assets/load-icon.svg
deleted file mode 100644
index 2c557522..00000000
--- a/website/static/assets/load-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M3.38 8A9.502 9.502 0 0 1 12 2.5a9.502 9.502 0 0 1 9.215 7.182.75.75 0 1 0 1.456-.364C21.473 4.539 17.15 1 12 1a10.995 10.995 0 0 0-9.5 5.452V4.75a.75.75 0 0 0-1.5 0V8.5a1 1 0 0 0 1 1h3.75a.75.75 0 0 0 0-1.5H3.38Zm-.595 6.318a.75.75 0 0 0-1.455.364C2.527 19.461 6.85 23 12 23c4.052 0 7.592-2.191 9.5-5.451v1.701a.75.75 0 0 0 1.5 0V15.5a1 1 0 0 0-1-1h-3.75a.75.75 0 0 0 0 1.5h2.37A9.502 9.502 0 0 1 12 21.5c-4.446 0-8.181-3.055-9.215-7.182Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/more-icon.svg b/website/static/assets/more-icon.svg
deleted file mode 100644
index f72be59f..00000000
--- a/website/static/assets/more-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M20 14a2 2 0 1 1-.001-3.999A2 2 0 0 1 20 14ZM6 12a2 2 0 1 1-3.999.001A2 2 0 0 1 6 12Zm8 0a2 2 0 1 1-3.999.001A2 2 0 0 1 14 12Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/pencil-icon.svg b/website/static/assets/pencil-icon.svg
deleted file mode 100644
index 4a95c93d..00000000
--- a/website/static/assets/pencil-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M17.263 2.177a1.75 1.75 0 0 1 2.474 0l2.586 2.586a1.75 1.75 0 0 1 0 2.474L19.53 10.03l-.012.013L8.69 20.378a1.753 1.753 0 0 1-.699.409l-5.523 1.68a.748.748 0 0 1-.747-.188.748.748 0 0 1-.188-.747l1.673-5.5a1.75 1.75 0 0 1 .466-.756L14.476 4.963ZM4.708 16.361a.26.26 0 0 0-.067.108l-1.264 4.154 4.177-1.271a.253.253 0 0 0 .1-.059l10.273-9.806-2.94-2.939-10.279 9.813ZM19 8.44l2.263-2.262a.25.25 0 0 0 0-.354l-2.586-2.586a.25.25 0 0 0-.354 0L16.061 5.5Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/plus-icon.svg b/website/static/assets/plus-icon.svg
deleted file mode 100644
index 0ef9b1c2..00000000
--- a/website/static/assets/plus-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M11.75 4.5a.75.75 0 0 1 .75.75V11h5.75a.75.75 0 0 1 0 1.5H12.5v5.75a.75.75 0 0 1-1.5 0V12.5H5.25a.75.75 0 0 1 0-1.5H11V5.25a.75.75 0 0 1 .75-.75Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/profile-icon.svg b/website/static/assets/profile-icon.svg
deleted file mode 100644
index b833090e..00000000
--- a/website/static/assets/profile-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M12 2.5a5.25 5.25 0 0 0-2.519 9.857 9.005 9.005 0 0 0-6.477 8.37.75.75 0 0 0 .727.773H20.27a.75.75 0 0 0 .727-.772 9.005 9.005 0 0 0-6.477-8.37A5.25 5.25 0 0 0 12 2.5Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/search-icon.svg b/website/static/assets/search-icon.svg
deleted file mode 100644
index 2b7dbc6d..00000000
--- a/website/static/assets/search-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M10.25 2a8.25 8.25 0 0 1 6.34 13.53l5.69 5.69a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215l-5.69-5.69A8.25 8.25 0 1 1 10.25 2ZM3.5 10.25a6.75 6.75 0 1 0 13.5 0 6.75 6.75 0 0 0-13.5 0Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/share-icon.svg b/website/static/assets/share-icon.svg
deleted file mode 100644
index 734a03ab..00000000
--- a/website/static/assets/share-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M20 5.5a3.498 3.498 0 0 1-6.062 2.385l-5.112 3.021a3.498 3.498 0 0 1 0 2.188l5.112 3.021a3.5 3.5 0 1 1-.764 1.29l-5.112-3.02a3.499 3.499 0 1 1-3.843-5.642 3.499 3.499 0 0 1 3.843.872l5.112-3.021A3.5 3.5 0 1 1 20 5.5Zm-1.5 13a2 2 0 1 0-3.999-.001 2 2 0 0 0 3.999.001Zm0-13a2 2 0 1 0-3.999-.001A2 2 0 0 0 18.5 5.5ZM5.5 14a2 2 0 1 0 .001-3.999A2 2 0 0 0 5.5 14Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/trash-icon.svg b/website/static/assets/trash-icon.svg
deleted file mode 100644
index fc095688..00000000
--- a/website/static/assets/trash-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M16 1.75V3h5.25a.75.75 0 0 1 0 1.5H2.75a.75.75 0 0 1 0-1.5H8V1.75C8 .784 8.784 0 9.75 0h4.5C15.216 0 16 .784 16 1.75Zm-6.5 0V3h5V1.75a.25.25 0 0 0-.25-.25h-4.5a.25.25 0 0 0-.25.25ZM4.997 6.178a.75.75 0 1 0-1.493.144L4.916 20.92a1.75 1.75 0 0 0 1.742 1.58h10.684a1.75 1.75 0 0 0 1.742-1.581l1.413-14.597a.75.75 0 0 0-1.494-.144l-1.412 14.596a.25.25 0 0 1-.249.226H6.658a.25.25 0 0 1-.249-.226L4.997 6.178Z"></path><path d="M9.206 7.501a.75.75 0 0 1 .793.705l.5 8.5A.75.75 0 1 1 9 16.794l-.5-8.5a.75.75 0 0 1 .705-.793Zm6.293.793A.75.75 0 1 0 14 8.206l-.5 8.5a.75.75 0 0 0 1.498.088l.5-8.5Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/assets/upload-icon.svg b/website/static/assets/upload-icon.svg
deleted file mode 100644
index 5e1f5263..00000000
--- a/website/static/assets/upload-icon.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24"><path d="M12.5 6.75a.75.75 0 0 0-1.5 0V9H8.75a.75.75 0 0 0 0 1.5H11v2.25a.75.75 0 0 0 1.5 0V10.5h2.25a.75.75 0 0 0 0-1.5H12.5V6.75ZM8.75 16a.75.75 0 0 0 0 1.5h6a.75.75 0 0 0 0-1.5h-6Z"></path><path d="M5 1h9.982a2 2 0 0 1 1.414.586l4.018 4.018A2 2 0 0 1 21 7.018V21a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V3a2 2 0 0 1 2-2Zm-.5 2v18a.5.5 0 0 0 .5.5h14a.5.5 0 0 0 .5-.5V7.018a.5.5 0 0 0-.146-.354l-4.018-4.018a.5.5 0 0 0-.354-.146H5a.5.5 0 0 0-.5.5Z"></path></svg>
\ No newline at end of file
diff --git a/website/static/home.css b/website/static/home.css
deleted file mode 100644
index 899ea917..00000000
--- a/website/static/home.css
+++ /dev/null
@@ -1,547 +0,0 @@
-* {
-    margin: 0px;
-    padding: 0px;
-    box-sizing: border-box;
-    font-family: "Roboto", sans-serif;
-    user-select: none;
-    -webkit-user-select: none;
-    -moz-user-select: none;
-    -ms-user-select: none;
-}
-
-.container {
-    width: 100%;
-    height: 100vh;
-    display: grid;
-    background: #f1f1f1;
-    grid-template-columns: auto 1fr;
-}
-
-.rotate-90 {
-    transform: rotate(90deg);
-}
-
-/* Sidebar Style Start */
-
-.sidebar {
-    width: 250px;
-    height: 100%;
-    background-color: #f8fafd;
-    padding: 20px;
-    display: flex;
-    flex-direction: column;
-    justify-content: start;
-    align-items: start;
-}
-
-.sidebar-header {
-    display: flex;
-    align-items: center;
-    justify-content: start;
-    width: 100%;
-}
-
-.brand-link {
-    display: inline-flex;
-    align-items: center;
-    min-height: 44px;
-    max-width: 100%;
-}
-
-.brand-link:focus-visible {
-    outline: 2px solid #3157ff;
-    outline-offset: 4px;
-}
-
-.sidebar-header .brand-logo {
-    display: block;
-    width: 180px;
-    max-width: 100%;
-    height: auto;
-}
-
-#get-password {
-    max-width: calc(100vw - 32px);
-}
-
-#get-password .login-brand {
-    display: block;
-    width: 180px;
-    max-width: 100%;
-    height: auto;
-    margin-bottom: 20px;
-}
-
-.sidebar .new-button {
-    padding: 15px 20px;
-    background-color: #fff;
-    border: 1px solid #e0e0e0;
-    border-radius: 20px;
-    margin-top: 20px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    transition: all 0.3s ease;
-    box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.1);
-    font-size: 0.9rem;
-    color: #282c35;
-    font-weight: 500;
-}
-
-.sidebar .new-button:hover {
-    background-color: #edf1fa;
-    border: 1px solid #c9d0e6;
-    box-shadow: 0px 5px 10px rgba(0, 0, 0, 0.3);
-}
-
-.sidebar .new-button img {
-    width: 24px;
-    height: 24px;
-    margin-right: 10px;
-}
-
-.new-upload {
-    position: absolute;
-    background-color: #ffffff;
-    padding: 5px 0px;
-    box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.2);
-    border-radius: 5px;
-    width: 250px;
-    top: 40px;
-    z-index: -1;
-    opacity: 0;
-    transition: all 0.2s;
-}
-
-.new-upload div {
-    padding: 10px 20px;
-    display: flex;
-    align-items: center;
-    justify-content: start;
-    cursor: pointer;
-    transition: all 0.3s ease;
-    font-size: 14px;
-}
-
-.new-upload div:hover {
-    background-color: #f1f1f1;
-}
-
-.new-upload div img {
-    margin-right: 10px;
-    height: 20px;
-    width: 20px;
-}
-
-.new-upload hr {
-    border: 1px solid #e0e0e0;
-    margin: 5px 0px;
-}
-
-.bg-blur {
-    position: fixed;
-    background-color: #000000;
-    height: 100dvh;
-    width: 100dvw;
-    transition: opacity 0.3s ease;
-    z-index: -1;
-    opacity: 0;
-}
-
-/* More Options Start */
-
-.more-options {
-    position: absolute;
-    background-color: #ffffff;
-    padding: 2px 0px;
-    box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.2);
-    border-radius: 5px;
-    z-index: -1;
-    opacity: 0;
-    transition: all 0.2s;
-    width: 150px;
-    transform: translateX(-50%);
-}
-
-.more-options div {
-    width: 100%;
-    padding: 5px 20px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    transition: all 0.3s ease;
-    font-size: 14px;
-}
-
-.more-options div:hover {
-    background-color: #f1f1f1;
-}
-
-.more-options div img {
-    margin-right: 10px;
-    height: 20px;
-    width: 20px;
-}
-
-.more-options hr {
-    border: 1px solid #e0e0e0;
-    margin: 2px 0px;
-}
-
-/* More Options End */
-
-
-/* Create New Folder Start */
-.create-new-folder {
-    position: fixed;
-    top: 50%;
-    left: 50%;
-    transform: translate(-50%, -50%);
-    padding: 20px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    flex-direction: column;
-    background-color: #fff;
-    border-radius: 10px;
-    z-index: -1;
-    opacity: 0;
-    box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.3);
-    transition: opacity 0.3s ease;
-    width: 400px;
-}
-
-.create-new-folder span {
-    font-size: 1.2rem;
-    font-weight: 400;
-    color: #444746;
-    margin-bottom: 20px;
-    width: 100%;
-    margin-left: 10px;
-}
-
-.create-new-folder input {
-    width: 100%;
-    padding: 10px 20px;
-    border: 1px solid #e0e0e0;
-    border-radius: 5px;
-    outline: none;
-    font-size: 0.9rem;
-    font-weight: 400;
-    color: #444746;
-    margin-bottom: 20px;
-}
-
-.create-new-folder div {
-    width: 100%;
-    display: flex;
-    align-items: center;
-    justify-content: end;
-    gap: 10px;
-}
-
-.create-new-folder button {
-    background-color: transparent;
-    border: none;
-    border-radius: 20px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    transition: all 0.3s ease;
-    font-size: 0.9rem;
-    color: #0b57d0;
-    font-weight: 500;
-    padding: 10px 20px;
-}
-
-.create-new-folder button:hover {
-    background-color: #edf1fa;
-    box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.2);
-}
-
-/* Create New Folder End */
-
-/* Remote URL Upload Start */
-
-#single-threaded-div{
-    display: flex;
-    flex-direction: row;
-    justify-content: start;
-    align-items: center;
-    width: 100%;
-    margin: 10px 0px;
-}
-
-#single-threaded-div input{
-    width: auto;
-    margin: 0px;
-    margin-left: 10px;
-}
-
-#single-threaded-div img{
-    height: 16px;
-    width: 16px;
-}
-#single-threaded-div a{
-    height: 16px;
-    width: 16px;
-}
-
-/* Remote URL Upload End */
-
-/* File Uploader Start */
-
-.file-uploader {
-    position: fixed;
-    top: 50%;
-    left: 50%;
-    transform: translate(-50%, -50%);
-    padding: 20px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    flex-direction: column;
-    background-color: #fff;
-    border-radius: 10px;
-    z-index: -1;
-    box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.3);
-    transition: opacity 0.3s ease;
-    width: 500px;
-    opacity: 0;
-}
-
-.upload-head {
-    font-size: 1.2rem;
-    font-weight: 500;
-    color: #444746;
-    margin-bottom: 20px;
-    width: 100%;
-}
-
-.upload-info {
-    font-size: 16px;
-    font-weight: 400;
-    color: #444746;
-    margin-bottom: 5px;
-    width: 100%;
-    max-height: 40px;
-    overflow: hidden;
-}
-
-.progress {
-    width: 100%;
-    background-color: #ddd;
-    border-radius: 5px;
-    overflow: hidden;
-    margin-top: 20px;
-}
-
-.progress-bar {
-    height: 20px;
-    background-color: #007bff;
-    width: 0;
-    transition: width 0.3s;
-}
-
-.file-uploader .btn-div {
-    width: 100%;
-    display: flex;
-    align-items: center;
-    justify-content: end;
-    margin-top: 20px;
-}
-
-.file-uploader button {
-    background-color: transparent;
-    border: none;
-    border-radius: 20px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    transition: all 0.3s ease;
-    font-size: 0.9rem;
-    color: #0b57d0;
-    font-weight: 500;
-    padding: 10px 20px;
-}
-
-.file-uploader button:hover {
-    background-color: #edf1fa;
-    box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.2);
-}
-
-/* File Uploader End */
-
-.sidebar-menu {
-    margin-top: 20px;
-    width: 100%;
-    display: flex;
-    flex-direction: column;
-    justify-content: start;
-    align-items: center;
-}
-
-.sidebar-menu a {
-    width: 100%;
-    padding: 10px 20px;
-    display: flex;
-    align-items: center;
-    justify-content: start;
-    color: #444746;
-    font-size: 0.9rem;
-    font-weight: 400;
-    text-decoration: none;
-    transition: all 0.3s ease;
-    border-radius: 20px;
-}
-
-.sidebar-menu .selected-item {
-    background-color: #c2e7ff;
-}
-
-.sidebar-menu .unselected-item:hover {
-    background-color: #cfcfcf;
-}
-
-.sidebar-menu a img {
-    width: 20px;
-    height: 20px;
-    margin-right: 10px;
-}
-
-/* Sidebar Style End */
-
-/* Main Content Style Start */
-
-.main-content {
-    width: 100%;
-    height: 100%;
-    padding: 20px;
-    display: flex;
-    flex-direction: column;
-    justify-content: start;
-    align-items: start;
-    background-color: #f8fafd;
-}
-
-.main-content .header {
-    width: 100%;
-    display: grid;
-    grid-template-columns: 1fr auto;
-    align-items: center;
-    gap: 40px;
-}
-
-#search-form {
-    height: 100%;
-    width: 100%;
-}
-
-.search-bar {
-    width: 100%;
-    display: flex;
-    align-items: center;
-    justify-content: start;
-    background-color: #e9eef6;
-    border-radius: 20px;
-    padding: 10px 20px;
-}
-
-.search-bar img {
-    width: 20px;
-    height: 20px;
-    margin-right: 20px;
-}
-
-.search-bar input {
-    width: 100%;
-    border: none;
-    outline: none;
-    background-color: transparent;
-    font-size: 1rem;
-    font-weight: 400;
-}
-
-.search-bar:focus-within {
-    background-color: #ffffff;
-    box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.1);
-}
-
-.directory {
-    background-color: #fff;
-    padding: 10px 20px;
-    width: 100%;
-    height: 100%;
-    border-radius: 20px;
-    margin-top: 20px;
-}
-
-.directory table {
-    width: 100%;
-    border-collapse: collapse;
-}
-
-.directory table tr th {
-    text-align: start;
-    font-size: 0.9rem;
-    font-weight: 500;
-    color: #444746;
-    padding: 10px 0px;
-    border-bottom: 1px solid #e0e0e0;
-}
-
-.directory table tr td {
-    text-align: start;
-    font-size: 0.9rem;
-    font-weight: 400;
-    color: #444746;
-    border-bottom: 1px solid #e0e0e0;
-    height: 50px;
-}
-
-.directory .body-tr {
-    transition: all 0.3s ease;
-}
-
-.directory .body-tr:hover {
-    background-color: #f1f1f1;
-}
-
-.directory .td-align {
-    display: flex;
-    align-items: center;
-    justify-content: start;
-    width: 100%;
-    height: 100%;
-}
-
-.directory .td-align img {
-    width: 24px;
-    height: 24px;
-    margin-right: 10px;
-}
-
-.directory .more-btn img {
-    width: 14px;
-    height: 14px;
-    margin: 0px;
-}
-
-.directory .more-btn {
-    padding: 8px;
-    border-radius: 20px;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    cursor: pointer;
-    transition: all 0.3s ease;
-}
-
-.directory .more-btn:hover {
-    background-color: #b9b9b9;
-    box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.1);
-}
diff --git a/website/static/js/apiHandler.js b/website/static/js/apiHandler.js
deleted file mode 100644
index 6e18a2b9..00000000
--- a/website/static/js/apiHandler.js
+++ /dev/null
@@ -1,347 +0,0 @@
-// Api Fuctions
-async function postJson(url, data) {
-    data['password'] = getPassword()
-    const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-            'Content-Type': 'application/json'
-        },
-        body: JSON.stringify(data)
-    })
-    return await response.json()
-}
-
-document.getElementById('pass-login').addEventListener('click', async () => {
-    const password = document.getElementById('auth-pass').value
-    const data = { 'pass': password }
-    const json = await postJson('/api/checkPassword', data)
-    if (json.status === 'ok') {
-        localStorage.setItem('password', password)
-        alert('Logged In Successfully')
-        window.location.reload()
-    }
-    else {
-        alert('Wrong Password')
-    }
-
-})
-
-async function getCurrentDirectory() {
-    let path = getCurrentPath()
-    if (path === 'redirect') {
-        return
-    }
-    try {
-        const auth = getFolderAuthFromPath()
-        console.log(path)
-
-        const data = { 'path': path, 'auth': auth }
-        const json = await postJson('/api/getDirectory', data)
-
-        if (json.status === 'ok') {
-            if (getCurrentPath().startsWith('/share')) {
-                const sections = document.querySelector('.sidebar-menu').getElementsByTagName('a')
-                console.log(path)
-
-                if (removeSlash(json['auth_home_path']) === removeSlash(path.split('_')[1])) {
-                    sections[0].setAttribute('class', 'selected-item')
-
-                } else {
-                    sections[0].setAttribute('class', 'unselected-item')
-                }
-                sections[0].href = `/?path=/share_${removeSlash(json['auth_home_path'])}&auth=${auth}`
-                console.log(`/?path=/share_${removeSlash(json['auth_home_path'])}&auth=${auth}`)
-            }
-
-            console.log(json)
-            showDirectory(json['data'])
-        } else {
-            alert('404 Current Directory Not Found')
-        }
-    }
-    catch (err) {
-        console.log(err)
-        alert('404 Current Directory Not Found')
-    }
-}
-
-async function createNewFolder() {
-    const folderName = document.getElementById('new-folder-name').value;
-    const path = getCurrentPath()
-    if (path === 'redirect') {
-        return
-    }
-    if (folderName.length > 0) {
-        const data = {
-            'name': folderName,
-            'path': path
-        }
-        try {
-            const json = await postJson('/api/createNewFolder', data)
-
-            if (json.status === 'ok') {
-                window.location.reload();
-            } else {
-                alert(json.status)
-            }
-        }
-        catch (err) {
-            alert('Error Creating Folder')
-        }
-    } else {
-        alert('Folder Name Cannot Be Empty')
-    }
-}
-
-
-async function getFolderShareAuth(path) {
-    const data = { 'path': path }
-    const json = await postJson('/api/getFolderShareAuth', data)
-    if (json.status === 'ok') {
-        return json.auth
-    } else {
-        alert('Error Getting Folder Share Auth')
-    }
-}
-
-// File Uploader Start
-
-const MAX_FILE_SIZE = MAX_FILE_SIZE__SDGJDG // Will be replaced by the python
-
-const fileInput = document.getElementById('fileInput');
-const progressBar = document.getElementById('progress-bar');
-const cancelButton = document.getElementById('cancel-file-upload');
-const uploadPercent = document.getElementById('upload-percent');
-let uploadRequest = null;
-let uploadStep = 0;
-let uploadID = null;
-
-fileInput.addEventListener('change', async (e) => {
-    const file = fileInput.files[0];
-
-    if (file.size > MAX_FILE_SIZE) {
-        alert(`File size exceeds ${(MAX_FILE_SIZE / (1024 * 1024 * 1024)).toFixed(2)} GB limit`);
-        return;
-    }
-
-    // Showing file uploader
-    document.getElementById('bg-blur').style.zIndex = '2';
-    document.getElementById('bg-blur').style.opacity = '0.1';
-    document.getElementById('file-uploader').style.zIndex = '3';
-    document.getElementById('file-uploader').style.opacity = '1';
-
-    document.getElementById('upload-filename').innerText = 'Filename: ' + file.name;
-    document.getElementById('upload-filesize').innerText = 'Filesize: ' + (file.size / (1024 * 1024)).toFixed(2) + ' MB';
-    document.getElementById('upload-status').innerText = 'Status: Uploading To Backend Server';
-
-
-    const formData = new FormData();
-    formData.append('file', file);
-    formData.append('path', getCurrentPath());
-    formData.append('password', getPassword());
-    const id = getRandomId();
-    formData.append('id', id);
-    formData.append('total_size', file.size);
-
-    uploadStep = 1;
-    uploadRequest = new XMLHttpRequest();
-    uploadRequest.open('POST', '/api/upload', true);
-
-    uploadRequest.upload.addEventListener('progress', (e) => {
-        if (e.lengthComputable) {
-            const percentComplete = (e.loaded / e.total) * 100;
-            progressBar.style.width = percentComplete + '%';
-            uploadPercent.innerText = 'Progress : ' + percentComplete.toFixed(2) + '%';
-        }
-    });
-
-    uploadRequest.upload.addEventListener('load', async () => {
-        await updateSaveProgress(id)
-    });
-
-    uploadRequest.upload.addEventListener('error', () => {
-        alert('Upload failed');
-        window.location.reload();
-    });
-
-    uploadRequest.send(formData);
-});
-
-cancelButton.addEventListener('click', () => {
-    if (uploadStep === 1) {
-        uploadRequest.abort();
-    } else if (uploadStep === 2) {
-        const data = { 'id': uploadID }
-        postJson('/api/cancelUpload', data)
-    }
-    alert('Upload canceled');
-    window.location.reload();
-});
-
-async function updateSaveProgress(id) {
-    console.log('save progress')
-    progressBar.style.width = '0%';
-    uploadPercent.innerText = 'Progress : 0%'
-    document.getElementById('upload-status').innerText = 'Status: Processing File On Backend Server';
-
-    const interval = setInterval(async () => {
-        const response = await postJson('/api/getSaveProgress', { 'id': id })
-        const data = response['data']
-
-        if (data[0] === 'running') {
-            const current = data[1];
-            const total = data[2];
-            document.getElementById('upload-filesize').innerText = 'Filesize: ' + (total / (1024 * 1024)).toFixed(2) + ' MB';
-
-            const percentComplete = (current / total) * 100;
-            progressBar.style.width = percentComplete + '%';
-            uploadPercent.innerText = 'Progress : ' + percentComplete.toFixed(2) + '%';
-        }
-        else if (data[0] === 'completed') {
-            clearInterval(interval);
-            uploadPercent.innerText = 'Progress : 100%'
-            progressBar.style.width = '100%';
-
-            await handleUpload2(id)
-        }
-    }, 3000)
-
-}
-
-async function handleUpload2(id) {
-    console.log(id)
-    document.getElementById('upload-status').innerText = 'Status: Uploading To Telegram Server';
-    progressBar.style.width = '0%';
-    uploadPercent.innerText = 'Progress : 0%';
-
-    const interval = setInterval(async () => {
-        const response = await postJson('/api/getUploadProgress', { 'id': id })
-        const data = response['data']
-
-        if (data[0] === 'running') {
-            const current = data[1];
-            const total = data[2];
-            document.getElementById('upload-filesize').innerText = 'Filesize: ' + (total / (1024 * 1024)).toFixed(2) + ' MB';
-
-            let percentComplete
-            if (total === 0) {
-                percentComplete = 0
-            }
-            else {
-                percentComplete = (current / total) * 100;
-            }
-            progressBar.style.width = percentComplete + '%';
-            uploadPercent.innerText = 'Progress : ' + percentComplete.toFixed(2) + '%';
-        }
-        else if (data[0] === 'completed') {
-            clearInterval(interval);
-            alert('Upload Completed')
-            window.location.reload();
-        }
-    }, 3000)
-}
-
-// File Uploader End
-
-
-// URL Uploader Start
-
-async function get_file_info_from_url(url) {
-    const data = { 'url': url }
-    const json = await postJson('/api/getFileInfoFromUrl', data)
-    if (json.status === 'ok') {
-        return json.data
-    } else {
-        throw new Error(`Error Getting File Info : ${json.status}`)
-    }
-
-}
-
-async function start_file_download_from_url(url, filename, singleThreaded) {
-    const data = { 'url': url, 'path': getCurrentPath(), 'filename': filename, 'singleThreaded': singleThreaded }
-    const json = await postJson('/api/startFileDownloadFromUrl', data)
-    if (json.status === 'ok') {
-        return json.id
-    } else {
-        throw new Error(`Error Starting File Download : ${json.status}`)
-    }
-}
-
-async function download_progress_updater(id, file_name, file_size) {
-    uploadID = id;
-    uploadStep = 2
-    // Showing file uploader
-    document.getElementById('bg-blur').style.zIndex = '2';
-    document.getElementById('bg-blur').style.opacity = '0.1';
-    document.getElementById('file-uploader').style.zIndex = '3';
-    document.getElementById('file-uploader').style.opacity = '1';
-
-    document.getElementById('upload-filename').innerText = 'Filename: ' + file_name;
-    document.getElementById('upload-filesize').innerText = 'Filesize: ' + (file_size / (1024 * 1024)).toFixed(2) + ' MB';
-
-    const interval = setInterval(async () => {
-        const response = await postJson('/api/getFileDownloadProgress', { 'id': id })
-        const data = response['data']
-
-        if (data[0] === 'error') {
-            clearInterval(interval);
-            alert('Failed To Download File From URL To Backend Server')
-            window.location.reload()
-        }
-        else if (data[0] === 'completed') {
-            clearInterval(interval);
-            uploadPercent.innerText = 'Progress : 100%'
-            progressBar.style.width = '100%';
-            await handleUpload2(id)
-        }
-        else {
-            const current = data[1];
-            const total = data[2];
-
-            const percentComplete = (current / total) * 100;
-            progressBar.style.width = percentComplete + '%';
-            uploadPercent.innerText = 'Progress : ' + percentComplete.toFixed(2) + '%';
-
-            if (data[0] === 'Downloading') {
-                document.getElementById('upload-status').innerText = 'Status: Downloading File From Url To Backend Server';
-            }
-            else {
-                document.getElementById('upload-status').innerText = `Status: ${data[0]}`;
-            }
-        }
-    }, 3000)
-}
-
-
-async function Start_URL_Upload() {
-    try {
-        document.getElementById('new-url-upload').style.opacity = '0';
-        setTimeout(() => {
-            document.getElementById('new-url-upload').style.zIndex = '-1';
-        }, 300)
-
-        const file_url = document.getElementById('remote-url').value
-        const singleThreaded = document.getElementById('single-threaded-toggle').checked
-
-        const file_info = await get_file_info_from_url(file_url)
-        const file_name = file_info.file_name
-        const file_size = file_info.file_size
-
-        if (file_size > MAX_FILE_SIZE) {
-            throw new Error(`File size exceeds ${(MAX_FILE_SIZE / (1024 * 1024 * 1024)).toFixed(2)} GB limit`)
-        }
-
-        const id = await start_file_download_from_url(file_url, file_name, singleThreaded)
-
-        await download_progress_updater(id, file_name, file_size)
-
-    }
-    catch (err) {
-        alert(err)
-        window.location.reload()
-    }
-
-
-}
-
-// URL Uploader End
\ No newline at end of file
diff --git a/website/static/js/extra.js b/website/static/js/extra.js
deleted file mode 100644
index 1f696514..00000000
--- a/website/static/js/extra.js
+++ /dev/null
@@ -1,119 +0,0 @@
-function getCurrentPath() {
-    const url = new URL(window.location.href);
-    const path = url.searchParams.get('path')
-    if (path === null) {
-        window.location.href = '/?path=/'
-        return 'redirect'
-    }
-    return path
-}
-
-function getFolderAuthFromPath() {
-    const url = new URL(window.location.href);
-    const auth = url.searchParams.get('auth')
-    return auth
-}
-
-// Changing sidebar section class
-if (getCurrentPath() !== '/') {
-    const sections = document.querySelector('.sidebar-menu').getElementsByTagName('a')
-    sections[0].setAttribute('class', 'unselected-item')
-
-    if (getCurrentPath().includes('/trash')) {
-        sections[1].setAttribute('class', 'selected-item')
-    }
-}
-
-function convertBytes(bytes) {
-    const kilobyte = 1024;
-    const megabyte = kilobyte * 1024;
-    const gigabyte = megabyte * 1024;
-
-    if (bytes >= gigabyte) {
-        return (bytes / gigabyte).toFixed(2) + ' GB';
-    } else if (bytes >= megabyte) {
-        return (bytes / megabyte).toFixed(2) + ' MB';
-    } else if (bytes >= kilobyte) {
-        return (bytes / kilobyte).toFixed(2) + ' KB';
-    } else {
-        return bytes + ' bytes';
-    }
-}
-
-const INPUTS = {}
-
-function validateInput(event) {
-    console.log('Validating Input')
-    const pattern = /^[a-zA-Z0-9 \-_\\[\]()@#!$%*+={}:;<>,.?/|\\~`]*$/;;
-    const input = event.target;
-    if (!pattern.test(input.value)) {
-        input.value = INPUTS[input.id]
-    } else {
-        INPUTS[input.id] = input.value
-    }
-}
-
-function getRootUrl() {
-    const url = new URL(window.location.href);
-    const protocol = url.protocol; // Get the protocol, e.g., "https:"
-    const hostname = url.hostname; // Get the hostname, e.g., "sub.example.com" or "192.168.1.1"
-    const port = url.port; // Get the port, e.g., "8080"
-
-    const rootUrl = `${protocol}//${hostname}${port ? ':' + port : ''}`;
-
-    return rootUrl;
-}
-
-function copyTextToClipboard(text) {
-    if (navigator.clipboard && navigator.clipboard.writeText) {
-        navigator.clipboard.writeText(text).then(function () {
-            alert('Link copied to clipboard!');
-        }).catch(function (err) {
-            console.error('Could not copy text: ', err);
-            fallbackCopyTextToClipboard(text);
-        });
-    } else {
-        fallbackCopyTextToClipboard(text);
-    }
-}
-
-function fallbackCopyTextToClipboard(text) {
-    const textArea = document.createElement('textarea');
-    textArea.value = text;
-    document.body.appendChild(textArea);
-    textArea.focus();
-    textArea.select();
-
-    try {
-        const successful = document.execCommand('copy');
-        if (successful) {
-            alert('Link copied to clipboard!');
-        } else {
-            alert('Failed to copy the link.');
-        }
-    } catch (err) {
-        console.error('Fallback: Oops, unable to copy', err);
-    }
-
-    document.body.removeChild(textArea);
-}
-
-function getPassword() {
-    return localStorage.getItem('password')
-}
-
-function getRandomId() {
-    const length = 6;
-    const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
-    let result = '';
-    for (let i = 0; i < length; i++) {
-        result += characters.charAt(Math.floor(Math.random() * characters.length));
-    }
-    return result;
-}
-
-function removeSlash(text) {
-    let charactersToRemove = "[/]+"; // Define the characters to remove inside square brackets
-    let trimmedStr = text.replace(new RegExp(`^${charactersToRemove}|${charactersToRemove}$`, 'g'), '');
-    return trimmedStr;
-}
\ No newline at end of file
diff --git a/website/static/js/fileClickHandler.js b/website/static/js/fileClickHandler.js
deleted file mode 100644
index 9e79364e..00000000
--- a/website/static/js/fileClickHandler.js
+++ /dev/null
@@ -1,214 +0,0 @@
-function openFolder() {
-    let path = (getCurrentPath() + '/' + this.getAttribute('data-id') + '/').replaceAll('//', '/')
-
-    const auth = getFolderAuthFromPath()
-    if (auth) {
-        path = path + '&auth=' + auth
-    }
-    window.location.href = `/?path=${path}`
-}
-
-function openFile() {
-    const fileName = this.getAttribute('data-name').toLowerCase()
-    let path = '/file?path=' + this.getAttribute('data-path') + '/' + this.getAttribute('data-id')
-
-    if (fileName.endsWith('.mp4') || fileName.endsWith('.mkv') || fileName.endsWith('.webm') || fileName.endsWith('.mov') || fileName.endsWith('.avi') || fileName.endsWith('.ts') || fileName.endsWith('.ogv')) {
-        path = '/stream?url=' + getRootUrl() + path
-    }
-
-    window.open(path, '_blank')
-}
-
-
-// File More Button Handler Start
-
-function openMoreButton(div) {
-    const id = div.getAttribute('data-id')
-    const moreDiv = document.getElementById(`more-option-${id}`)
-
-    const rect = div.getBoundingClientRect();
-    const x = rect.left + window.scrollX - 40;
-    const y = rect.top + window.scrollY;
-
-    moreDiv.style.zIndex = 2
-    moreDiv.style.opacity = 1
-    moreDiv.style.left = `${x}px`
-    moreDiv.style.top = `${y}px`
-
-    const isTrash = getCurrentPath().includes('/trash')
-
-    moreDiv.querySelector('.more-options-focus').focus()
-    moreDiv.querySelector('.more-options-focus').addEventListener('blur', closeMoreBtnFocus);
-    moreDiv.querySelector('.more-options-focus').addEventListener('focusout', closeMoreBtnFocus);
-    if (!isTrash) {
-        moreDiv.querySelector(`#rename-${id}`).addEventListener('click', renameFileFolder)
-        moreDiv.querySelector(`#trash-${id}`).addEventListener('click', trashFileFolder)
-        try {
-            moreDiv.querySelector(`#share-${id}`).addEventListener('click', shareFile)
-        }
-        catch { }
-        try {
-            moreDiv.querySelector(`#folder-share-${id}`).addEventListener('click', shareFolder)
-        }
-        catch { }
-    }
-    else {
-        moreDiv.querySelector(`#restore-${id}`).addEventListener('click', restoreFileFolder)
-        moreDiv.querySelector(`#delete-${id}`).addEventListener('click', deleteFileFolder)
-    }
-}
-
-function closeMoreBtnFocus() {
-    const moreDiv = this.parentElement
-    moreDiv.style.opacity = '0'
-    setTimeout(() => {
-        moreDiv.style.zIndex = '-1'
-    }, 300)
-}
-
-// Rename File Folder Start
-function renameFileFolder() {
-    const id = this.getAttribute('id').split('-')[1]
-    console.log(id)
-
-    document.getElementById('rename-name').value = this.parentElement.getAttribute('data-name');
-    document.getElementById('bg-blur').style.zIndex = '2';
-    document.getElementById('bg-blur').style.opacity = '0.1';
-
-    document.getElementById('rename-file-folder').style.zIndex = '3';
-    document.getElementById('rename-file-folder').style.opacity = '1';
-    document.getElementById('rename-file-folder').setAttribute('data-id', id);
-    setTimeout(() => {
-        document.getElementById('rename-name').focus();
-    }, 300)
-}
-
-document.getElementById('rename-cancel').addEventListener('click', () => {
-    document.getElementById('rename-name').value = '';
-    document.getElementById('bg-blur').style.opacity = '0';
-    setTimeout(() => {
-        document.getElementById('bg-blur').style.zIndex = '-1';
-    }, 300)
-    document.getElementById('rename-file-folder').style.opacity = '0';
-    setTimeout(() => {
-        document.getElementById('rename-file-folder').style.zIndex = '-1';
-    }, 300)
-});
-
-document.getElementById('rename-create').addEventListener('click', async () => {
-    const name = document.getElementById('rename-name').value;
-    if (name === '') {
-        alert('Name cannot be empty')
-        return
-    }
-
-    const id = document.getElementById('rename-file-folder').getAttribute('data-id')
-
-    const path = document.getElementById(`more-option-${id}`).getAttribute('data-path') + '/' + id
-
-    const data = {
-        'name': name,
-        'path': path
-    }
-
-    const response = await postJson('/api/renameFileFolder', data)
-    if (response.status === 'ok') {
-        alert('File/Folder Renamed Successfully')
-        window.location.reload();
-    } else {
-        alert('Failed to rename file/folder')
-        window.location.reload();
-    }
-});
-
-
-// Rename File Folder End
-
-async function trashFileFolder() {
-    const id = this.getAttribute('id').split('-')[1]
-    console.log(id)
-    const path = document.getElementById(`more-option-${id}`).getAttribute('data-path') + '/' + id
-    const data = {
-        'path': path,
-        'trash': true
-    }
-    const response = await postJson('/api/trashFileFolder', data)
-
-    if (response.status === 'ok') {
-        alert('File/Folder Sent to Trash Successfully')
-        window.location.reload();
-    } else {
-        alert('Failed to Send File/Folder to Trash')
-        window.location.reload();
-    }
-}
-
-async function restoreFileFolder() {
-    const id = this.getAttribute('id').split('-')[1]
-    const path = this.getAttribute('data-path') + '/' + id
-    const data = {
-        'path': path,
-        'trash': false
-    }
-    const response = await postJson('/api/trashFileFolder', data)
-
-    if (response.status === 'ok') {
-        alert('File/Folder Restored Successfully')
-        window.location.reload();
-    } else {
-        alert('Failed to Restored File/Folder')
-        window.location.reload();
-    }
-}
-
-async function deleteFileFolder() {
-    const id = this.getAttribute('id').split('-')[1]
-    const path = this.getAttribute('data-path') + '/' + id
-    const data = {
-        'path': path
-    }
-    const response = await postJson('/api/deleteFileFolder', data)
-
-    if (response.status === 'ok') {
-        alert('File/Folder Deleted Successfully')
-        window.location.reload();
-    } else {
-        alert('Failed to Delete File/Folder')
-        window.location.reload();
-    }
-}
-
-async function shareFile() {
-    const fileName = this.parentElement.getAttribute('data-name').toLowerCase()
-    const id = this.getAttribute('id').split('-')[1]
-    const path = document.getElementById(`more-option-${id}`).getAttribute('data-path') + '/' + id
-    const root_url = getRootUrl()
-
-    let link
-    if (fileName.endsWith('.mp4') || fileName.endsWith('.mkv') || fileName.endsWith('.webm') || fileName.endsWith('.mov') || fileName.endsWith('.avi') || fileName.endsWith('.ts') || fileName.endsWith('.ogv')) {
-        link = `${root_url}/stream?url=${root_url}/file?path=${path}`
-    } else {
-        link = `${root_url}/file?path=${path}`
-
-    }
-
-    copyTextToClipboard(link)
-}
-
-
-async function shareFolder() {
-    const id = this.getAttribute('id').split('-')[2]
-    console.log(id)
-    let path = document.getElementById(`more-option-${id}`).getAttribute('data-path') + '/' + id
-    const root_url = getRootUrl()
-
-    const auth = await getFolderShareAuth(path)
-    path = path.slice(1)
-
-    let link = `${root_url}/?path=/share_${path}&auth=${auth}`
-    console.log(link)
-
-    copyTextToClipboard(link)
-}
-
-// File More Button Handler  End
\ No newline at end of file
diff --git a/website/static/js/main.js b/website/static/js/main.js
deleted file mode 100644
index 9fe2c74b..00000000
--- a/website/static/js/main.js
+++ /dev/null
@@ -1,95 +0,0 @@
-function showDirectory(data) {
-    data = data['contents']
-    document.getElementById('directory-data').innerHTML = ''
-    const isTrash = getCurrentPath().startsWith('/trash')
-
-    let html = ''
-
-    // Step 2: Sort the array based on the 'date' values
-    let entries = Object.entries(data);
-    let folders = entries.filter(([key, value]) => value.type === 'folder');
-    let files = entries.filter(([key, value]) => value.type === 'file');
-
-    folders.sort((a, b) => new Date(b[1].upload_date) - new Date(a[1].upload_date));
-    files.sort((a, b) => new Date(b[1].upload_date) - new Date(a[1].upload_date));
-
-    for (const [key, item] of folders) {
-        if (item.type === 'folder') {
-            html += `<tr data-path="${item.path}" data-id="${item.id}" class="body-tr folder-tr"><td><div class="td-align"><img src="static/assets/folder-solid-icon.svg">${item.name}</div></td><td><div class="td-align"></div></td><td><div class="td-align"><a data-id="${item.id}" class="more-btn"><img src="static/assets/more-icon.svg" class="rotate-90"></a></div></td></tr>`
-
-            if (isTrash) {
-                html += `<div data-path="${item.path}" id="more-option-${item.id}" data-name="${item.name}" class="more-options"><input class="more-options-focus" readonly="readonly" style="height:0;width:0;border:none;position:absolute"><div id="restore-${item.id}" data-path="${item.path}"><img src="static/assets/load-icon.svg"> Restore</div><hr><div id="delete-${item.id}" data-path="${item.path}"><img src="static/assets/trash-icon.svg"> Delete</div></div>`
-            }
-            else {
-                html += `<div data-path="${item.path}" id="more-option-${item.id}" data-name="${item.name}" class="more-options"><input class="more-options-focus" readonly="readonly" style="height:0;width:0;border:none;position:absolute"><div id="rename-${item.id}"><img src="static/assets/pencil-icon.svg"> Rename</div><hr><div id="trash-${item.id}"><img src="static/assets/trash-icon.svg"> Trash</div><hr><div id="folder-share-${item.id}"><img src="static/assets/share-icon.svg"> Share</div></div>`
-            }
-        }
-    }
-
-    for (const [key, item] of files) {
-        if (item.type === 'file') {
-            const size = convertBytes(item.size)
-            html += `<tr data-path="${item.path}" data-id="${item.id}" data-name="${item.name}" class="body-tr file-tr"><td><div class="td-align"><img src="static/assets/file-icon.svg">${item.name}</div></td><td><div class="td-align">${size}</div></td><td><div class="td-align"><a data-id="${item.id}" class="more-btn"><img src="static/assets/more-icon.svg" class="rotate-90"></a></div></td></tr>`
-
-            if (isTrash) {
-                html += `<div data-path="${item.path}" id="more-option-${item.id}" data-name="${item.name}" class="more-options"><input class="more-options-focus" readonly="readonly" style="height:0;width:0;border:none;position:absolute"><div id="restore-${item.id}" data-path="${item.path}"><img src="static/assets/load-icon.svg"> Restore</div><hr><div id="delete-${item.id}" data-path="${item.path}"><img src="static/assets/trash-icon.svg"> Delete</div></div>`
-            }
-            else {
-                html += `<div data-path="${item.path}" id="more-option-${item.id}" data-name="${item.name}" class="more-options"><input class="more-options-focus" readonly="readonly" style="height:0;width:0;border:none;position:absolute"><div id="rename-${item.id}"><img src="static/assets/pencil-icon.svg"> Rename</div><hr><div id="trash-${item.id}"><img src="static/assets/trash-icon.svg"> Trash</div><hr><div id="share-${item.id}"><img src="static/assets/share-icon.svg"> Share</div></div>`
-            }
-        }
-    }
-    document.getElementById('directory-data').innerHTML = html
-
-    if (!isTrash) {
-        document.querySelectorAll('.folder-tr').forEach(div => {
-            div.ondblclick = openFolder;
-        });
-        document.querySelectorAll('.file-tr').forEach(div => {
-            div.ondblclick = openFile;
-        });
-    }
-
-    document.querySelectorAll('.more-btn').forEach(div => {
-        div.addEventListener('click', function (event) {
-            event.preventDefault();
-            openMoreButton(div)
-        });
-    });
-}
-
-document.getElementById('search-form').addEventListener('submit', async (event) => {
-    event.preventDefault();
-    const query = document.getElementById('file-search').value;
-    console.log(query)
-    if (query === '') {
-        alert('Search field is empty');
-        return;
-    }
-    const path = '/?path=/search_' + encodeURI(query);
-    console.log(path)
-    window.location = path;
-});
-
-// Loading Main Page
-
-document.addEventListener('DOMContentLoaded', function () {
-    const inputs = ['new-folder-name', 'rename-name', 'file-search']
-    for (let i = 0; i < inputs.length; i++) {
-        document.getElementById(inputs[i]).addEventListener('input', validateInput);
-    }
-
-    if (getCurrentPath().includes('/share_')) {
-        getCurrentDirectory()
-    } else {
-        if (getPassword() === null) {
-            document.getElementById('bg-blur').style.zIndex = '2';
-            document.getElementById('bg-blur').style.opacity = '0.1';
-
-            document.getElementById('get-password').style.zIndex = '3';
-            document.getElementById('get-password').style.opacity = '1';
-        } else {
-            getCurrentDirectory()
-        }
-    }
-});
diff --git a/website/static/js/sidebar.js b/website/static/js/sidebar.js
deleted file mode 100644
index 0c760203..00000000
--- a/website/static/js/sidebar.js
+++ /dev/null
@@ -1,102 +0,0 @@
-// Handling New Button On Sidebar Click
-const isTrash = getCurrentPath().startsWith('/trash')
-const isSearch = getCurrentPath().startsWith('/search')
-const isShare = getCurrentPath().startsWith('/share')
-
-if (!isTrash && !isSearch) {
-    document.getElementById('new-button').addEventListener('click', () => {
-        document.getElementById('new-upload').style.zIndex = '1'
-        document.getElementById('new-upload').style.opacity = '1'
-        document.getElementById('new-upload').style.top = '80px'
-        document.getElementById('new-upload-focus').focus()
-    });
-}
-else {
-    document.getElementById('new-button').style.display = 'none'
-}
-
-if (isShare) {
-    document.getElementById('new-button').style.display = 'none'
-    const sections = document.querySelector('.sidebar-menu').getElementsByTagName('a')
-    sections[1].remove()
-}
-
-// New File Upload Start
-
-function closeNewUploadFocus() {
-    setTimeout(() => {
-        document.getElementById('new-upload').style.opacity = '0'
-        document.getElementById('new-upload').style.top = '40px'
-        setTimeout(() => {
-            document.getElementById('new-upload').style.zIndex = '-1'
-        }, 300)
-    }, 200)
-}
-document.getElementById('new-upload-focus').addEventListener('blur', closeNewUploadFocus);
-document.getElementById('new-upload-focus').addEventListener('focusout', closeNewUploadFocus);
-
-document.getElementById('file-upload-btn').addEventListener('click', () => {
-    document.getElementById('fileInput').click()
-});
-
-// New File Upload End
-
-// New Folder Start
-
-document.getElementById('new-folder-btn').addEventListener('click', () => {
-    document.getElementById('new-folder-name').value = '';
-    document.getElementById('bg-blur').style.zIndex = '2';
-    document.getElementById('bg-blur').style.opacity = '0.1';
-
-    document.getElementById('create-new-folder').style.zIndex = '3';
-    document.getElementById('create-new-folder').style.opacity = '1';
-    setTimeout(() => {
-        document.getElementById('new-folder-name').focus();
-    }, 300)
-})
-
-document.getElementById('new-folder-cancel').addEventListener('click', () => {
-    document.getElementById('new-folder-name').value = '';
-    document.getElementById('bg-blur').style.opacity = '0';
-    setTimeout(() => {
-        document.getElementById('bg-blur').style.zIndex = '-1';
-    }, 300)
-    document.getElementById('create-new-folder').style.opacity = '0';
-    setTimeout(() => {
-        document.getElementById('create-new-folder').style.zIndex = '-1';
-    }, 300)
-});
-
-document.getElementById('new-folder-create').addEventListener('click', createNewFolder);
-
-// New Folder End
-
-// New Url Upload Start
-
-document.getElementById('url-upload-btn').addEventListener('click', () => {
-    document.getElementById('remote-url').value = '';
-    document.getElementById('bg-blur').style.zIndex = '2';
-    document.getElementById('bg-blur').style.opacity = '0.1';
-
-    document.getElementById('new-url-upload').style.zIndex = '3';
-    document.getElementById('new-url-upload').style.opacity = '1';
-    setTimeout(() => {
-        document.getElementById('remote-url').focus();
-    }, 300)
-})
-
-document.getElementById('remote-cancel').addEventListener('click', () => {
-    document.getElementById('remote-url').value = '';
-    document.getElementById('bg-blur').style.opacity = '0';
-    setTimeout(() => {
-        document.getElementById('bg-blur').style.zIndex = '-1';
-    }, 300)
-    document.getElementById('new-url-upload').style.opacity = '0';
-    setTimeout(() => {
-        document.getElementById('new-url-upload').style.zIndex = '-1';
-    }, 300)
-});
-
-document.getElementById('remote-start').addEventListener('click', Start_URL_Upload);
-
-// New Url Upload End
\ No newline at end of file
diff --git a/website/tsconfig.json b/website/tsconfig.json
new file mode 100644
index 00000000..239d814a
--- /dev/null
+++ b/website/tsconfig.json
@@ -0,0 +1,16 @@
+{
+    "compilerOptions": {
+        "target": "ES2023",
+        "lib": ["ES2023", "DOM", "DOM.Iterable"],
+        "module": "ESNext",
+        "moduleResolution": "Bundler",
+        "jsx": "react-jsx",
+        "strict": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "isolatedModules": true,
+        "allowImportingTsExtensions": true,
+        "types": ["vite/client"]
+    },
+    "include": ["src", "vite.config.ts"]
+}
diff --git a/website/vendor/README.md b/website/vendor/README.md
new file mode 100644
index 00000000..6dbe4a5f
--- /dev/null
+++ b/website/vendor/README.md
@@ -0,0 +1,39 @@
+# TGDrive viewer packages
+
+The frontend installs these committed npm archives directly. Normal installs,
+development, tests and builds do not patch `node_modules`.
+
+Each archive contains the complete exact upstream package, including all exports,
+type declarations and licenses. TGDrive changes one reviewed JavaScript runtime
+file, adds `TGDRIVE-NOTICE.txt` and gives the package a local version suffix. The
+decoder WASM is unchanged. `manifest.json` records upstream integrity, local
+archive integrity, individual file hashes and the patch recipe identity.
+
+## Update deliberately
+
+1. Review the pinned upstream URLs/integrities in `scripts/vendor_viewers.py` and
+   the recipes in `website/scripts/patch-movi-player.js` and `patch-pdf-worker.js`.
+2. From the repository root, use supported Node.js 24.22:
+
+   ```bash
+   python scripts/vendor_viewers.py --node node
+   ```
+
+   The generator downloads only those exact upstream archives and verifies their
+   SHA-512 integrity before reading members. `--upstream-dir PATH` uses already
+   downloaded archives with the same integrity requirement. `--output-dir PATH`
+   produces candidates outside this directory for comparison.
+3. Review the archive/manifest diff, update the local dependency filenames and
+   lockfile with lifecycle scripts disabled, and run the approved focused viewer
+   checks before updating release artifacts.
+
+Archive order, ownership, permissions and gzip/tar timestamps are normalized.
+The same inputs and Python/zlib runtime reproduce the same bytes; the manifest
+contains no generation timestamps or machine-specific paths. No upstream install
+or package lifecycle scripts run during generation.
+
+Preserve `website/public/third-party/` in runtime releases. It contains the public
+licenses and Movi decoder source/relink archive. Vendoring the JavaScript does not
+replace those materials. PDF.js resource licenses remain in its complete package; preserve each relevant
+license alongside the CMaps, fonts, color profiles and decoder assets emitted by
+the frontend build.
diff --git a/website/vendor/manifest.json b/website/vendor/manifest.json
new file mode 100644
index 00000000..d0d184bc
--- /dev/null
+++ b/website/vendor/manifest.json
@@ -0,0 +1,1093 @@
+{
+    "schema_version": 1,
+    "packages": {
+        "movi-player": {
+            "upstream": {
+                "version": "0.4.1",
+                "url": "https://registry.npmjs.org/movi-player/-/movi-player-0.4.1.tgz",
+                "integrity": "sha512-oA91s8nxyt7tnd7SaZNKVkjkz8UeHVrcZNxWQSBo5Jj/MOog7pnGtwv0edimjwocJkZVBBtBMy8Ef4HOGzBJGQ==",
+                "sha256": "11456922d3b526c669555c8a71f09a13e4dbd5008addce730234aa1513531b2d",
+                "bytes": 51226747
+            },
+            "vendored": {
+                "version": "0.4.1-tgdrive.1",
+                "archive": "movi-player-0.4.1-tgdrive.1.tgz",
+                "integrity": "sha512-7TVpUAklTBPtgdxJGWh8771ZNvLt8uF6aQ8R7i7iNOu/np0gEMTVmfv0WRwKEwnTnJvBBUnA9qMaZwnSLGx2Eg==",
+                "sha256": "c927e6c472d68edf94a8f2b7070a0f7db988ac04ae2d204bf118f28862a89db9",
+                "bytes": 50950006,
+                "package_json_sha256": "8a92e89a5d2502be09d4d66d0608a7d952c04b0e6388251203bf6d6f662fdef8",
+                "package_files_sha256": "35f478fe3fbc55705df1315168b330e03cb609de9eb4311b094c982f85e57fb3",
+                "file_count": 477
+            },
+            "patch": {
+                "file": "dist/element.slim.js",
+                "upstream_sha256": "834efaa395f82503fdea3538e03c2ad83f01a7fc409ca93d93dea500affa63c7",
+                "vendored_sha256": "01f6e03d105bc78bc94ea2dbfdbf18308bad7a46cc283ceb68eb8edbbaf7bc6c",
+                "recipe": "website/scripts/patch-movi-player.js",
+                "recipe_sha256": "8968027519e8ce9f1174d79ce25c6ea7e46aff26ddb89c1dcbf75b730a214dc6"
+            },
+            "files_sha256": {
+                "AGENTS.md": "c40bdfa0174a711557eee188c916a19ecc1aa0f3fcdc0e8d1c14a2afc870d124",
+                "LICENSE": "ea3f732c7310bc1a3bdab94e82b9ed0addb63efbdb8175611a184bf07ef9bfee",
+                "README.md": "40628cc724bdc82f87b30ed2e645eab12d46363f35362911fb35df43b1f6450e",
+                "TGDRIVE-NOTICE.txt": "80725016574853b368ff1c5e0c9fb4a02e1116d57a71f40e35974b7cf19ecebe",
+                "custom-elements.json": "5a9bb21da664f232c311dcd31e719c85289883590ab2000f07716950b80a2412",
+                "dist/build-flags.d.ts": "14bf92986cbaf26c57e66c10c7f947282bf64b311bae07a465a2862b9451961c",
+                "dist/build-flags.d.ts.map": "c44ffca6c3169cdc104730ce397634e630d2858846b3302a8086a4ed2178a3ae",
+                "dist/build-flags.js": "be7895b38d124d5af8c8d4e768bd397ae72d9759e815d7412e2b09c16e8eec3a",
+                "dist/build-flags.js.map": "e2ac30a1ce41b8f7390460db14aa5dab4504c009a3de184f5196fcb400a847ea",
+                "dist/cache/CacheAdapter.d.ts": "cb6339ddd6cc216aa842c8e5d66c841bbfa339b80fbe22f815c408318c73ffba",
+                "dist/cache/CacheAdapter.d.ts.map": "3af274935c4fe82d1f2678fd53dd60a83b7ffa744445c06c555048808b7b5eb8",
+                "dist/cache/CacheAdapter.js": "6625b76dbc7bc0d714bb4d811de9e2ddf15ddec800fd4824d9ff9e9915d9fe88",
+                "dist/cache/CacheAdapter.js.map": "36b586d1920ffc5691aff8b97d10c72ebdf9696b02f17560c6d08b38989f07f9",
+                "dist/cache/LRUCache.d.ts": "d9316ea78d6a1b6eba218471525ca87c27f388e392a46b87eaa1aa95a559bce1",
+                "dist/cache/LRUCache.d.ts.map": "ab15794a54f808a33eed8519c10d7b93464c898ae3a7db7304dc5234803f9ccc",
+                "dist/cache/LRUCache.js": "5d60ec111feddd9a001f4cc71c0d52e011e134ca1c99015d7eba53f3cf0a8afc",
+                "dist/cache/LRUCache.js.map": "e3768c892d89582b2f17920e8751b194cc38ebd87170228c87ad96990c502f24",
+                "dist/cache/index.d.ts": "7e124b2775b504485cf2d6a237c117afdfcb021a7f51ab6a41902d9a2e9ef66b",
+                "dist/cache/index.d.ts.map": "b630106d034cf401c862dacd09b3a43a18a1703d3b133feda6a6767050fe257b",
+                "dist/cache/index.js": "827deedea58fabfb845e5cd1762647c87424ea3679b48fb4ede41b734b58f994",
+                "dist/cache/index.js.map": "c69fea212b0d7da7964d941bea8b82cc7d2289cfb520a96e9f6051da72efd888",
+                "dist/core/Clock.d.ts": "ec6cddd82042e3d6eca5f862209a377dc3e9c1802898fa0c873769d93c67fed9",
+                "dist/core/Clock.d.ts.map": "ee019d15b9c5a462205dc8cd0d2fc07713e9e7f700b6c91ed55ec347881dd512",
+                "dist/core/Clock.js": "01b6e7aa6ed5703650cb04f927084ef0184d859d68d8665250362c7ef2d2c71d",
+                "dist/core/Clock.js.map": "a0c934c366986a5a6aabef8bfb178bde301071b4e9dee857e5a05d473612e61c",
+                "dist/core/MoviPlayer.d.ts": "478c6dfe69b15fdf7b8a84e6978684e0ca989908dbeac695e5a68d4a839c7322",
+                "dist/core/MoviPlayer.d.ts.map": "958c57076dfd8da8d8a5d0f79393c58b4a795f8b45bbddb526de24a54e0eac5c",
+                "dist/core/MoviPlayer.js": "f25b45442bd2e3659015bfddf44109fa17f4b63d7a257c85e3bfd7e8fb812fe9",
+                "dist/core/MoviPlayer.js.map": "319b85fe0a7c08367424a9e4fb927b4c4ab2efcc15faa5b5de6fed331e113e32",
+                "dist/core/PlaybackController.d.ts": "6bf96915fc0408e056c2f424e27a74a6d94b802c4c9e0e4305c7880a4ba8eb10",
+                "dist/core/PlaybackController.d.ts.map": "91bcd71071e92eb5c937dd620eb1b543db4604b3cd831344ee5a8bdd8c2bb74b",
+                "dist/core/PlaybackController.js": "06f17b753eda20be90e2dc9ccca3c92e64b5de4798836c9994466496f7740cd6",
+                "dist/core/PlaybackController.js.map": "f2af6e07d78ae12815e54ec50ec8e5daf05d38d94f85e8cdb85299b05534ba0a",
+                "dist/core/PlayerState.d.ts": "127d1fd0f15df3938afbbd26f83c33cb9a89009dbe1824e28ef8513ffad928e9",
+                "dist/core/PlayerState.d.ts.map": "7fa2254cf10379fc7801e6bdf64784486404d0bd4bdb4fb456e4c3fb0b448004",
+                "dist/core/PlayerState.js": "0a94a0f384e27cd8617c11046f4e7eecb8d4ef4cebdeaf5c9d905452f7418d8d",
+                "dist/core/PlayerState.js.map": "fa105f7601b77027e39c81e9d051b5d9ca62dd036e838bcd554c0cda93f36e66",
+                "dist/core/TrackManager.d.ts": "62b66c202d37eecbffa3ec3ca15cb2e848060956eecf7b857d3d2fdc691b5b37",
+                "dist/core/TrackManager.d.ts.map": "d01b504b00ef62899e50c918a2bd9de7358e3f07f99f349eeb4e8945d39bce8f",
+                "dist/core/TrackManager.js": "7d073124801aa754b91f1b6550f05c62e109e7d57ed1266adc48822dbaab18be",
+                "dist/core/TrackManager.js.map": "451840793ae8ec95be01d26157cbc39bec38fca2e527e0d682f9411828905086",
+                "dist/core/index.d.ts": "9ced3050f45a371b4245d5366d05c11efe7916a1baa252342b8ccf3f7bed6b5c",
+                "dist/core/index.d.ts.map": "26eb2a21bed369253e41a4555d53aa154ee846897020778d640ae8b96cf6c21a",
+                "dist/core/index.js": "df3d40f066f1e62f6f74996905c09954b427aa35c415317efed398a32b9454da",
+                "dist/core/index.js.map": "3acca557283ad432ab33280d73fcceb4d2daba6443ece8de496a61fb2d708384",
+                "dist/dav1d/include/dav1d/common.h": "62bcebef397d127de595d24164730a026670a3428303f809aed59f7aa26175a6",
+                "dist/dav1d/include/dav1d/data.h": "283e79ba35c3f90083d68f729a82a3d3625945c0776de5e87b4c081f0296a529",
+                "dist/dav1d/include/dav1d/dav1d.h": "dbc211a0f5480d8c38877dc18380fbd7cd6bb8375ac49a599e0c6e5f5e3ae15e",
+                "dist/dav1d/include/dav1d/headers.h": "3349f02ca7ebc5a09d9a623f83b820769903f86313638a9277b930cdd8071fe8",
+                "dist/dav1d/include/dav1d/picture.h": "66680595e5c6686395073ce55a5dc123369daa7d2f2a0c6df9a13ce8cfb57e17",
+                "dist/dav1d/include/dav1d/version.h": "ee63fe5d8bba3a84ed9e57360ea593dbd81c7e9b731e2e02ca2724f813b89fdd",
+                "dist/dav1d/lib/libdav1d.a": "320514fe8414645c604e51f05ec6910607028d8ff7d65e4708fa3f3f39724c88",
+                "dist/dav1d/lib/pkgconfig/dav1d.pc": "a91b5d1be94c76e295dd0af7d2abf32a715746f8b2ecf9be690d97e9a7672925",
+                "dist/decode/AudioDecoder.d.ts": "da4ec1afe0c1ebc0f68d3614672d66eba674a9ddf2b284d3bb17051a5f934d17",
+                "dist/decode/AudioDecoder.d.ts.map": "614ece897adc897a2597c71f20af57c2790692d722a8ee9cfe52955ba6c48711",
+                "dist/decode/AudioDecoder.js": "8e7898d92de0cba6965effb9fb123e3e35abfd81c6e9b3668139457540e5394f",
+                "dist/decode/AudioDecoder.js.map": "e5d8e9518e4f8bf57995df55cdd49c90bb53403e3f805222d27705e0ab5b6ece",
+                "dist/decode/CodecParser.d.ts": "86f4d57ad022cd39016415f7a57b0a7e8051cb8eb7a24aa2943598c33d076a7e",
+                "dist/decode/CodecParser.d.ts.map": "9bd2824d277dc43ea556ce07099f793f94791bd48c13e9450bc9d6c52785e9df",
+                "dist/decode/CodecParser.js": "32b9b64802bcc0c76318f5eb95a217d6ba59d0e7c2fb2bf809703244b3b44d93",
+                "dist/decode/CodecParser.js.map": "7507512dd332ef60f270877d681b0f9b2b837f9c4a825d72c8afbe1350a8d214",
+                "dist/decode/SoftwareAudioDecoder.d.ts": "1e90243293ee63f2106f7ddc6698d16d26dba0175e712a7a34486e7f95828962",
+                "dist/decode/SoftwareAudioDecoder.d.ts.map": "0e533fa0aae46c51d4864f7de8714dbc503ab1a186f65566614a02f68aeb635e",
+                "dist/decode/SoftwareAudioDecoder.js": "b2f940f0bc54b997212fbd9c57c59d04ce49fac74acd161b2ae88830b2f3960c",
+                "dist/decode/SoftwareAudioDecoder.js.map": "442bca4c8b6c6561ce81d5b686355e25ef52ddf8e3d6c490b2bea1dc953bc04a",
+                "dist/decode/SoftwareVideoDecoder.d.ts": "18794710a5cb4fe999f875f16d7030bed00d9537d47948c4f58c23d097e770d4",
+                "dist/decode/SoftwareVideoDecoder.d.ts.map": "ef56e1a14e07ca7a9a9f19c078382af9e7fb5e3ca90820565183163a9a4cff0f",
+                "dist/decode/SoftwareVideoDecoder.js": "97d788e2bf84d134758781c3369be9592ab8bcac86e1cdc2a98a308927b3140e",
+                "dist/decode/SoftwareVideoDecoder.js.map": "0425a6b574f29b5a883102001caa7478a1b5919edcf8b4a73976b391def7a34e",
+                "dist/decode/SubtitleDecoder.d.ts": "ca98bd34260e2a5fd773a72fd01355b26e3268b77dfe14dbc79bff4935bc3add",
+                "dist/decode/SubtitleDecoder.d.ts.map": "27aacf79045916ebbdd2fba0339eee606a4c104780d3b42a0d300b8bdf428105",
+                "dist/decode/SubtitleDecoder.js": "b9e0d561e5fa2fc83859ef8a84136e3cb0fc03bdd9a8ed7e58b54a2968065c51",
+                "dist/decode/SubtitleDecoder.js.map": "d25725e6fec48450ccaea232f2fbac651c0be5aeaba990f9278e36f274d647fa",
+                "dist/decode/VideoDecoder.d.ts": "9002fd78023a7d1d1554127b8392e2ebb221a53e8aa86af4f91bbb0650bff31f",
+                "dist/decode/VideoDecoder.d.ts.map": "0c7cb761bf65c3eb8042c26fb525dfb3ddf92c019782811e77ff5a51d95144e8",
+                "dist/decode/VideoDecoder.js": "739b063a0b28cb463b4c896bbbd079f254c7d40eefbb633ebeae38fac4321e85",
+                "dist/decode/VideoDecoder.js.map": "1ed9ad818d11144adc96a1b7596fb83721aac75609c375c807be6d29fae2f518",
+                "dist/decode/index.d.ts": "dcc849dc6ac8d14fe81a5f431d50c957d767e4fb57addc370bdb365800bcc91a",
+                "dist/decode/index.d.ts.map": "2e07232b38b661524f1662eec554803c40be2cda0e407a8446b4f245c7fe7a25",
+                "dist/decode/index.js": "6ff5e30c82ca3b704b112e706bcb1580bd6215baaa6ed44f0dc9482c1e7f2e8f",
+                "dist/decode/index.js.map": "d10ebf8174a92ebe4066262f27e5df8429b7de060beff069c14bde31d22012e1",
+                "dist/demux/Demuxer.d.ts": "5da521d92c24d4592b4b25b86b18a5dd0ff97fc8041215ff4c35c34d56e579ad",
+                "dist/demux/Demuxer.d.ts.map": "df4fe77aeeb547b4aed88796416c2d66bcb9d1c61dc1864c32471ce218fe3358",
+                "dist/demux/Demuxer.js": "3ec07dc54cf7547434c8845849f5098250c53157fb5027913e10c41c1e7b4c32",
+                "dist/demux/Demuxer.js.map": "6f5bdfeffd60f2b99c9dd8f40b656ca56dbccbbf9491b75b83a89ceeb8385bc1",
+                "dist/demux/index.d.ts": "3102602dd1c5fbbaa5fa80534f99e9969026fad9bf707b26fad1852523a6b8f7",
+                "dist/demux/index.d.ts.map": "d5d2b2d231d23eecca64dbad453833b7cad749a16caf686c588bb4a7c531a592",
+                "dist/demux/index.js": "637ca4ec535d7d96778067e0d08fd135cfd0cfa9e0a46ba7eae457001c39dbb8",
+                "dist/demux/index.js.map": "661e07df5281ae253b234cc0a58f7180cfdbce227811ef26db8bec0d2baf2b32",
+                "dist/demuxer.cjs": "757b83ed76b42b30be5ab45dfe5eb38c87ca1bf54e5aca24692f8d1f09c91bfa",
+                "dist/demuxer.d.ts": "5341810361956260ed8e4f53b4c57ac15ece2ce13d3b2985566e14338b2bac0a",
+                "dist/demuxer.d.ts.map": "74db342c82f458ada79cb1f7472dae62908f70a3710dd3dd9dda32901d8a31d8",
+                "dist/demuxer.js": "8bf2f60a8bd87bec0bb1f00ad41a54b66d547ed09d57dd01a5db547c74400ae1",
+                "dist/demuxer.js.map": "d5c7d22aa1ac6d05f90d5eab641bb190c658efedb0020ceb67d20255bf1b3f26",
+                "dist/element-slim.d.ts": "e47f7c5faf42b802395304c287e1ef7addc3291b7b126744afe9252040558097",
+                "dist/element-slim.d.ts.map": "d1066142b4e5e6f1ebde8f7081eeeb8e1abbfd26f66a41d5dedcf1bb1fee7e76",
+                "dist/element-slim.js": "9fb1e93037080bf1acca56002ef21b342ead21bfb8c6559c276f21b8791f62a5",
+                "dist/element-slim.js.map": "72a9454672e0ef0c459eae7700a1ca21f7fb518e9a415d8cbdecfdaa505fdf24",
+                "dist/element.cjs": "32dc7c7fa6a82c86f57acf929790224fd1f4a9b602936360420d95aff44ee99c",
+                "dist/element.d.ts": "8add69c0fd12353139d9d86ae8b74290d01d8926bb500ba3ef0629ff0076e662",
+                "dist/element.d.ts.map": "c35abab8691fac4192ba56aef213fd925aca7e1c76cc1fd16b4b6a829c99c118",
+                "dist/element.global.js": "fe01849c9076c0b5462fbc769b4bb300a9a9f6796945cbb3e6165ef014ab6f7c",
+                "dist/element.js": "0250d186acc001e3766d217f344016043f3d600d81e86fb2c46346dd8b7cd5d8",
+                "dist/element.js.map": "93b685697d776961a98c8b3eef594a78b1156dc200344e4ea8fceb242f06c847",
+                "dist/element.slim.cjs": "5d527ea8bcf27dea840e976da66fd263c485da3ee7ce8b2ae5194a1f17d93c13",
+                "dist/element.slim.global.js": "2da55c476a42fb3edd954eb31dbea5d99c0e02a3b3bda26a86c096e6ee027c1d",
+                "dist/element.slim.js": "01f6e03d105bc78bc94ea2dbfdbf18308bad7a46cc283ceb68eb8edbbaf7bc6c",
+                "dist/events/EventEmitter.d.ts": "2956957390cf117fa99d592f014398fe39d4e3e9023deee0943e6462c62a9cad",
+                "dist/events/EventEmitter.d.ts.map": "6ee0e5ac312e83693748b6e1ac18278d5111eabd98bb9d37111a6ccf5c300a72",
+                "dist/events/EventEmitter.js": "901f806ee93712aef38937a2f1c059ea10bad48f668da3adee493a96f2825033",
+                "dist/events/EventEmitter.js.map": "813d77216b4d12db430d086e27b7eb1d4278e7500eb7fc8a5902ab8ece56e326",
+                "dist/events/index.d.ts": "64bba77dbea96e7a0308e2dcbba9f2ff5688f32912074b8c2dfeeab51266f3df",
+                "dist/events/index.d.ts.map": "9644c86764253ed9b2c0cbe7f61fdaf2ae4a5cbe045167a8db9bdaeba2788f1c",
+                "dist/events/index.js": "cfbe60563c0ab7b10efbb289f824f74c6fd241b93a8329c57a66cd554ad38636",
+                "dist/events/index.js.map": "96227e5ac0b38dd715899d8a26859546ea363b32f98ea556f3d0251008b56250",
+                "dist/ffmpeg/include/libavcodec/ac3_parser.h": "200c6d2e96975196e8ba5f5716223dc9dda999d51578dabce2fca93175a05252",
+                "dist/ffmpeg/include/libavcodec/adts_parser.h": "d466583a8dc1260b015e588adbe3abd45f3f8ca0e43722f3088b472e80492a15",
+                "dist/ffmpeg/include/libavcodec/avcodec.h": "324452903f0d3b4bb4078652ca32c9ca29d7b3db5e005e1af04487409bd3090d",
+                "dist/ffmpeg/include/libavcodec/avdct.h": "c13d581750798e92f6d93e5903fbfdf81ee3a3b56003cbb2683f95d87e84b725",
+                "dist/ffmpeg/include/libavcodec/bsf.h": "cc26676aa44638fa5cbef953d967e19e2084b46aaa100f0a35ba2d34b302301c",
+                "dist/ffmpeg/include/libavcodec/codec.h": "ad4550b3f8ff7c7dd1c79a373721ba43273c4d1f156c683e11e27f9b5d89be1a",
+                "dist/ffmpeg/include/libavcodec/codec_desc.h": "d1fc6e89a3a7e49e61893620e00256d4f00db994764435ebe159b46a3c4326b5",
+                "dist/ffmpeg/include/libavcodec/codec_id.h": "765765fee16f9551ebd4fb5441fc6e5fc3d93c4754703831673bf887f2b1c87d",
+                "dist/ffmpeg/include/libavcodec/codec_par.h": "c33270179f2d44d94a75438923400f6a1c6dacf7b755692e723e3101cbeb65d3",
+                "dist/ffmpeg/include/libavcodec/d3d11va.h": "0a5b324124f3dd67942bac8d8288aba152215fb0ef2dede40d492198e0989346",
+                "dist/ffmpeg/include/libavcodec/defs.h": "f1d391ac2417702b59b7a4b6ae3927eea8c8b5e9858ae9ade6fdd009a60bd9ce",
+                "dist/ffmpeg/include/libavcodec/dirac.h": "09fd1f670422ee61713568abd90fdf371b30e6fe35bc6fb8213f1ad32b45cf56",
+                "dist/ffmpeg/include/libavcodec/dv_profile.h": "19f59e0b20ac583de4bfd76d18889d334bf0b6cdf7b5356723a33f3874738466",
+                "dist/ffmpeg/include/libavcodec/dxva2.h": "3a603c2cf8bc00d0c9df6cc80a5f0ed091d48d20303713baac1c7e432619f0bb",
+                "dist/ffmpeg/include/libavcodec/exif.h": "f3305bce9777fe9bafdb6abf2b90ebdd9c3b17a4149b33002d8c22d1c4d9a6d3",
+                "dist/ffmpeg/include/libavcodec/jni.h": "f98405ffb7ba26665cde92daef33bc4371c91aa6c85b522b36864ed289600ebc",
+                "dist/ffmpeg/include/libavcodec/mediacodec.h": "1f64544000dd2f2ec94604d5fcf7c2a6d26d32d085264356084a4b53a7f0c3f0",
+                "dist/ffmpeg/include/libavcodec/packet.h": "2e10c19c2fd953a5f18198eea1106334254d963f86df7999857c293dee8ac056",
+                "dist/ffmpeg/include/libavcodec/qsv.h": "e45780237ab0e9ea9ec11aab9f62dfb8b059138f846632ecacdc024db16dfb1b",
+                "dist/ffmpeg/include/libavcodec/smpte_436m.h": "6e5a93aad21b7c098fb8ac5d1e4ba469887f8cfce0eb21762b35c2fd1097f2a8",
+                "dist/ffmpeg/include/libavcodec/vdpau.h": "014ec822b00aa33305d503ea128c04287e7d1265194fda3a91cc00cd2a763272",
+                "dist/ffmpeg/include/libavcodec/version.h": "fd125ee7795a7ada495fb5491f01f09b72aa81d7c01ffb0aa42bc24e7b019b6f",
+                "dist/ffmpeg/include/libavcodec/version_major.h": "4ce6f0974cff7069900045ee551001bb57902a2f5ec0b5f538fbc1e4e9f6aa83",
+                "dist/ffmpeg/include/libavcodec/videotoolbox.h": "b182be72a4404f99dc761680193f647c47c2a792ab50d975f6d8b75984c6f5b9",
+                "dist/ffmpeg/include/libavcodec/vorbis_parser.h": "57077b2e1d28d42636cab0f69e4b92b1ad64ac2eaa2843c270a6afaf308a76ae",
+                "dist/ffmpeg/include/libavformat/avformat.h": "694da025f30497481f4703e06de106bd417a5718f8fdcdf5e09e34f4b5f21114",
+                "dist/ffmpeg/include/libavformat/avio.h": "30312971fc299e65bc69cf1beddb76f50394e044d9c71fe32fec3ae9c13bd1af",
+                "dist/ffmpeg/include/libavformat/version.h": "6e75a8cd7772f334958ffce859e3e23987963e3b406f12d9ec71650ca437fb92",
+                "dist/ffmpeg/include/libavformat/version_major.h": "436db6c1b56db87e83682639fd0285e8b0138acc4fb572868c70a690eda7bb5e",
+                "dist/ffmpeg/include/libavutil/adler32.h": "f21a861957bf4b1812ed67fdc528890f9cff1bb483facf0f5109e4a51932fe3b",
+                "dist/ffmpeg/include/libavutil/aes.h": "0a86ebeaf9ed33548bf0f92359f7047e521d4d80fe6b0ef1c8ef9505e38b6d28",
+                "dist/ffmpeg/include/libavutil/aes_ctr.h": "fbbb94888bfab2ea7141e7e1afa5872de099e7ee57baea17632c3d4fdd2cba3f",
+                "dist/ffmpeg/include/libavutil/ambient_viewing_environment.h": "00135de08089f8c711bb113588f80575a1d26e86d50b6dac5928a27a0ff9a8c7",
+                "dist/ffmpeg/include/libavutil/attributes.h": "041300e50a7e4c97d5ab3ea8c92d3db637e7047c8cb021f64ead2874391ee954",
+                "dist/ffmpeg/include/libavutil/audio_fifo.h": "3c513ca46927346c0673cd9db302afe62dbbf976844f36da0307fd10f7f47bfd",
+                "dist/ffmpeg/include/libavutil/avassert.h": "986182bd395e6559ec1a20243e540018ac99a64f1cd148f203ab6fbc4878f3ac",
+                "dist/ffmpeg/include/libavutil/avconfig.h": "6d78a911a2128e926262114c9904209209674e3bc1a18c208c850ecbfc3393ec",
+                "dist/ffmpeg/include/libavutil/avstring.h": "630d231013e996b10b2c9aec98c569f8f88dc53a425491d435d868172a53ecb0",
+                "dist/ffmpeg/include/libavutil/avutil.h": "01a511d927eaab20cf57076611ff5649bc6089d2d766c4b20c9d11c3da095efd",
+                "dist/ffmpeg/include/libavutil/base64.h": "81ac13d23f3744fe85ea2651ce903e201cd55fc63fcdd899d2cfe5560d50ef3d",
+                "dist/ffmpeg/include/libavutil/blowfish.h": "b955a63c60c8b3be0203ec6c3973f9084d848cf884fe56cd56088301aeef7992",
+                "dist/ffmpeg/include/libavutil/bprint.h": "5e3800d797fb8f67ffa7917420d3710c759afaca6f84b655fb64bf4dfa4650d2",
+                "dist/ffmpeg/include/libavutil/bswap.h": "1d985324139f195d3247c3bb59aa7976c074fbaaf85b8b783f88c178c59f48d3",
+                "dist/ffmpeg/include/libavutil/buffer.h": "f16742d574216434580573a2b09f56fc5b66b7dda1960d4f02ba59e3269ba548",
+                "dist/ffmpeg/include/libavutil/camellia.h": "1db30753e71c73f1937e807850069e8215cdf37a1bc3ff89d3a6370a719c1fde",
+                "dist/ffmpeg/include/libavutil/cast5.h": "05b2e13aecaa0adbb470081a689f45baffb8e03a71997c31f37a22ea4e383a60",
+                "dist/ffmpeg/include/libavutil/channel_layout.h": "fbd3246297cd72be45268eacd9229d23247dfe394fb15b6a40ce8773422661c6",
+                "dist/ffmpeg/include/libavutil/common.h": "08f14cf0ea3fede141d3790b30df2ed6edfc5dd81eb3c8181c3a33c314c46bbb",
+                "dist/ffmpeg/include/libavutil/container_fifo.h": "d8bbe3f1f4dfcdcd56f40618961736ff3bc34fafd81f52ac6c993c91ef43916a",
+                "dist/ffmpeg/include/libavutil/cpu.h": "52034bd08c5fa7b476451acb4578152bfd88e650774a92c107c810e820314063",
+                "dist/ffmpeg/include/libavutil/crc.h": "5728cf65705a46723ea28b4f6c8361aad82b76a90e859943efe8af0edb79ec86",
+                "dist/ffmpeg/include/libavutil/csp.h": "2760b91454642f77f88339f39b614da987c806b30ea54b6f6eddb1a7ac3a738e",
+                "dist/ffmpeg/include/libavutil/des.h": "15ebdda1af65d91c4607a3444c5f749d5e9757ff5d7f4b04213b3194603f74d9",
+                "dist/ffmpeg/include/libavutil/detection_bbox.h": "8f5817d77af243a52e905947aa5ae73c218d68dba909040b2f63bd2ca6f93922",
+                "dist/ffmpeg/include/libavutil/dict.h": "b8b7abebb6e5ab5ffa70b8463df52c96d4e774aa2d5574bebbc02f6031e62ad8",
+                "dist/ffmpeg/include/libavutil/display.h": "b9c78c80aa9331b945802b6bcd1db4ecc9ec4f9fad41993cc82b880c0dec2576",
+                "dist/ffmpeg/include/libavutil/dovi_meta.h": "e0ca4be00b203f35ceff50b53c92f448450c823eb24df7f01db0cd0d6c9077cb",
+                "dist/ffmpeg/include/libavutil/downmix_info.h": "2fc23ad8f0750d82fcd6aa3b653998e2ea9721f9d1664df7b6cb80e93d7fa3aa",
+                "dist/ffmpeg/include/libavutil/encryption_info.h": "ccc3a4a889b8a3c5aaf37b9fb2407bcdf23a065487c7cba718518a517c463b18",
+                "dist/ffmpeg/include/libavutil/error.h": "bcf4f7e69c7e0d658ad6e81611810f7cf1f0b8334ebe948d27e518c459e4104c",
+                "dist/ffmpeg/include/libavutil/eval.h": "68efeaa9b6600ec47dae9031d1f0869818c88083b24fb133de3c2cf73f8adf1f",
+                "dist/ffmpeg/include/libavutil/executor.h": "db578edacd55adbb7be49ff6662777f3ddb84f530e0ad7d7cd8e0c18f0aae878",
+                "dist/ffmpeg/include/libavutil/ffversion.h": "ab5072141e83b33c18de336c2eff477f0cec25b79bc95bb0dfdcb6359eaf3100",
+                "dist/ffmpeg/include/libavutil/fifo.h": "9d6e9a6db887d32ee3f4bdafab68869d00f9d89590e33718922c37067eb7f5fe",
+                "dist/ffmpeg/include/libavutil/file.h": "10daa0d0f1f2a3bedf2b7d8b5c4fea208dd9cf8caabb81dac341fc6ad24f685f",
+                "dist/ffmpeg/include/libavutil/film_grain_params.h": "414d2755769a6993d0c3f4b5a7e92e22a558675f0c49b44df3afc876473e825c",
+                "dist/ffmpeg/include/libavutil/frame.h": "2eb83475589dbe72d9dbbb5367370b7c1384fbb20afffbcf482de0437b6eaf8e",
+                "dist/ffmpeg/include/libavutil/hash.h": "b0896571267220736679eea28c454783795a02a0f1aef008ebe7c40489a75fdd",
+                "dist/ffmpeg/include/libavutil/hdr_dynamic_metadata.h": "a33138bdb7eea6c7895c8daa2cfcdf6eec5bea0774d40f4d62051426ddab8678",
+                "dist/ffmpeg/include/libavutil/hdr_dynamic_vivid_metadata.h": "91580e9f4eb39ef296365aa756ef48a170b57c07b288be4bb10affd98ede83f2",
+                "dist/ffmpeg/include/libavutil/hmac.h": "d14d625a897d6bba0668acdf33dc597bb0050237c5c1a5f7e568fe36822782e7",
+                "dist/ffmpeg/include/libavutil/hwcontext.h": "229c918d0809dbbaa0aaebd18848bece039ad458538f0fcafc11015fd2111fc2",
+                "dist/ffmpeg/include/libavutil/hwcontext_amf.h": "ce2775092bba5f8b5b24d281394487bcf89ba560eb115547bfe43f0698bca8b9",
+                "dist/ffmpeg/include/libavutil/hwcontext_cuda.h": "4878f46347271bc7a9ff26bb1573449a99cc81447684e1034a3edd4b0ff91d9a",
+                "dist/ffmpeg/include/libavutil/hwcontext_d3d11va.h": "ac6ffe37fb89e9b935c2654cebd931f78972b960cd16406dfe9cc2b80869eef9",
+                "dist/ffmpeg/include/libavutil/hwcontext_d3d12va.h": "62c67ab00795c6a521801d3ac32e9e09180982958130d3737a48f38d2db9d75b",
+                "dist/ffmpeg/include/libavutil/hwcontext_drm.h": "b598f37f40cf1342f923c0b97784a6f2830b543868eccee046375e096fbd5f24",
+                "dist/ffmpeg/include/libavutil/hwcontext_dxva2.h": "73a0333b65e99675834dcb1b63a5e9339638ccc619f1a2fcba85cdd0e179ade0",
+                "dist/ffmpeg/include/libavutil/hwcontext_mediacodec.h": "8c602859ebca906ba6e43ea548ff28821cf2886b4500b2be1deaaf2d552496d4",
+                "dist/ffmpeg/include/libavutil/hwcontext_oh.h": "62df338901602b1ac41b8a61fb26b2179de39662e78f3e2b87b6464c53895ddc",
+                "dist/ffmpeg/include/libavutil/hwcontext_opencl.h": "c6e9ec709d824a24928e1dd9e5f80411b008657402320d6e02d149df83dc6c3c",
+                "dist/ffmpeg/include/libavutil/hwcontext_qsv.h": "735168cd07100f41000e2cb4121786dcbd7d54fc12585b4682faae28f883d653",
+                "dist/ffmpeg/include/libavutil/hwcontext_vaapi.h": "5a63f50d3f1972b63038f03e005d53d8e666f119d8015f07038312c713aaf0f1",
+                "dist/ffmpeg/include/libavutil/hwcontext_vdpau.h": "6c96373d9e5deb2c500004f3f55ee1d2cea0f76cdfaeabaf5a3ad3e4938e8252",
+                "dist/ffmpeg/include/libavutil/hwcontext_videotoolbox.h": "71bbb6baf2dceff96c8673ef5afc5467548efb7b99c4d98d67df49c624f740c1",
+                "dist/ffmpeg/include/libavutil/hwcontext_vulkan.h": "aeb211e2a4c97eac7fd2ff8908e57b075dc2a125f66a2fe47e770c8cf7cc2634",
+                "dist/ffmpeg/include/libavutil/iamf.h": "c085745f71262d01c47f7c4eadbfd624cfd192056a87e4a83a9224e868c789ce",
+                "dist/ffmpeg/include/libavutil/imgutils.h": "8e0055fd86fb10b7c9e435e9375736b6db201cb9930a38fb4ff1e1a1da8e0cff",
+                "dist/ffmpeg/include/libavutil/intfloat.h": "3a29e4eebc8c269cfd867b96de91d8231773d392c12a8820e46eaba96d2b4ca1",
+                "dist/ffmpeg/include/libavutil/intreadwrite.h": "6e9c404e70f71a02208af81910434e47c501cbe1b0a80116e731cb673f98c734",
+                "dist/ffmpeg/include/libavutil/lfg.h": "6f094721480df57814cad6e6ce0f3f81867ffec24c58ee4d3e1800ec3484a061",
+                "dist/ffmpeg/include/libavutil/log.h": "b8ef46be6210baadb3ad61eb72ee48e7dd7d6be39c17c3a8bbc8c81ba9e26110",
+                "dist/ffmpeg/include/libavutil/lzo.h": "61e89928dee9d83030adececac06aa6c1ae2aada06c5682fde52c52015c53556",
+                "dist/ffmpeg/include/libavutil/macros.h": "b63b3a268b096f0eed1e91b821714cff334e5dc5bb34365148704393ae15321e",
+                "dist/ffmpeg/include/libavutil/mastering_display_metadata.h": "dbb1584931d4d8ff7d7a868b519097b6d92f0426d781543987cb784f80ba973a",
+                "dist/ffmpeg/include/libavutil/mathematics.h": "e85c71fb77b0fe7823a88db904982e2a9b953e806ced0714fe6cc6b8a0951469",
+                "dist/ffmpeg/include/libavutil/md5.h": "5b42de1758d289f78b4d20c47686f443e4ea8a5a6411c0deb357f709d2ef34d7",
+                "dist/ffmpeg/include/libavutil/mem.h": "bf9a1d8c218c38b333efb16be076c5778d31d66a0691bdd6175f171c08283d7c",
+                "dist/ffmpeg/include/libavutil/motion_vector.h": "dc0b0a15a638c8b91df95a418c5951ee5e787d518f22b6e3d70094922536e8bb",
+                "dist/ffmpeg/include/libavutil/murmur3.h": "649258a51c4737fa19a025a489e2ac9e9b06a96eafa802f2765178c684382887",
+                "dist/ffmpeg/include/libavutil/opt.h": "ed473055a2c58dc24bc560d9c86dbbc51558c3e87836f1c0869011130783d999",
+                "dist/ffmpeg/include/libavutil/parseutils.h": "e8efed69396851f429a8258d50e9c4f0431f921687a7c31bf6db13d14f7482c3",
+                "dist/ffmpeg/include/libavutil/pixdesc.h": "4dc17f708daedb294fd3aa7ec1940f4b9a504518b4d4813be83db605ac13494d",
+                "dist/ffmpeg/include/libavutil/pixelutils.h": "339cd6ffb6460d06401801c5dfb91ca66b9bdc028e1acc9ff4a0f447cfd3785c",
+                "dist/ffmpeg/include/libavutil/pixfmt.h": "6a8f5a61fe8d3bda60a62e59cc15237f61555ebd77adf477fc6d69ab8e609f77",
+                "dist/ffmpeg/include/libavutil/random_seed.h": "4490fd79919aadb18f765caac0c210d22cafa4d63cddcf9275e6f5bf66e2fdea",
+                "dist/ffmpeg/include/libavutil/rational.h": "f4fb850924b414f9ca35579df4e50d6f406734eb9735bbfbf388ae22ec5a0a9c",
+                "dist/ffmpeg/include/libavutil/raw_color_params.h": "75710ebb3492d2d08734ac5530bca3b4ee60b614fb619aa50acd6da81e9f74c5",
+                "dist/ffmpeg/include/libavutil/rc4.h": "61b69b7bc0183b17e5d6e4a56e991fa2452bb97c0d4512c4b0d70b69656ee305",
+                "dist/ffmpeg/include/libavutil/refstruct.h": "8e7be80109d14fce52e3de7a30932efea283abe963ccdd755787e219a4699b19",
+                "dist/ffmpeg/include/libavutil/replaygain.h": "4ec82edbdc4e5493fba3cae6a27566f0f15d1399ccf16e25073ffd50ba8187ea",
+                "dist/ffmpeg/include/libavutil/ripemd.h": "df9ef8c29ee31e5bd8ea299b03d51bd25fe937583793a994db53d1df2b316620",
+                "dist/ffmpeg/include/libavutil/samplefmt.h": "bec4e2708b42a026450c1227e137661f71850698f19b89f6e9f721fe993f56a9",
+                "dist/ffmpeg/include/libavutil/sha.h": "91280db6995b1b99b9e5aad0aa211a3177dc4d2841da2fea097f54964b7891fd",
+                "dist/ffmpeg/include/libavutil/sha512.h": "da265152798b221706d7fe95293a0e8cd18fa2b5087bf32504a8120f10e7658f",
+                "dist/ffmpeg/include/libavutil/spherical.h": "ab945689e58b593157d8532f315c8fb8674fb4c9f4ac96c1106a5aa62be8889d",
+                "dist/ffmpeg/include/libavutil/stereo3d.h": "32cc28caac01b5bf18ae016af4b0ffffbe40feb77e96cb434d723954a83b776a",
+                "dist/ffmpeg/include/libavutil/tdrdi.h": "9b7ac5326cadef9f3956470e22cdb9ba751c0da90b39f9df4562bffc8e4115a3",
+                "dist/ffmpeg/include/libavutil/tea.h": "3c1e93c566630bb4eeedad3ef3c8719bd6050081ac1c764b1fde81aba4969076",
+                "dist/ffmpeg/include/libavutil/threadmessage.h": "9bb242d7adc48662b947726843108aff7c34547d7a4a0d0e6f58f54a00fc4c9f",
+                "dist/ffmpeg/include/libavutil/time.h": "40e11fa242e0585996753affb054443e78be25919b7c3063042d0aaff1656760",
+                "dist/ffmpeg/include/libavutil/timecode.h": "20936b639afa89e7a356bd5f5317b33745b1f4c3d467486ad043cb9b5d51527a",
+                "dist/ffmpeg/include/libavutil/timestamp.h": "dfd2e2071577f04ddc3cae200abd96ba0fb7d38f53359025af319d4b902f1947",
+                "dist/ffmpeg/include/libavutil/tree.h": "2f8e906917612a05c138036dea7ed9f8faee5899413a523fdad4eb51711bc1e5",
+                "dist/ffmpeg/include/libavutil/twofish.h": "b71714336821e1c606b65620ba4b1ea47e431666be41f3174facbc51047fd814",
+                "dist/ffmpeg/include/libavutil/tx.h": "a1c5c309f493cc22f4637e67696581be676cd33fdcaa0661a01f5bb4345c900a",
+                "dist/ffmpeg/include/libavutil/uuid.h": "e669ce76a6b987e189b4d7ff62d0fd9ad6e334fa4967076cc6d912976574b646",
+                "dist/ffmpeg/include/libavutil/version.h": "9173c3eae6d2a81d5db376784431768b37f436bfb42c00d70abc99d34d8ddbac",
+                "dist/ffmpeg/include/libavutil/video_enc_params.h": "f287486c4f828f82e579f93ea98fccb98749129544f660decfa56da6f818fd57",
+                "dist/ffmpeg/include/libavutil/video_hint.h": "7ae7b1e152aa7daf0ae55e29b1ed673039678d62d3f7a11d9c9443cfc8236997",
+                "dist/ffmpeg/include/libavutil/xtea.h": "2eb91f780cc4ad86095e4ebbce453475d40f4e9b8737d52bdf20a068dfafcdf0",
+                "dist/ffmpeg/include/libswresample/swresample.h": "b23e625ab295d57a3d1ae0142c937b485dc386a36e4ed63f4b99ed886dc905e1",
+                "dist/ffmpeg/include/libswresample/version.h": "82e6be19053e0007658d30c18bb463fdde69f9f1e957314908cae73ae3e38b68",
+                "dist/ffmpeg/include/libswresample/version_major.h": "c730cced7041664f716e82872850329b59fa965f1c93044ce37593bd14a59c40",
+                "dist/ffmpeg/include/libswscale/swscale.h": "3c3c7c2aec2494f4881e8fed8baf01ef0db8c08e7c01a3300946ea3bb102a162",
+                "dist/ffmpeg/include/libswscale/version.h": "ff958451c8c25cc4f6afa659fc2d7acf3bef43a36d5462f6c39552b0a204d80b",
+                "dist/ffmpeg/include/libswscale/version_major.h": "b5981c7a57dda91c1b58aa9df212dd0214091f9d87448f2d86dac07f0ea17549",
+                "dist/ffmpeg/lib/libavcodec.a": "0f3b635dc39996f01b6e8bc44dcff41cc89e3ac2f16acec98890b52d1e279e13",
+                "dist/ffmpeg/lib/libavformat.a": "eee254ead5dd63eb3b4d924840d2585f95de9f38a9e2c78b086201f40e04ea85",
+                "dist/ffmpeg/lib/libavutil.a": "720382b4da7acf8eacd6f71c5f09018e94a69682ddcfbb2d413d0ff9c203f8c1",
+                "dist/ffmpeg/lib/libswresample.a": "1c986b808a7cabcae648a5f295190436847a0eaa5cc60c0ed954b826928010ef",
+                "dist/ffmpeg/lib/libswscale.a": "de0c1f2ac9fbad39793f7eb1f67d2567d3808966371f4b66452ed772551c734a",
+                "dist/ffmpeg/lib/pkgconfig/libavcodec.pc": "ec7d8be63e4cad59e024f6cae7615fbe0f283e79ccd67e94d9b9b2fa82aa94aa",
+                "dist/ffmpeg/lib/pkgconfig/libavformat.pc": "ed2239b8f7e72b7519faadd769abe8d35c67807b409d44757f9832b291beda8d",
+                "dist/ffmpeg/lib/pkgconfig/libavutil.pc": "ecf233d0aeefc8f02b778f795dbf81a6259fb5a2511273bef4bd0639ce2e164e",
+                "dist/ffmpeg/lib/pkgconfig/libswresample.pc": "6e3637e4ee222f8ced7e96c1226932ac6173d8727e7ea22703545ab7a6d4406c",
+                "dist/ffmpeg/lib/pkgconfig/libswscale.pc": "4bcfd8d2b2e95b05780ed9fc0deee1461508cf0b50efc38f3771d7a69d699345",
+                "dist/ffmpeg/share/ffmpeg/examples/Makefile": "e2a4f8f5829caaf9c0f1cf93d28d944d5c8c79e760d4ce64d2eaf89df9f1bf2d",
+                "dist/ffmpeg/share/ffmpeg/examples/README": "62449d3a232b8cd634f6293afdac97330ce0b7a67130e1a126df8670c5ff87b4",
+                "dist/ffmpeg/share/ffmpeg/examples/avio_http_serve_files.c": "1a8e90bb702d32074bab2d5a72e7de1f077fdc7006d29db70e6e7e0984b2f929",
+                "dist/ffmpeg/share/ffmpeg/examples/avio_list_dir.c": "a9281301000b5ab55783ef134a5aa07fe187aee97d7891a721235a558f907d03",
+                "dist/ffmpeg/share/ffmpeg/examples/avio_read_callback.c": "6ac07cdbed4d7487208b701df024e0af4146f4f355382b8185f2d2faa63f893f",
+                "dist/ffmpeg/share/ffmpeg/examples/decode_audio.c": "5d9a16e09501b0d4767ab2733375f2ba4791f792caf2d92a28d36e505e6f1384",
+                "dist/ffmpeg/share/ffmpeg/examples/decode_filter_audio.c": "95e4c398719f2016b2c4360457f30857649043cc73ebd14f994e520f7bc5bfe0",
+                "dist/ffmpeg/share/ffmpeg/examples/decode_filter_video.c": "de4920497284507099c9108a89b8ccd5666c1f64214e66472194f439680bb9d7",
+                "dist/ffmpeg/share/ffmpeg/examples/decode_video.c": "e4b4cd6a3750a6dbb6d1fffcc15acf9f6ffc4ea6852e18cb2cd62eada4138f78",
+                "dist/ffmpeg/share/ffmpeg/examples/demux_decode.c": "e1ce42ba6d835c80f2d380da2c69ef9025663db2e709166d5f3da2cee64e07d5",
+                "dist/ffmpeg/share/ffmpeg/examples/encode_audio.c": "dd4d96aa42ad7aa6ca9917d25c9a5e6ddaab8950655edfec1d7a02d605ca09af",
+                "dist/ffmpeg/share/ffmpeg/examples/encode_video.c": "c9b1c21af4f6af47c40d36391d03b4e1d920e9199c6aae98064fb648b620beb5",
+                "dist/ffmpeg/share/ffmpeg/examples/extract_mvs.c": "7b4ba185272866ee134d4594bd5a75903eeb85ab81a80e24a2c8b6944610b034",
+                "dist/ffmpeg/share/ffmpeg/examples/filter_audio.c": "5ce4d08d9eb229ff69bdf66e961fb24af83e28255758afdd6afc7ef36c7a27ad",
+                "dist/ffmpeg/share/ffmpeg/examples/hw_decode.c": "7eeb4a0a337c28aa2756a27f0a135c9e5acdd76a9cf6fc6f483d23e08e3f823e",
+                "dist/ffmpeg/share/ffmpeg/examples/mux.c": "7ea79dc87031e872fb1f27e190f71da6e67ca78056a6957f1561af76aa8ee96d",
+                "dist/ffmpeg/share/ffmpeg/examples/qsv_decode.c": "fcd4c209b0aeff3d957ce50ab38b3ca2cb67e0696d506ef21af5f1eea813b0f0",
+                "dist/ffmpeg/share/ffmpeg/examples/qsv_transcode.c": "d5372e67e94c33194092628ebc8bcd0627f57b2f77d2f9576f1dd7d155775b42",
+                "dist/ffmpeg/share/ffmpeg/examples/remux.c": "50400642ae3147b563d186ec335bb7a94939e715ab6fd722dfb9c05632d7af55",
+                "dist/ffmpeg/share/ffmpeg/examples/resample_audio.c": "cb2eaba58e7d21e57367d0e925f254f06ea6b8368af0d17168417d1e8487f4b5",
+                "dist/ffmpeg/share/ffmpeg/examples/scale_video.c": "c56a52fc425bd0e47d5ee06e14f5127b614d9e75560eff02d345083df297ca0f",
+                "dist/ffmpeg/share/ffmpeg/examples/show_metadata.c": "fe5315ac3fe6b82632fc0f51bbe5c63fee4fee9734d4b9221ed0c0c3787661ac",
+                "dist/ffmpeg/share/ffmpeg/examples/transcode.c": "3152ac03ea0a80d8159bbb4213fd79fc7f0283bcdf5e3b8a9688fb0b50be41ad",
+                "dist/ffmpeg/share/ffmpeg/examples/transcode_aac.c": "ac5701ee830622f3c67ea642c768d4108086f6425113bafa15b24b5fab1e7a41",
+                "dist/ffmpeg/share/ffmpeg/examples/vaapi_encode.c": "e4903465e29d6ad7891e1afea0e86165692645d3aba92bcda292b40dd1c9f31c",
+                "dist/ffmpeg/share/ffmpeg/examples/vaapi_transcode.c": "8d2e7cba70d587ec4df8e8d6bbe8f2af0e66222ad6f6bced0c122a3a6c7dd22c",
+                "dist/index.cjs": "f452c8519f296313e52c8d37f5ff5fe6fad3191d0e0192d76b8709edda76b6af",
+                "dist/index.d.ts": "a4c6616749e5c101d0f2697de63c0a2dc544bc0dad40953210c0281ebafb67c2",
+                "dist/index.d.ts.map": "1691c3398224e270d8ef7b755cc00add6cacc62fcce128e0758660b9820c99a7",
+                "dist/index.js": "0250d186acc001e3766d217f344016043f3d600d81e86fb2c46346dd8b7cd5d8",
+                "dist/index.js.map": "94f0e3085a04d5f3334b8824825c61d9f6d5e2a45456799820ad05520afef633",
+                "dist/movi.wasm": "a90da45449126b10b68ac2b816aa28b9ce43cd7d3e307e7201e0ebd73f92f530",
+                "dist/player.cjs": "2bc51c94f9431f40dbf4ddc338b26a1fd0ef81826c63516d1c4f3d94ac464ce1",
+                "dist/player.d.ts": "13a4b46dfda001000bd245157f0ab710f310ec30f1c837766eb5e964eebda58c",
+                "dist/player.d.ts.map": "5449f1b3c5389c0eeb2417ceac01494699410c902daf86b65fd132446f6d80c7",
+                "dist/player.js": "39f2298831a9bf2594508250b3f7e2b3c12d1affb00fe93463f474f05c85be14",
+                "dist/player.js.map": "d4b7497fa46f745c0dc9aeea877916cc3ac505dad1a17c94f9f7e84dd7b8bfe1",
+                "dist/react/index.js": "99cd5a7a8eb88b59f495e008564aeda777f74aef990d90ecd5d73cffc32ec546",
+                "dist/react/index.tsx": "5879a823963c555ea2450d936e8cf0f59643353c103af0f56161cd6d7de60bbf",
+                "dist/react/slim.js": "21c34915554df8a527bd2427d1ccad0c6088031ab91afbb6ed1f1f2c738bb6e5",
+                "dist/react/slim.tsx": "11a413ea504233363bfd695596dc8b7022dbe8896338f36ae6a442466aaaa32f",
+                "dist/react/wrapper.js": "b8f4d2014250b7eeb306635093e40dc83ba3b2bc28b9357604faa8be4dbd1766",
+                "dist/react/wrapper.tsx": "441683b4af15c0854f463eb44343f653339f43c7ac86ff3dc7a45d210c444d8c",
+                "dist/render/AudioRenderer.d.ts": "a7c8ac54f7c2118c9ec4493b0c7abc08fae02cd5de968b9e7ee9d414ec2fcc0f",
+                "dist/render/AudioRenderer.d.ts.map": "56142680ea2f9690b7fb2bf8386c2654346e91557538f0c352279bf610d73b4a",
+                "dist/render/AudioRenderer.js": "1d295bcd8a0722de1b37ea96d7ed79d3268cbe6dc964b23296bdbdc1e68aea6a",
+                "dist/render/AudioRenderer.js.map": "fdb157afe13e71f1f84159cafa47ab535098a4cb7fec77ba8d2add82d41e3375",
+                "dist/render/CanvasRenderer.d.ts": "d78d5ac86167693d492c9405b2f4bb4fc587b0b25ae0854d3a907a198ee8a29b",
+                "dist/render/CanvasRenderer.d.ts.map": "ce92bf293eca72d84f8956978b85d35b14f44edac74cf98a86e12e9f42262dfc",
+                "dist/render/CanvasRenderer.js": "bba43f267578872c5e99c927e1588cef7581a81c2f8bdb77722345515600d745",
+                "dist/render/CanvasRenderer.js.map": "087b19d7bae83b377d2c83822bd7221bf9ef1db878bbf60a3a980155fb485bbf",
+                "dist/render/DASHPlayerWrapper.d.ts": "ea2399813aa71f94e6705820f3c29ed5a47f694bdac7568f338a1d1a00ed7a99",
+                "dist/render/DASHPlayerWrapper.d.ts.map": "93304f5289d4c898e0ac1a7cd59d8f97ff79087a1e085a382a6c66d1678d66b0",
+                "dist/render/DASHPlayerWrapper.js": "ecfd9084121ffb2150ce3bdef67012f68018ab12f26d8cdf07e18803254a2d10",
+                "dist/render/DASHPlayerWrapper.js.map": "d4e3736f28b83d7fc3d23bede66dd92613ed0dd960cd5b6aa0d73585c1038c6c",
+                "dist/render/HLSPlayerWrapper.d.ts": "c8c9949270dda2bf65f5f7d294886df2195c6f4992c60054f1ce9a985a06dd65",
+                "dist/render/HLSPlayerWrapper.d.ts.map": "01cbf14463ea5fb337f92aad7c70580b74de9ba9167b74e6e04d765af9e55eb6",
+                "dist/render/HLSPlayerWrapper.js": "35a36c42c5e5d0c01ad360a07d69ba545b49b11060aa520adb0b1944930cb2ac",
+                "dist/render/HLSPlayerWrapper.js.map": "c8ed50576b1928014865e177362399e25c7250935a3054267038677ba1666f2d",
+                "dist/render/LoadingIndicator.d.ts": "9701f759a47e2f2b04d441bea96e1b8cb671c12bcccc3f232969db48d6455847",
+                "dist/render/LoadingIndicator.d.ts.map": "6b228c08b8e15343b7122a92acc53b6b1a0f9d4cc7c8551ab6eb594ca3374969",
+                "dist/render/LoadingIndicator.js": "5af1bacc5c908d4c489fa64288f466874383d214c8a6fb5579841e5d679a57cd",
+                "dist/render/LoadingIndicator.js.map": "858332e2e7550290e891d99471cea8dd12172f7a11aa645598a8b1ed47ec9646",
+                "dist/render/MoviElement.d.ts": "81737752d462b6aec567848763a882e454f4448c50d776b6409a9345357f1879",
+                "dist/render/MoviElement.d.ts.map": "e5a8dacafa7cbe08d85d5d54b7158b913893424dcf87fe06637a58aa2afbf734",
+                "dist/render/MoviElement.js": "5a5e2cb6f71c141f799c6fb6edd1bd88020715697eb6989ab8e32d1982e5d206",
+                "dist/render/MoviElement.js.map": "7511ca7c0670aafa53b62057696a33457929db092d9a725d3e7f51ae77405a54",
+                "dist/render/NativeVideoWrapper.d.ts": "6b0909301f950755ca55ce4b5fddcc30caaf3471701aeaeb26b63b7f80b9e72a",
+                "dist/render/NativeVideoWrapper.d.ts.map": "353ee1097ad9e6c89a25644e384b3b899bb3af55ed810937d9e21101236fc10c",
+                "dist/render/NativeVideoWrapper.js": "ce067090ad941a068250e2ba23023991e4eceb33fadd1fae93288c45e5950f68",
+                "dist/render/NativeVideoWrapper.js.map": "a0959af2bf354d1f1e3e80031063e694d5086c8b52da0c057de22038523e94a4",
+                "dist/render/ShakaPlayerWrapper.d.ts": "817a95450eaaf732f5bca7d254827b811998c7e48cd8bcfcc1dbf6f03796669e",
+                "dist/render/ShakaPlayerWrapper.d.ts.map": "b06e4109cfa29cb2310f14d0b580822ec0e5f07ade531dc192d3bda1f2a8c0f3",
+                "dist/render/ShakaPlayerWrapper.js": "cced411bf2ff61e60606fd59cde54a383750cd7448dc4e7700d287f3fc9a6203",
+                "dist/render/ShakaPlayerWrapper.js.map": "f59298b1ea48d659621897fa405c42fc049f618af68f7378d7f495458aee6e8c",
+                "dist/render/index.d.ts": "eed78cc73ca6cbf6bacb802b60442dcc8f381b79546392922fdccfeb1ab6c51b",
+                "dist/render/index.d.ts.map": "b37d9d90d8c6c0c505064368770de8183d425cc38daa5e800886812e8219df5d",
+                "dist/render/index.js": "8b09012c03759221ae0ceed523afef1a88d0c4800a5d7fccbc6929b78b469ffc",
+                "dist/render/index.js.map": "2d345cc9b8bd2a9f535642d2ec955312bdda88d6b8e7208b0441df340f3242df",
+                "dist/render/sanitizeVttHtml.d.ts": "37ec5bc1941af521ca373cbe58bfd5724f64b11e7d76fcda96431a34599ba079",
+                "dist/render/sanitizeVttHtml.d.ts.map": "eab67e11250cf87b02b51a49ca56c81aed2fb3219283c39e6ad9c2448fbbc7fe",
+                "dist/render/sanitizeVttHtml.js": "3fe7bf82ebcc15a6b2012043468945bc8007acf95c613b7ace7c1e1ff397610f",
+                "dist/render/sanitizeVttHtml.js.map": "d9dd9ff6767200fb80162eb466fcca3aa47fc2df1f6ba3d5bf532567ef79c484",
+                "dist/source/DashFallback.d.ts": "2d76c515c25fb64572e2e30f1a2aa8490b0365421ac61cd902c6ebb2fc05741e",
+                "dist/source/DashFallback.d.ts.map": "c823e1c32d78b90d0cad7efe0a98339f03252b4d1f797636c6165a98be539ba7",
+                "dist/source/DashFallback.js": "67d9c089562113230f94dad987cd7f400dc1220bec19e6c5f478b4a3e377acde",
+                "dist/source/DashFallback.js.map": "f0e9b505d16a1238ac20d4d5d89f9a7233dfc078c92a803ee92e9f209431e95e",
+                "dist/source/EncryptedHttpSource.d.ts": "193f8029f735f41c3a62c43d1b8a5c44e2e8b7ac23d1ffecf932adf68a765a39",
+                "dist/source/EncryptedHttpSource.d.ts.map": "78ca239b405766eb6228895dea86baaa9737da0d2162509701111124f0d9e88b",
+                "dist/source/EncryptedHttpSource.js": "c18a68b8fcebeb75b8dd14500f7473b4e8ba0c7ab9f056c92e19725a9b2ca1f0",
+                "dist/source/EncryptedHttpSource.js.map": "33861dd244ff27fedb795ca902ec50b01bdc2b2deb01643e05f83428e6599611",
+                "dist/source/FileSource.d.ts": "025b22c9f6646cb87d2c3ff4e278eff09614fd1d54f1a73d12fe367897648f6b",
+                "dist/source/FileSource.d.ts.map": "5272d69568fe35a93bd0dbee505acb9b77f2bfdf42b311b8f0ab0ab9d6aaf2b0",
+                "dist/source/FileSource.js": "62a5c1437f1cd9d0ab0257e5a5f0a749ccd169d11369171cc873f8b6c8335487",
+                "dist/source/FileSource.js.map": "6ca94a0490e487efe597b6595551a44a48d7d4ff13c543b3994d8ff76902b419",
+                "dist/source/HlsFallback.d.ts": "d913b83c592653ffe0530f031249e262f8f9d319e2ccb2e6f86dcf0012a67d19",
+                "dist/source/HlsFallback.d.ts.map": "4ebe013daed8cfdb0d6d7eb56b8a83ecb42f800c6529bb23da96f92ef8aeec29",
+                "dist/source/HlsFallback.js": "8f7a134e7205a9d9a33fb326493af62cd60794cd68432274b335359927924648",
+                "dist/source/HlsFallback.js.map": "f07c3e6415b49ea7cf7886d699a8802b9392ffbe66d18e61e2dac5b0f8a36843",
+                "dist/source/HttpSource.d.ts": "3052e6cf20ce18850bda47505afa05a4798f2d845275412168d62f4c3cf025c4",
+                "dist/source/HttpSource.d.ts.map": "62baa7655005928715db2a7b9d505ee17a2a04c274dc36bbadeae18243a59fd5",
+                "dist/source/HttpSource.js": "43fa1c73dbdd51a7d65be31406abe199ba5426287b64b8e79360f2e479d37ae6",
+                "dist/source/HttpSource.js.map": "73f47627d57469d670a5dcefdc15a384265dc5127d27ac47cb8b54d6eaf51b5e",
+                "dist/source/SeenRanges.d.ts": "55a89bdbd34a9b73782541068bdbb8d3fa1119520fdc72bc7d4ed52d44522d24",
+                "dist/source/SeenRanges.d.ts.map": "f8b62185f8da88e882a65f59f50b5787fe49ec906d34edcea364140fe5e35fd0",
+                "dist/source/SegmentStreamSource.d.ts": "0b27835b7c4e77519607d5a1fa7a53943c538e0c1657c5721f845a94b7756ff5",
+                "dist/source/SegmentStreamSource.d.ts.map": "7e7516c5bd0ac0b08350b25ab07f59b12d39bd591ed5b4b448116038a414fd28",
+                "dist/source/SegmentStreamSource.js": "0b676d0422a05cd8b8608d6c266debffd4e2b9a23e9ad0d1feff1d86ba1374aa",
+                "dist/source/SegmentStreamSource.js.map": "69585501a1c94dc83fbced2061045294c7a0ff3e97b1f2dfbcfa8ae2bbabbdca",
+                "dist/source/SourceAdapter.d.ts": "2b4d7026d59d76d6b004a261d1522a154471a20af975401994f8dcc3106d94b7",
+                "dist/source/SourceAdapter.d.ts.map": "ef711215620af7b7f469fa760574aaa3ef47bf418333dbc6befd85e26a0eae34",
+                "dist/source/SourceAdapter.js": "46e98943ea5be47b4e7ceb9a9506a8ee87897b4493c63cc17ab8765f1f687016",
+                "dist/source/SourceAdapter.js.map": "0f9e71f6808a34a5a39f8fed3dbe6f879f6155fadbee67c7e4b2eda51576eb0f",
+                "dist/source/ThumbnailHttpSource.d.ts": "08da2113a231a885ae9db6513cd27abaebe3e7e766172f64ce310dd4db82f257",
+                "dist/source/ThumbnailHttpSource.d.ts.map": "ba06119526a4dadb8309b6ba49e91b526d9506d1a4063f808ba428d0ae4ffe36",
+                "dist/source/ThumbnailHttpSource.js": "e44340a67ff829d64c70c4944786e5cfa40961fb8cf4b345c7bc2450ad8749a3",
+                "dist/source/ThumbnailHttpSource.js.map": "387ab6f6bccfa3d6832e62e8e6ca11285c6591ebf2e53ed87649296f52a16864",
+                "dist/source/adapterRegistry.d.ts": "380c28eaf2940c84967446a17e6f06ce0cdaa1b0262d2ec39e0efd0fb40fca97",
+                "dist/source/adapterRegistry.d.ts.map": "29e4da8b397a6339f84926c5df5387e06a002e23ce70747fbab04231e74b9f0f",
+                "dist/source/adapterRegistry.js": "c14690d79a52bc288b4e549a7b80768a0671ebad897866bacf33d75b43c398a4",
+                "dist/source/adapterRegistry.js.map": "444938fad44e536dcf1f0c828f95cba99474b6675c60d33c7ae07c3e48cb307c",
+                "dist/source/index.d.ts": "05c1a1739a006e963ee660f1ef9d8d962823f5f35192ca302a6f3e3eefecbb52",
+                "dist/source/index.d.ts.map": "5b08bd0cc953c4e43d882d43bbc3a481164060ac9c2f8349abafeca17333928b",
+                "dist/source/index.js": "4a36a53dd250771e0ca684303e5f41fa7cddb0a979e5e8d7a84b9fadea2f6a57",
+                "dist/source/index.js.map": "72b75c3fa7358cf6703239810581e5a2ea212e651ed6e4fe09e483abd777ebad",
+                "dist/svelte/MoviPlayer.svelte": "b3caa10c8478d5ff6690ab221e5c5330a9a9579df57a26a75e8fed5e1cd5aea9",
+                "dist/svelte/MoviPlayerSlim.svelte": "8dba3db9ea981e1553901969630787aa02cbb1a08c0bcabdbc5bc4991687da41",
+                "dist/svelte/MoviSource.svelte": "299f53869b666bc58d3809e36e45c6c5b82ae71a56d297648f63bdaa2e8a84d3",
+                "dist/svelte/MoviTrack.svelte": "23c9288530d5606e0466e2c488add882e80da53c139b094854ab54f069f28e2c",
+                "dist/types.d.ts": "eb28d64c0d8b5c2475b26ccc10851fa6754ecdc4f107699e33d2d3f87b5fd2be",
+                "dist/types.d.ts.map": "0f20eaaa580d6bcee25739ef3a60c981b7faf7b41211e07b741990b80f18f031",
+                "dist/types.js": "a8b309cd0a4294e30da5c426b9b8a1645a22d9b69e92041befc1d159c03230d6",
+                "dist/types.js.map": "011a4c5276969e1dd6edb89d9f146e9c81f7595302508f196fe0b7287b3e6c58",
+                "dist/upgrade.d.ts": "dfb8b57c1fa88e4f1a3cf04be0971a12c90b132667abdd7cec4488a4e1d03b66",
+                "dist/upgrade.d.ts.map": "5f3c8912f95a7b8426fe3f1c210af09532ba4234aa347e6cb3047201ba938f91",
+                "dist/upgrade.js": "3b9bf4e27c5126e59be1c5c832a5f450ff27264f3d666697d6d4e8b30b936659",
+                "dist/upgrade.js.map": "f5de38263ed38d151a400737ba5ee260146ad9a91bce40012eb12037f89ed088",
+                "dist/utils/Fingerprint.d.ts": "d7c51b4f1bc47af5ae3441719bc3e0298dd3d9a09b38f103bf52a9ef57a2e7d3",
+                "dist/utils/Fingerprint.d.ts.map": "2ab36709ef7e234d66825b89c9042fb824809150d05196e5e6d18ecba542ef70",
+                "dist/utils/Fingerprint.js": "c8fb5affbdc0e61be8741bef1c8fc8c945cd6121302547872c60b01cf3b05c43",
+                "dist/utils/Fingerprint.js.map": "f379e6b00077b1da021010b02bd9212445898e8d4eca238c58c30a0357e82d1d",
+                "dist/utils/LinkRate.d.ts": "77eaddad0e5cfa261df2e5db8f1421090fc70df348330735e335e69ae1995806",
+                "dist/utils/LinkRate.d.ts.map": "71c846d5727175ec0acf2e08c7532a18d0a9321d6f1a1e36eedc913a592f1aaa",
+                "dist/utils/LinkRate.js": "d94b4da182465404c247e4f702f3d26a3d46e058adc0ce236e35fbef5e5e6976",
+                "dist/utils/LinkRate.js.map": "a579d50443d7dc8887e2bcbfd7019b338ac7fcc1bcec5815d21e33ffae6de2bb",
+                "dist/utils/Logger.d.ts": "c620dd7fddd858505d3b6f2e9b9bcd8850bd1f36d760a38f3b90610e14132c10",
+                "dist/utils/Logger.d.ts.map": "997fbbe5c9c4ea6ec98569d9b3cabbc2deec843e9fea5764e41886a3d9c36fa8",
+                "dist/utils/Logger.js": "46a5cc04f3fa44378f19c583e3d3db02a3e60864b0b7a727b479b67c8b923467",
+                "dist/utils/Logger.js.map": "1c33a2bc2d3f7e6b6da929c41ce923a7e499f5905791234fe7e9144eaa71f921",
+                "dist/utils/QoE.d.ts": "2ee4e3b16782d0e08b561a19ac343885edfee75206b59bd99c88c1bcd1e3cc07",
+                "dist/utils/QoE.d.ts.map": "0e967ffee03a2a1ac9f32aff4605241aa22444447085a9db630d7bea3e13e0b8",
+                "dist/utils/QoE.js": "a940d962800482cba4a8202d530bac3c25f8939317f040e7f59e577c06435c47",
+                "dist/utils/QoE.js.map": "5d243eabd9e2efc86e08af2719a9bb44aec0324f414d62681e605b5b7874b49c",
+                "dist/utils/SettingsStorage.d.ts": "dd58fc7edf2e1bdfe55b2248df8a941a47ab271b7a5c2af8ed99fdfdae2898f0",
+                "dist/utils/SettingsStorage.d.ts.map": "1f6bbcbfd1fff7be832f60f3f9ed852a5b4eafdaa3da49a69a7390f80b57abde",
+                "dist/utils/SettingsStorage.js": "630bc581281a1ac94e6774b6571f949cb14e3eaa4465fb53d9cbe0c0a54a067a",
+                "dist/utils/SettingsStorage.js.map": "f10873c6fd48b1ecc286fd04ffad05f67886707e96e68c5b326cef24254a5d12",
+                "dist/utils/Storyboard.d.ts": "7aba26a140093f60c3d3a9480c5d284e726fb1df1d67fe2a8d0484823a9dc17d",
+                "dist/utils/Storyboard.d.ts.map": "99a77fbc57b43919548575ff95db495371f78e39e00a4d701b38ac9183d1a9c7",
+                "dist/utils/Storyboard.js": "e79d4d3de38dbc41036e6eb23a385738232900b2f1b3c9a8d6a49c5439201489",
+                "dist/utils/Storyboard.js.map": "21454c90591e1d1d611a9c14a6c42c3a1b20cb9710d2ac8947983c53b3a6efc7",
+                "dist/utils/ThumbnailRenderer.d.ts": "ab904315b2487b5b90eb005af1103931a3d3f233c938e5a5bec5de0c69a3144e",
+                "dist/utils/ThumbnailRenderer.d.ts.map": "b45423143a6df9a4977ae9e9cd525ef56bd2230cf180f6a2f258f2c3fa7e9bec",
+                "dist/utils/ThumbnailRenderer.js": "4992792cb53ea7ffa83485c62eb15296d13c5a94a6bf9c9a42f6e0a83e79cc03",
+                "dist/utils/ThumbnailRenderer.js.map": "d00f49ab9e6ef2826434351aac2a6b3b522158ce383711289224d0ac2c883df9",
+                "dist/utils/Time.d.ts": "823348f21ec14ae10494fe1ebd99c8d8eb8c4e1e43fa7929bd66d51bd67fef6d",
+                "dist/utils/Time.d.ts.map": "19ad141bb5f0cb90f1fc187de26b33fc741347b42de55ee2d4ecd2b745e6daaf",
+                "dist/utils/Time.js": "54ea4933208cf47327f7b0cf80ecd5076ac285f791c366458fb9156de923cba4",
+                "dist/utils/Time.js.map": "d4e2715da09a98399cbdb6071c1243f3269ca1e1eb47fce8f97d930033b1fe72",
+                "dist/utils/abort.d.ts": "44697e5b61176574b79f6d36f12ffb2411e70799f74ec0ed19b84432d5ecabff",
+                "dist/utils/abort.d.ts.map": "d41376157b048a744f9c3a1d104c9b1b368849a5dce90281fc955fce3c21a4ef",
+                "dist/utils/abort.js": "f40dc6ae4bdbdcb9510d36203c5a8b021807534a9024e642a399a24985cdff73",
+                "dist/utils/abort.js.map": "3fcfbb1343e8910035558fb0618f54ef2d5e3ef0371cd88e6b3dab6aa61c8148",
+                "dist/utils/bandwidthProbe.d.ts": "bade940124984a13ccc0bdaf6f7e4f15a8eb150f203278fa16d26598198707a9",
+                "dist/utils/bandwidthProbe.d.ts.map": "8b998a3992fff260dd499a55415d86c7572f51d7a363cf2c253574c285aaa837",
+                "dist/utils/bandwidthProbe.js": "e35fe23c26749e3ba1c4b20db6866e90776a4cb0f39f0f947fa690fe5a92b812",
+                "dist/utils/bandwidthProbe.js.map": "b8e8cde4bb8419c81cb5986c0d97d92ec371f34a62ed85c17d4f3a8ed09e288b",
+                "dist/utils/index.d.ts": "a3bb1789e4218cfcb4997f839bd8ad35aac7b4504e379d4e8e3b030fc3f52275",
+                "dist/utils/index.d.ts.map": "e47ef11fec3e6322e6a13ebea7af59efa057e55860fbfd33e7315acc71f8f8fb",
+                "dist/utils/index.js": "d8f70f13f208070d4a597689a60696adc9b236581ae658f4d82d2b0760805d73",
+                "dist/utils/index.js.map": "7886f680cdce191023682841670861d20a9c97003705e3a3d010e44341f57716",
+                "dist/utils/signalsmith.d.ts": "5d8f43798dae7084f8dbc7bf433b29e6bd4a797d22b34c27b1d3fa9127342fb4",
+                "dist/utils/signalsmith.d.ts.map": "35dbf230f31a071de6c86d18af375611aedfb8ba89667b7a366a9d62852a106e",
+                "dist/utils/signalsmith.js": "4b7c8b7240162a5dc3324eee6eb390d7bffdec1c9bac58b2a46f74acb9913965",
+                "dist/utils/signalsmith.js.map": "271db8c85b6bd0005a6b26a92eed0a977183562e8b03ff738cb2316d02523e79",
+                "dist/version.d.ts": "e532cbf90bbd9a9f56fa4d5d16a3bcdd75323107027ec3e24a3c1eec166c220d",
+                "dist/version.d.ts.map": "c13fbcbe1960808a1e86675cd8881822492fa17d29571f9ad5a6f48082b028eb",
+                "dist/version.js": "00e087d4f69cbfa96b1a3603749ebfc0a5cc745737ea1a307157f74161e89e0c",
+                "dist/version.js.map": "159d1c02e480b28979db62adee2f51ca4a896b6a692d5530dc140e1a5bb03527",
+                "dist/vue/index.js": "99cd5a7a8eb88b59f495e008564aeda777f74aef990d90ecd5d73cffc32ec546",
+                "dist/vue/index.ts": "148bcb7c8b912e26fbade98720d06e4c5fbd173b6a236a6823b6b9bfd8bfff39",
+                "dist/vue/slim.js": "21c34915554df8a527bd2427d1ccad0c6088031ab91afbb6ed1f1f2c738bb6e5",
+                "dist/vue/slim.ts": "0a8abcb03efb59aa2212b82a9f641d7d2c3fd22d82454a881ebedd5c5d22c705",
+                "dist/vue/wrapper.js": "8f5f21171e05def5456e8dff699bfb7b27940e20e9c15a0097513a6d504fc00c",
+                "dist/vue/wrapper.ts": "1094d9f4ef65f25917d2764042af84530f16528071daebd6a9f331406a58d175",
+                "dist/wasm/FFmpegLoader.d.ts": "8598ac2bdc8226383dcd08f013cee0e82a8f0d1864523cbb889ef8b89662a7fa",
+                "dist/wasm/FFmpegLoader.d.ts.map": "e7c6569a0439fab5ab39c7429a3fc358b2b4c3a668b7fd2622e2aa7d687344d3",
+                "dist/wasm/FFmpegLoader.js": "f53083485bde91e17c354a8b44b2a9065ddfaa796c323ead471c3f7996244fdb",
+                "dist/wasm/FFmpegLoader.js.map": "e90f46158e8ba9f1dac69d3af3fadc6ad614a075563bed02b88326de148e3932",
+                "dist/wasm/bindings.d.ts": "536ad964e5af659d2fa7523f8cb9feda529b37717a5fd187e22d9bd556339ef4",
+                "dist/wasm/bindings.d.ts.map": "cca0924d7a733019ee65f842511d983c6dc61915dfea72d1beacb6ebd593cb0c",
+                "dist/wasm/bindings.js": "d464f622357d110e6b7f5b1ff0fc47970864875c44a6a55821f78be632a7d280",
+                "dist/wasm/bindings.js.map": "9abc1986b2b55fc24d07201c48a0cbec8d984c389e05c646b0f0ba0d1c8f28c4",
+                "dist/wasm/external/movi.js": "668b4325632d2d8d3616f7fde577ca8ae2fa5c65347f37e9dadc7daaee71850f",
+                "dist/wasm/external/movi.wasm": "a90da45449126b10b68ac2b816aa28b9ce43cd7d3e307e7201e0ebd73f92f530",
+                "dist/wasm/index.d.ts": "581b9d321326dcf840dab9ae5f86a892d6b022a129e51b337177cc3c8f500397",
+                "dist/wasm/index.d.ts.map": "aac0e0dcc235a00060466f2bbd3ef2f6834ed7026550dd76e3d37fd931238963",
+                "dist/wasm/index.js": "5ad3678c727d24c14bb4db291e7e160f84be5570ccdd56710804a382a4407217",
+                "dist/wasm/index.js.map": "54b7e7c7d970571cb9d51031eef8e01e7008d131607fb483fb927965ed4ab795",
+                "dist/wasm/movi.js": "3c2684c63e176ed497b1abaf61881e67f0f8cbe52ed787a8ec6f1551588ffa0e",
+                "dist/wasm/types.d.ts": "14c4a173c3545c533a3a9632164cdc5461a7e30240d9a1e610477fc71559ef48",
+                "dist/wasm/types.d.ts.map": "0a43c91c3e10777353540af195ae0a0b902eae6772d6321402396d351d09be93",
+                "dist/wasm/types.js": "258fcbe06ad609becd20787adf17c9af42e28be495721e0363afc7217bc85044",
+                "dist/wasm/types.js.map": "11768ded6cde2b9c78182e2256a026d4faab3c8119c57b0a2c88e1e20dd4b910",
+                "package.json": "8a92e89a5d2502be09d4d66d0608a7d952c04b0e6388251203bf6d6f662fdef8"
+            }
+        },
+        "pdfjs-dist": {
+            "upstream": {
+                "version": "6.4.299",
+                "url": "https://registry.npmjs.org/pdfjs-dist/-/pdfjs-dist-6.4.299.tgz",
+                "integrity": "sha512-AVl138zALtfaAPvADulE0PZThbYzCBS79nL4pOSL/6Sm/4AH5A21BD9VHt97OlCuzJuCpmeZtAtkinisF4Vb1g==",
+                "sha256": "86269b40170eb41740ea05ad2102d71d33de4f122b34eb2f478be0ea7779c415",
+                "bytes": 8539589
+            },
+            "vendored": {
+                "version": "6.4.299-tgdrive.1",
+                "archive": "pdfjs-dist-6.4.299-tgdrive.1.tgz",
+                "integrity": "sha512-+Ff7Uf04N7pZmoje7r0m7NLP5PmaH6sTwg6lt+GktFSF8ShHQStFAnSTR4fcKQJ50O+jcjX7YHJliJZPj0zf1Q==",
+                "sha256": "2acb15b222ce34075a34b72e8cc6fd5a36c447448be3690513264e13cfa76927",
+                "bytes": 8551606,
+                "package_json_sha256": "9a343cbb1db43294051abbe1d4fa615de03e39ad5e2dbdd9bf3ece40417e12cb",
+                "package_files_sha256": "13ff506fa14742c05bc9e5fe6e637109c8cd7288f76e199ed6cdb73eb7eb5d00",
+                "file_count": 555
+            },
+            "patch": {
+                "file": "build/pdf.worker.mjs",
+                "upstream_sha256": "07ceb740d746e5d9012fcf9f27d5c7dea09f7d2f5e74f5c8109e5787551a2333",
+                "vendored_sha256": "17a05acff3cc48a8196adc0ba2c9f7a31decab3a546603d21cdcde7e19681e43",
+                "recipe": "website/scripts/patch-pdf-worker.js",
+                "recipe_sha256": "c23eb6433d2c27da866dfd84de0ad3f051bc662342f98343aa3e9a614b4cdd61"
+            },
+            "files_sha256": {
+                "CODE_OF_CONDUCT.md": "902d5357af363426631d907e641e220b3ec89039164743f8442b3f120479b7cf",
+                "LICENSE": "0d542e0c8804e39aa7f37eb00da5a762149dc682d7829451287e11b938e94594",
+                "README.md": "c53acbcd27bb9851954ac2bc244df531bad1d0769c8be3bfaeccd95eb650d31c",
+                "TGDRIVE-NOTICE.txt": "6a6210423d8ae4b15fd41070d651f080749de732813b038fcb71f2f28fdebbec",
+                "build/pdf.min.mjs": "57456c8e0c81e46be31174b499ef77f2b9f5ee46d04412ba627320a36755d4c2",
+                "build/pdf.mjs": "dd13af821c9c3e1778653340d6539a1ba07bc56cba40073a4c727864cf0c232a",
+                "build/pdf.mjs.map": "f6eb4b71d5c5cf67d136bd4398f37bda1834874fd167f254d0b13a587fbd1754",
+                "build/pdf.sandbox.min.mjs": "19cc05d44224f10dddafe76f5067ed94d5191c2e7cf440d46dbe5253cd35b72f",
+                "build/pdf.sandbox.mjs": "279b3cc4d0b78ecba09a53b3dbfcc16a86644927ac4479bef3d33b6a3cee92f2",
+                "build/pdf.sandbox.mjs.map": "2fe523d31d515a7727833e007312d9abdf981560a863ff157dd45636312d4fe0",
+                "build/pdf.worker.min.mjs": "9536359f1b8367850d485731ca1d5e45c159a7b7a0912325e539937aa21ceb18",
+                "build/pdf.worker.mjs": "17a05acff3cc48a8196adc0ba2c9f7a31decab3a546603d21cdcde7e19681e43",
+                "build/pdf.worker.mjs.map": "74109e9ba30734f0cca2a1c880de30ac63d9b8d8405e234360d1518bd6ef3d0e",
+                "cmaps/78-EUC-H.bcmap": "d92a261336dc18b8c03a46eb4d462382d33f4338fa195d303256b2031434c874",
+                "cmaps/78-EUC-V.bcmap": "61670bebc4e4827b67230c054fd0d820d6e30c3584d02e386804e62bbedc032a",
+                "cmaps/78-H.bcmap": "ece6415b853d61e1b2560165151407d35cf16e6556932b85a13ea75276b77402",
+                "cmaps/78-RKSJ-H.bcmap": "696b1f973c97623496703809eaaa5f9b40696c77540057413f4b826a08edfa7b",
+                "cmaps/78-RKSJ-V.bcmap": "53cb6d560ab377da48cf65d6dcacb0bdb31f13fab7066c580de38c12a73a7ff9",
+                "cmaps/78-V.bcmap": "289000f02fd34872b6975503217f33abae6bee676e7d28f640473a67c8db1712",
+                "cmaps/78ms-RKSJ-H.bcmap": "a2442595218f5f8bd8e1b42188e368587d876cfe0cc4cd87196f077c878f72e2",
+                "cmaps/78ms-RKSJ-V.bcmap": "f8ddceba96bfd9d3740bd1789ee30d1f47c78371520a8084f71f7df58f19be0b",
+                "cmaps/83pv-RKSJ-H.bcmap": "44040051ec818fe09b9703472bea72efd2759d5eeb5ff0d77c718d6bb5e6d1df",
+                "cmaps/90ms-RKSJ-H.bcmap": "c13e043e85ff715b75bb03801e8fd0fb8f3a75e4a48496faa6baaf92b5b48ba1",
+                "cmaps/90ms-RKSJ-V.bcmap": "499bb916ce1adbe4289b6e5811f4dc20eb238cdc2ffad20cf26ae56716885bab",
+                "cmaps/90msp-RKSJ-H.bcmap": "7b8b3b8bbf821702e9a4df9f3596ce292380c8c1b0925dedadbb4e4b2d80498b",
+                "cmaps/90msp-RKSJ-V.bcmap": "6296c2b5c07dca8128e96d5296d621a3268803d4fa0e5812a21e52fe2802aacb",
+                "cmaps/90pv-RKSJ-H.bcmap": "fb5103f03d3a34547e18d316e52b6d9b26e485c662999222f84d2ba54c2e4fa8",
+                "cmaps/90pv-RKSJ-V.bcmap": "7bcb5ad2ba55b9662ce379e16c2d9cc2b82d621a579807353741172e4af615c2",
+                "cmaps/Add-H.bcmap": "a2ffab28b990998181bcca9b0e914bb2207820f100ae31d5c469444892e5ad8e",
+                "cmaps/Add-RKSJ-H.bcmap": "b29f4b52e2465d0485856d5e69f1ba69927deb2848d8fd328c8035583b35bb7e",
+                "cmaps/Add-RKSJ-V.bcmap": "2aa2232c283a3f5d0997c2834a36cead0b79ce2657944cfeed08140c293460ff",
+                "cmaps/Add-V.bcmap": "25125d3b1be64e86b2df5b3344170b45a42bcaa0b46e43a34314ef73c166e542",
+                "cmaps/Adobe-CNS1-0.bcmap": "8c65be9d51a9f269a547dc12460707aaf4031ab67ebe8a2900f4b4cc6b3e450e",
+                "cmaps/Adobe-CNS1-1.bcmap": "73152bc1a59cc594b414ac6068be48e5512b96ae85920c40e32a99269fdb0c04",
+                "cmaps/Adobe-CNS1-2.bcmap": "a1b8d353bdef9584c820464e8f1c9e2013d64ebf433cba0aa831dddf515818c2",
+                "cmaps/Adobe-CNS1-3.bcmap": "2ffc0c75c79fafde506163d3c08c390d183251009f3fbf6ae50d1167d14b9570",
+                "cmaps/Adobe-CNS1-4.bcmap": "98a1f470c878c6b9691a4d7aef776af8ac9b55f5587c9fafa00547f3bf655716",
+                "cmaps/Adobe-CNS1-5.bcmap": "ddd6e29955eb8cb545f2ebd09c628c3bbda5023256eda1b728f743c75fb77829",
+                "cmaps/Adobe-CNS1-6.bcmap": "317bb2db71e0e5b7b0c47b75de1da915c2e22f65f0c0861507f9ca7ba238f8a2",
+                "cmaps/Adobe-CNS1-UCS2.bcmap": "e665837f2197c6bd08cd8955ad4d6932cee2398e2e328b25b00e6bfb3bd72af9",
+                "cmaps/Adobe-GB1-0.bcmap": "8b81cce8a11d510e505704953cfa4e4ab080c1a0cab991145a3512ee433946b9",
+                "cmaps/Adobe-GB1-1.bcmap": "0426983081788ec7202703e71f1efa4b860f75b936994236010b39d89251a81e",
+                "cmaps/Adobe-GB1-2.bcmap": "e67b37a83b160ab3831306a71a605893b24454ee81ac9b6123bf2d3984d268d5",
+                "cmaps/Adobe-GB1-3.bcmap": "aa299afc3e12a28726147305f191be28c7498078c8b182ece7886ac79cd99078",
+                "cmaps/Adobe-GB1-4.bcmap": "8fbd7d74c2ddb1350c1cecce54a73fde3f5453093d4bed445283ec0033d2097f",
+                "cmaps/Adobe-GB1-5.bcmap": "c22cb2fcff24112fa31dab2111bdc51957006576d31aad5a25e67793ac01428c",
+                "cmaps/Adobe-GB1-UCS2.bcmap": "20507620260c0c935c35afc1e70e5888aa7125d5ec7ffc03cef1959feb2c1641",
+                "cmaps/Adobe-Japan1-0.bcmap": "464f08905236f5703b1f5cf8358767c8b18e6bcc808840d081f1de2c7ab38134",
+                "cmaps/Adobe-Japan1-1.bcmap": "4c823848722187d1ffe75ae3f5f9126ccd2d7895a05fad14c919fb119e037008",
+                "cmaps/Adobe-Japan1-2.bcmap": "7810fb808e367e70429e90a9478fe6a3fdc3e214f25c7582ce9c2da6a242315c",
+                "cmaps/Adobe-Japan1-3.bcmap": "84deb1828711ad3d390c9899c38abce1bf619d65ff7bf1a326ec95acc45f08f8",
+                "cmaps/Adobe-Japan1-4.bcmap": "3f8a4f974919c2b8bae5d10175ffa2673be140481e00840542c85d48ef184067",
+                "cmaps/Adobe-Japan1-5.bcmap": "1d3ce4ff28d977f8cf37a912ae4ec811f4175c3167b1ec0b2567feec3e79e1db",
+                "cmaps/Adobe-Japan1-6.bcmap": "5609797b9401b30be72ef9645da62a87829f058c3be4b5c623383119f584b1d9",
+                "cmaps/Adobe-Japan1-UCS2.bcmap": "66c5d0dc4964f4093e77b194023f3a0f689324028ec8330e1e1d0570bcba7c2f",
+                "cmaps/Adobe-Korea1-0.bcmap": "dfb8c3874f0e5a8c3acf597d2c12d2b63e90bc5e4f0fce990ec4c56077d80b32",
+                "cmaps/Adobe-Korea1-1.bcmap": "62f277b7b1c441c007797ae707d5c37258d029ce4661a2b911e2e1ee35e6adc1",
+                "cmaps/Adobe-Korea1-2.bcmap": "1d77068af462f96d7ad28ad7e7d43eef6423c685b479d7dc25ff5df38db0380d",
+                "cmaps/Adobe-Korea1-UCS2.bcmap": "857b723088be97255053562bfa41bd1075a7f7910d3bab59a0645c8bbc7060ff",
+                "cmaps/B5-H.bcmap": "718ad0ffbef4c34f8f3f31292c462e519cd567a5511fc8b346c60010d64f4ef9",
+                "cmaps/B5-V.bcmap": "b5c37383517477620ced927b6b4ffd4f4cc6230d8051b5b46a21d6768e07f7d8",
+                "cmaps/B5pc-H.bcmap": "bab6028aead1d6149400e904ab10cfd319082d826473ed4c582c8eeed920f17e",
+                "cmaps/B5pc-V.bcmap": "41543142b9767f3b76133899fc8453282b01ad3c653acaeea42d78c5a7d08c63",
+                "cmaps/CNS-EUC-H.bcmap": "e8f89cd61e6486b948205da46499d659ed0aed949b7095fd3c8e95ffe2b0e7a9",
+                "cmaps/CNS-EUC-V.bcmap": "cae422bec2ac6dbe86bf921cec942bacd2d0b733ffcca5f91b3ba14e917025a0",
+                "cmaps/CNS1-H.bcmap": "e8487971ab20cd16f3de3e8ac56ec994b72b658ad113f2818239dfd5108f501a",
+                "cmaps/CNS1-V.bcmap": "42df8076aaa7574505e7304af83a3323ec032c4177d64b1309db8c043d594a8a",
+                "cmaps/CNS2-H.bcmap": "bc6024d274d440f0625c69e25f37036ef6cb6689432ceaa160d3432a2a716ca7",
+                "cmaps/CNS2-V.bcmap": "2e4f70a8afd23a121030fc2e5b5f3816e903b11e7ba8b8c09654b31c80399c38",
+                "cmaps/ETHK-B5-H.bcmap": "d2f10fa519336bc4efcc7b6deb9604b75429946b40d82e311cb3a97a1994c89a",
+                "cmaps/ETHK-B5-V.bcmap": "1fea3fd0d9f0f679f80505800851ef2e4131d81127e18c006938ffa2f4c8b247",
+                "cmaps/ETen-B5-H.bcmap": "87ee6b3f5bfda5fe26fa35431264c7d73070d10dbbf398a75185d63ae322c18d",
+                "cmaps/ETen-B5-V.bcmap": "47dc0d2c21e3bde317947aec1675ceabc1d5460a60bf9c24334b8c407a17172c",
+                "cmaps/ETenms-B5-H.bcmap": "d5f5a73da4173b7da9a3a20e16f26f9cd5d12deb1553409919e0cec6fd37fdee",
+                "cmaps/ETenms-B5-V.bcmap": "18252fca90f472f479af1bddd60d6ab51c8e1b55dcf6845951426504934543e0",
+                "cmaps/EUC-H.bcmap": "f9939cd57fccdc65c5d9f4c205fd497ebdbd283643308da5663801a8c1d9c595",
+                "cmaps/EUC-V.bcmap": "1283a50a706507c4436da83ede9ad7a4440be25378f2e96f6c81a430081426a3",
+                "cmaps/Ext-H.bcmap": "4000ed4e61a1c668ef453bbd0603cfa383defa793abd46a57ed870d7f527350b",
+                "cmaps/Ext-RKSJ-H.bcmap": "e0d2f0df337660e73813238dd4a725f11f0621b90f3273857db253d0e7694caa",
+                "cmaps/Ext-RKSJ-V.bcmap": "f617a22b6d67febb187990952006c91a9f5a4db21155d268c656252d0c21985d",
+                "cmaps/Ext-V.bcmap": "c2087fb845a9e3acea0c2922cd40e6af67e11957bec74dcd597f1285edd490ce",
+                "cmaps/GB-EUC-H.bcmap": "928bad06fd84a48f5ba7150d7716609119fb660f2aaa73eccad81ddab9b9d203",
+                "cmaps/GB-EUC-V.bcmap": "a9ad88ac2479da529b16dc48abc5952332e27bc355335f91df5729a587533324",
+                "cmaps/GB-H.bcmap": "1018c777a8910b5bb46d7d54a4aee9d51ca5cff8addb2b41c969d9101cb3fd1c",
+                "cmaps/GB-V.bcmap": "0b96789143c0bbf9f1641ae7165b3456dccd14dabffcbb0bd654d5bf6f94f863",
+                "cmaps/GBK-EUC-H.bcmap": "2103fed28650ede096a2281104a1a8a4304dae0db414342c636867522307123b",
+                "cmaps/GBK-EUC-V.bcmap": "a7fd35dd14d9dbdb955f34e6c0630618b6620dfd09d4283b2f65a65ce77fcaea",
+                "cmaps/GBK2K-H.bcmap": "3d919ae72af16c5cc6846ec87a4326a9f125e493c59d3628429d35c2c95fe8c4",
+                "cmaps/GBK2K-V.bcmap": "b927fdfd595c07ce9158bf2ec13f4641b2e83b01c70989dadfabd6ed7c6ac2dc",
+                "cmaps/GBKp-EUC-H.bcmap": "d15ebd8e81fb4fe8a244f1b1e877922e03500ac69eddf5001093e502430451d2",
+                "cmaps/GBKp-EUC-V.bcmap": "fdc736d46e642625dccc8ad8c59f2c69fc7db7a13f2e799c6c6b779e707bb97a",
+                "cmaps/GBT-EUC-H.bcmap": "dc5f44e48a39f3367ae28665027d8ab1d8cedb5a9dcc5068a900acd6709f60f9",
+                "cmaps/GBT-EUC-V.bcmap": "a1ad24e63653b8aa388c18fa5e498f007564e43dde699a9f91ccb4645c999be8",
+                "cmaps/GBT-H.bcmap": "8afda745a505763f3ff54c8126eeb48ef376ea9ed07d9f42ff9a22c5c547ec57",
+                "cmaps/GBT-V.bcmap": "cdc2ec5c3c7c7033290c9a8894878202f08674eb9b1ae7d36218430326768771",
+                "cmaps/GBTpc-EUC-H.bcmap": "7b23e2f7bfdb6c918f567b7324bf858f398bd8cd5f268d74ece19a3c91bf4f32",
+                "cmaps/GBTpc-EUC-V.bcmap": "d7a1b13ead9ab511cf2cd01de6ce8b02aa8e8767e84895337d7a3b67f039f93b",
+                "cmaps/GBpc-EUC-H.bcmap": "3c4a4eb82f05abe51f6650985c630e180438bfdd491318f5d20d2ec29236e1c3",
+                "cmaps/GBpc-EUC-V.bcmap": "215bdfa2842705624b4cf4cd29b8e3c720f1e192365e0305c11030a424c84d7c",
+                "cmaps/H.bcmap": "a0233e21047ec00b852125b243cbcf30abee511155b6d8159c24f944384bc9ee",
+                "cmaps/HKdla-B5-H.bcmap": "5242bce18fb13ab4cc59b146a03eba36e4ce42667eeff09e10981a9d2aa4996b",
+                "cmaps/HKdla-B5-V.bcmap": "2e0537f786c0791d41a925f72bad2d4e7268aa6cbf15a1400a722672cec38e2c",
+                "cmaps/HKdlb-B5-H.bcmap": "fdc8159984bf5dbe475c0d5dfcb621ecee4dea07c38c668bd77f4c679e23b9b3",
+                "cmaps/HKdlb-B5-V.bcmap": "b249eb9dcb915ab45057c5d4d7aa55ef88d0efbb092af6bae0b2d4705d139abf",
+                "cmaps/HKgccs-B5-H.bcmap": "ab64c7fc5e9b2e97750cc4f269b0da14fd8649e49151b7598c8df86599bac591",
+                "cmaps/HKgccs-B5-V.bcmap": "02ebdf7cdffb5395fb21091cd58a013a18ae5388922822f9dc6292ef16b98956",
+                "cmaps/HKm314-B5-H.bcmap": "bfd8bbde6b36a9da4c1c902c74121a30d9807a7079a00eeea218be6adc223cef",
+                "cmaps/HKm314-B5-V.bcmap": "2a64a815cfb6fdd480674a868762e3d161fda17543b20c9209978559f0667164",
+                "cmaps/HKm471-B5-H.bcmap": "49d7c037758826b5b6c0fa329c35bbf25d3943197754e72ecd30c6fb04d745e6",
+                "cmaps/HKm471-B5-V.bcmap": "be24c109e78aa4fe3c1f27d30aab3ed0741e783fa1b6b6c2719741072b54b132",
+                "cmaps/HKscs-B5-H.bcmap": "08599378f41d96b40537adef6e6edcc4a787bc63f5accf47c026df4905a13914",
+                "cmaps/HKscs-B5-V.bcmap": "d073542b7dad1c4cbf01c1af5f0cd13218d1281a491956e310c55702fc8705c4",
+                "cmaps/Hankaku.bcmap": "b454701f7aecd7856769016dfd04ca64280a060f2c67a2466d50b4395d24974e",
+                "cmaps/Hiragana.bcmap": "2ed669394756dd9458651cd9995ab29ab691ecb7686659003306cdf22767a414",
+                "cmaps/KSC-EUC-H.bcmap": "6784e16dbc5861c036c23d3e55f0d4ba0975a3e464da0ee8e49bcfff0be070c4",
+                "cmaps/KSC-EUC-V.bcmap": "fdb36bad85e9924823d49db374067988e024cf80fc894711f2c9178951cbbe95",
+                "cmaps/KSC-H.bcmap": "c1f6d61f1d3304fd539a65ae72624fa567ecc3853bf52e283958a7a2515b3eee",
+                "cmaps/KSC-Johab-H.bcmap": "939993d213f68db763bf156217c217ae23af082b91a0eacecf3d11eb4ff8ef8c",
+                "cmaps/KSC-Johab-V.bcmap": "5d61967aac0e666def721e8b8d0fed8f95a879a14f2e76ce516c3d11c621e519",
+                "cmaps/KSC-V.bcmap": "d7da5afd9f1fe74816d79c9325f0139a4efb6438664ebfdf9a7aa92f3034360f",
+                "cmaps/KSCms-UHC-H.bcmap": "5b70d8f6a4fa9e2283dc649f0ff95d906d56efbee50a20e8d2faec3a8fed078e",
+                "cmaps/KSCms-UHC-HW-H.bcmap": "a5e6ba22aceb02fdedee11bfb9ed138463d89e85b87810b9f075b469d936f8ec",
+                "cmaps/KSCms-UHC-HW-V.bcmap": "890332a6a26880d463a12f2a6ff048bf9cf7e45077cfb1ca8815b89baa7bf411",
+                "cmaps/KSCms-UHC-V.bcmap": "1631b531c9a40c8cbe24c2317dba107362e49fa6e18af620414d627c111d570c",
+                "cmaps/KSCpc-EUC-H.bcmap": "709480682c55cedbb0124b9960d78e28febeee0df2e34607d61aac6601647ec7",
+                "cmaps/KSCpc-EUC-V.bcmap": "031707887d6fc2378a36cdb6775334fd7a236c3f95048d8436abf43fe26fc49d",
+                "cmaps/Katakana.bcmap": "3b6ca6642fbf8822da00d5e58a8aa275216d5c32dbf2bd73e934197fc9fc5c53",
+                "cmaps/LICENSE": "aa92ab5a472974865a96fd4a4e9c13bb41bf6fe1b309cb6b8da48bc9e19839a2",
+                "cmaps/NWP-H.bcmap": "286c6c9e335da330928a01edc3c97a3a623f1f7f3c42762b0a7dc2f651b1a78f",
+                "cmaps/NWP-V.bcmap": "3a75fb7b59adfb172710758c425d8ac6c93fd5360a64dd4afd5dd04e60ab4b4d",
+                "cmaps/RKSJ-H.bcmap": "a70de61a22a898f693f02cc011c3e3cff2e10aaa7cddb4661e456a21ae859f78",
+                "cmaps/RKSJ-V.bcmap": "68c1a64506471a524ea5cfc3b3a9f8f70031989a6bd95427b1351f33ccf50b06",
+                "cmaps/Roman.bcmap": "1c6b3ef9d9e5cb1aa329142ce9414b90f9b6d7f9182a2a9e927378dab8f0d43f",
+                "cmaps/UniCNS-UCS2-H.bcmap": "779428116752f34e2490a1941d24e4634c71e3c22d053b811d2090ae2fb3c704",
+                "cmaps/UniCNS-UCS2-V.bcmap": "1e5cc184b850ea44abc2df8ae5674279df668e8edf5e2a1a2ea2bd77adbd280f",
+                "cmaps/UniCNS-UTF16-H.bcmap": "32ff139b3c7b91d6ad25f994701f3ce7b242906022c418fd73e6493fc228bfe5",
+                "cmaps/UniCNS-UTF16-V.bcmap": "278eb1e68d1a236c60ef59472cf0176ee0d45f364285e76ca12419a08d46fb9a",
+                "cmaps/UniCNS-UTF32-H.bcmap": "bf26eb67fe19ee5ba915799e80ca72408400aa8342fdf6a244a4f44de8f97336",
+                "cmaps/UniCNS-UTF32-V.bcmap": "f7da3caf83ceb1cb37936fa10700d9ba6e9c3f72c5bc9724e3ac79bff0c0179e",
+                "cmaps/UniCNS-UTF8-H.bcmap": "2f2a742bcd1a84a148a4a518b9eed51a8f9c6ca5ed3bc5e2e41fff97de5dc2d8",
+                "cmaps/UniCNS-UTF8-V.bcmap": "b7c3f10780a8c62dd1c8ff6c30dc1e4e23b6cdc87c3a96fcd514cc98ffd3af9d",
+                "cmaps/UniGB-UCS2-H.bcmap": "9201569b402e81ad8860650bd86350c4fa28e5dd5971f05fcacaf40f51de18ed",
+                "cmaps/UniGB-UCS2-V.bcmap": "f10282335e4d64203bc2a653a3a47d745ec76c8ae04549f4d50180c1899be216",
+                "cmaps/UniGB-UTF16-H.bcmap": "386fd39581245c034da016a92d23f3df1117d169f996100050b264fc09a84e35",
+                "cmaps/UniGB-UTF16-V.bcmap": "0473cfbba612b92dd9918f0ff8aee9112897c48e0ffdc0eb82da3144ed8ea84a",
+                "cmaps/UniGB-UTF32-H.bcmap": "f48a145dc4e3ed1dca1dde7111716a72306a2a4191ab05c6bae3a5c3a961cd2f",
+                "cmaps/UniGB-UTF32-V.bcmap": "106acc49b7118bdef944e32107b4f348238f3929a0a15d3b7aab7b9101535993",
+                "cmaps/UniGB-UTF8-H.bcmap": "f217b439c80ee5fa1bc2cf6d1defcc319f8d84483d166a00ee199e05a68588df",
+                "cmaps/UniGB-UTF8-V.bcmap": "a64df947632878eacc532fa193c735c92a383b7d66e6f8374ac193af7c64fc63",
+                "cmaps/UniJIS-UCS2-H.bcmap": "ad2352f40870880fbf7f8ee5abadff743fbd025fbf9830b8ada472d1c5e4da0b",
+                "cmaps/UniJIS-UCS2-HW-H.bcmap": "16e87edca954177c0881c874859d6783220925d821b5cdfb8755b61ebd93f9ce",
+                "cmaps/UniJIS-UCS2-HW-V.bcmap": "1973457e2c0192819947e56068625b34fb9a72ecc8a476ce6d7eaae5f73e2e5c",
+                "cmaps/UniJIS-UCS2-V.bcmap": "42a133d8e2ce9dd6d2288018e01592d2bf2435b326d39b94ea0b6e6a44ac33d3",
+                "cmaps/UniJIS-UTF16-H.bcmap": "f6a89c5688978548c83fcee990e205bc63c74274d5c69b49032a3bd4c49a05ee",
+                "cmaps/UniJIS-UTF16-V.bcmap": "c67126fc7c73850855186bb0d6482ac0a365057e0b58778c4ab9f234683fef53",
+                "cmaps/UniJIS-UTF32-H.bcmap": "96195950ce0fe24443d8eb426fa6b88534ec421d7bef9046f0b2362809cfba73",
+                "cmaps/UniJIS-UTF32-V.bcmap": "ed4dafda402bdd19c4d5d8bf2ab41473c0f86f384552b4c7b963d6627daedeb1",
+                "cmaps/UniJIS-UTF8-H.bcmap": "798fb0bf06ab0788d1f6a91c2db7de581612eef03c628f10e8f7ecd8f70ab448",
+                "cmaps/UniJIS-UTF8-V.bcmap": "1021611424f913b2df0bfdbe94bd327c04e224ec89d8e821c6501ea3d21f4265",
+                "cmaps/UniJIS2004-UTF16-H.bcmap": "710a32d7cb43fd6bd9dbf30da5971f8c941590f74441e208d852c2be0e74cc97",
+                "cmaps/UniJIS2004-UTF16-V.bcmap": "3b149aff5c5707b57fb3215d1775852c8b1f413ec0f679ea628f25cf87fe098d",
+                "cmaps/UniJIS2004-UTF32-H.bcmap": "8d2658e18741af7937d586a57c89729a6fec0d86121197c1f8518aa58b29cdfb",
+                "cmaps/UniJIS2004-UTF32-V.bcmap": "6dd475782f2897648a683c48b2fa015a15b8f06856760bddc8a17a63f418bacb",
+                "cmaps/UniJIS2004-UTF8-H.bcmap": "691c614ce432b3e62486efb54e5c84c6da5afe9b51b21253bde4758feb484183",
+                "cmaps/UniJIS2004-UTF8-V.bcmap": "40a8c7ea2d46711c5f78fc9a878a7db68b1543ba5cd60ecf14f519a2deb829b7",
+                "cmaps/UniJISPro-UCS2-HW-V.bcmap": "6826f94d789d7bf1960668c1c5819c34c9585c1b23152fbc19ee81c7df08524b",
+                "cmaps/UniJISPro-UCS2-V.bcmap": "493de9fd1a08f7946065d8ab58f0c3c9fe489f5a0f109f2d05a3169b4bd5789f",
+                "cmaps/UniJISPro-UTF8-V.bcmap": "6181d382cf736c5e09492e8be9f26f31fa25b7462253f23ab16646af432cad81",
+                "cmaps/UniJISX0213-UTF32-H.bcmap": "692044e1fb33445668632bc9fe7386805c624864be1ddeb29d65bb0c99fc630c",
+                "cmaps/UniJISX0213-UTF32-V.bcmap": "dd54e16ca7bffb3a886242549b2bf7d78a277087f7c60d2636f118c21a5b0646",
+                "cmaps/UniJISX02132004-UTF32-H.bcmap": "f80ea5a989be30ccda5a8804baef6d3b4b044d2b339bf8b31c671b2466171cf6",
+                "cmaps/UniJISX02132004-UTF32-V.bcmap": "94c22bd99e771c5fbe0dd8dc39850570d4db0075074aca13e272813edd7cc57f",
+                "cmaps/UniKS-UCS2-H.bcmap": "a1081396ab4adb6f4a5b6c15f896963c244c1c9bcb65ce5616d06096a1b9811c",
+                "cmaps/UniKS-UCS2-V.bcmap": "6cab547431958fbdc1d401d06ebd4dd61a73f5509a10f974df32bcbca11a2e43",
+                "cmaps/UniKS-UTF16-H.bcmap": "42d35b396286499dfae1737a07adb3a64500df37b426580bfb1d3ea872938519",
+                "cmaps/UniKS-UTF16-V.bcmap": "5bdb7390c80dcc136cb47d41dc7460082560969c17322ee739fe3020fb642410",
+                "cmaps/UniKS-UTF32-H.bcmap": "3a01ec51ed1b828101351e337ffb8250abe11880032e5210f881170fed2588de",
+                "cmaps/UniKS-UTF32-V.bcmap": "dfda895eceaed081af030dbbb962b49629eea817fc3c02bae15db93d0c68acd7",
+                "cmaps/UniKS-UTF8-H.bcmap": "3fac9c65145f72d7d42157a3b9c5ed6904632184e6a0888f2b828699afd2002f",
+                "cmaps/UniKS-UTF8-V.bcmap": "9ecc6cf30dd354b9778ddba163b6cc7302b087ce9f39d1ba73472d2b75ed13ca",
+                "cmaps/V.bcmap": "b9ad1c0c09ff14bca52f9a28a9767eb857ad0e8946e64ba14c7387a7eb69866a",
+                "cmaps/WP-Symbol.bcmap": "543923bead225732aba30976690ee89095a19628277b5863efecc2c728d5d7bf",
+                "iccs/CGATS001Compat-v2-micro.icc": "73e1ba37d2bad5bab2a964f40a9eed96209666efc067c3322626214bbef234a0",
+                "iccs/LICENSE": "286e4fd7b447330b2c88e23890e3cd0a9d38cb398d4a59cb247f578ccbda3213",
+                "image_decoders/pdf.image_decoders.min.mjs": "2ce7c5e8028ff9015c95bd79f56f261e7519abd7a8831bd7a0c11a2e413006d5",
+                "image_decoders/pdf.image_decoders.mjs": "e834780a4924a54b7e4f0fc844987b3bd81d941db00c33dcc59b16a0d793eef7",
+                "image_decoders/pdf.image_decoders.mjs.map": "5a7b7ad7d4eb56a6478ca0edec59c11b2a07db74f247502ab4269cef57a43b85",
+                "legacy/build/pdf.d.mts": "dc11ac5030092409dd3183dbb24174beaf35739b9b5c90f268b3cf82b9453708",
+                "legacy/build/pdf.min.mjs": "bccc24ea711db8e44503629519904a5292d73b9daaa214bbe7cdcc282b0f4259",
+                "legacy/build/pdf.mjs": "bc51f4874a66e3853189cb5d50aba4b3096afa83ed433b885d293a3d94583cdc",
+                "legacy/build/pdf.mjs.map": "fc4626175932076624b69d37aa368922e4fbea9421621937c9840b5678df9566",
+                "legacy/build/pdf.sandbox.min.mjs": "a08ff6d71e7618e2f8c974da2aa24addb5108efc39bfe902625a1b257d846c7f",
+                "legacy/build/pdf.sandbox.mjs": "a2585f385c03ef63b7a9c787371a4d1011b6b452e31f959fd196b1bef5f57d2b",
+                "legacy/build/pdf.sandbox.mjs.map": "600e419faf8211d419a187af4c0824e38ab3d3c1eac401b7cf438306a514b5e9",
+                "legacy/build/pdf.worker.min.mjs": "145d2dd3ab0c86151011dba95acfa2d5336e2accd59388ea43dbee0efddaaec6",
+                "legacy/build/pdf.worker.mjs": "bb422f60804477de4a0b09091d8347a916a387755ed1cbad24ccaec1d09c78bf",
+                "legacy/build/pdf.worker.mjs.map": "9d039e6f6bfba644f7bee73f88cb6b055840883754ff5d9d66963e81a3284b3c",
+                "legacy/image_decoders/pdf.image_decoders.min.mjs": "3fa284b5c15ffd7b4690ecbf04c8a8224567aa9a878d37f03b17c04401676a0b",
+                "legacy/image_decoders/pdf.image_decoders.mjs": "b23b948733e6eea6d07e3450dfb3e51069165de4b384d6641779b02958fb3c6a",
+                "legacy/image_decoders/pdf.image_decoders.mjs.map": "8ae7dbbe3cc3a69a0654254111ce08801c92add1afd2f1a5294ca4832bd80051",
+                "legacy/web/images/altText_add.svg": "1a9591a23999e1924438b948a9f9671147f04e01e5be724391a3a8a2b58289d9",
+                "legacy/web/images/altText_disclaimer.svg": "5d19067a6b51e5bcc2d61325033a8450d301535505a97c50f4141f4cd9e2cf05",
+                "legacy/web/images/altText_done.svg": "5b40360d098d1a93227a0a5cdb110f6e5ff3a3eb4af97b61e856c49e17141621",
+                "legacy/web/images/altText_spinner.svg": "4089182e21627182ed1d4020978b597d984fb8de4cf547e9f4ac2aec9af13179",
+                "legacy/web/images/altText_warning.svg": "07264f4de78a45a4177ddefb48837217aa69b51462ef5b35d3fb9f90000c9ead",
+                "legacy/web/images/annotation-check.svg": "9a680f1212888ede7dcae6bfc8cafc447babf4ce531271c8d07277b0aedade96",
+                "legacy/web/images/annotation-comment.svg": "c58b385b4a0be6de822a3262b8191073d1730f6420368bd9c6d80db7312327ff",
+                "legacy/web/images/annotation-help.svg": "74d9bba0814d12f5ae2715189e1747b7edf5ff6d82c4ca75bae86d717319b6eb",
+                "legacy/web/images/annotation-insert.svg": "b2153e2c88c62179029ea9876d463216529ecf581b77d52c971a2cdf3d3166c6",
+                "legacy/web/images/annotation-key.svg": "5772b8dd158b0f02bb2be689bb680f4903d84e202cb29a3dc0560af53134c6ba",
+                "legacy/web/images/annotation-newparagraph.svg": "a583cca122263d94c3eebfefe83c965a1b305b9c84e5aa3c5ba10527941db7db",
+                "legacy/web/images/annotation-noicon.svg": "76399e70d311834d11ab2d6239118b36847d79a78d7655b1f839d51c811304cf",
+                "legacy/web/images/annotation-note.svg": "11a75c9f233dd3e5e3500edcdd733358394f28395337616e8b0430694bf0dba1",
+                "legacy/web/images/annotation-paperclip.svg": "0213c8baed4f8c497881ffed0e49abb309291d51725aaf1a0a757174b4999368",
+                "legacy/web/images/annotation-paragraph.svg": "efbcd2a6cfb4581dad74a1c09ad43cf2b8245611e5b19c966317da948f2bcb7c",
+                "legacy/web/images/annotation-pushpin.svg": "22197186d18445959e5fe5577d8e34440b31d87c811daf47318078310c0c5530",
+                "legacy/web/images/checkmark.svg": "424df6b8515df22424c9505a9e87d35d87d3fd59962d56692fcc4d17613f2165",
+                "legacy/web/images/comment-actionsButton.svg": "281b2348ed747ea3ee74763a01d56441d8c570b3e68f11556dc4084a14484d1f",
+                "legacy/web/images/comment-closeButton.svg": "fdb819984e10758952bc35b5be3220538b21a787656794b1071fecd3d2648930",
+                "legacy/web/images/comment-editButton.svg": "e79c41bf53a89ced9a3ad364a49943813189d06fd96174952e5fb2636938b70f",
+                "legacy/web/images/comment-popup-editButton.svg": "857c0198bc536885f2b486353d5719d0c1bb91d69325474f7d787ce5b43cfe1e",
+                "legacy/web/images/cursor-editorFreeHighlight.svg": "90b04428328a67e184fe1b1a1f28cb0d62bf6e298614ca241b6564fb24cb9e7e",
+                "legacy/web/images/cursor-editorFreeText.svg": "fedb05ee0dd510514ed9edb24b3b4da2707931279a0bf48e2a1deb3a1f4cf581",
+                "legacy/web/images/cursor-editorInk.svg": "0ae889debe01269b49b89d8845995281223b8ae289405758631076b763da3efe",
+                "legacy/web/images/cursor-editorTextHighlight.svg": "c6252b0edcb68dac87557a027180fcbdbd93466841aa34792530f7cce54cec5d",
+                "legacy/web/images/editor-toolbar-delete.svg": "f1f47a2cb479a87807f9bd61bd5813c1fe857dbbcb4fb35ae7a77ca39114f920",
+                "legacy/web/images/editor-toolbar-edit.svg": "c6eacc709e4dd30a57120b6531856c003a4c931c46656c3625e2fd5886cf4ce6",
+                "legacy/web/images/findbarButton-next.svg": "3029879b7e1060d54c4edcfe0c93c8c3b8c1756fb794e5d4add64028b5f99fab",
+                "legacy/web/images/findbarButton-previous.svg": "766d12bb08b9f13c753d289f3c029f5ca202eda3a8be52afc9e31697335f4a80",
+                "legacy/web/images/gv-toolbarButton-download.svg": "010d9d77a425e80eb666a196f500cdd8b15758af69a19ad7f11279b78c29e3f5",
+                "legacy/web/images/loading-icon.gif": "483c4a0396691993a641ec409c44b8b7e1daab0ae7e2b2944c4bc59520bb7655",
+                "legacy/web/images/loading.svg": "7d6e14cf6226c74c26e2141180eadc944ef4ce8565e9b6dd2670ec202417a764",
+                "legacy/web/images/messageBar_closingButton.svg": "7393c7791916243eca6bbdda8bf137d36600fffc76d7a55d33a77bd4e7778193",
+                "legacy/web/images/messageBar_info.svg": "050e838b982b1b3e993e06bd666f8693ea98e89fb568c39c4af32e128477aeef",
+                "legacy/web/images/messageBar_warning.svg": "888a4bf2ad5150028663dde01fe71599336c87ca12697180e51bd8a13b88084f",
+                "legacy/web/images/pages_closeButton.svg": "03577a1fc1fc16be0331c65d45accc4d57c269381999e00b2bec9005225a7643",
+                "legacy/web/images/pages_selected.svg": "a66ae84122fc40cc1282c68205909387e05a80061b9a7268a54b4bd0c9e7e2fc",
+                "legacy/web/images/pages_viewArrow.svg": "409d9a306df6e86bc433365f961be50c9b4256b7a89b741f2f858af5b456b2ce",
+                "legacy/web/images/pages_viewButton.svg": "f49c2ddd994c602dcaceb3c6b1445ef37bfd6ca8e2cb468d894741368c3344af",
+                "legacy/web/images/secondaryToolbarButton-documentProperties.svg": "735a4bc556610bc6dedaa40a36ccf444c31032be02ad20df5ac4c66ebaa5bbc3",
+                "legacy/web/images/secondaryToolbarButton-firstPage.svg": "d46a7b0760fbc043a98f9b328f6b4ee56df8de140a2a290f0e2a915ff772e287",
+                "legacy/web/images/secondaryToolbarButton-handTool.svg": "e968339ba921e68d4d83e6ec7a4321f1791c86f4eff552f28cf4c81c6f88155b",
+                "legacy/web/images/secondaryToolbarButton-lastPage.svg": "4cc4b92888b776ea3a09d5e86b17d7bb50a8f3e6d09854d4c2e3f050c34dc9f8",
+                "legacy/web/images/secondaryToolbarButton-rotateCcw.svg": "7eb24492df9f42c8ab053cbead5d985b0daaccced649392d1fbfde4931459451",
+                "legacy/web/images/secondaryToolbarButton-rotateCw.svg": "03d2e7bad2fc95895334e43edf34309a64223f32504304034eb1f6b163954898",
+                "legacy/web/images/secondaryToolbarButton-scrollHorizontal.svg": "c61fb184d5311255b627a9943c156bb1f00f835282d832241e01a7d82a22b678",
+                "legacy/web/images/secondaryToolbarButton-scrollPage.svg": "e60ae21987a2e6e5352ac3171363352cac9d2cae36bf828d1729cbfa286e085d",
+                "legacy/web/images/secondaryToolbarButton-scrollVertical.svg": "79871e2329cbb4dc2b6df94aae5f3074b3fdebffba46fe7d3ade9aff5726bfb0",
+                "legacy/web/images/secondaryToolbarButton-scrollWrapped.svg": "8734aa2747f6fff9e8fd09f6e9509db43ec1b63935c8f6b8291e9347bc7e2706",
+                "legacy/web/images/secondaryToolbarButton-selectTool.svg": "332e08979379ff2f8a7bfd336e8ca6348546c78ce2a6bf464cd31dc2c64004ac",
+                "legacy/web/images/secondaryToolbarButton-spreadEven.svg": "ac385199d448c0d5ae5d4c06d2c76db0a31bb5db54d0fbd727f3dc889e73271b",
+                "legacy/web/images/secondaryToolbarButton-spreadNone.svg": "649934c2f447d7a239d6ffce8f8e0804b50dfe1d9421a1d16e9543c0aee9b03e",
+                "legacy/web/images/secondaryToolbarButton-spreadOdd.svg": "43b6862d35f86dbe5fec6b16e2cb59ca22c490bdf0787e4590c1ceb494d05244",
+                "legacy/web/images/signature-properties-row-check.svg": "3fe9e7e5869e80c04e560ec79e8960ed0f3e918195b6de2b039bd33fb23ecf0f",
+                "legacy/web/images/toolbarButton-bookmark.svg": "f2a335bc963e95344d26d61157b1511f5f78d705b38579004971d51a3c62401c",
+                "legacy/web/images/toolbarButton-currentOutlineItem.svg": "5f6505f05dbc728301942b37de22d490f09276e6c9a6561b1894afa91f34439c",
+                "legacy/web/images/toolbarButton-download.svg": "afa286c8ea1941eaec589ed6a2103c5a845f3ff76a7423ba985f449465005163",
+                "legacy/web/images/toolbarButton-editorFreeText.svg": "9ec2202e18ba668ee1753179afead4e1786eac82da2cc82afc5a09584c242c43",
+                "legacy/web/images/toolbarButton-editorHighlight.svg": "df0aac50621777fb63da60b38c71c5bbbde746c4dd55c30dd141621cb30b7cc4",
+                "legacy/web/images/toolbarButton-editorInk.svg": "081bf99d3c2390036a2d9c7e9485316bcd049f90a74e982f1eebcfd4d9b178e3",
+                "legacy/web/images/toolbarButton-editorSignature.svg": "32e07998fd55a7ed40ec2b542fe324ec097d9023fc4c59d6debe33becdf215c2",
+                "legacy/web/images/toolbarButton-editorStamp.svg": "18294793f2399a8a44ee246d63b20cd46cb3cd38a1bb72f00b826e7f756c5f52",
+                "legacy/web/images/toolbarButton-menuArrow.svg": "2db41f97615a8c912f676a62c88b12e2b8715f4ed188df325737423501aa4a8a",
+                "legacy/web/images/toolbarButton-menuArrowNova.svg": "8677b09af730ba49dde7be6f16d08a0b4eb594ed3402f9693e298223d3e9efff",
+                "legacy/web/images/toolbarButton-openFile.svg": "7acb9e9964dd618bfcb657d8d18db2c55ef8f168c37f3873c06d72c63e1b11ec",
+                "legacy/web/images/toolbarButton-pageDown.svg": "09a14cbd902aad9fe40f2351db2ac5593ad897aed8810b9c6aeb0e56389ff100",
+                "legacy/web/images/toolbarButton-pageUp.svg": "bac79138cb730c6bfa63bef02d7e5906aee727bb54df15878823426822badaaa",
+                "legacy/web/images/toolbarButton-presentationMode.svg": "2a08e4277e39a9faef69520570744650bb017c2e90fe7c15224144d6b4abfbe7",
+                "legacy/web/images/toolbarButton-print.svg": "267745d6c176afe038630c3f7c0fcda78141fc7634f73898ffc6cbb1262c77ab",
+                "legacy/web/images/toolbarButton-search.svg": "32889acafd84edeec513db6131252fa97ffff00fee6272d05e35e2d95216e30f",
+                "legacy/web/images/toolbarButton-secondaryToolbarToggle.svg": "ff717321d89309f51bcccc28f347e6a888e73570527845d6560a84f5d70cb3a0",
+                "legacy/web/images/toolbarButton-signaturePropertiesError.svg": "957d6ce5e6c4a62f88ad0e79c50b6ccd94358524a7450d3b04eb318146a46351",
+                "legacy/web/images/toolbarButton-signaturePropertiesVerified.svg": "ae9f3a3e7e8e16900e6b2dbaa7acea0111763b72125246e55b572f4e9e66bc16",
+                "legacy/web/images/toolbarButton-viewAttachments.svg": "e07fbf17b3c7ca2cda9c4e54cdd66cb0aa63d368232cbb2c9aed5559720bf96c",
+                "legacy/web/images/toolbarButton-viewLayers.svg": "e0b8a59c272dc9a1d9a07d461363f96c3b3bd3df2db778f8f99743dfffd51d78",
+                "legacy/web/images/toolbarButton-viewOutline.svg": "eeb6cd0ce94dcfea6bd2aca222da7b1583d74800ea9c94640ff8fa06c13fb044",
+                "legacy/web/images/toolbarButton-viewThumbnail.svg": "5fa35769db66b33d6408f378e8aa68fa060331f0cc9dd6ad41fb7366082aad34",
+                "legacy/web/images/toolbarButton-viewsManagerToggle.svg": "88098d3e47fd921122c5263dce50ee67c662c9cb65908be0481891dfe521a6c5",
+                "legacy/web/images/toolbarButton-zoomIn.svg": "722dfe315686a5841d0a0d00f34df8f706d2c6e24551d46a5ebe971fe4af62d2",
+                "legacy/web/images/toolbarButton-zoomOut.svg": "366a40c3627e67f97164976d5ff38b5484716e834d08fefe252a6ea37feda895",
+                "legacy/web/images/treeitem-collapsed.svg": "37c96d0dc2f626c541303a76067184ac09614f2390a8430e973a84e5184e2646",
+                "legacy/web/images/treeitem-expanded.svg": "df4a149c4eaed4573620621087f7bab816f049e3e341574654fab598435db086",
+                "legacy/web/pdf_viewer.css": "1f3c7c3c692d4da2334d0386d2286ec040a37db8654e02b8704b11262bc9bf49",
+                "legacy/web/pdf_viewer.d.mts": "6f2878ba5118b5f3cc4f08d112ba64e3362921cda7bef7e23f1c64f811757e71",
+                "legacy/web/pdf_viewer.mjs": "94836afa5e6d3e5f9abea50dced92dac6083ac2a11548d3681c3414dd6d3425f",
+                "legacy/web/pdf_viewer.mjs.map": "330b75c07a79fe28a88698922a457bae19df6280e56a77b54f33ef0a66b73885",
+                "legacy/webpack.mjs": "eac3e389a6200bbfdd5006caaa71a59c26bb5df2a358f90eddbf5c63b67ea450",
+                "package.json": "9a343cbb1db43294051abbe1d4fa615de03e39ad5e2dbdd9bf3ece40417e12cb",
+                "standard_fonts/FoxitDingbats.pfb": "845c752392b6c914fb989c75a08b7792b88f542d2499042ef2889f8c814a16ed",
+                "standard_fonts/FoxitFixed.pfb": "b6c8fe53f134b8b6d4578cd2d544df4cee9624c4efa8d51a560fb40ea296101b",
+                "standard_fonts/FoxitFixedBold.pfb": "f1b7159702973f54fc86254ea38bcf3712b2a736eb3a0995751e9f4bb45ad603",
+                "standard_fonts/FoxitFixedBoldItalic.pfb": "8a000945843bd31add06aee63bf9fd41b7578b4f3242a4b7cd46349ad9d24d4d",
+                "standard_fonts/FoxitFixedItalic.pfb": "5007faf8320fa1fcc08b8894b356ad976f60b992ba29ee5272578bbdebaf3876",
+                "standard_fonts/FoxitSerif.pfb": "4f57d2b9d884af8f907bf22df6019b52d86cbf6214fdbd02b1ae05472a543f35",
+                "standard_fonts/FoxitSerifBold.pfb": "0bdf4b04e964139818d51eda03d566ba999fc3ba2421b1c6c51f9dc969022e80",
+                "standard_fonts/FoxitSerifBoldItalic.pfb": "a406cac82583bf98175cb62c87ed5e95c45fbb34eece63a10b0a13e793cb2e10",
+                "standard_fonts/FoxitSerifItalic.pfb": "610ae0687198045c4db5d1a6650fd5e92536631706382eb8b72e38df578d0ae9",
+                "standard_fonts/FoxitSymbol.pfb": "47967d055530e7357088a08403115425643ec2cdfd6201ba8af0fbd7116c1539",
+                "standard_fonts/LICENSE_FOXIT": "b578cdd2345840ada550bd12519533812320d5f1d21cf4c1c7e1b1b0a31c98b7",
+                "standard_fonts/LICENSE_LIBERATION": "d2c4d5b3e115a519cb58eb691aa64538397e2611f9ebe801392cf9667997e7dc",
+                "standard_fonts/LiberationSans-Bold.ttf": "361c61b82d575c5c35fd9157fda8b0194bcfcd0d88ea8521a4fb5dd53d33dddc",
+                "standard_fonts/LiberationSans-BoldItalic.ttf": "a224075ac17495ad0a3af3bc0a419ac0704a8b3fd1095456201fb9b095fc281d",
+                "standard_fonts/LiberationSans-Italic.ttf": "832b4406dbef23628800d3aaad21048534ac84d7e3ad955be83b8172ed8ef512",
+                "standard_fonts/LiberationSans-Regular.ttf": "f8ace1f892b2bd9dc1792ba7f097fa7588f84fed48321480e04de5390828221f",
+                "types/external/brotli/decode.d.ts": "11ab2f892f18c1e3393aac59a0493485fe51d71419bc5bfaf2497015d85b1949",
+                "types/external/jbig2/jbig2.d.ts": "46b469eb4b7f996277e92c9e58b8569868b8fc8276ba0012bcb3c3b70c206175",
+                "types/external/openjpeg/openjpeg.d.ts": "bf2530244283630564774c353b1971f5ad3d3fb87a04d6489e62b8c21d7c63f1",
+                "types/external/qcms/qcms.d.ts": "95c187fec62a4f0941bb17ff5da679b95febc544bea66e5a63eddb964bfe0ca0",
+                "types/external/qcms/qcms_utils.d.ts": "da6a2d40c7b624019071b6ee981f4a3d71ba1ef53b9f79fd4975f3b529ce2871",
+                "types/src/core/ascii_85_stream.d.ts": "3dbfbba1ee7fb7f453351aa392a9accafb5e08c752ed72a66e210ddd633d664a",
+                "types/src/core/ascii_hex_stream.d.ts": "7c30733074008ffe38635cce00fe41a6fc5f80b7d1344311e798f4e4ff73234a",
+                "types/src/core/base_stream.d.ts": "c778ae2e56db7fa3ce5e8e65a62433b0d812e130631abdf4724eb246048c0c76",
+                "types/src/core/brotli_stream.d.ts": "dcc4422c8bb66a14c64f878d2ecfe6b88ba1518156a8077216d17b07b057a038",
+                "types/src/core/calculate_md5.d.ts": "7ea7bebefce8494d51885d68f5b673e636419249576bbfa993358e633347a90b",
+                "types/src/core/calculate_sha256.d.ts": "861222a0e59b278fabd77e5fb1bc1aeb9ff319bec73ca83aeffbc7dd07cc86c4",
+                "types/src/core/calculate_sha_other.d.ts": "fd88e77b3cd07e882eabafc5e39e87783e2753710ddea4d10d2cb68488a50fda",
+                "types/src/core/catalog.d.ts": "e3435c037cd2287bacbfb1a38e70515834676d3e07c5bdc9aede9015bd8a989b",
+                "types/src/core/ccitt_stream.d.ts": "56a9149b57fe8750a2cdc382d4873b610967894fe19e300fadecd07cc3abd2e8",
+                "types/src/core/cleanup_helper.d.ts": "505248bebe39ea019495c8b102118bfb21591e8bf2353194db9c54a7e0c36f37",
+                "types/src/core/colorspace.d.ts": "5904732241e2159ba13f84b790dbf1b04eff56a95fd619f539e27b22d27a400c",
+                "types/src/core/colorspace_utils.d.ts": "d2b4f871c0172d950fb5ea55cbcfb7d7317d345bcf71348dc5fdfd3295baa75d",
+                "types/src/core/core_utils.d.ts": "3d0cfe675951abf2b19ec27a7a6a9da97c93f62f9fa0b22a8dfdb4e982daddaa",
+                "types/src/core/crypto.d.ts": "8a515666eda0e1e6c693b02ff7ad9e66f88f85841b8536a8c2ae3ff73ed50b24",
+                "types/src/core/decode_stream.d.ts": "7ffa230ceee805a9d44eb9d8d0259da9e09f9af13614ff472e026275e153e362",
+                "types/src/core/decrypt_stream.d.ts": "c0801f5564dee3351293510b61c9c2e38fe78872af10d4ffe73e0dc3f4829395",
+                "types/src/core/file_spec.d.ts": "cbd4c0541c573b4852e522c720485b8cf9941d5e8d984fd14629f7b9036911f3",
+                "types/src/core/flate_stream.d.ts": "ddd06f6f66a85608857a51d9060af7e5d494d18622595779ec3fe0e8a2a2a99d",
+                "types/src/core/icc_colorspace.d.ts": "7f61601eacbedde15311067ae20effa292942098227d3b4c3d9bc64105b16bbb",
+                "types/src/core/image_resizer.d.ts": "50fb9e0ef3d1c84d26060d3e13238b4fc9867650dfc16c7bfc3fec5fc976bf38",
+                "types/src/core/image_utils.d.ts": "d5bafda2bf053cab0e25175725774fc26d06801d2f5b28759f01b9ecbec1f8d7",
+                "types/src/core/jbig2_ccittFax.d.ts": "ac2c9402e514c91b2c11349ce0662436678f52d20c4ed6d4e892f75552969d09",
+                "types/src/core/jbig2_stream.d.ts": "0896e7c596cf1b557e48c0f378ba3331992959b05424f5ff6c8a8f5cdd0666c3",
+                "types/src/core/jpeg_stream.d.ts": "da6000ccdec04e0bc24edbd1b038bbac1ae0aa8f39815284ca887544fcda44ca",
+                "types/src/core/jpg.d.ts": "b20ead74eaa475d99b6047baa0474d3ecd5d35323b24dba88e978b2e71327b40",
+                "types/src/core/jpx.d.ts": "50d81dfe961586045272770733144c8d71266290c6e3648021095a4f4e5e7113",
+                "types/src/core/jpx_stream.d.ts": "877b529b1da4bf3751fb701c5422c8dccac020360a715e173b1ec6865b929a09",
+                "types/src/core/lzw_stream.d.ts": "fa2c37029c206d07873bd8cc26f3baf3ccf26bdd281f82d646193717754a1641",
+                "types/src/core/metadata_parser.d.ts": "c3fb0e111b538e19b37e073e25b54e9b518f62729f0f75a38740e7bb14524985",
+                "types/src/core/name_number_tree.d.ts": "c926815a8b2e5abc5fa6a2fe99c6a47346b1e3e889980c9b1e622a884aad9354",
+                "types/src/core/parser.d.ts": "3474e195e8a8f5fc668eb7415b6192767446806f7f5424c82208e347db05dbd4",
+                "types/src/core/pattern.d.ts": "9ab1696974334031e19cf316b12bf3008851e38e2fd3ea1ab87a49d303740a76",
+                "types/src/core/predictor_stream.d.ts": "955ac151e0dff450dd54387311b530199fddedc5f42596beeb4854f1791716b9",
+                "types/src/core/primitives.d.ts": "5158f8fa5220ae4a75246d554199f3d0bb40e250f40d2a76e64db93fb3b20926",
+                "types/src/core/run_length_stream.d.ts": "d162a5b3f7a0c01084166b9bdf8d9051d56f5fd6da5ccbe786577cfa214dc00f",
+                "types/src/core/sasl_prep.d.ts": "16f2d86fc7d2e976af8306dfea8e8fce8a3cd62e9312202d7014dcd597fa4c07",
+                "types/src/core/sound.d.ts": "9eeb02ec5956cf962a2705920d018a445ab89609d78dd12f1bc2ed57991d52de",
+                "types/src/core/stream.d.ts": "012290b89ae349c1955bebb2788232ee350924bcbedc550e2e5266c6704cd6ed",
+                "types/src/core/string_utils.d.ts": "5df9b6c87c31c54f23ace1ab74ba99e49040eccdf10fcce09636fafdad8b3f4d",
+                "types/src/core/struct_tree.d.ts": "05352bd5af40cf6c41f93df55979057004f1c9c823e78beccd334734f2f60711",
+                "types/src/core/unicode.d.ts": "0786bc904066405e00508d6eec3782746d3db020dfb63127ccf005880246f5d3",
+                "types/src/core/wasm_image.d.ts": "0d34368731ede533ae7f5c0c15315053dceb4bc8717a8c78d0cf87dc00c2e56a",
+                "types/src/core/xml_parser.d.ts": "64d5813b75d2ea75ca74fa48357df21c8e520f7062884c9a172c9b4db8b4af61",
+                "types/src/core/xref.d.ts": "533fa935b3bb1b1d94166132450ebc610eac0bd38fa1c6b1ec33dfef86f9c483",
+                "types/src/display/annotation_layer.d.ts": "f7d806fc8293d1c02a6d72962e2b424f5d7bb2f168157a7da8e7b1a6fee0e135",
+                "types/src/display/annotation_storage.d.ts": "930b3623228dfab48905a0ab440682f210dca435e64cf53afc30b72c95000c88",
+                "types/src/display/api.d.ts": "16cdbb9a8adc01c15b602db44e6a7e84885307f54148bffe22de075ee958c2b8",
+                "types/src/display/api_utils.d.ts": "bf2f7981c0568c3925827f14809273b12e17dad7c5de15b5246e14bb981f30a8",
+                "types/src/display/binary_data_factory.d.ts": "a69d6c49e7e17b43e0ca8fccc44bf9081388407980da68d6cd59917eff563d6e",
+                "types/src/display/canvas.d.ts": "b4e945806a5edbe61a8dbb0592773c3d600d96e7a3ff31407890914819801e64",
+                "types/src/display/canvas_dependency_tracker.d.ts": "118607b270cec5df60081776501cb55d543c13888b264627e80c6c1bfbc6e5c4",
+                "types/src/display/canvas_factory.d.ts": "87157026c728d377eed5e7e1f89f8ae7ffc791409b2908cd99bcf2e1e1244df1",
+                "types/src/display/content_disposition.d.ts": "6b37ccf5bd62d4ae35fb191f00ab7978205798fa8c69ecdae73a52c20e3a003a",
+                "types/src/display/display_utils.d.ts": "2e10d87ef648cd54f83b64bd3d455487ae0b7baa008ece279eb43566d2c9eac0",
+                "types/src/display/draw_layer.d.ts": "9dd2d11db4196fa4aee41e3e6d1515614f2c7da09fedacfde87168f1755321db",
+                "types/src/display/editor/alt_text.d.ts": "360124e5519ac8bce62c1b6882558942686bce3f90dd3ce5ec90fadb3a3f83c6",
+                "types/src/display/editor/annotation_editor_layer.d.ts": "ff619044aad82e56b7628e8ef78043c50a1d399405e53bd7bb0482967fd73905",
+                "types/src/display/editor/color_picker.d.ts": "f93252b7de8853289eb8b5601e8bd5901a30e74efb02be3c5538857fc2c843c3",
+                "types/src/display/editor/comment.d.ts": "54b9f78ad1f428e06c8d4d00cfc8d7544ad474d19a30fe47a2b8842ffdb2a516",
+                "types/src/display/editor/draw.d.ts": "7f62c36129a01836bde9fab47a70169ddef112d0f8de60d3106a6ae61d7addbc",
+                "types/src/display/editor/drawers/contour.d.ts": "d91760a87cfa14defc105b86c2d2b2f6fddc9636f3986a35fb6c01deef8165d8",
+                "types/src/display/editor/drawers/freedraw.d.ts": "5410316ebb6e6045838e78b287ce6ce65c36ad92b4e52e449ec149936b2d7351",
+                "types/src/display/editor/drawers/highlight.d.ts": "ef8fca7500be7a104a3e48a816d6b9835ce21c1c57f7705cac296873e005da27",
+                "types/src/display/editor/drawers/inkdraw.d.ts": "066e91b6c26c66af0a9697c66df2265aebe33ede658d8b8c0bd40bd11e5ebbb7",
+                "types/src/display/editor/drawers/outline.d.ts": "65f214624fdb7df66f12ed4b4174304bb40ee461e9ebe0aa84817cfc695fc9ba",
+                "types/src/display/editor/drawers/signaturedraw.d.ts": "2244d3a7dcb203968127e13d4d83d507fbe91529c434fc20426ae6c814e6e351",
+                "types/src/display/editor/editor.d.ts": "7bd14ceea540223d3f7a95c06c0a397aaed165388f7dece16e7ff2be85b05352",
+                "types/src/display/editor/freetext.d.ts": "0c2ab3df99dd84fdd05a8aff1deb6fe34e8a3ff4537faa69cc199339e3e3cc56",
+                "types/src/display/editor/highlight.d.ts": "6051306b2031c8bca5b8d40d40f6161131819910c4ea63e0a7da29e3373d28dc",
+                "types/src/display/editor/ink.d.ts": "51bd849812bd12c8598b8bcc0890c983c84359715aeff43f26b557d3d74d8710",
+                "types/src/display/editor/signature.d.ts": "d713078712400f84d8a7d4a2d1a1fd7eeb4879603ef87ee06580220ef12d1bc9",
+                "types/src/display/editor/stamp.d.ts": "c6d92ba3e9ca2097645bf4a350db64ce499b1e6c09acf8261336934f29d85d58",
+                "types/src/display/editor/toolbar.d.ts": "60217ee6f9bdcfd23ef32ffeee3fc08951b3c4d1ffbcf9ad4955b662a67335c5",
+                "types/src/display/editor/tools.d.ts": "631715c0cd1fb06f4e509c7518c27cbd6fedbd8d66b73db2d23ea8ad46182a8f",
+                "types/src/display/fetch_stream.d.ts": "c67667390812988a3caaa3bd44c2449c25e4e7114acbf9bef0b64c09ecbf29ee",
+                "types/src/display/filter_factory.d.ts": "8cd4d9eca72b7cf344cf9c63994e4ef7957982b230251e4e02ff704d5ec85c4f",
+                "types/src/display/font_loader.d.ts": "ee45cdeee3ae49b0526bfa1526821b7ba55bd3b26c8c1307265983caca5daedf",
+                "types/src/display/metadata.d.ts": "83e01ec16b5a8424ba35047471fe772e4fdeba7dfa7884d9ced04dd84c01a26c",
+                "types/src/display/network.d.ts": "0c85768d58e05618bfbee0e2de690e23df5f47a4f2bcf4cced9e69263b85f049",
+                "types/src/display/network_stream.d.ts": "6285a8eed1f0c6d3bc6c0fe7239d131e72a83a3bdbf2dae6cc723055eaf3eeea",
+                "types/src/display/network_utils.d.ts": "2c79d965c77bdfc6aa7f4392828a67b3ca48dd706b7f50aa163043e9690c0403",
+                "types/src/display/node_stream.d.ts": "a16e557eefc22f6fc73ed2512c5199e8e7bf1999dd8bd40bc0c9ca75d9d99219",
+                "types/src/display/node_utils.d.ts": "d1adeec90eda374b6e4d37e7c66175aa8d940cd6b69e502f788520e4c8d3cba4",
+                "types/src/display/obj_bin_transform_display.d.ts": "3acbb0ddb63b789001da8525b335270a41d7f3b763dee002f5b6dfa9da03f127",
+                "types/src/display/optional_content_config.d.ts": "c29404d7e2e3121580988dde115a606a2c6e61107a37f48fea250bbc1f9e2e43",
+                "types/src/display/page_viewport.d.ts": "42685ce1ac3e954632ec46acb8b5a04ac60d675a25d59c6195ad674c82ba4c10",
+                "types/src/display/pages_mapper.d.ts": "a0d3fcf64a3bad43bf08f239afab66aab5812dcda36882f3b1829a50a25f3cd2",
+                "types/src/display/pattern_helper.d.ts": "c5260ddf3504be054fa17bea0d6f18de8f16258acfed523ed133a5e042b96fac",
+                "types/src/display/pdf_objects.d.ts": "87e910be68ccbc0140cde26097f6b2e3666bdfaf5e77100c0d35e059403be02f",
+                "types/src/display/svg_factory.d.ts": "22759dfadc7f47badde31230a0a34ba6810f88b29ff314fb5e0ffd5fe91ba379",
+                "types/src/display/text_layer.d.ts": "271ee9f3165368b79f8b22738b2aa3e3651e3b563f5b3f4fc864f1225280af45",
+                "types/src/display/text_layer_images.d.ts": "a69008712ab6c633c5a735856a33f490cb74077fcd9c4cb1393f1ca036957e4b",
+                "types/src/display/touch_manager.d.ts": "eaabaec39200945796546dcdad5025127e9b1095d21bcb528d049881b7128ae0",
+                "types/src/display/transport_stream.d.ts": "616ec906cb980374c2fd2832d5288d26a916345029ed7e229521aa7673f2a6d2",
+                "types/src/display/webgpu.d.ts": "df892ace6527b98a6cd553c70bade6b8a2767339f0c090ba2f335218741c65dd",
+                "types/src/display/worker_options.d.ts": "da42d839e0acb2d3191ea6c872aaa09b6bb9ab5381cd6c0fcad8044adce03543",
+                "types/src/display/xfa_layer.d.ts": "7cabe8159e64a3bb53f61eb2102f1424a7a0d1437249e63d647ee2ae9cd4f2a2",
+                "types/src/display/xfa_text.d.ts": "97eeb7815e75c1d350dd55a52ba4000ff5ff5c1f6d609d91a111148e0e5a0588",
+                "types/src/pdf.d.ts": "f84ad720764c29f38d6a84e69343535f3d67e23ee1562f782d73e8f55985ffc8",
+                "types/src/shared/base_pdf_stream.d.ts": "37b640f33fb865d3d9196fc77a0c836f0fe58e5dc1fc2655f8e5730dcb432ad9",
+                "types/src/shared/css_utils.d.ts": "f0bed3268eb55523631b5c178b1f178d05cfd89024ad01321b71a842a789d832",
+                "types/src/shared/image_utils.d.ts": "c66b591e1faa8d6672aac5f9c45df8937e0c25539d8a02e641085e5ed4c2dc45",
+                "types/src/shared/internal_evt.d.ts": "0029d260739f482c55e703ffa42ba85fda782309b63ccfd2dd3375d8beb7a902",
+                "types/src/shared/math_clamp.d.ts": "d0d901c56e02004e6a31e49f51a08293f54ca7faa0fa1cff4d6a01cac24b2644",
+                "types/src/shared/message_handler.d.ts": "ea883ecccfc4a10851d2b148690398dca489f564b937c693b1cd4578b76b78bc",
+                "types/src/shared/murmurhash3.d.ts": "1418f74ab5cd9ad695ff51b17174667109acdaed54d2b20e93798cada918b354",
+                "types/src/shared/obj_bin_transform_utils.d.ts": "9dd51eabd9005d02b826ba6539287e304f565678dd01ac2d94e83fefb9867beb",
+                "types/src/shared/scripting_utils.d.ts": "c58fd6146bb0dcb60ae81370e3ea6e0eec94f67e52256a511659c7511f59ae1c",
+                "types/src/shared/util.d.ts": "a78f23fcaff6616c6fe9b2f54f688c06cb782273f89a959ede02b20f0860f27d",
+                "types/web/annotation_editor_layer_builder.d.ts": "65765b4eec23d896328fa82cceaa4a4781c46a6143824c96dc3e413b17a24939",
+                "types/web/annotation_layer_builder.d.ts": "deea8fe37dbaad0be688ed23afa8169e02439a89486b152a39ec96838bd8c85b",
+                "types/web/app_options.d.ts": "6b030ac3774f1591accb096f5f563dab8752dca3be09d7020991a48f512d1495",
+                "types/web/autolinker.d.ts": "55f096f8e3040eedd0dc8d22bd2411fbaa87ed941ca43e61fd8176b69c2373ca",
+                "types/web/base_download_manager.d.ts": "7354af961c75ecf99a1baa62657a9a9b04af1bb503c1d2bb8d6b4cae270c77e0",
+                "types/web/base_pdf_page_view.d.ts": "03c825b842ad07eca2a75565cb4324826072eada9753365a7dd183da7645ac64",
+                "types/web/comment_manager.d.ts": "31170205d4db6086561abc7ca5a80740b0fd4c33b925f14f470667dfc11e110d",
+                "types/web/download_manager.d.ts": "368e77d014cfcf98d10a5d744bb8c1a86cff7befbb51ba18004f01ce4bd65e93",
+                "types/web/draw_layer_builder.d.ts": "24fd34868f78ba9e7bbdb6875a353c7c8726cb34d92c6ee7021f4d2a91c3816a",
+                "types/web/event_utils.d.ts": "589e25d75ad4bfcde6e6058db0bc3264b95b1e7d1866c015042c6853de78edd4",
+                "types/web/generic_scripting.d.ts": "a1c7f498a9b1c9f39f96652c9682a69c0b1cff8df3fbe91b739ef798ea0f593e",
+                "types/web/genericl10n.d.ts": "eb2829cdafffaaa1549a287a583c98cecc2ced5749f4121a1bc7e1b3ea7e2c95",
+                "types/web/internal_evt.d.ts": "69f11323c859cfc110c3dba74eae301755faae88da0af500d869b7b84f90dd40",
+                "types/web/l10n.d.ts": "28628cfe6ec6d805c544f2ed16b471da84a98fd902b74155a44b4d1b86094dcb",
+                "types/web/menu.d.ts": "b72b670b0328ed6b3558386d6ba3fb711b66839575df422e2ba4c2ed0b49a64c",
+                "types/web/pdf_find_controller.d.ts": "832346d635783b595b6532d76b9bb35587f18bbfce41c77de7f45a890ee97ec8",
+                "types/web/pdf_find_utils.d.ts": "9c48e10d673a1bbaf0db30e7ce06b4acff2bb7969551dddb73c365fedc2a51c2",
+                "types/web/pdf_history.d.ts": "869da4c6dcc94eb7beb2e3120c56b552a34e751828d8f55188e542d70c16addf",
+                "types/web/pdf_link_service.d.ts": "fead4204ff7a4be81b5b7863948e0049a270743db2ad1538ac3df78e00b79305",
+                "types/web/pdf_page_detail_view.d.ts": "bd9679cbcd3d43aeda9a4c7b290fc605e7bfbdae775bdb52fcd6c23a9e6a2643",
+                "types/web/pdf_page_view.d.ts": "a3c4dafd22c781ea4ce7ccb22af5c5ba8a9be69280af020a29db099f5d110d07",
+                "types/web/pdf_rendering_queue.d.ts": "09f8c88d9b4ed209d25ce2dc731698972b91aed2fff1fec0a2445f1bbcc67185",
+                "types/web/pdf_scripting_manager.component.d.ts": "e68c0160c90b14d4b56de5a511770d86d0df85c482248840fa7972520b5291d6",
+                "types/web/pdf_scripting_manager.d.ts": "5a96a867e66d5d0572c915d09a36ba9cb3d67bf13df0388c3e1870322abb5301",
+                "types/web/pdf_single_page_viewer.d.ts": "670de16502dfdb66b259b73fb7fe3046128a5d15cd4ecc91d4a357fc9da21ee1",
+                "types/web/pdf_thumbnail_view.d.ts": "4d79b52b12f431c790cf67a2803413dc883b0b092bf86a704fdbb5edae4913dd",
+                "types/web/pdf_thumbnail_viewer.d.ts": "994c08620cd9df15b69ef8713c6dc3ad3d5af1e3d52d69ccbcfb6558dc553f51",
+                "types/web/pdf_viewer.component.d.ts": "73d6ea0095cac548d6e161e640c429ad1de26399ac45842497641dd89e85da8d",
+                "types/web/pdf_viewer.d.ts": "ab7c7c48f6a3d3f2db49332de9069ccccee35087120cc24dbe20da3a17abd6d2",
+                "types/web/renderable_view.d.ts": "ef4819bc5b8b12c843323ba3e618d10ca35f2d8b6a8e99d70ce7072940843311",
+                "types/web/sidebar.d.ts": "c20591639b21c3751f8210654ab1c88ea850565bb703aab707d7ee319c1f23be",
+                "types/web/struct_tree_layer_builder.d.ts": "796e95799fd64c99effb4d57f01eb834e9a8b6909d06851d521158de88e1b8e5",
+                "types/web/text_accessibility.d.ts": "937f87dae6d313bce5e4fe2ca59e22c2de544e4b700ba4f32c5df63aa66c63a5",
+                "types/web/text_highlighter.d.ts": "df180533f2f1ba79735d3d0547ad025b1646641ddeb31d0177ae74932843bf1d",
+                "types/web/text_layer_builder.d.ts": "afb7f4cb408a5f498dc11c7506e399167d8f001f386fd534e3cfbd229f55e92e",
+                "types/web/ui_utils.d.ts": "e4b1f02aed111c77546ffdd39c7d3383dfaf885a4ce5397fe718ee465edac669",
+                "types/web/xfa_layer_builder.d.ts": "326f4256b5c797bf4dee707f64ceb8b7953e55d8c9f6bccf7e669b138885d81a",
+                "wasm/LICENSE_JBIG2": "9e66b7f1b934a28b37f3bc4dac97915de1674271e79a0a88182a18ed9731b4d1",
+                "wasm/LICENSE_OPENJPEG": "a6af136f3e15038a666b61f376612a07d9a4e48cb7c01adbf3e33b3f14ab49b6",
+                "wasm/LICENSE_PDFJS_JBIG2": "aad3cce09842e00e9e11ad5e8fef8cc02fbc3a3768fe2f007443b9cee37aaee5",
+                "wasm/LICENSE_PDFJS_OPENJPEG": "717fc62da03292dbb4dd0c8280bd4ce7bb8550dcf31d772bc93455fb50313425",
+                "wasm/LICENSE_PDFJS_QCMS": "508a77d2e7b51d98adeed32648ad124b7b30241a8e70b2e72c99f92d8e5874d1",
+                "wasm/LICENSE_QCMS": "36d847ae882f6574ebc72f56a4f354e4f104fde4a584373496482e97d52d31bc",
+                "wasm/jbig2.wasm": "466f45c2a61a698152fb5400c27e56ff2ceb73dcb71fde3fc366a502308eaab0",
+                "wasm/jbig2_nowasm_fallback.js": "68686ced624a48c42f84cdaa482ec44b72b0de4dc84a0df903af1fb7b45b5d9a",
+                "wasm/openjpeg.wasm": "95e5002597af0824004aa57b1900fe019715db389e37640b1e58395e42f00cc5",
+                "wasm/openjpeg_nowasm_fallback.js": "9047b34b6bc142d85e4b0aa1b08b0b9baad4c6f8b7ac87641b9e8f90eb6fd23e",
+                "wasm/qcms_bg.wasm": "663d86126d5f5fcb1c61490f94353e2a8375660b8c5498ab3ebab5a34b08800e",
+                "wasm/quickjs-eval.js": "fe7930418e869791ce892567dbd0bc4698152b7e550b5cefa553992c56ddc325",
+                "wasm/quickjs-eval.wasm": "7bcacc9f22cacf7e9b23866d2a6d1639693d40c7f144e41b7c69ed37ba9cbe8f",
+                "web/images/altText_add.svg": "1a9591a23999e1924438b948a9f9671147f04e01e5be724391a3a8a2b58289d9",
+                "web/images/altText_disclaimer.svg": "5d19067a6b51e5bcc2d61325033a8450d301535505a97c50f4141f4cd9e2cf05",
+                "web/images/altText_done.svg": "5b40360d098d1a93227a0a5cdb110f6e5ff3a3eb4af97b61e856c49e17141621",
+                "web/images/altText_spinner.svg": "4089182e21627182ed1d4020978b597d984fb8de4cf547e9f4ac2aec9af13179",
+                "web/images/altText_warning.svg": "07264f4de78a45a4177ddefb48837217aa69b51462ef5b35d3fb9f90000c9ead",
+                "web/images/annotation-check.svg": "9a680f1212888ede7dcae6bfc8cafc447babf4ce531271c8d07277b0aedade96",
+                "web/images/annotation-comment.svg": "c58b385b4a0be6de822a3262b8191073d1730f6420368bd9c6d80db7312327ff",
+                "web/images/annotation-help.svg": "74d9bba0814d12f5ae2715189e1747b7edf5ff6d82c4ca75bae86d717319b6eb",
+                "web/images/annotation-insert.svg": "b2153e2c88c62179029ea9876d463216529ecf581b77d52c971a2cdf3d3166c6",
+                "web/images/annotation-key.svg": "5772b8dd158b0f02bb2be689bb680f4903d84e202cb29a3dc0560af53134c6ba",
+                "web/images/annotation-newparagraph.svg": "a583cca122263d94c3eebfefe83c965a1b305b9c84e5aa3c5ba10527941db7db",
+                "web/images/annotation-noicon.svg": "76399e70d311834d11ab2d6239118b36847d79a78d7655b1f839d51c811304cf",
+                "web/images/annotation-note.svg": "11a75c9f233dd3e5e3500edcdd733358394f28395337616e8b0430694bf0dba1",
+                "web/images/annotation-paperclip.svg": "0213c8baed4f8c497881ffed0e49abb309291d51725aaf1a0a757174b4999368",
+                "web/images/annotation-paragraph.svg": "efbcd2a6cfb4581dad74a1c09ad43cf2b8245611e5b19c966317da948f2bcb7c",
+                "web/images/annotation-pushpin.svg": "22197186d18445959e5fe5577d8e34440b31d87c811daf47318078310c0c5530",
+                "web/images/checkmark.svg": "424df6b8515df22424c9505a9e87d35d87d3fd59962d56692fcc4d17613f2165",
+                "web/images/comment-actionsButton.svg": "281b2348ed747ea3ee74763a01d56441d8c570b3e68f11556dc4084a14484d1f",
+                "web/images/comment-closeButton.svg": "fdb819984e10758952bc35b5be3220538b21a787656794b1071fecd3d2648930",
+                "web/images/comment-editButton.svg": "e79c41bf53a89ced9a3ad364a49943813189d06fd96174952e5fb2636938b70f",
+                "web/images/comment-popup-editButton.svg": "857c0198bc536885f2b486353d5719d0c1bb91d69325474f7d787ce5b43cfe1e",
+                "web/images/cursor-editorFreeHighlight.svg": "90b04428328a67e184fe1b1a1f28cb0d62bf6e298614ca241b6564fb24cb9e7e",
+                "web/images/cursor-editorFreeText.svg": "fedb05ee0dd510514ed9edb24b3b4da2707931279a0bf48e2a1deb3a1f4cf581",
+                "web/images/cursor-editorInk.svg": "0ae889debe01269b49b89d8845995281223b8ae289405758631076b763da3efe",
+                "web/images/cursor-editorTextHighlight.svg": "c6252b0edcb68dac87557a027180fcbdbd93466841aa34792530f7cce54cec5d",
+                "web/images/editor-toolbar-delete.svg": "f1f47a2cb479a87807f9bd61bd5813c1fe857dbbcb4fb35ae7a77ca39114f920",
+                "web/images/editor-toolbar-edit.svg": "c6eacc709e4dd30a57120b6531856c003a4c931c46656c3625e2fd5886cf4ce6",
+                "web/images/findbarButton-next.svg": "3029879b7e1060d54c4edcfe0c93c8c3b8c1756fb794e5d4add64028b5f99fab",
+                "web/images/findbarButton-previous.svg": "766d12bb08b9f13c753d289f3c029f5ca202eda3a8be52afc9e31697335f4a80",
+                "web/images/gv-toolbarButton-download.svg": "010d9d77a425e80eb666a196f500cdd8b15758af69a19ad7f11279b78c29e3f5",
+                "web/images/loading-icon.gif": "483c4a0396691993a641ec409c44b8b7e1daab0ae7e2b2944c4bc59520bb7655",
+                "web/images/loading.svg": "7d6e14cf6226c74c26e2141180eadc944ef4ce8565e9b6dd2670ec202417a764",
+                "web/images/messageBar_closingButton.svg": "7393c7791916243eca6bbdda8bf137d36600fffc76d7a55d33a77bd4e7778193",
+                "web/images/messageBar_info.svg": "050e838b982b1b3e993e06bd666f8693ea98e89fb568c39c4af32e128477aeef",
+                "web/images/messageBar_warning.svg": "888a4bf2ad5150028663dde01fe71599336c87ca12697180e51bd8a13b88084f",
+                "web/images/pages_closeButton.svg": "03577a1fc1fc16be0331c65d45accc4d57c269381999e00b2bec9005225a7643",
+                "web/images/pages_selected.svg": "a66ae84122fc40cc1282c68205909387e05a80061b9a7268a54b4bd0c9e7e2fc",
+                "web/images/pages_viewArrow.svg": "409d9a306df6e86bc433365f961be50c9b4256b7a89b741f2f858af5b456b2ce",
+                "web/images/pages_viewButton.svg": "f49c2ddd994c602dcaceb3c6b1445ef37bfd6ca8e2cb468d894741368c3344af",
+                "web/images/secondaryToolbarButton-documentProperties.svg": "735a4bc556610bc6dedaa40a36ccf444c31032be02ad20df5ac4c66ebaa5bbc3",
+                "web/images/secondaryToolbarButton-firstPage.svg": "d46a7b0760fbc043a98f9b328f6b4ee56df8de140a2a290f0e2a915ff772e287",
+                "web/images/secondaryToolbarButton-handTool.svg": "e968339ba921e68d4d83e6ec7a4321f1791c86f4eff552f28cf4c81c6f88155b",
+                "web/images/secondaryToolbarButton-lastPage.svg": "4cc4b92888b776ea3a09d5e86b17d7bb50a8f3e6d09854d4c2e3f050c34dc9f8",
+                "web/images/secondaryToolbarButton-rotateCcw.svg": "7eb24492df9f42c8ab053cbead5d985b0daaccced649392d1fbfde4931459451",
+                "web/images/secondaryToolbarButton-rotateCw.svg": "03d2e7bad2fc95895334e43edf34309a64223f32504304034eb1f6b163954898",
+                "web/images/secondaryToolbarButton-scrollHorizontal.svg": "c61fb184d5311255b627a9943c156bb1f00f835282d832241e01a7d82a22b678",
+                "web/images/secondaryToolbarButton-scrollPage.svg": "e60ae21987a2e6e5352ac3171363352cac9d2cae36bf828d1729cbfa286e085d",
+                "web/images/secondaryToolbarButton-scrollVertical.svg": "79871e2329cbb4dc2b6df94aae5f3074b3fdebffba46fe7d3ade9aff5726bfb0",
+                "web/images/secondaryToolbarButton-scrollWrapped.svg": "8734aa2747f6fff9e8fd09f6e9509db43ec1b63935c8f6b8291e9347bc7e2706",
+                "web/images/secondaryToolbarButton-selectTool.svg": "332e08979379ff2f8a7bfd336e8ca6348546c78ce2a6bf464cd31dc2c64004ac",
+                "web/images/secondaryToolbarButton-spreadEven.svg": "ac385199d448c0d5ae5d4c06d2c76db0a31bb5db54d0fbd727f3dc889e73271b",
+                "web/images/secondaryToolbarButton-spreadNone.svg": "649934c2f447d7a239d6ffce8f8e0804b50dfe1d9421a1d16e9543c0aee9b03e",
+                "web/images/secondaryToolbarButton-spreadOdd.svg": "43b6862d35f86dbe5fec6b16e2cb59ca22c490bdf0787e4590c1ceb494d05244",
+                "web/images/signature-properties-row-check.svg": "3fe9e7e5869e80c04e560ec79e8960ed0f3e918195b6de2b039bd33fb23ecf0f",
+                "web/images/toolbarButton-bookmark.svg": "f2a335bc963e95344d26d61157b1511f5f78d705b38579004971d51a3c62401c",
+                "web/images/toolbarButton-currentOutlineItem.svg": "5f6505f05dbc728301942b37de22d490f09276e6c9a6561b1894afa91f34439c",
+                "web/images/toolbarButton-download.svg": "afa286c8ea1941eaec589ed6a2103c5a845f3ff76a7423ba985f449465005163",
+                "web/images/toolbarButton-editorFreeText.svg": "9ec2202e18ba668ee1753179afead4e1786eac82da2cc82afc5a09584c242c43",
+                "web/images/toolbarButton-editorHighlight.svg": "df0aac50621777fb63da60b38c71c5bbbde746c4dd55c30dd141621cb30b7cc4",
+                "web/images/toolbarButton-editorInk.svg": "081bf99d3c2390036a2d9c7e9485316bcd049f90a74e982f1eebcfd4d9b178e3",
+                "web/images/toolbarButton-editorSignature.svg": "32e07998fd55a7ed40ec2b542fe324ec097d9023fc4c59d6debe33becdf215c2",
+                "web/images/toolbarButton-editorStamp.svg": "18294793f2399a8a44ee246d63b20cd46cb3cd38a1bb72f00b826e7f756c5f52",
+                "web/images/toolbarButton-menuArrow.svg": "2db41f97615a8c912f676a62c88b12e2b8715f4ed188df325737423501aa4a8a",
+                "web/images/toolbarButton-menuArrowNova.svg": "8677b09af730ba49dde7be6f16d08a0b4eb594ed3402f9693e298223d3e9efff",
+                "web/images/toolbarButton-openFile.svg": "7acb9e9964dd618bfcb657d8d18db2c55ef8f168c37f3873c06d72c63e1b11ec",
+                "web/images/toolbarButton-pageDown.svg": "09a14cbd902aad9fe40f2351db2ac5593ad897aed8810b9c6aeb0e56389ff100",
+                "web/images/toolbarButton-pageUp.svg": "bac79138cb730c6bfa63bef02d7e5906aee727bb54df15878823426822badaaa",
+                "web/images/toolbarButton-presentationMode.svg": "2a08e4277e39a9faef69520570744650bb017c2e90fe7c15224144d6b4abfbe7",
+                "web/images/toolbarButton-print.svg": "267745d6c176afe038630c3f7c0fcda78141fc7634f73898ffc6cbb1262c77ab",
+                "web/images/toolbarButton-search.svg": "32889acafd84edeec513db6131252fa97ffff00fee6272d05e35e2d95216e30f",
+                "web/images/toolbarButton-secondaryToolbarToggle.svg": "ff717321d89309f51bcccc28f347e6a888e73570527845d6560a84f5d70cb3a0",
+                "web/images/toolbarButton-signaturePropertiesError.svg": "957d6ce5e6c4a62f88ad0e79c50b6ccd94358524a7450d3b04eb318146a46351",
+                "web/images/toolbarButton-signaturePropertiesVerified.svg": "ae9f3a3e7e8e16900e6b2dbaa7acea0111763b72125246e55b572f4e9e66bc16",
+                "web/images/toolbarButton-viewAttachments.svg": "e07fbf17b3c7ca2cda9c4e54cdd66cb0aa63d368232cbb2c9aed5559720bf96c",
+                "web/images/toolbarButton-viewLayers.svg": "e0b8a59c272dc9a1d9a07d461363f96c3b3bd3df2db778f8f99743dfffd51d78",
+                "web/images/toolbarButton-viewOutline.svg": "eeb6cd0ce94dcfea6bd2aca222da7b1583d74800ea9c94640ff8fa06c13fb044",
+                "web/images/toolbarButton-viewThumbnail.svg": "5fa35769db66b33d6408f378e8aa68fa060331f0cc9dd6ad41fb7366082aad34",
+                "web/images/toolbarButton-viewsManagerToggle.svg": "88098d3e47fd921122c5263dce50ee67c662c9cb65908be0481891dfe521a6c5",
+                "web/images/toolbarButton-zoomIn.svg": "722dfe315686a5841d0a0d00f34df8f706d2c6e24551d46a5ebe971fe4af62d2",
+                "web/images/toolbarButton-zoomOut.svg": "366a40c3627e67f97164976d5ff38b5484716e834d08fefe252a6ea37feda895",
+                "web/images/treeitem-collapsed.svg": "37c96d0dc2f626c541303a76067184ac09614f2390a8430e973a84e5184e2646",
+                "web/images/treeitem-expanded.svg": "df4a149c4eaed4573620621087f7bab816f049e3e341574654fab598435db086",
+                "web/pdf_viewer.css": "1f3c7c3c692d4da2334d0386d2286ec040a37db8654e02b8704b11262bc9bf49",
+                "web/pdf_viewer.d.mts": "85ad88b315ef15eff4fa2311c4a1d29aa77e1db0355de822a14cb007c2b713b4",
+                "web/pdf_viewer.mjs": "2e112bf95cf962bcc9d3ace10d5bc74b3c5095245baa3eacd6bbbb9fc9a940a3",
+                "web/pdf_viewer.mjs.map": "75ce71f117128993de8d80d556daa118ec065270384eaa67b5e9e8d28e5da87a",
+                "webpack.mjs": "eac3e389a6200bbfdd5006caaa71a59c26bb5df2a358f90eddbf5c63b67ea450"
+            }
+        }
+    }
+}
diff --git a/website/vendor/movi-player-0.4.1-tgdrive.1.tgz b/website/vendor/movi-player-0.4.1-tgdrive.1.tgz
new file mode 100644
index 00000000..f670dc11
Binary files /dev/null and b/website/vendor/movi-player-0.4.1-tgdrive.1.tgz differ
diff --git a/website/vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz b/website/vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz
new file mode 100644
index 00000000..09ab78c8
Binary files /dev/null and b/website/vendor/pdfjs-dist-6.4.299-tgdrive.1.tgz differ
diff --git a/website/vite.config.ts b/website/vite.config.ts
new file mode 100644
index 00000000..04d4f7d9
--- /dev/null
+++ b/website/vite.config.ts
@@ -0,0 +1,14 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { pdfjsAssets } from "./scripts/pdfjs-assets.ts";
+export default defineConfig({
+    plugins: [react(), pdfjsAssets()],
+    build: { outDir: "dist", emptyOutDir: true },
+    server: {
+        proxy: {
+            "/api": "http://127.0.0.1:8000",
+            "/file": "http://127.0.0.1:8000",
+            "/stream": "http://127.0.0.1:8000",
+        },
+    },
+});